#docerr

A little touch I've started to add to my command-line tools, inspired by docopt, is an "errors" section which is pretty clear to humans, and yet tells you precise API information. For example:

$ cdexec --help Execute a command in the given directory. If no command is given, just check if going into the directory works. Usage: cdexec [--] <directory> [<command> [<argument>]...] cdexec (--help | --version) [<ignored>]... Options: -h --help show this help text -V --version show version information Errors: need directory argument bad option: <option> error writing output: <...> error changing directory: <directory>: <...> error executing command: <command>: <...>

That describes every error this program can have, and those exact words will be the first thing written to standard error as part of the error message when those errors happen (prefixed only by "cdexec: ", since it is a universal convention for command-line programs to prefix their errors with the name they were invoked as).

This doesn't come up nearly as often as "docerr" for me, because most programs can reasonably just exit with success or failure and save all specificity for stderr, but I have a similar little touch for a program to document its exit statuses in help text.

For example, a diff program could use this section in its help text like this:

Exits:

    0 if the input files are the same

    1 if the input files differ

    2 if there was an error

And for ssh it would look like this:

Exits:

    0-255 exit status of the remote command

    255 if there was an error in ssh