[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: man pages for Subversion

From: Thomas ┼kesson <thomas_at_akesson.cc>
Date: Wed, 14 Aug 2013 00:44:02 +0200

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. 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.

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.

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.

regards,
Thomas ┼.

On 12 aug 2013, at 12:38, Julian Foad <julianfoad_at_btopenworld.com> 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
>
>
>
> --
> Join WANdisco's free daily demo sessions on Scaling Subversion for the Enterprise
> <http://www.wandisco.com/training/webinars>
>
>
>
> ----- Original Message -----
>> From: James K. Lowden <jklowden_at_schemamania.org>
>> To: Daniel Shahaf <danielsh_at_elego.de>
>> Cc: dev_at_subversion.apache.org
>> Sent: Saturday, 10 August 2013, 4:22
>> Subject: Re: man pages for Subversion
>>
>> On Fri, 9 Aug 2013 11:21:23 +0300
>> Daniel Shahaf <danielsh_at_elego.de> wrote:
>>
>>>> 1. Get the sources for 1.9
>>>> 2. Examine svn_cl__cmd_table
>>>> 3. Prepare a doc build tree that creates two things:
>>>> a. man pages
>>>> b. plain text for --help, one file per subcommand
>>>>
>>>> The plain text filenames will have the extension ".in", so a
>>>> simple Makefile rule can convert them to ".h" for inclusion
>> into the
>>>> appropriate source module.
>>>
>>> You'd have to figure out something for windows as well, since we
>> don't
>>> use make that on that platform. (Several of our dependencies do, but
>>> we just generate Visual Studio projects.)
>>
>> Hmm. This is a sticky wicket.
>>
>> My plan is to keep mdoc sources and generate plain text for
>> inclusion in the help subsystem. That's done easily with groff, see
>> below. But I notice in INSTALL you support building on Windows not only
>> in a tarball but also directly in-tree. That means the Windows
>> build machine would have to be able to convert the mdoc sources to ASCII
>> strings.
>>
>> I'd like to point out, btw, that in 2013 this is the tail wagging the
>> dog. Windows command-line users are rare; most people use Tortoise.
>> Those that do use the command line don't rely on --help very much,
>> either. Consider:
>>
>> $ svn propset --help | wc -l
>> 95
>>
>> and that more.exe resembles UNIX more(1) circa 1984 and that most
>> Windows users don't even know it exists. "svn help" on Windows is
>> not
>> the model of ease of use.
>>
>> Preserving --help for anything more than a short recap of the options
>> isn't worth it, especially when PDFs are available! The time is much
>> better spent improving the documentation and Subversion itself.
>>
>> But let us suppose ad argumentum that we want to preserve --help, and
>> to support in-tree builds on Windows. That means something has to
>> convert the mdoc source to plain text. I don't see any better way than
>> to require mdocml or groff to be installed.
>>
>>> In general, it'll be best if you hook into the existing build system
>>> --- configure.ac, gen-make.py, and build.conf. The latter two are
>>> used on all platforms (on unix they generate build-outputs.mk).
>>
>> I don't want to get too deeply involved. I know mdoc, and I want to
>> see man pages become part of Subversion. I'm willing to provide
>> up-to-date mdoc source for them, and to generate plain text, and to
>> write a little Perl to convert the plain text to static constant
>> character arrays in C. I'm prepared to do the work to make it easy
>> -- for someone who knows how -- to integrate that work into the build
>> system. I don't want to peek inside gen-make.py.
>>
>> Below is a sample of what I'd expect from the mdoc -> ascii
>> conversion.
>>
>> --jkl
>>
>> $ groff -P -bc -Tascii -mdoc man1/svn-copy.1 \
>> | sed -ne '/NAME/,/specify/p'
>> NAME
>> svn copy -- Duplicate something in working copy or repository
>>
>> SYNOPSIS
>> svn copy (cp) [-Fmq] [--config-dir DIR] [--config-option OPT]
>> [--editor-cmd CMD] [--encoding ENC] [--file] [--force-log]
>> [--ignore-externals] [--message] [--no-auth-cache]
>> [--non-interactive] [--parents] [--password PWD] [--quiet]
>> [{-r | --revision} REV] [--trust-server-cert] [--username
>> USR] [--with-revprop PROP] SRC[@REV] ... DST
>>
>> DESCRIPTION
>> When copying multiple sources, they will be added as children of
>> DST, which must be a directory. SRC and DST can each be either a
>> working copy (WC) path or URL:
>> WC -> WC copy and schedule for addition (with history)
>> WC -> URL immediately commit a copy of WC to URL
>> URL -> WC check out URL into WC, schedule for addition
>> URL -> URL complete server-side copy; used to branch and tag
>> All the SRCs must be of the same type.
>>
>> OPTIONS
>> --editor-cmd CMD use CMD as external editor
>> --encoding ENC treat value as being in charset encoding ENC
>> -F --file FIL read log message from file FIL
>> --force-log force validity of log message source
>> --ignore-externals ignore externals definitions
>> -m --message MSG specify log message MSG
> <svn-help-from-xml-4.patch>
Received on 2013-08-14 00:44:39 CEST

This is an archived mail posted to the Subversion Dev mailing list.