Re: man pages for Subversion

Thomas Åkesson wrote: > Hi Julian et al, > I think your XML approach is the way to go in order to fulfill current and > future requirements. A single source to keep updated is vital. XML is an ideal > source format for HTML, PDF while plaintext (svn help), man etc should be no > problems to sort out with XSLT. > > I was unable to find the XML or XSLT in the patch. Oops.  Here, attached, is a complete patch (svn-help-from-xml-5.patch). > Since the svnbook is Docbook > I would go with that schema unless we find very specific requirements that we > can't fulfill (usually doable with some creative use of attributes). The > reasonable alternative, given that we prefer standards, would be DITA but that > is a whole new level of complexity. > > How is the stuff that you removed from the .c files translated? Given that > different languages take very different amounts of space the line breaks must to > be... well, problematic. I inserted manual "soft" line-break annotations into the XML in order to match the C code formatting exactly, with the intention that we would eventually remove those from the XML source and do some kind of automatic line splitting instead. > Going with Docbook would enable the svnbook authors to quite easily generate a > set of XML fragments from the svn XML. These XML fragments would be at minimum > screen-elements and probably also some list-stuff. All of which can be XIncluded > into the Svnbook instead of duplicated. Yes -- I had that in mind but have not tried to do it. > I can help out with schema discussions and XSLT programming (in September, > preferably). I have a fair share of experience transforming Docbook-like schemas > into XHTML, XSL-FO and other formats. Cool. Thanks. - Julian > On 12 aug 2013, at 12:38, Julian Foad wrote: >> Hi James.  I have one thing to throw into the mix, which you might >> be interested in looking at.  I experimented a few months ago with >> generating both the C help strings and man pages from an XML source >> file.  My patch to do this is attached; it is complete and and usable, >> although not finished or quite how I would want it. >> >> One of my requirements was to produce C strings identical to those we >> have now, in order to prove that it can be done and to be able to >> check whether I've missed anything.  I invented my own XML schema and >> hand-wrote the XSL transformations, and to be honest the XSL is ugly. >> Before using a method like this, I would want to change it to use a >> somewhat standard schema, or at least a standard schema as far as >> possible plus our own extensions for the rest. >> >> If you want to play with this patch, it applies to svn trunk as of >> r1456600 (March 2013); I haven't updated it since then.  It's >> integrated into the build system (Unix only, so far), using xsltproc. >> To create the man page, use "make subversion/svn/svn-help.man", and >> use something like "(cd subversion/svn && man -l svn.1)" to view it. >> It currently creates a single man page for 'svn', listing all of the >> subcommands within it. >> >> - Julian