<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (c) 2010 Stijn van Dongen -->
<head>
<meta name="keywords" content="manual">
<style type="text/css">
/* START aephea.base.css */
body
{ text-align: justify;
margin-left: 0%;
margin-right: 0%;
}
a:link { text-decoration: none; }
a:active { text-decoration: none; }
a:visited { text-decoration: none; }
a:link { color: #1111aa; }
a:active { color: #1111aa; }
a:visited { color: #111166; }
a.local:link { color: #11aa11; }
a.local:active { color: #11aa11; }
a.local:visited { color: #116611; }
a.intern:link { color: #1111aa; }
a.intern:active { color: #1111aa; }
a.intern:visited { color: #111166; }
a.extern:link { color: #aa1111; }
a.extern:active { color: #aa1111; }
a.extern:visited { color: #661111; }
a.quiet:link { color: black; }
a.quiet:active { color: black; }
a.quiet:visited { color: black; }
div.verbatim
{ font-family: monospace;
margin-top: 1em;
margin-bottom: 1em;
font-size: 10pt;
margin-left: 2em;
white-space: pre;
}
div.indent
{ margin-left: 8%;
margin-right: 0%;
}
.right { text-align: right; }
.left { text-align: left; }
.nowrap { white-space: nowrap; }
.item_leader
{ position: relative;
margin-left: 8%;
}
.item_compact { position: absolute; vertical-align: baseline; }
.item_cascade { position: relative; }
.item_leftalign { text-align: left; }
.item_rightalign
{ width: 2em;
text-align: right;
}
.item_compact .item_rightalign
{ position: absolute;
width: 52em;
right: -2em;
text-align: right;
}
.item_text
{ position: relative;
margin-left: 3em;
}
.smallcaps { font-size: smaller; text-transform: uppercase }
/* END aephea.base.css */
body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; }
body
{ text-align: justify;
margin-left: 8%;
margin-right: 8%;
}
</style>
<title>Portable Unix Documenation</title>
</head>
<body>
<p style="text-align:right">
8 Jan 2010
<a class="local" href="pud.ps"><b>pud</b></a>
1.002, 10-008
</p>
<a name="name"></a>
<h2>NAME</h2>
<p style="margin-bottom:0" class="asd_par">
<acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> — Portable Unix Documentation for manual pages and <abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr> documents</p>
<a name="description"></a>
<h2>DESCRIPTION</h2>
<p style="margin-bottom:0" class="asd_par">
Portable Unix Documentation or <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> currently provides two
mini-languages for authoring in the <span class="smallcaps">UNIX</span> environment.
The two mini-languages are for writing <span class="smallcaps">UNIX</span> manual pages and <abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr> documents.
Source documents in <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> languages can be compiled to either
cross-linked html or to troff. The troff output can be further compiled
into PostScript, <abbr class="ucase" title="Portable Document Format">PDF</abbr>, and plain text.</p>
<a name="toc"></a>
<h2>Table of Contents</h2>
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">1.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#name">NAME</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">2.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#description">DESCRIPTION</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">3.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#toc">Table of Contents</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">4.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#zoem">Portable Unix Documentation extends Aephea and zoem</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">5.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#started">Getting started</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">6.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#man"><span class="smallcaps">UNIX</span> manual pages in <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>, troff and PostScript</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">7.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#faq"><abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr> documents in html, troff and PostScript</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">8.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#elsewhere">Manuals and <abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr> examples elsewhere</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">9.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#dch">DocBook considered harmful</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">10.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#info">Info evil</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">11.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#author">AUTHOR</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">12.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#seealso">SEE ALSO</a>
</div>
</div>
<a name="zoem"></a>
<h2>Portable Unix Documentation extends Aephea and zoem</h2>
<p style="margin-bottom:0" class="asd_par">
Portable Unix Documentation (<acronym class="ucase" title="Portable Unix Documentation">PUD</acronym>) is part of the <a target="_parent" class="extern" href="http://micans.org/aephea">Aephea
documentation framework</a>. Aephea is built on top of
<a target="_parent" class="extern" href="http://micans.org/zoem">zoem</a>, an all-purpose
macro/programming language. Both Aephea and
<acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> documents are processed by compiling
them with the zoem processor.
The documents themselves are generally well-structured, relatively free
of formatting statements and compact to write.
They can be easily extended since the full zoem language is available
from within a <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> document.
</p>
<p style="margin-bottom:0" class="asd_par">
Portable Unix Documentation is currently shipped with <a target="_parent" class="extern" href="http://micans.org/aephea">Aephea</a>.
You will also need to install <a target="_parent" class="extern" href="http://micans.org/zoem">zoem</a>.
</p>
<a name="started"></a>
<h2>Getting started</h2>
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_rightalign " style="right:-4em">i</div></div>
<div class=" item_text " style="margin-left:5em">
<p style="margin-top:0em; margin-bottom:0em">
Get and install both
<a target="_parent" class="extern" href="http://micans.org/aephea">Aephea</a>
and
<a target="_parent" class="extern" href="http://micans.org/zoem">zoem</a>. Follow the instructions
in the Aephea <span class="smallcaps">README</span> file, which boil down to this recipe:</p>
<div class="verbatim">Aephea:
./configure --prefix=$AEPHEAPREFIX
make
make install
Zoem:
./configure --with-includepath=$AEPHEAPREFIX/share/aephea --prefix=$OTHERPREFIX
make
make install</div>
<p style="margin-top:0em; margin-bottom:0em">
All <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> files will be installed as you install Aephea. If you are reading this
locally on your system, chances are zoem and Aephea are installed.</p>
</div>
<div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_rightalign " style="right:-4em">ii</div></div>
<div class=" item_text " style="margin-left:5em">
<p style="margin-top:0em; margin-bottom:0em">
On this page read the pointers in section
<a class="intern" href="#man">Section 6</a> if you want to write a manual page.
Read the pointers in section <a class="intern" href="#faq">Section 7</a> if you
want to write an <abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr>. The fastest way to get up to speed is to copy and
modify a template or existing source document.</p>
</div>
<div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_rightalign " style="right:-4em">iii</div></div>
<div class=" item_text " style="margin-left:5em">
<p style="margin-top:0em; margin-bottom:0em">
While writing your document, consult
the <a class="local sibling" href="pud-man.html">pud-man</a> documentation,
the <a class="local sibling" href="pud-faq.html">pud-faq</a> documentation,
and the <a class="local sibling" href="aephea-base.html">aephea-base</a> documentation as necessary.</p>
</div>
<div style="margin-top:0em"> </div><div class=" item_compact"><div class=" item_rightalign " style="right:-4em">iv</div></div>
<div class=" item_text " style="margin-left:5em">
<p style="margin-top:0em; margin-bottom:0em">
Off you go. If you need macro
facilities or programming facilities, zoem is there to assist you.
Simple macro tasks are easy to accomplish. For more involved stuff you
might want to consult the Zoem User Manual (or <abbr class="ucase" title="Zoem User's Manual">ZUM</abbr>).
<abbr class="ucase" title="Zoem User's Manual">ZUM</abbr> should be installed
<a class="local" href="../doc/zum.html">locally</a>.
Alternatively view the latest <abbr class="ucase" title="Zoem User's Manual">ZUM</abbr>
<a target="_parent" class="extern" href="http://micans.org/zoem/doc/zum.html">at micans</a>
or subscribe to the mailing list
(<a class="extern" href="http://micans.org/zoem/index.html#list">http://micans.org/zoem/index.html#list</a>).</p>
</div>
</div>
<a name="man"></a>
<h2><span class="smallcaps">UNIX</span> manual pages in <abbr class="ucase" title="Hyper Text Markup Language">HTML</abbr>, troff and PostScript</h2>
<p style="margin-bottom:0" class="asd_par">
With the <a class="local sibling" href="pud-man.html">pud-man</a>
package you create manual pages for output in either
<i>troff</i> (groff, nroff) or html. The first can be viewed from a
terminal, the second in a browser.</p>
<p style="margin-bottom:0" class="asd_par">
The fictitious <i>buzzz</i> utility is described in a <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> manual
page. It is shipped with every zoem distribution and the
<a class="local" href="buzzz.html">buzzz manual page</a>
should be installed <a class="local" href="buzzz.html">locally</a>
in the same location as <a class="local" href="buzzz.azm">its source</a>.
If the location is hard to find you can just obtain the
<acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> source from the zoem source distribution, or alternatively
you may view the latest
<a target="_parent" class="extern" href="http://micans.org/zoem/mac/buzzz.azm">buzzz source</a>
upstream at micans.
Further local links are to the
<a class="local" href="buzzz.ps">PostScript version</a> and the
<a class="local" href="buzzz.txt">plain text format</a>.</p>
<p style="margin-bottom:0" class="asd_par">
For other examples consider the oldest <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> manual page ever written: the
<a target="_parent" class="extern" href="http://micans.org/mcl/man/mcl.html"><abbr class="ucase" title="Markov CLuster">MCL</abbr> manual page</a>,
the same in
<a target="_parent" class="extern" href="http://micans.org/mcl/man/mcl.ps">PostScript output</a>,
and the
<a target="_parent" class="extern" href="http://micans.org/mcl/man/mcl.azm">source for all this</a>.
By using the venerable <i>col</i> program, the troff output
can be converted to nice looking
<a target="_parent" class="extern" href="http://micans.org/mcl/man/mcl.txt">plain text format</a>.
Find the
<a target="_parent" class="extern" href="http://micans.org/mcl/man/mcl.1">troff output</a> disclosed as well.</p>
<p style="margin-bottom:0" class="asd_par">
There are some 20+ manual pages for
<a target="_parent" class="extern" href="http://micans.org/mcl/man/">different utilities in the mcl family</a>.</p>
<a name="faq"></a>
<h2><abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr> documents in html, troff and PostScript</h2>
<p style="margin-bottom:0" class="asd_par">
Create <abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr> documents with <a class="local sibling" href="pud-faq.html">pud-faq</a> for output in either <i>troff</i>
(groff, nroff) or html. The former can be viewed in a terminal via the <span class="smallcaps">UNIX</span>
man page system, the latter can be viewed in a browser.</p>
<p style="margin-bottom:0" class="asd_par">
The
<a class="local" href="pud-faq.html"><acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> <abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr> mini-language</a>
is described as a rather trivial <abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr> itself. It can be viewed in
<a class="local" href="pud-faq.ps">PostScript</a>
(compiled from troff compiled from
<a class="local" href="pud-faq.azm">the zoem source</a>
and in
<a class="local" href="pud-faq.txt">plain text</a>
(again compiled from troff).</p>
<p style="margin-bottom:0" class="asd_par">
For examples behold the
<a target="_parent" class="extern" href="http://micans.org/mcl/man/mclfaq.html">browsing delight</a>
that is the mcl <abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr>, and the
<a target="_parent" class="extern" href="http://micans.org/mcl/man/mclfaq.ps">PostScript pleasure</a>.
Find the
<a target="_parent" class="extern" href="http://micans.org/mcl/man/mclfaq.txt">noblest format</a>, the
<a target="_parent" class="extern" href="http://micans.org/mcl/man/mclfaq.7">impregnable troff</a>, and the
<a target="_parent" class="extern" href="http://micans.org/mcl/man/mclfaq.azm">source</a> for all that jazz.</p>
<a name="elsewhere"></a>
<h2>Manuals and <abbr class="ucase" title="Frequently Asked Questions">FAQ</abbr> examples elsewhere</h2>
<p style="margin-bottom:0" class="asd_par">
<b>Other people</b> exist writing <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym>. Not many yet.
Joost van Baal has used the pud-faq package and the pud-man package
to create documentation for
<a target="_parent" class="extern" href="http://mdcc.cx/gnupg/">GnuPG (in Dutch)</a>,
<a target="_parent" class="extern" href="http://mdcc.cx/pub/caspar/caspar-latest/doc/">caspar</a>,
and the
<a target="_parent" class="extern" href="http://mdcc.cx/pub/uruk/uruk-latest/man/">strong (fire)walls of uruk</a>.
The links point to directory listings; the zoem source files have
<tt>.azm</tt> suffixes. The Makefile(.am) files might be of interest as well.</p>
<a name="dch"></a>
<h2>DocBook considered harmful</h2>
<p style="margin-bottom:0" class="asd_par">
People justly wonder why <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> turns away from the blazing light of
goodness that is DocBook. DocBook does provide manual page elements and
it does support gazillions of output devices.
Nevertheless DocBook man pages are a cruelty, a curse
and the bane of all things good and pure.</p>
<p style="margin-bottom:0" class="asd_par">
DocBook cannot be written, it cannot be maintained, it cannot be
programmed. Yes, XML and DocBook are not <i>supposed</i> to be
programmed, but where is the decree that man should toil and suffer so
that his documentation would be transmogrifyable into all eternity?</p>
<p style="margin-bottom:0" class="asd_par">
DocBook provides some sort of manual page ontology, describing
supposedly every element you might ever need. Inevitably you will
want to do things that are not provided and then you are stuck.
DocBook lists and enumerations are painful and limited. The verbosity
of DocBook makes a mountain out of what should be a mole hill.</p>
<p style="margin-bottom:0" class="asd_par">
<acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> manual pages are concise and can be easily cross-referenced. The
source is a pleasure to read and output from self-documenting commands can
be imported. Zoem IO, macro and programming facilities make the
source extendable so that new requirements can be coped with.</p>
<p style="margin-bottom:0" class="asd_par">
Wise people argue that one cannot fathom the needs of future generations and
urge the good people of <span class="smallcaps">UNIX</span> to use DocBook. The fool knows that this
particular premise disproves the thesis and that joy begets joy.
Factor the present into the authoring sustainability equation and the
scales tip.</p>
<p style="margin-bottom:0" class="asd_par">
At this juncture, I am hesitantly willing to bet that the <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> languages
can easily be ported to DocBook. None of the pain, all of the gain.
The <acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> <i>itemize</i> environment is a sticking point though. It
provides, horrors, a few formatting options. Optional paragraphs skips,
compact mode, right-alignment of items, automatic enumeration, and the
fantabulous intermezzo feature.</p>
<a name="info"></a>
<h2>Info evil</h2>
<p style="margin-bottom:0" class="asd_par">
The good people of info consider manual pages obsolete. What
more is there to say? It is all written
<a target="_parent" class="extern" href="http://micans.org/stijn/views/infoinferno.html">here</a>.</p>
<a name="author"></a>
<h2>AUTHOR</h2>
<p style="margin-bottom:0" class="asd_par"><acronym class="ucase" title="Portable Unix Documentation">PUD</acronym> was written by Stijn van Dongen.</p>
<a name="seealso"></a>
<h2>SEE ALSO</h2>
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_leftalign nowrap " ><a class="local sibling" href="pud-man.html">pud-man</a></div></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em"> </p>
</div>
<div class=" item_compact"><div class=" item_leftalign nowrap " ><a class="local sibling" href="pud-faq.html">pud-faq</a></div></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em"> </p>
</div>
<div class=" item_compact"><div class=" item_leftalign nowrap " ><a class="local sibling" href="aephea-base.html">aephea-base</a></div></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em"> </p>
</div>
<div class=" item_compact"><div class=" item_leftalign nowrap " ><a class="local sibling" href="aephea-ref.html">aephea-ref</a></div></div>
<div class=" item_text " style="margin-left:2em">
<p style="margin-top:0em; margin-bottom:0em"> </p>
</div>
</div>
</body>
</html>
