Re: [Monotone-devel] monotone man page

[Stephen Leake]

Thomas Keller <address@hidden> writes:

> I've just pushed some initial work to nvm.man-page to let monotone
> auto-generate its own man page. 

In my opinion, there are two uses for a man page:

-   to give a summary of the arguments and options, all in one place, so
    you can search for things

-   to point to the more complete manual somewhere else.

mtn is lacking these two things at the moment. But the command line help
tends to be very good, and I know about the info manual (I read it in
Emacs), so I don't miss the man page.

It makes perfect sense to generate the manpage from the mtn help
information. Adding the reference to the local info and online html
manuals can simply be hardcoded in the C++ code for the 'mtn manpage'
command.

Note that many man pages refer to a manual, but don't give precise
instructions on how to access it, which is just frustrating. So be sure
to include a URL for the online manual, and the full path to the actual
info file on the local disk. Hmm, the later assumes you can deduce the
info install path from the mtn executable install path; I guess that's
not true. So each distribution will have to customize that. Maybe there
needs to be a hook to run the user's favorite info viewer, or at least
to give the full path to the info file.

On distributions with standard locations for man and info files, it
might be enough to just say "in the standard locations for this
distribution". But it's better to give a precise reference if possible;
when someone is learning a new distribution, they need all the help they
can get :).

> If you compile this, a new hidden "manpage" command will be available,
> which dumps the command tree and a few additional information in
> (g)roff format, so you can then basically
>
>       mtn manpage | groff -man -Tascii - | less

> I haven't yet touched the build process part for that, so no, the man
> page will not be automatically generated / installed when you hit make
> install now...

Man pages are not much use if not installed, but that's also not hard to
do once the man page is ready. On the other hand, the installation
location is distribution dependent.

On Win32, there is no 'man' command, so we probably don't need to bother
with man for that distribution. On the other hand, if someone has a
MinGW toolset with man, they might want it.

Cygwin has a normal 'man', and a standard location for info files; the
Cygwin monotone package installs the info file properly, and could
install the man page also.

The monotone Debian package installs the info file in the standard
location; it could also install the man page. It could also install the
html version of the manual in a standard location; it doesn't do that at
the moment. The man page should give URLs for both the remote and local
HTML manuals.

-- 
-- Stephe