Articles / Time to Rethink Your Help F…

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

Contact Shlomi Fish, 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).

Recent comments

03 Sep 2002 16:50 Avatar 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.

30 Aug 2002 00:52 Avatar 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.

22 Aug 2002 11:51 Avatar 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.

17 Aug 2002 01:10 Avatar 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 :-(

16 Aug 2002 11:26 Avatar 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)

> 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 ;)

> 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 :)


Project Spotlight

Kigo Video Converter Ultimate for Mac

A tool for converting and editing videos.


Project Spotlight


An efficient tagger for MP3, Ogg/Vorbis, and FLAC files.