pud - Portable Unix Documentation for manual pages and faq documents
Portable Unix Documentation or pud currently provides two mini-languages for
authoring in the UNIX environment. The two mini-languages are for writing UNIX
manual pages and faq documents. Source documents in pud languages can be
compiled to either cross-linked html or to troff. The troff output can be
further compiled into PostScript, pdf, and plain text.
1. NAME
2. DESCRIPTION
3. Table of Contents
4. Portable Unix Documentation extends Aephea and zoem
5. Getting started
6. UNIX manual pages in html, troff and PostScript
7. faq documents in html, troff and PostScript
8. Manuals and faq examples elsewhere
9. DocBook considered harmful
10. Info evil
11. AUTHOR
12. SEE ALSO
Portable Unix Documentation (pud) is part of the
Aephea documentation
framework. Aephea is built on top of
zoem (
http://micans.org/zoem),
an all-purpose macro/programming language. Both Aephea and pud 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 pud document.
Portable Unix Documentation is currently shipped with
Aephea. You will
also need to install
zoem.
i Get and install both
Aephea (
http://micans.org/aephea) and
zoem
(
http://micans.org/zoem). Follow the instructions in the Aephea README file,
which boil down to this recipe:
Aephea:
./configure --prefix=$AEPHEAPREFIX
make
make install
Zoem:
./configure --with-includepath=$AEPHEAPREFIX/share/aephea --prefix=$OTHERPREFIX
make
make install
All pud files will be installed as you install Aephea. If you are reading this
locally on your system, chances are zoem and Aephea are installed.
ii On this page read the pointers in section
Section 6 if you want
to write a manual page. Read the pointers in section
Section 7 if
you want to write an faq. The fastest way to get up to speed is to copy and
modify a template or existing source document.
iii While writing your document, consult the
pud-man(7) documentation,
the
pud-faq(7) documentation, and the
aephea-base(7)
documentation as necessary.
iv 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 zum). zum
should be installed locally. Alternatively view the latest zum
at
micans (
http://micans.org/zoem/doc/zum.html) or subscribe to the mailing
list (
http://micans.org/zoem/index.html#list).
With the
pud-man(7) package you create manual pages for output in either
troff (groff, nroff) or html. The first can be viewed from a terminal,
the second in a browser.
The fictitious
buzzz utility is described in a pud manual page. It is
shipped with every zoem distribution and the
buzzz manual page should
be installed
locally in the same location as
its source. If the
location is hard to find you can just obtain the pud source from the zoem
source distribution, or alternatively you may view the latest
buzzz
source (
http://micans.org/zoem/mac/buzzz.azm) upstream at micans. Further
local links are to the
PostScript version and the
plain text
format.
For other examples consider the oldest pud manual page ever written: the
mcl
manual page (
http://micans.org/mcl/man/mcl.html), the same in
PostScript output (
http://micans.org/mcl/man/mcl.ps), and the
source
for all this (
http://micans.org/mcl/man/mcl.azm). By using the venerable
col program, the troff output can be converted to nice looking
plain
text format (
http://micans.org/mcl/man/mcl.txt). Find the
troff
output (
http://micans.org/mcl/man/mcl.1) disclosed as well.
There are some 20+ manual pages for
different utilities in the mcl family
(
http://micans.org/mcl/man/).
Create faq documents with
pud-faq(7) for output in either
troff
(groff, nroff) or html. The former can be viewed in a terminal via the UNIX
man page system, the latter can be viewed in a browser.
The
pud faq mini-language is described as a rather trivial faq itself. It
can be viewed in
PostScript (compiled from troff compiled from
the
zoem source and in
plain text (again compiled from troff).
For examples behold the
browsing delight
(
http://micans.org/mcl/man/mclfaq.html) that is the mcl faq, and the
PostScript pleasure (
http://micans.org/mcl/man/mclfaq.ps). Find the
noblest format (
http://micans.org/mcl/man/mclfaq.txt), the
impregnable troff (
http://micans.org/mcl/man/mclfaq.7), and the
source (
http://micans.org/mcl/man/mclfaq.azm) for all that jazz.
Other people exist writing pud. Not many yet. Joost van Baal has used the
pud-faq package and the pud-man package to create documentation for
GnuPG
(in Dutch) (
http://mdcc.cx/gnupg/), caspar
(
http://mdcc.cx/pub/caspar/caspar-latest/doc/), and the
strong (fire)walls
of uruk (
http://mdcc.cx/pub/uruk/uruk-latest/man/).
People justly wonder why pud 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.
DocBook cannot be written, it cannot be maintained, it cannot be programmed.
Yes, XML and DocBook are not
supposed to be programmed, but where is
the decree that man should toil and suffer so that his documentation would be
transmogrifyable into all eternity?
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.
pud 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.
Wise people argue that one cannot fathom the needs of future generations and
urge the good people of UNIX 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.
At this juncture, I am hesitantly willing to bet that the pud languages can
easily be ported to DocBook. None of the pain, all of the gain. The pud
itemize 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.
The good people of info consider manual pages obsolete. What more is there to
say? It is all written
here
(
http://micans.org/stijn/views/infoinferno.html).
pud was written by Stijn van Dongen.
pud-man(7)
pud-faq(7)
aephea-base(7)
aephea-ref(7)