Articles / Time to Rethink Your Help Flag

Time to Rethink Your Help Flag

It may come as a surprise to many of you, but sometimes, featuritis can be a good thing. Sure, you may only use 20% or even just 10% of the features, but, to quote Joel Spolsky, everybody uses a different 20%. Take 10 or 20 random people, and you'll get about 99%. You may happen to face the situation in which your program has gained more commandline arguments than GNU ls. How should you deal with the --help switch?

Freecell Solver (one of my projects) is such a case. Its --help screen now takes seven clicks to display entirely when invoked with "fc-solve -h | less". The problem is that people like choices, but don't want to be confused with a lot of options. If the program does nothing (or misbehaves in the first board layout you try) and you want a quick answer, you're not going to read through seven pages. Spolsky tends to be a bit GUIish, but the same rule applies to commandline programs.

Several solutions have been brought forth to deal with this situation:

  1. The CVS solution: --help displays a short screen giving pointers to other help screens (--help-options, --help-command, -H command, etc.).
  2. Some programs differentiate between -h and --help; -h's output is shorter and --help's is more comprehensive.
  3. The RTFM solution: Refer the user to the man page, info document, README, or online help for more information.
  4. The Perl solution: --help displays part of the man page, while myprog -man displays the entire man page (invoking the pager, too).

Here is my take on the pros and cons of each approach:

The CVS one is a bit annoying because I instinctively type "cvs --help" and get something absolutely useless. (This could be solved with a shell function, though).

-h and --help distinguishing is ok, but you may eventually make --help unusable, too.

The RTFM option: Many users will not bother to read a different source, so you may be losing some of them there. Also, if the man page is bloated, you are back to square one.

The Perl solution is not bad as long as you make sure the relevant parts of the man page are not bloated, and outsource things to different man pages. Website META Language has an interactive application for displaying and accessing its various man pages.

My problem with Freecell Solver is that I want it be portable to Win32 and other non-Unix platforms. If you stick to Unix, you can stay with the Perl approach and simply make sure your man pages are sane (and that you have HTML documentation and, optionally, a PDF file).

In any case, my portable solution is a combination of the CVS and Perl solutions. I am going to have a default CVS-like help screen, which could later be changed to something else, using an environment variable.

Here's what I'm going to write:


fc-solve [flags] [board_file|-]

Reads board from standard input by default or if a "-" is specified.

- If it takes too long to finish, try one of the commandline
  configurations presented in --help-configs.

- If it erroneously reports a board as unsolvable, try "-to 01ABCDE".

- If the solution is too long, try running it with the "-opt" flag or
  with "--method a-star".

- If you want to present the moves only, try "-m" (long notation) or
  "-m -sn" (very compact).

- For a description of all the options, type "--help-all".

- For other problems, type "fc-solve --help-problems".

- To turn --help back into something more useful, read
  "--help-real-help".

Contact Shlomi Fish, shlomif@vipe.technion.ac.il for more information.

