man page generator

[Martin Pool]

On  7 Jun 2005, Hans Ulrich Niedermann <arch at n-dimensional.de> wrote:

> Yes, that was what I was looking for. :)
> 
> However, restructured text alone probably cannot help us yet - we
> still need a way to express:
> 
>   a) command synopsis:
>      command name, valid values for the parameters and options

Yes, for this reason I'd suggest it eventually be somewhat integrated
with (or call in to) bzrlib.help.

A goal here should be that the manpage is just a convenience for Unix
users, and gives no more or less information than people on Windows
can find by bzr help.

>   b) items to be substituted:
>      e.g. the actual name of the bzr executable

> Oh, and our options need to be documented somehow (the option
> themselves, and what they do in the context of the command they are
> used with).

Yes, some options really need to be explained in that context to make
sense.  For example, what the --force option forces may vary by
command.  That can be done.

We should also work out if there is any standard or reasonable way to
make distutils (setup.py) install a manpage into the right place.  Or
maybe it's enough to just treat it as a data file into
$prefix/man/man1.

-- 
Martin