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

Re: Removing the manpage requirement for GUI programs?

On Sat, Feb 27, 2010 at 08:06:37PM +0100, Josselin Mouette wrote:
> Therefore I propose that we drop the requirement of a manual page if
> these conditions are met: 
>       * the program requires graphical interaction with the user, and is
>         not meant to be used from a script; 
>       * the command-line switches are properly documented with a --help
>         option.

A manual page contains more information than just command line switches.
For example, iceweasel's manpage contains information about environment
variables and files that it uses.  This is almost never found in --help
output.  Also, in order for this requirement to be acceptable, every
binary in Debian that does not have a manpage must, upon first upload,
have a working --help output.  Otherwise, as Russ pointed out, we have
no way of knowing whether the program supports --help.  If it has no
manpage, it could be buggy and need a manpage, or it could be buggy and
need --help, but there's no way to know.

Also, if I'm looking through /usr/games for new ways to waste time, how
am I supposed to immediately intuit whether this program is GUI or not?
With a manual page, I can learn about the program and determine whether
it's a game I want to play at all.

Additionally, in some cases, the --help output is not sufficient to
explain what a program does.  "gcc-4.4 --help" does not list all the
options; one has to use "gcc-4.4 -v --help".  Also, using only the
latter, please tell me what the "-dM" argument does when passed to

Although this example is not a GUI program, it is a great example of why
--help output is often not sufficient.  In my opinion, your proposed
change to policy will not result in the elimination of many manpages,
because in most cases, the programs will be inadequately documented by
the --help output.  --help output is for the case where you already are
intimately familiar with the program and what it does, and need a quick
reminder, or for cases when manpages are not available (emergency
single-user boot).

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

Attachment: signature.asc
Description: Digital signature

Reply to: