\import{../pud/man.zmm}
\import{aephea.shared}

\begin{pud::man}{

   {name}{pud}
   {html_title}{Portable Unix Documenation}
   {author}{Stijn van Dongen}
   {section}{7}
   {defstyle}{long}
   {synstyle}{long}

   \man_share
}

\${html}{\def{apudref#2}{\aref{\2}{\1}}}
\${roff}{\def{apudref#2}{\bf{\1} (\httpref{\2})}}

\sec{name}{NAME}
\NAME{\${html}{\pud}{pud}}{Portable Unix Documentation for manual pages and \faq documents}

\sec{description}{DESCRIPTION}
\par{
   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.}


\sec{toc}{Table of Contents}

\"pud::man::maketoc"

\sec{zoem}{Portable Unix Documentation extends Aephea and zoem}

\par{
   Portable Unix Documentation (\pud) is part of the \aref{http://micans.org/aephea}{Aephea
   documentation framework}. Aephea is built on top of
\apudref{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.
   }

\par{
   Portable Unix Documentation is currently shipped with \aref{http://micans.org/aephea}{Aephea}.
   You will also need to install \aref{http://micans.org/zoem}{zoem}.
   }


\sec{started}{Getting started}

\begin{itemize}{
   {flow}{compact}
   {interitem}{1}
   {align}{right}
   {textindent}{5}
   {itemmargin}{4}
   {type}{roman}
}

\item
\car{
   Get and install both
\apudref{Aephea}{http://micans.org/aephea}
and
\apudref{zoem}{http://micans.org/zoem}. Follow the instructions
   in the Aephea \readme file, which boil down to this recipe:}

\verbatim{\:/
Aephea:
   ./configure --prefix=$AEPHEAPREFIX
   make
   make install

Zoem:
   ./configure --with-includepath=$AEPHEAPREFIX/share/aephea --prefix=$OTHERPREFIX
   make
   make install}

\car{
   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.}

\item
\car{
   On this page read the pointers in section
   \iref{man}{Section\~\refnumber{man}} if you want to write a manual page.
   Read the pointers in section \iref{faq}{Section\~\refnumber{faq}} 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.}

\item
\car{
   While writing your document, consult
   the \sibref7{pud-man} documentation,
   the \sibref7{pud-faq} documentation,
   and the \sibref7{aephea-base} documentation as necessary.}

\item
\car{
   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
   \${html}{\lref{../doc/zum.html}{locally}}\${roff}{locally}.
   Alternatively view the latest \zum
\apudref{at micans}{http://micans.org/zoem/doc/zum.html}
   or subscribe to the mailing list
(\httpref{http://micans.org/zoem/index.html#list}).}

\end{itemize}

\sec{man}{\unix manual pages in \html, troff and PostScript}

\par{
   With the \sibref7{pud-man}
   package you create manual pages for output in either
   \it{troff} (groff, nroff) or html.  The first can be viewed from a
   terminal, the second in a browser.}

\par{
   The fictitious \it{buzzz} utility is described in a \pud manual
   page. It is shipped with every zoem distribution and the
   \lref{buzzz.html}{buzzz manual page}
   should be installed \lref{buzzz.html}{locally}
   in the same location as \lref{buzzz.azm}{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
\apudref{buzzz source}{http://micans.org/zoem/mac/buzzz.azm}
   upstream at micans.
   Further local links are to the
\lref{buzzz.ps}{PostScript version} and the
\lref{buzzz.txt}{plain text format}.}


\par{
   For other examples consider the oldest \pud manual page ever written: the
\apudref{\mcl manual page}{http://micans.org/mcl/man/mcl.html},
   the same in
\apudref{PostScript output}{http://micans.org/mcl/man/mcl.ps},
   and the
\apudref{source for all this}{http://micans.org/mcl/man/mcl.azm}.
   By using the venerable \it{col} program, the troff output
   can be converted to nice looking
\apudref{plain text format}{http://micans.org/mcl/man/mcl.txt}.
   Find the
\apudref{troff output}{http://micans.org/mcl/man/mcl.1} disclosed as well.}

\par{
   There are some 20+ manual pages for
\apudref{different utilities in the mcl family}{http://micans.org/mcl/man/}.}


\sec{faq}{\faq documents in html, troff and PostScript}

\par{
   Create \faq documents with \sibref7{pud-faq} for output in either \it{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.}

\par{
   The
\lref{pud-faq.html}{\pud \faq mini-language}
   is described as a rather trivial \faq itself.  It can be viewed in
\lref{pud-faq.ps}{PostScript}
   (compiled from troff compiled from
\lref{pud-faq.azm}{the zoem source}
   and in
\lref{pud-faq.txt}{plain text}
   (again compiled from troff).}

\par{
   For examples behold the
\apudref{browsing delight}{http://micans.org/mcl/man/mclfaq.html}
   that is the mcl \faq, and the
\apudref{PostScript pleasure}{http://micans.org/mcl/man/mclfaq.ps}.
   Find the
\apudref{noblest format}{http://micans.org/mcl/man/mclfaq.txt}, the
\apudref{impregnable troff}{http://micans.org/mcl/man/mclfaq.7}, and the
\apudref{source}{http://micans.org/mcl/man/mclfaq.azm} for all that jazz.}


\sec{elsewhere}{Manuals and \faq examples elsewhere}

\par{
   \bf{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
\apudref{GnuPG (in Dutch)}{http://mdcc.cx/gnupg/},
\apudref{caspar}{http://mdcc.cx/pub/caspar/caspar-latest/doc/},
   and the
\apudref{strong (fire)walls of uruk}{http://mdcc.cx/pub/uruk/uruk-latest/man/}.
\${html}{The links point to directory listings; the zoem source files have
   \v{.azm} suffixes. The Makefile(.am) files might be of interest as well.}}


\sec{dch}{DocBook considered harmful}

\par{
   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.}

\par{
   DocBook cannot be written, it cannot be maintained, it cannot be
   programmed. Yes, XML and DocBook are not \it{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?}

\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.}

\par{
   \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.}

\par{
   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.}

\par{
   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 \it{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.}

\sec{info}{Info evil}

\par{
   The good people of info consider manual pages obsolete. What
   more is there to say? It is all written
\apudref{here}{http://micans.org/stijn/views/infoinferno.html}.}

\sec{author}{AUTHOR}

\par{\pud was written by Stijn van Dongen.}

\sec{seealso}{SEE ALSO}

\begin{itemize}{{flow}{compact}{interitem}{0}}
\item{\sibref7{pud-man}}  \car{\~}
\item{\sibref7{pud-faq}}  \car{\~}
\item{\sibref7{aephea-base}} \car{\~}
\item{\sibref7{aephea-ref}}  \car{\~}
\end{itemize}

\end{pud::man}