.\" Copyright (c) 2010 Stijn van Dongen
.TH "pud-man" 7 "8 Jan 2010" "pud-man 1\&.002, 10-008" "MISCELLANEOUS "
.po 2m
.de ZI
.\" Zoem Indent/Itemize macro I.
.br
'in +\\$1
.nr xa 0
.nr xa -\\$1
.nr xb \\$1
.nr xb -\\w'\\$2'
\h'|\\n(xau'\\$2\h'\\n(xbu'\\
..
.de ZJ
.br
.\" Zoem Indent/Itemize macro II.
'in +\\$1
'in +\\$2
.nr xa 0
.nr xa -\\$2
.nr xa -\\w'\\$3'
.nr xb \\$2
\h'|\\n(xau'\\$3\h'\\n(xbu'\\
..
.if n .ll -2m
.am SH
.ie n .in 4m
.el .in 8m
..
.SH NAME
pud-man \- A description of the Portable Unix Documentation Language for writing manual pages
.SH DESCRIPTION

This document describes the Portable Unix Documentation (PUD) manual
page mini-language\&. PUD-man is built on top of the macro interpreter
zoem\&. A PUD document is generally well-structured, relatively free of
formatting statements, compact to write and easily extendable\&. It can
be converted to both troff and html, for viewing in terminals and
browsers\&. High quality Postscript and plain text formats can be derived
from the troff output\&.

Write your own manual pages by copying the example page
\fIbuzzz\&.azm\fP
and modifying it to your needs\&. If you are documenting \fIfoo\fP,
the usual approach is to create \fIfoo\&.azm\fP, and from that
create \fIfoo\&.1\fP and \fIfoo\&.html\fP as follows:

.di ZV
.in 0
.nf \fC
   zoem -i foo -d html
   zoem -i foo -d html
   zoem -i foo -d roff -o foo\&.1
   zoem -i foo -d roff -o foo\&.1