This deals with common problems in a graceful way (of course, I'll have to implement the other help screens). If you're asking why I don't configure Freecell Solver so it won't have these problems, you're asking a good question. However, the default configuration works well for most of the boards out there, and I don't want to give the user something more complex that may or may not work better (and is itself a compound configuration).

I will use an environment variable named FREECELL_SOLVER_DEFAULT_HELP (I'm a bit obsessed with maintaining namespace integrity) to specify the default help screen. That way, the user can modify the help screen to something more useful than the summary (which would always be available in --help-summary). I haven't used environment variables before, but I don't think I have a choice now.

I guess I'll have to do something regarding usability before I add support for system threads[1]. That's why I'm planning that the 2.7.x tree will be dedicated entirely to rethinking usability. The factoring of the help screens would be one thing, but I'll also try to have better documentation with more diverse formats than text files (God bless Perl POD and DocBook), and other such changes.

If you think human factors engineering does not apply to commandline programs, think again. Even in the Unix world, where Real Men(tm) and Real Women(tm) use commandline utilities like it was their second nature, you still need to make sure your program behaves in a sensible way. When was the last time you managed to find a forgotten flag in the gcc man page in less than two minutes?

Enough said.

[1] Freecell Solver is thread-safe and can task switch but cannot be thread-enabled. If you are asking why I need to make it thread-enabled when most Freecell users will never need to run it on an SMP machine, my answer is: Just for fun(tm).

RSS Recent comments

10 Aug 2002 03:56 antrik

some thoughts
Generally, I do not consider oversized help screens that bad; at least, you
have everthing in one place... And if you know what you are looking for, using
|grep is just perfect :-)

The CVS version is quite OK for CVS-like programs, which have a couple of major
operation modes, and many switches to each. Once learned that I can access help
for a certain mode simply by using it with --help, it's actually very nice.
(It's not too hard to learn, as many interactive command line programs behave
similar...) The only thing I miss is an overview of available modes in the
default help screen.

However, this version is quite annoying for programs with dozens of different
options, that can be grouped only by topic (like dpkg, but there are worse
examples...): it requires several runs, as I first have to find out which one I
need. Moreover, haveing to type things like --force-help isn't very
convinient...

As for discriminating between -h and --help, I do not happen to know any
program doing this -- which I am glad of, as I do not consider that a very good
idea. People generally expect them to be the same. (At least I do...)

I completely agree that the RTFM version is very annoying: I hate it to have to
go into man, info, or even /usr/doc/foo/whatever just to look up a command line
option...

The perl version (I had that with some program just recently) is plain stupid.
If I want to see the man-page, I can use man foo just as well... That's akin to
the RTFM version, if not worse.

All in all, none of the presented alternatives is optimal. The best version I
know is that of gcc: Normally just show the most important things (your
suggested default screen should do quite well), and listing all options when
--help (of -h) is used together with -v. How about that?

In any case, I am glad to see someone considering such ergonomical issues at
all -- that's sadly a thing quite seldom seen in the free software world...

10 Aug 2002 10:07 leonbrooks

--long-help? --full-help? --war-and-peace?
Fine and good, but before you get too carried away I'd like to see published conventions for getting full or specific kinds of help.

I'd also like to see any help for some GUI programs at all; many of them (KDE tools are notable for this) have neither --help nor a manpage, and in that specific case no handbook either. It would be handy to have KDE/GNOME/etc field --help if the application does not and at least list the KDE/GNOME/whatever options, plus the X options, and who knows what else is possible, maybe filch out a getopts array from the application, if it has one.

10 Aug 2002 12:20 pevans

Good solution
It's about time some serious thought were given to the problem and I like your solution very much.

It provides the quick one-liner you may need for args, but also takes the lost in hand and points to
more help and provides more /real/ information at the same time.

Very nice.

10 Aug 2002 13:22 wildchild

real time examples
I am missing a lot of real-time-examples in the help of a lot of programs. It would be a lot easier to understand and learn how to use a command-line utility if you can just see how it works.

For example:

If I do a tar --help I see a lot of help but not a (few) example(s).

If I would see some pointer how to decompress a file I would be working on-the-spot with the program and I would start learning the advanced options.

Alltough I do know how to use tar now, it would have been easier this way instead of learning it "the hard way". There is the easy way and the middle way ...

10 Aug 2002 13:52 magnusdamm

completion
If some sort of standard was made, then it would make it much easier to add generic option/argument completion to the shell.

10 Aug 2002 16:30 bkorb

Help
The solution one arrives at depends upon the complexity of the initializations required and your philosophy. In MNSHO, the usage text should be constrained to hints about the options so that a user can get reminders. If one needs more help than that, they need to go elsewhere to avoid cluttering the screen for those that only need the hint.

Notwithstanding all of that, there still comes a time when there are too many options to fit easily on a page. To cope with all of this, I wrote a package AutoOpts (autogen.sf.net/autoopt... ) that
* uses a short help form when invalid options are supplied

* provides a long help form when help is specifically requested

* provides for visual separation of options for programs with exceptionally long lists of options.

* the ``--more-help'' option will run the help through a pager automatically.

An extended example of its usage can be seen here:

AutoGen Usage (Autogen.sf.Net/doc/aut... )

Using this package eliminates the need to mess with usage text or parsing options or reading config files and alleviates much of the burden of maintaining a man page.

15 Aug 2002 12:45 pimpity

Re: real time examples

> I am missing a lot of real-time-examples
> in the help of a lot of programs. It
> would be a lot easier to understand and
> learn how to use a command-line utility
> if you can just see how it works.
> For example:
>
> If I do a tar --help I see a lot of help
> but not a (few) example(s).

it is possible of course to dig through the tar man pages for examples, but i do agree. maybe have within your --help or -h some little note that says something like "for some common examples, try 'man -examples'" and have a simple, concise listing of what you often use the program for.

but these are just my $0.02. and i may expect change from that. (:

15 Aug 2002 12:50 pimpity

Re: real time examples

%maybe have within your --help or
> -h some little note that says something
> like "for some common examples, try 'man
> -examples'"

i goofed. i really meant "for some common examples, try 'man <command>-examples"

but my 'html' (i.e., < and >), as so obviously noted below the text Posting mode, was escaped. pfft.

16 Aug 2002 11:26 EvilIdler

Re: some thoughts

> if you know what you are looking for,
> using % |grep is just perfect :-)

grep is your friend, together with sort and uniq :)

