Re: svn commit: rev 2348 - trunk trunk/subversion/svnadmin trunk/subversion/clients/cmdline/man

Thu, Jun 27, 2002 at 11:24:30AM -0500 wrote:
> sussman@tigris.org writes:
>
> > Add svnadmin(1) man page, written by David Kimdon <dwhedon@debian.org>.
>
>
> > +++ trunk/subversion/svnadmin/svnadmin.1 Thu Jun 27 11:13:26 2002
> > @@ -0,0 +1,160 @@
> > +.TH svnadmin 1 "27 Jun 2002" "svn 0.13.0" "Subversion Command Line Tool"
>
> Man, isn't there some nice, automated way to get our SVN_VER_NUMBER
> constant out of svn_version.h and into our man pages?

Unless we find a way to automatically update the manpages this might
create confusion. That is, the above manpage is accurate (or tries to
be anyway) for 0.13.0, if we extracted the version automatically we
could mislead.

Which brings up the question of automatically generating the whole
manpage. We could use help2man, but AFAIK that doesn't work too well
on the svn tools, help2man expects :

command [OPTION]

not

command [OPTION] subcommand [SUBOPTION]

I tried it on svn and the output wasn't pretty, I didn't look deeply
at help2man though, maybe we just need some tweaks.

If texinfo is to be the standard we could have the documentation in
that format and create manpages from it, but then we'd have to keep
the texinfo up to date.

In general I haven't found a good way of keeping documentation and
source code in sync automatically. Most of the tools floating around
come close but the documentation generated gets much better after some
manual human intervention.

It isn't that big a deal once the software has matured though since it
won't be changing so much.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Jun 27 19:23:52 2002