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.

[...]