[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: James K. Lowden <jklowden_at_schemamania.org>
Date: Thu, 8 Aug 2013 22:25:08 -0400

On Thu, 8 Aug 2013 08:58:29 +0300
Daniel Shahaf <danielsh_at_elego.de> wrote:

> Perhaps this is a good time to point out that you were writing man
> pages for 1.7, which is in "Security fixes only" mode. The supported
> release is 1.8 and trunk (where new development should be targeted)
> is 1.9.
>
> > 1. Keep the man pages in mdoc format as the "souce code".
> > 2. Convert "svn foo --help" and "svn help foo" to invoke man(1), as
> > git does. Or use groff to generate plain text for static inclusion
> > in the the binary.
>
> As Bert said: not possible. We support Windows and that has no man(1)
> or nroff(1) binaries.

OK. It's easier to convert mdoc to ascii than the other way around.
What you want, I think, is one long C string (with embedded newlines)
that per subcommand that you can print in response to --help. Can do.

> So you'd need a solution that allows compiling the man pages source
> to C strings that uses only Python (and maybe Perl).

Yeah, the poverty of Windows has been a problem since ever. We can
leave the functionality of --help as is.

> You realise we already have such a database? svn_cl__cmd_table in
> subversion/svn/svn.c.

I will look into it. I suppose it sounds odd to this group, but I'm
just a Subversion user. I've never been tempted to hack on it, and
never looked at the code.

> > Contrary to popular wisdom, good old troff is the best system there
> > is
>
> Clearly you have a strong opinion on this.

Yes. :-) It's not as though I've been using troff for 30 years and
never learned anything else. I came to it reluctantly, having tried
several others, and found it actually works pretty well. As Dijkstra
said of Algol 60, "an advance over its predecessors, and over many of
its successors."

Stefan Sperling <stsp_at_elego.de> wrote:
> If you manage to generate both the compiled-in strings and the man
> pages (on UNIX only) from the same source format during the build,
> I"m happy with that. If you manage to generate man pages from
> 'svn help' output during the build process on UNIX, then I'm happy,
> too.

It sounds like we have agreement and the ball is back in my court. If
there are no objections, I'll work on the following as a next step:

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.

I'll also subscribe to the list to make it more convenient for us to
communicate.

Regards,

--jkl
Received on 2013-08-09 04:25:49 CEST

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