\def{"man::synstyle"}{long}
\def{"man::defstyle"}{long}

\import{man.zmm}
\import{zoem.zmm}

\set{"man::name"}{man_zmm}
\set{"man::html-title"}{The zoem man macro package}
\set{"man::author"}{Stijn van Dongen}
\set{"man::section"}{7}

\"man::preamble"
\${html}{\"man::maketoc"}


\sec{name}{NAME}
\NAME{man_zmm}{A description of the zoem man macro package.}

\sec{description}{DESCRIPTION}

\par
   Write your own manual pages by copying the example page
   \lref{../doc/buzzz.azm}{buzzz.azm}
   and modifying it to your needs. If you are documenting \it{foo},
   the usual approach is to create \it{foo.azm}, and from that
   create \it{foo.1} and \it{foo.html} as follows:

\verbatim{\
   zoem -i foo -d html
   zoem -i foo -d roff -o foo.1}

\car
   Assuming, of course, that \it{foo} belongs in section 1 of the
   manual pages. PostScript and text versions
   can be made from \v{foo.1} as follows:

\verbatim{\
   groff -man foo.1 > foo.ps
   groff -t -e -mandoc -Tascii foo.1 | col -bx > foo.txt}

\par
   Note though that \v{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.

\par
   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 \sibref{generic_zmm}{generic_zmm} manual page documents those macros,
   which are also essential for writing manual pages. These are

\begin{itemize}{
   {compact}{1}
   {mark}{\*{bullet}}
   {type}{roman}
   {rp}{)}
   {align}{right}
}
\item
   The \it{itemize} environment
   (used as \v{\\begin{itemize[options]} ... \\end{itemize}})
   and its associated macros
   \v{\\item#1}, \v{\\items#1}, \v{\\item}
   \v{\\itemskip}, \v{\\intermezzo}, and others.

\item
   The pair of \v{\\publanch} and \v{\\publref}.

\item
   The font style/appearance macros \v{\\bf#1}, \v{\\it#1}, \v{\\tt#1},
   \v{\\v#1},
   the font size macros \v{\\ftinc#2} and \v{\\ftdec#2}.

\item
   The paragraph mark \v{\\par} (required for each paragraph).

\item
   The verbatim macros \v{\\verbatim#1} and \v{\\verbatix#1}.

\item
   The link macros \v{\\httpref#1}, \v{\\sibref#2}, \v{\\iref#2},
   \v{\\lref#2}, \v{\\aref#2}.

\end{itemize}

\par
and several others.  For the authorative listing consult the
\sibref{generic_zmm}{generic_zmm} manual page.  The listing above includes a
silly demonstration of some itemize features such as alignment and automatic
numbering.
Read the \sibref{../doc/zum}{Zoem User Manual} for a better understanding
of zoem macro packages and the design of zoem.

\sec{macros}{MACROS}

\begin{itemize}

\items{
   {\defmac{"man::author"}}
   {\defmac{"man::day"}}
   {\defmac{"man::html-title"}}
   {\defmac{"man::month"}}
   {\defmac{"man::name"}}
   {\defmac{"man::section"}}
   {\defmac{"man::cat"}}
   {\defmac{"man::tag"}}
   {\defmac{"man::year"}}
}
   These have to be set to appropriate values before the
   macro \v{\\"man::preamble"} is used.
   See the example page \lref{../doc/buzzz.azm}{buzzz.azm}.

\par
   The \v{\\"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 \v{\\"man::section"} macro.
   Below is the listing of default headers. It can probably be improved.

\verbatim{\:/
      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}

\items{
   {\defmac{"man::preamble"}}
   {\defmac{"man::postamble"}}
}
   Before any text or macro resulting in output occurs, the
   macro \v{\\"man::preamble"} has to be used.
   This macro may certainly be preceded by \v{\\def#2} uses
   and variants thereof. See the macros listed in the
   previous entry and the example page \lref{../doc/buzzz.azm}{buzzz.azm}.

\par
   The last textual item in a manual page must be the macro
   \v{\\"man::postamble"}.
   See the example page \lref{../doc/buzzz.azm}{buzzz.azm}.

\items{
   {\defmac{sec#2}}
   {\defmac{secref#1}}
}
   Start a section, refer to a section.  The first argument of \v{\\sec#2} is
   the anchor for that section, the second argument is the title.  The macro
   \v{\\secref#1} takes an anchor and outputs the title of the associated
   section.

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

\verbatim{\protect{
\sec{name}{NAME}
\NAME{zoem}{interpreter for the Zoem macro/programming language.}}}

\car
   Usage of the NAME macro ensures that the zoem troff output
   complies with the format expected by \bf{apropos}.

\items{
   {\defmac{defopt#2}}
   {\defmac{defopt#3}}
   {\defmac{defkvp#3}}
}
   Write entry in the options section.  typical usage is within an \v{\\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 \v{\\"man::defstyle"} is set to \v{long}.  The
   macro \v{\\defopt#3} is used for options taking arguments; the second
   argument is the name describing the argument.
   The macro \v{\\defkvp#3} is used for long options of the form
   \v{--mode=str}, which you would enter as
   \v{\\defkvp{mode}{str}{set foo mode}}. Long options of the form
   \v{--verbose} are simply entered using \v{\\defopt#2}.

\item{\defmac{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.

\items{
   {\defmac{synoptopt#2}}
   {\defmac{synoptopt#3}}
   {\defmac{synreqopt#2}}
   {\defmac{synreqopt#3}}
}
   Write entries in the synopsis section. This assumes that somewhere
   an option was created using one of the \v{defopt} family members
   described below.

   \par
   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
   \v{defopt} macros.  The last argument is always a short string describing
   the option. It depends on the style chosen, i.e. whether
   \v{\\"man::synstyle"} is \v{long} or \v{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.

   \par
   Here is an example from the zoem manual page:

\verbatim{\
\\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}}

\items{
   {\defmac{"man::synstyle"}}
   {\defmac{"man::defstyle"}}
}
   Before importing the manual macros, set these to your prefered
   style. Each of these should be set either to \v{short} or \v{long}.

\items{
   {\defmac{genopt#1}}
   {\defmac{genopt#2}}
   {\defmac{genarg#1}}
   {\defmac{useopt#1}}
   {\defmac{useopt#2}}
   {\defmac{usearg#1}}
   {\defmac{genkvp#2}}
   {\defmac{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.

   \par
   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:
   
\begin{spacing}{
   {left}{3}
}
\par
   Modes can be chosen using \genopt{-mode}{str} where \genarg{str} is any of
   \usearg{small}, \usearg{medium}, or \usearg{large}. Use
   \useopt{-mode}{small} if your hardware is outdated.

\par
   Use \genkvp{--milage}{str} to set the milage, e.g. \usekvp{--milage}{high}
   or \usekvp{--milage}{astronomical}.
\end{spacing}

\end{itemize}

\sec{seealso}{SEE ALSO}

\begin{itemize}{
   {compact}{1}
   {margintop}{0}
   {align}{right}
}

\item
   The \sibref{generic_zmm}{generic_zmm} manual page, documenting
   base authoring facilities ported to both html and troff.

\item
   The example source \lref{../doc/buzzz.azm}{buzzz.azm}.

\item
   The example html output \lref{../doc/buzzz.html}{buzzz.html}.

\item
   The example PS output \lref{../doc/buzzz.ps}{buzzz.ps}.

\item
   The \sibref{../doc/zum}{Zoem User Manual.} Comprehensive overview
   of the Zoem language and how it is interpreted.

\item
   The \sibref{../doc/zoem}{zoem manual page.} This describes
   the options available for the zoem interpreter.

\end{itemize}

\"man::postamble"

