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

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

On Mon, Mar 02, 2009 at 11:22:52AM +0100, Simon Josefsson wrote:
How about submitting a patch to use help2man instead?


Then the man page will be kept up to date with --help output.

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.

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.

brian m. carlson / brian with sandals: Houston, Texas, US
+1 713 440 7475 | http://crustytoothpaste.ath.cx/~bmc | My opinion only
troff on top of XML: http://crustytoothpaste.ath.cx/~bmc/code/thwack
OpenPGP: RSA v4 4096b 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187

Attachment: signature.asc
Description: Digital signature

Reply to: