On Documentation

Or... “How to make this website obsolete”

Jackson Pauls By Jackson Pauls

What if all Linux documentation were fully tagged semantic HTML?

[Need example – html source, browser rendering, console rendering]

[Why not docbook?]

So, for each command, a tagged synopsis, each option and its definition tagged, all references to other documents tagged… So, for every document, a tagged package and applicable versions, a tagged type or category...

As HTML, all documentation would be accessible in the familiar interface of a browser: great for any new user installing Linux. The tagged data would be machine readable, used to build new tools and enhance existing ones. And documentation authors could use a modern tool-set and never have to learn troff.

It’s a big “what if” - it’s hard to fathom how to get there from where we are today given the quantity of documentation currently written in arcane typesetting languages. But let’s briefly slip into a parallel dimension, where Linux documentation is all semantically tagged HTML, to see what it’s like… here we go: Zooop!

Browser-Based Documentation

We install a Linux distribution, and note that clicking “Help” in the system menu opens the default browser at http://localdocs/ - all the documentation is available from here. Clicking “Help” in any GUI application also opens the browser at the correct URL, e.g. the GIMP opens http://localdocs/gimp.

This documentation can be browsed by category (text editor, browser, game…) or software package (LibreOffice, GIMP...). It has a full index, which can be listed alphabetically, or by type (command, configuration file, tutorial…).

I can be quickly searched, say to find a terminal command by name. It also supports full-text search across the whole documentation.

Importantly, the browser is a familiar interface to new users. Questions like "Does anyone have any tricks and tips for finding information in man pages?" and "How to follow links in linux man pages?" are never asked. Posts like “How to Exit the MAN Command and Quit Man Pages Properly” are never written. Nobody gets stuck trying to find the info tutorial on how to use info. Bookmarking and having a history of recently visited pages work naturally.

The documentation is consistently presented in each distribution: the synopsis is always formatted in the same way, there is an easy to use navigation menu to switch between sections in a page… And it works perfectly with screen readers and other assistive technology.

And it is the full documentation. Not only the content we’d find in man pages and Info documents, but also any associated tutorials, guides, reference sections, all in the same interface, complete with relevant images and diagrams.

How is this implemented? With a local HTTP server, customized to index the semantic tags in the documentation. This uses an index to generate pages like the category listing, and power the search functionality. It adds navigation and search to static HTML documents, and turns references between documents into links. It integrates with the distribution’s package manager to prompt installation of any missing documentation.

Terminal Commands

As expert users, we decide to check whether any documentation is available in the terminal, and are delighted to find a “doc” command which behaves pretty much in the same way as we’d expect “man.”

The “doc” command has additional options:

Shells offers contextual auto-completion for command options and parameters. Entering a portion of a command and then hitting “tab” shows possible completions based on the tagged synopsis and option data in the command’s documentation.

Creating Documentation

Let’s take a tour of some public source repositories, to see how the documentation is created. We see that most projects generate the tagged HTML from reStructuredText, AsciiDoc or markdown. These are familiar tools that many programmers also use in other contexts, whether building websites with AsciiDoc or participating in online discussions with markdown. For Linux documentation, extensions or plugins are used for each language to handle domain-specific elements, like specifying a command’s options.

A specific file format (e.g. docopt) defines options a command can take: this is used to build the option handling in the command binary itself, but also to generate the tagged synopsis for the documentation.

A linter is used on the generated HTML, to point out any issues. Hard requirements include having valid markup and tagged elements for package name, version, and document type. Soft requirements include things like a fully tagged synopsis when the documentation type is “command”. Documentation can still be displayed even when it’s not fully tagged, but things like contextual auto-complete no longer work.

Most packages use a tool to export a versioned rendering of the full documentation on the package’s official website. This serves as a canonical reference which can be linked to and shared. In most cases local documentation contains a link to the online version make sharing links easy.


Zoop back again to our world... Now we can’t help but notice things are not quite as slick. What would it take to transition to a similar system? We’ll cover that in part 2: “How to Transition Linux to a User-Friendly Documentation System”.