while the manual should be a detailed and comprehensive
source of information.
I certainly agree that `the manual' should be detailed and
comprehensive. However, I do not think the *man page* needs to be that
manual. The Texinfo format is superior for `detailed and comprehensive'
information. The man format lends itself to quick summaries.
I know that a few programs, such as bash, gawk, tcsh, etc, have
extremely detailed and long man pages. That's fine, but I don't think
it's necessary to promulgate that as the standard.
Also, whenever a package includes more than executable files you need
man pages for several chapters, not just the exe.1.
It is true, and those man pages have to be written by hand.
I think most users won't be happy with either the output of --help
or the output of help2man.
As I said, help2man is being used now to generate all the *utils man
pages, the texinfo man pages, and perhaps others. I haven't received
any complaints yet, only happiness that there *were* man pages, and that
they were up to date.
