Re: man pages for Subversion
From: Julian Foad <julianfoad_at_btopenworld.com>
Date: Wed, 14 Aug 2013 08:21:24 +0100 (BST)
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.
> 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
This is an archived mail posted to the Subversion Dev mailing list.