Unixdoc - an Integrated Offline and Online Documentation Framework

Introduction

The traditional Unix help command is the ubiquitous man command, which displays a page using a pager (such as GNU less), and lets you read it forward and backward and search for patterns there. Obviously this solution is inadequate, and several better solutions evolved. The purpose of Unixdoc (a pun on the Perl Perldoc command) is to create one fully-featured and integrated system for offline and online technical documentation.

How Unixdoc Works

The following figure shows the Unixdoc workflow:

Essentially it receives inputs in most popular formats:

1. Man page (formatted using nroff macros)
2. perl POD
3. The WikiWiki formats of MediaWiki and other popular wikis.
4. HTML and XHTML.
5. Etc.

And displays them using several popular media: a terminal display, a web browser, a graphical user interface, etc.

That’s not all. Other functions that Unixdoc will provide are:

1. Hyperlinking.
2. Applying visual and logical style to the document.
3. Annotating using keywords.
4. Searching using keywords, phrases, words in the internal hyperlinks that point to the document (a la Google’s PageRank algorith ).
5. Including and embedding rich media such as images, videos, sounds, mathematical equations and line drawings.

Eric Raymond talks about “the present chaos (of Unix documentation) and a Possible Way Out” in his book The Art of Unix Programming. He gives DocBook/XML as the possible solution, and this may actually be a good final format for Unixdoc.