www.BrettDaniel.com

Here is a scenario that may sound familiar to Linux users: say you want to do something in a terminal but don't know the appropriate command. A quick web search yields a number of possible solutions, but every one is a long, impenetrable command with several unexplained flags. One should avoid running unknown commands that may do something malicious (e.g. "rm -rf ~"), but it is difficult to search through each command's documentation to find the meaning of all of the flags.

I wrote a small utility program that addresses this problem. The utility, called explain, prints short documentation for a given command string, including the documentation for all flags passed to the command.

For example, say you want to copy a file only when it is newer than the destination file. This superuser.com thread suggests the following commands:

cp --update src dest

rsync -avz /from/where/ /to/dest/

explain shows what both of these commands actually mean:

$ explain cp --update src dest
cp - copy files and directories
    -u, --update
        copy only when the SOURCE file is  newer  than  the  destination
        file or when the destination file is missing

$ explain rsync -avz /from/where/ /to/dest/
rsync - copying tool
    -a, --archive
        This  is equivalent to -rlptgoD. It is a quick way of saying you
        want recursion and want to preserve almost everything  (with  -H
        being  a  notable  omission).   The  only exception to the above
        equivalence is when --files-from is specified, in which case  -r
        is not implied.
    -v, --verbose
        This  option increases the amount of information the daemon logs
        during its startup phase.  After the client connects,  the  dae‐
        mon’s verbosity level will be controlled by the options that the
        client used and the "max verbosity" setting in the module’s con‐
        fig section.
    -z, --compress
        With  this  option, rsync compresses the file data as it is sent
        to the destination machine, which reduces  the  amount  of  data
        being transmitted — something that is useful over a slow connec‐
        tion.

This documentation is simpler than a command's full man page, provides a more focused view of only the flags that one cares about (including their synonyms), and makes it easier to compare different commands. Thus, explain is complementary to existing Unix utilities like man, whatis and apropos.

To get explain, you can download its source code or clone its Mercurial repository. The bundled INSTALL file contains installation instructions.

Update from the comments: internally explain parses the command's man(1) page and searches for sections that look like flag documentation. This is somewhat challenging because the file contains no semantic markup and there is no "standard" format, just ad-hoc suggestions on what it should contain. These two factors are probably part of the reason why a utility like explain doesn’t already exist.

explain currently handles just one command at a time. I hope to improve the utility by explaining more complex commands with sub-commands, pipes, and redirects. I would also like it to explain non-flag arguments such as the source and destination arguments in the examples above. Finally, certain common commands use nonstandard flags that explain could probably handle as special cases. For example, it would be good if explain could show documentation for commands like "java -Xmx1024M" or "chmod +x". If you have any other feature requests or if you find any bugs, please post them on the issues page.

Over the past week, I have used explain at least once per day. I hope others find it useful, too.