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 gcc-4.4. 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