.fi \fR
.in
.di
.ne \n(dnu
.nf \fC
.ZV
.fi \fR

This generates files foo\&.html and foo\&.1\&.
Each device is run twice to be certain that references
are found and linked\&. PostScript and text versions
can be made from \fCfoo\&.1\fP as follows:

.di ZV
.in 0
.nf \fC
   groff -man foo\&.1 > foo\&.ps
   groff -t -e -mandoc -Tascii foo\&.1 | col -bx > foo\&.txt
.fi \fR
.in
.di
.ne \n(dnu
.nf \fC
.ZV
.fi \fR

Note though that \fCfoo\&.1\fP does not use any groff specific
extensions; it should be acceptable input to ancient roffs as well\&.
Exceptions to this imply a bug in the PUD man macros\&.

You are advised to start by inspecting a template manual
page such as \fIbuzzz\&.azm\fP\&. The current manual
page documents the facilities and macros made available
by the PUD manual language by importing the file \fCman\&.zmm\fP\&.
The structure of a manual page thus typically looks like this:

.di ZV
.in 0
.nf \fC
\eimport{man\&.zmm}

   \ebegin{pud::man}{

      {name}{pud-man}
      {html_title}{The PUD manual page mini-language}
      {author}{Stijn van Dongen}
      {section}{7}
      {year}{2009}
      {month}{Jan}
      {day}{15}
      {tag}{1\&.002}
      {stamp}{09-015}
      {defstyle}{long}
      {synstyle}{long}

   }

   \e${html}{\e"pud::man::maketoc"}

   \esec{name}{NAME}
   \eNAME{pud-man}{A description of the Portable Unix Documentation Language for writing manual pages}

   \esec{description}{DESCRIPTION}
   \epar{ \&.\&.\&.\&.\&.  \&.\&.\&.\&.\&.}

   \esec{some}{SECTION}
   \epar{ \&.\&.\&.\&.\&.  \&.\&.\&.\&.\&.}
    
   \eend{pud::man}
.fi \fR
.in
.di
.ne \n(dnu
.nf \fC
.ZV
.fi \fR

The PUD manual page macro package automatically imports a set of generic
macros from the \fCaephea-base\fP and \fCaephea-ref\fP packages\&. The
\fBaephea-base(7)\fP and \fBaephea-ref(7)\fP manual pages document those
macros, which are also essential for writing manual pages\&. The most
important are

.ZJ 1m 2m "i)"
The \fIitemize\fP environment
(used as \fC\ebegin{itemize}[{options}] \&.\&.\&. \eend{itemize}\fP)
and its associated macros
\fC\eitem#1\fP, \fC\eitems#1\fP, \fC\eitem\fP
\fC\eitemskip\fP, \fC\eintermezzo\fP, and others\&.
.in -3m

.ZJ 1m 2m "ii)"
The font style/appearance macros \fC\ebf#1\fP, \fC\eit#1\fP, \fC\ett#1\fP,
\fC\ev#1\fP, the font size macros \fC\eftinc#2\fP and \fC\eftdec#2\fP\&.
.in -3m

.ZJ 1m 2m "iii)"
The paragraph mark \fC\epar#1\fP (required for each paragraph)\&.
.in -3m

.ZJ 1m 2m "iv)"
The verbatim macros \fC\everbatim#1\fP and \fC\everbatix#1\fP\&.
.in -3m

.ZJ 1m 2m "v)"
The link macros \fC\ehttpref#1\fP, \fC\esibref#2\fP, \fC\eiref#2\fP,
\fC\elref#2\fP, \fC\earef#2\fP\&.
.in -3m

.ZJ 1m 2m "vi)"
In \fBaephea-ref(7)\fP the pair of \fC\ereference#2\fP and \fC\erefer#1\fP\&.
.in -3m

For the authorative listing consult the \fBaephea-base\fP
manual page\&. The listing above includes a silly demonstration of some
itemize features such as alignment and automatic numbering\&. Read the
\fBZoem User Manual\fP for a better understanding of
zoem macro packages and the design of zoem\&.
.SH MACROS

The \fC\e$man\fP key in the \fCpud::man\fP environment can be used to set the
centered heading found in all UNIX roff manual pages\&. If not set, a heading
is derived from the \fC\e$section\fP macro\&. Below is the listing of default
headers\&. It can probably be improved\&.

.di ZV
.in 0
.nf \fC
      1     USER COMMANDS
      2     SYSTEM CALLS
      3     LIBRARY CALLS
      4     SPECIAL FILES
      5     FILE FORMATS
      6     GAMES
      7     MACRO PACKAGES
      8     SYSTEM ADMINISTRATION
      9     KERNEL ROUTINES
.fi \fR
.in
.di
.ne \n(dnu
.nf \fC
.ZV
.fi \fR

The last textual item in a manual page must be the macro \fC\eend{pud::man}\fP\&.
See the example page \fIbuzzz\&.azm\fP\&.
.ZI 2m "\fB\esec#2\fP"
\&
'in -2m
.ZI 2m "\fB\esecref#1\fP"
\&
'in -2m
'in +2m
\&
.br
Start a section, refer to a section\&. The first argument of \fC\esec#2\fP is
the anchor for that section, the second argument is the title\&. The macro
\fC\esecref#1\fP takes an anchor and outputs the title of the associated
section\&.

The NAME section should be written like the example below, taken
from the zoem interpreter manual\&.

.di ZV
.in 0
.nf \fC

\esec{name}{NAME}
\eNAME{zoem}{interpreter for the Zoem macro/programming language\&.}
.fi \fR
.in
.di
.ne \n(dnu
.nf \fC
.ZV
.fi \fR

Usage of the NAME macro ensures that the troff output
complies with the format expected by \fBapropos\fP\&.
.in -2m

.ZI 2m "\fB\edefopt#2\fP"
\&
'in -2m
.ZI 2m "\fB\edefopt#3\fP"
\&
'in -2m
.ZI 2m "\fB\edefkvp#3\fP"
\&
'in -2m
'in +2m
\&
.br
Write entry in the options section\&. typical usage is within an \fC\eitem#1\fP
macro\&. For all macros the first argument is the option being described,
and the last argument is a short string describing the option\&. This string
is printed in case the macro \fC\e"man::defstyle"\fP is set to \fClong\fP\&. The
macro \fC\edefopt#3\fP is used for options taking arguments; the second
argument is the name describing the argument\&.
The macro \fC\edefkvp#3\fP is used for long options of the form
\fC--mode=str\fP, which you would enter as
\fC\edefkvp{mode}{str}{set foo mode}\fP\&. Long options of the form
\fC--verbose\fP are simply entered using \fC\edefopt#2\fP\&.
.in -2m

.ZI 2m "\fB\eoptref#2\fP"
\&
.br
Refer to an option\&. The first argument is the option, the second argument
is the text associated with the link\&. This text will indeed be linking
in html, but nothing special will happen in troff - the text is printed
as is\&.
.in -2m

.ZI 2m "\fB\esynoptopt#2\fP"
\&
'in -2m
.ZI 2m "\fB\esynoptopt#3\fP"
\&
'in -2m
.ZI 2m "\fB\esynreqopt#2\fP"
\&
'in -2m
.ZI 2m "\fB\esynreqopt#3\fP"
\&
'in -2m
'in +2m
\&
.br
Write entries in the synopsis section\&. This assumes that somewhere
an option was created using one of the \fCdefopt\fP family members
described below\&.

For all \&'syn\&' options the first argument is simply the option itself\&. From
this argument the anchor is reconstructed that was created by one of the
\fCdefopt\fP macros\&. The last argument is always a short string describing
the option\&. It depends on the style chosen, i\&.e\&. whether
\fC\e"man::synstyle"\fP is \fClong\fP or \fCshort\fP, whether this string shows up
or not\&. The macros in this group that take two arguments describe unary
options that take no argument\&. The macros taking three arguments describe
options that do take an argument\&.

Here is an example from the zoem manual page:

.di ZV
.in 0
.nf \fC
\esynoptopt{--trace}{trace mode, default}
\esynoptopt{--trace-all-long}{long trace mode}
\esynoptopt{--trace-all-short}{short trace mode}
\esynoptopt{--trace-regex}{trace regexes}
\esynoptopt{--show-tracebits}{show trace bits}
\esynoptopt{-trace}{k}{trace mode, explicit}
\esynoptopt{--stats}{show symbol table stats after run}
.fi \fR
.in
.di
.ne \n(dnu
.nf \fC
.ZV
.fi \fR

.in -2m

.ZI 2m "\fB\e""man::synstyle""\fP"
\&
'in -2m
.ZI 2m "\fB\e""man::defstyle""\fP"
\&
'in -2m
'in +2m
\&
.br
Before importing the manual macros, set these to your prefered
style\&. Each of these should be set either to \fCshort\fP or \fClong\fP\&.
.in -2m

.ZI 2m "\fB\egenopt#1\fP"
\&
'in -2m
.ZI 2m "\fB\egenopt#2\fP"
\&
'in -2m
.ZI 2m "\fB\egenarg#1\fP"
\&
'in -2m
.ZI 2m "\fB\euseopt#1\fP"
\&
'in -2m
.ZI 2m "\fB\euseopt#2\fP"
\&
'in -2m
.ZI 2m "\fB\eusearg#1\fP"
\&
'in -2m
.ZI 2m "\fB\egenkvp#2\fP"
\&
'in -2m
.ZI 2m "\fB\eusekvp#2\fP"
\&
'in -2m
'in +2m
\&
.br
These are for creating a consistent style when refering to options\&. One is
free to disregard these altogether\&. They are meant as convenience, but some
may find the extra typing annoying\&.

The idea is that the \&'gen\&' macros are used when generic mention is
made of an option and possibly its argument\&.
The \&'use\&' macros are used when explicit usage is mentioned\&.
An example is the following:
.in +2m
.ll -3m

Modes can be chosen using \fB-mode\fP\ \&\fIstr\fP where \fIstr\fP is any of
\fBsmall\fP, \fBmedium\fP, or \fBlarge\fP\&. Use
\fB-mode\fP\ \&\fBsmall\fP if your hardware is outdated\&.

Use \fB--mileage\fP=\fIstr\fP to set the mileage, e\&.g\&. \fB--mileage\fP=\fBhigh\fP
or \fB--mileage\fP=\fBastronomical\fP\&.
.in -2m
.ll +3m
.in -2m
.SH SEE ALSO

The \fBpud\fP manual page gives an overview of PUD\&.