> As for discriminating between -h and
> --help, I do not happen to know any
> program doing this -- which I am glad
> of, as I do not consider that a very
> good idea

I do know of many examples, actually. Most GNU
programs will come up with "unknown option,
use --help" if you use -h alone :/
(Try it on gawk or something)

%beginquote%
> I completely agree that the RTFM version
> is very annoying: I hate it to have to
> go into man, info, or even
> /usr/doc/foo/whatever just to look up a
> command line option...

I hate doing that with programs, too - for instance,
MPlayer now has so many options it could do away
entirely with option listing in its --help and just print
some examples of common operations (play vcd/DVD
track #n, chap #n, choose stream numbers etc.).
And tar..urgh. Thank goodness we've got cut and
paste for configure scripts, and some sane defaults
for make dist ;)

%beginquote&
> and listing all options when
> --help (of -h) is used together with -v.
> How about that?

There's an idea I should consider for my own programs..
Not that they are circulated far beyond my computer,
but it's a good idea, anyway :)

17 Aug 2002 01:10 antrik

Re: real time examples

> I am missing a lot of real-time-examples
> in the help of a lot of programs. It
> would be a lot easier to understand and
> learn how to use a command-line utility
> if you can just see how it works.

That's actually the kind of information that does *not* belong into a --help
screen usually. If you do not have an idea how the program is used, man is for
you. The --help screen is good when you generally know the program, and have
forgotten just that little detail...

The real problem is that many programs do not have any examples in the man page
either :-(

22 Aug 2002 11:51 mwoodiupui

Some more solutions
A more radical solution would be re-examining your product to see if it can be usefully decomposed into several simpler pieces, each with its own smaller set of options. This doesn't make sense for every program but it's worth remembering.

Still another approach would be a more-capable help viewer. One of the things I like about OpenVMS is the help librarian, which defines a tree structure for help text and provides a default viewer which can be easily linked into your program and invoked with '/help'. Texinfo is the obvious parallel in Unixland, probably by just forking a suitable 'info' command, but you have to deal with the possibility that 'info' isn't installed on the box in question. On MS Windows, again there is a built-in help application which makes larger, more comprehensive help easily navigable. HTML help might provide a cross-platform solution, but most HTML browsers are too heavy and you never know which one you'll have to call.

30 Aug 2002 00:52 acli

Re: Some more solutions
Inclusion of a help viewer by an OS does not guarantee that people will use it. Some people will just use something else. Like, some (a lot?) Macintosh programs do not use AppleGuide even though it is included. Almost all Macintosh programs do not use Tool Tips, including some programs that are bundled with the MacOS CD (!).

The problem with using info in X is probably because there is no generally-available good X info viewer. Lilypond used to have a very good X info viewer (and it probably still do), but I don't see this viewer used anywhere else.

03 Sep 2002 16:50 LodeRunner

X info viewer

> The problem with using info in X is
> probably because there is no
> generally-available good X info viewer.


Konqueror is a fairly decent Info viewer.
Try typing something like "info:cvs" or
"info:bison". Enjoy.

Screenshot

Project Spotlight

Highlight

A universal source code to formatted text converter.

Screenshot

Project Spotlight

libdvbpsi

A library designed for MPEG TS and DVB PSI tables decoding and generation.