First, a caveat: I'm not a dd, and have only been involved with Debian and Linux for around 8 months.
That makes me uniquely qualified :-) to suggest some kind of standardization for online help be implemented in policy for console programs. I've grown accustomed to typing <console-command> --help first, before using any given command, to assure myself that I'm going to be using it right. My expectation that's built up over time is that it should be harmless to type that syntax; almost all programs print their usage information and then exit. However, some commands don't respond to this, others act as if the --help was not present and do their function anyway. That violates the don't-surprise-your-user software quality guideline, when so many packages conform to the unwritten 'standard'. I was going to submit a bug to lintian so it would check for this, but i realized lintian would probably complain that it wasn't policy. I searched the bug archives for policy, and it seems like online help has never come up. Well, I wasn't able to find it if it has. And certainly policy as it exists today is silent. In the X environment, there should probably be some standardization for the help menu also; but I'm not very familiar with that so I won't pursue it here. Perhaps it's already taken care of within X software guidelines. If so, perhaps the proposed Online Help section could reflect the current X practice too. A case could be made that online help is a form of documentation, and would belong in that section. But it seems to me to be a different ball of wax. At least for console programs, the help is generated by the program itself, whereas documentation is generated separately, moved hither and yon, etc. etc. Here's the proposal: Chapter 14 Online Help 14.1 Support of --help Argument Programs which can be executed from the Linux console may provide online help when the program is invoked with the --help argument. Programs which provide online help should display a brief message on standard output including a Usage: or Syntax: section which shows a sketch of the syntax or various valid syntaxes for the command, and then exit immediately afterward. If the syntax sketch includes portions such as [options], then the most commonly used options should be listed in an Options: section. It is desirable for the response to --help to be 24 lines or less, so it will fit on all terminal screens in one piece without the necessity of piping the response to a pager. If more information is deemed appropriate than will fit in 24 lines, the program may provide separate help options explained in the initial --help response, such as --help-options or --help-commands. The program might also call /usr/bin/pager to handle the output. 14.2 Support of --version Argument Programs which can be executed from the Linux console may provide their version number and a brief summary of program version-related information when the program is invoked with the --version argument. The response to --version should be less than 24 lines. Programs which provide a response to --version should exit immediately afterward. 14.3 Support of Help Menu in X ??? -- *------v--------- Installing Debian GNU/Linux 3.0 --------v------* | <http://www.debian.org/releases/woody/installmanual> | | debian-imac (potato): <http://debian-imac.sourceforge.net> | | Chris Tillman [EMAIL PROTECTED] | | May the Source be with you | *----------------------------------------------------------------*
