table of contents
pud-man(7) | MISCELLANEOUS | pud-man(7) |
NAME¶
pud-man - A description of the Portable Unix Documentation Language for writing manual pages
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 buzzz.azm and modifying it to your needs. If you are documenting foo, the usual approach is to create foo.azm, and from that create foo.1 and foo.html as follows:
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
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 foo.1 as follows:
groff -man foo.1 > foo.ps groff -t -e -mandoc -Tascii foo.1 | col -bx > foo.txt
Note though that foo.1 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 buzzz.azm. The current manual page documents the facilities and macros made available by the PUD manual language by importing the file man.zmm. The structure of a manual page thus typically looks like this:
\import{man.zmm} \begin{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} } \${html}{\"pud::man::maketoc"} \sec{name}{NAME} \NAME{pud-man}{A description of the Portable Unix Documentation Language for writing manual pages} \sec{description}{DESCRIPTION} \par{ ..... .....} \sec{some}{SECTION} \par{ ..... .....} \end{pud::man}
The PUD manual page macro package automatically imports a set of generic macros from the aephea-base and aephea-ref packages. The aephea-base(7) and aephea-ref(7) manual pages document those macros, which are also essential for writing manual pages. The most important are
i) The itemize environment (used as \begin{itemize}[{options}] ... \end{itemize}) and its associated macros \item#1, \items#1, \item \itemskip, \intermezzo, and others.
ii) The font style/appearance macros \bf#1, \it#1, \tt#1, \v#1, the font size macros \ftinc#2 and \ftdec#2.
iii) The paragraph mark \par#1 (required for each paragraph).
iv) The verbatim macros \verbatim#1 and \verbatix#1.
v) The link macros \httpref#1, \sibref#2, \iref#2, \lref#2, \aref#2.
vi) In aephea-ref(7) the pair of \reference#2 and \refer#1.
For the authorative listing consult the aephea-base manual page. The listing above includes a silly demonstration of some itemize features such as alignment and automatic numbering. Read the Zoem User Manual for a better understanding of zoem macro packages and the design of zoem.
MACROS¶
The \$man key in the pud::man 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 \$section macro. Below is the listing of default headers. It can probably be improved.
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
The last textual item in a manual page must be the macro \end{pud::man}. See the example page buzzz.azm.
\sec#2
\secref#1
\sec{name}{NAME} \NAME{zoem}{interpreter for the Zoem macro/programming language.}
Usage of the NAME macro ensures that the troff output complies with the format expected by apropos.
\defopt#2
\defopt#3
\defkvp#3
\optref#2
\synoptopt#2
\synoptopt#3
\synreqopt#2
\synreqopt#3
\synoptopt{--trace}{trace mode, default} \synoptopt{--trace-all-long}{long trace mode} \synoptopt{--trace-all-short}{short trace mode} \synoptopt{--trace-regex}{trace regexes} \synoptopt{--show-tracebits}{show trace bits} \synoptopt{-trace}{k}{trace mode, explicit} \synoptopt{--stats}{show symbol table stats after run}
\"man::synstyle"
\"man::defstyle"
\genopt#1
\genopt#2
\genarg#1
\useopt#1
\useopt#2
\usearg#1
\genkvp#2
\usekvp#2
Modes can be chosen using -mode str where str is any of small, medium, or large. Use -mode small if your hardware is outdated. Use --mileage=str to set the mileage, e.g. --mileage=high or --mileage=astronomical.
SEE ALSO¶
The pud manual page gives an overview of PUD.
8 Jan 2010 | pud-man 1.002, 10-008 |