[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Requirement for a “proper manpage” for every command

* brian m. carlson [Mon, 02 Mar 2009 19:45:22 +0000]:

> help2man is a fine starting point for a manpage, but unless the help
> messages are very verbose, it is not sufficient.  A manpage needs to
> explain all the possibilities and interactions between different
> options that are usually not provided by --help output.

> An excellent example is gpg(1).  help2man could provide a very basic
> starting point, but the resulting manpage would be woefully incomplete.

This is true.

>> Possibly the document around the man page requirement could point to
>> help2man as a quick solution in case there is useful --help output but
>> no man page.

> My concern is that people will solely use help2man instead of providing
> a real manpage.  Debian requires manpages for a reason: to provide
> adequate documentation on how to use installed programs.

Many times the problem is that upstreams do provide such adequate
documentation... in other formats than man pages. What should the
packager do in that case? Create a dummy man page pointing out to eg.
/usr/share/doc/foopkg/html/fooprog.html? Copy over the contents of
fooprog.html to fooprog.1? Other?

Adeodato Simó                                     dato at net.com.org.es
Debian Developer                                  adeodato at debian.org
                                    Listening to: Ana Torroja - Les Murs

Reply to: