The zoem man macro package

21 Jun 2004 man_zmm 1.001, 04-173

1. |  | NAME
2. |  | DESCRIPTION
3. |  | MACROS
4. |  | SEE ALSO

## NAME

man_zmm - A description of the zoem man macro package.

## DESCRIPTION

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 roff -o foo.1

Assuming, of course, that foo belongs in section 1 of the manual pages. 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 imply a bug in the zoem man macros.

The zoem man macros are described below. The zoem man macro package automatically imports a set of generic macros from the generic_zmm package. The generic_zmm manual page documents those macros, which are also essential for writing manual pages. These 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 pair of `\publanch` and `\publref`.
iii) |  | The font style/appearance macros `\bf#1`, `\it#1`, `\tt#1`, `\v#1`, the font size macros `\ftinc#2` and `\ftdec#2`.
iv) |  | The paragraph mark `\par` (required for each paragraph).
v) |  | The verbatim macros `\verbatim#1` and `\verbatix#1`.
vi) |  | The link macros `\httpref#1`, `\sibref#2`, `\iref#2`, `\lref#2`, `\aref#2`.

and several others. For the authorative listing consult the generic_zmm 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

`\"man::author"`
`\"man::day"`
`\"man::html-title"`
`\"man::month"`
`\"man::name"`
`\"man::section"`
`\"man::cat"`
`\"man::tag"`
`\"man::year"`
|  | These have to be set to appropriate values before the macro `\"man::preamble"` is used. See the example page buzzz.azm. The `\"man::cat"` macro can be used to set the centered heading found in all UNIX roff manual pages. If not set, a heading is derived from the `\"man::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
`\"man::preamble"`
`\"man::postamble"`
|  | Before any text or macro resulting in output occurs, the macro `\"man::preamble"` has to be used. This macro may certainly be preceded by `\def#2` uses and variants thereof. See the macros listed in the previous entry and the example page buzzz.azm. The last textual item in a manual page must be the macro `\"man::postamble"`. See the example page buzzz.azm.
`\sec#2`
`\secref#1`
|  | Start a section, refer to a section. The first argument of `\sec#2` is the anchor for that section, the second argument is the title. The macro `\secref#1` 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.
    \sec{name}{NAME}
    \NAME{zoem}{interpreter for the Zoem macro/programming language.}
Usage of the NAME macro ensures that the zoem troff output complies with the format expected by apropos.
`\defopt#2`
`\defopt#3`
`\defkvp#3`
|  | Write entry in the options section. typical usage is within an `\item#1` 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 `\"man::defstyle"` is set to `long`. The macro `\defopt#3` is used for options taking arguments; the second argument is the name describing the argument. The macro `\defkvp#3` is used for long options of the form `--mode=str`, which you would enter as `\defkvp{mode}{str}{set foo mode}`. Long options of the form `--verbose` are simply entered using `\defopt#2`.
`\optref#2`
|  | 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.
`\synoptopt#2`
`\synoptopt#3`
`\synreqopt#2`
`\synreqopt#3`
|  | Write entries in the synopsis section. This assumes that somewhere an option was created using one of the `defopt` 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 `defopt` macros. The last argument is always a short string describing the option. It depends on the style chosen, i.e. whether `\"man::synstyle"` is `long` or `short`, 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:
    \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"`
|  | Before importing the manual macros, set these to your prefered style. Each of these should be set either to `short` or `long`.
`\genopt#1`
`\genopt#2`
`\genarg#1`
`\useopt#1`
`\useopt#2`
`\usearg#1`
`\genkvp#2`
`\usekvp#2`
|  | 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 a macro and possibly its argument. The 'use' macros are used when explicit usage is mentioned. An example is the following: 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 --milage=str to set the milage, e.g. --milage=high or --milage=astronomical.

## SEE ALSO

* |  | The generic_zmm manual page, documenting base authoring facilities ported to both html and troff.
* |  | The example source buzzz.azm.
* |  | The example html output buzzz.html.
* |  | The example PS output buzzz.ps.
* |  | The Zoem User Manual. Comprehensive overview of the Zoem language and how it is interpreted.
* |  | The zoem manual page. This describes the options available for the zoem interpreter.