shlomi-fish-homepage / t2 / philosophy / ideas / unixdoc / index.html.wml

#include '../template.wml'
#include "toc_div.wml"

<latemp_subject "Unixdoc - an Integrated Offline and Online Documentation Framework" />

<latemp_meta_desc "Unixdoc - an Integrated Offline and Online Documentation Framework" />

<toc_div />

<h2 id="intro">Introduction</h2>

<p>
The traditional <a href="http://en.wikipedia.org/wiki/Unix">Unix</a> help
command is the ubiquitous
<a href="http://www.primate.wisc.edu/computer/man.html">man command</a>, which
displays a page using a pager (such as
<a href="http://www.gnu.org/software/less/less.html">GNU less</a>), 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 <i>Unixdoc</i> (a pun on the Perl
<a href="http://perldoc.perl.org/perldoc.html">Perldoc command</a>) is to
create one <strong>fully-featured and integrated</strong> system for
<strong>offline and online technical documentation</strong>.
</p>

<h2 id="how_it_works">How Unixdoc Works</h2>

<p>
The following figure shows the Unixdoc workflow:
</p>

<p><img
    src="unixdoc1-32.png"
    alt="Many Format into Unixdoc and many presentations out of it"
    style="margin: 1em;"
    /></p>

<p>
Essentially it receives inputs in most popular formats:
</p>

<ol>
<li>
Man page (formatted using nroff macros)
</li>
<li>
<a href="http://perldoc.perl.org/perlpod.html">perl
POD</a>
</li>
<li>
The WikiWiki formats of <a href="http://www.mediawiki.org/">MediaWiki</a>
and other popular wikis.
</li>
<li>
HTML and XHTML.
</li>
<li>
Etc.
</li>
</ol>

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

<p>
That’s not all. Other functions that Unixdoc will provide are:
</p>

<ol>
<li>
Hyperlinking.
</li>
<li>
Applying visual and logical style to the document.
</li>
<li>
Annotating using keywords.
</li>
<li>
Searching using keywords, phrases, words in the internal hyperlinks that point
to the document (a la <a href="http://en.wikipedia.org/wiki/PageRank">Google’s
PageRank algorithm</a> ).
</li>
<li>
Including and embedding rich media such as images, videos, sounds,
mathematical equations and line drawings.
</li>
</ol>

<p>
Eric Raymond <a href="http://www.faqs.org/docs/artu/ch18s04.html">talks
about “the present chaos (of Unix documentation) and a Possible Way Out”</a>
in his book <a href="http://www.faqs.org/docs/artu/"><i>The Art of Unix
Programming</i></a>. He gives DocBook/XML as the possible solution, and this
may actually be a good final format for Unixdoc.
</p>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.