Re: man pages for Subversion

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@schemamania.org> > To: Daniel Shahaf <danielsh@elego.de> > Cc: dev@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@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 >