Explainshell – A New Use for Man Pages
A More Modern Man Page

Photo by Brett Jordan on Unsplash
Explainshell aims to make documentation more accessible.
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).
[...]
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

News
-
openSUSE Tumbleweed Ditches AppArmor for SELinux
If you're an openSUSE Tumbleweed user, you can expect a major change to the distribution.
-
Plasma 6.3 Now Available
Plasma desktop v6.3 has a couple of pretty nifty tricks up its sleeve.
-
LibreOffice 25.2 Has Arrived
If you've been hoping for a release that offers more UI customizations, you're in for a treat.
-
TuxCare Has a Big AlmaLinux 9 Announcement in Store
TuxCare announced it has successfully completed a Security Technical Implementation Guide for AlmaLinux OS 9.
-
First Release Candidate for Linux Kernel 6.14 Now Available
Linus Torvalds has officially released the first release candidate for kernel 6.14 and it includes over 500,000 lines of modified code, making for a small release.
-
System76 Refreshes Meerkat Mini PC
If you're looking for a small form factor PC powered by Linux, System76 has exactly what you need in the Meerkat mini PC.
-
Gnome 48 Alpha Ready for Testing
The latest Gnome desktop alpha is now available with plenty of new features and improvements.
-
Wine 10 Includes Plenty to Excite Users
With its latest release, Wine has the usual crop of bug fixes and improvements, along with some exciting new features.
-
Linux Kernel 6.13 Offers Improvements for AMD/Apple Users
The latest Linux kernel is now available, and it includes plenty of improvements, especially for those who use AMD or Apple-based systems.
-
Gnome 48 Debuts New Audio Player
To date, the audio player found within the Gnome desktop has been meh at best, but with the upcoming release that all changes.