Online Help
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 tillman@azstarnet.com |
| May the Source be with you |
*----------------------------------------------------------------*
Reply to: