Man pages are the most common form of documentation for Linux. However, they first appeared in 1971, designed for a small audience of experts. As a result, while they generally provide an exhaustively thorough summary of their topics, from a modern perspective, they can have several limitations. Their thoroughness can be intimidating for new users, and some contain numerous options, many of which are obscure because they are not frequently combined. Nor do they always cover which multiple commands are combined through pipes or joined by regular expressions and notations unique to a particular programming language. Consequently, recent years have seen attempts to address these limitations. For instance, tldr provides quick references for the most common use cases of commands. More recently, explainshell has appeared, an online resource that parses commands like high school English classes parse sentences. By doing so, it provides a quick reference to complicated commands, as well as a useful learning tool. If you have ever wondered about the commands for installing software without a package system are about, explainshell can be especially useful. It can also be a handy way to check the validity of commands or Bash scripts.

Explainshell was written by Idan Kamara as part of an ongoing effort to make documentation more accessible. It is based on 29,761 man pages from Ubuntu. As the project's GitHub page explains, explainshell uses Python scripts to convert these pages to HTML, then classifies each paragraph as an option or not. Options are then extracted and stored, and matched to the relevant help text. When a query is made, it is parsed into an Abstract Syntax Tree (AST), and explainshell notes likely relevant commands or shell-related nodes such as pipes. The results are rendered using Flask, a lightweight web application for Python, that makes for quick results. Currently, there is no way to enter any additional man pages, although the GitHub page suggests that might be possible in the future, and it is an obvious way for a small project to grow. The GitHub page also includes instructions about how to install a local version of explainshell using Docker (Figure 1), as well as how to parse and save a gzipped man page in raw format (Figure 2).

Figure 1: Instructions for creating a local instance of explainshell.

Figure 2: Instructions for preparing your own man pages.

Entering a Query

Explainshell is not the first tool of its kind. At least one other similar tool exists, called shell.how. However, shell.how gives less thorough results, laid out in a less useful way. The explainshell home page offers a Light or Dark theme and results are color-coded, with separate colors for the basic command and each option, pipe, or regular expression (Figure 3). Long commands, of course, require scrolling, but this is partially compensated for by the colored connecting lines between parts of the query and their explanations. In addition, at the top and bottom of the parsing diagram are navigation tools to toggle the view to show all the explanations, or just the sort, the shell, unique features, or duplicate explanations. The explanations themselves are excerpts from man pages and often aided by the fact that Ubuntu, unlike many distributions, frequently edits its man pages to make them more accessible to new users.

Figure 3: A sample parsing diagram for a command from explainshell.

Given the number of man pages used as a reference, you would expect few gaps in the results. And, in fact, looking at a dozen random examples, drawn from a variety of instructions, that seems to be true for anything native to the Bash shell. Commands unique to other shells may not be successfully parsed, or, for that matter, unusual characters used for a prompt if they are accidentally copied and pasted into the search field. Although Bash scripts are successfully parsed, the most common failures seem to involve code unique to a particular programming language, even Python, the language explainshell is written in. However, that is not surprising, considering that programming languages are not included in Ubuntu's man pages. Apparently, the name "explainshell" accurately reflects the tool's limitations; that is, it only fully covers the Bash shell. However, explainshell itself – if not its source material – appears to be less than a year old, judging from its commits. Possibly, support for programming languages might be added in the future. Meanwhile, the processing of a query ends the first time it finds something it cannot explain.

Parsing Coding Languages

For now, a few coding languages are supported in showthedocs, explainshell's sister app accessible from a link at the top of explainshell's home page (Figure 4). For now, its support is confined to PostgreSQL, MySQL, NGINX, and git config, all of which are relatively simple compared to languages such as Python or Rust, and serve mainly as proofs of concept. Each of these is linked to a detailed introduction, but while parsing examples are available, currently showthedocs lacks explainshell's display filters, which makes it less useful as a learning tool. Whether showthedocs will continue to be developed separately or will eventually be merged with explainshell is uncertain, but as I write it is less developed than explainshell, and therefore less useful.

Figure 4: Showthedocs is a companion site to explainshell, specializing in programming languages, although it is currently less developed.

Looking Ahead

Although more developed than showthedocs, explainshell still has some rough edges. Besides the lack of an easy way to add man pages to its resources, explainshell could use some improvements in its interface. To start with, the display filters are easy to miss, and without them, the parsing diagrams can be almost as overwhelming as the man pages themselves – which defeats their purpose. Similarly, the search field needs a Clear button. At the moment, the only ways to clear the search field are to return to the previous page, either by using the Browser's navigation arrows or by clicking on the title bar.

Still, the foundations for a useful tool are in place. Explainshell's development team is to be congratulated for finding a way to make the almost archaic man page useful to modern users. I would not be surprised if some distribution aimed at new users eventually includes a local version in its installation.