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

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

\: (stupid test)

\: customized command for the synopsis section.
\def{fileopt#2}{\bf{\1} (\it{\2})}
\def{z#1}{\bf{\\\1}}

\set{"man::name"}{zoem}
\set{"man::html-title"}{zoem}
\set{"man::author"}{Stijn van Dongen}
\set{"man::section"}{1}

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

\def{zoem}{\bf{zoem}}

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

\sec{synopsis}{SYNOPSIS}

\par
\zoem
   \synoptopt{-i}{<file name>[.azm]}{entry file name}
   \synoptopt{-I}{<file name>}{entry file name}
   \synoptopt{-o}{<file name>}{output file name}
   \synoptopt{-d}{<device>}{set device key}

\par
\zoem\|
   (enter interactive mode - happens when none of \genopt{-i},
   \genopt{-I}, \genopt{-o} is given)

\par
\zoem
   \synreqopt{-i}{<file name>[.azm]}{entry file name}
   \synreqopt{-I}{<file name>}{entry file name}
   \synoptopt{-o}{<file name>}{output file name}
   \synoptopt{-d}{<device>}{set device key}
   \synoptopt{-x}{enter interactive mode on error}
   \synoptopt{-s}{<key>=<val>}{set key to val}
   \synoptopt{-e}{<any>}{evaluate any, exit}
   \synoptopt{-E}{<any>}{evaluate any, proceed}
   \synoptopt{-chunk}{<num>}{process chunks of size num}
   \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}
   \synoptopt{--split}{assume \\writeto usage, set \\__split__}
   \synoptopt{--stress-write}{make \\write#3 recover}
   \synoptopt{--unsafe}{prompt for \\system#3}
   \synoptopt{--unsafe-silent}{simply allow \\system#3}
   \synoptopt{--system-honor}{require \\system#3 to succeed}
   \synoptopt{-nuser}{k}{user dict stack size}
   \synoptopt{-ndollar}{k}{dollar dict stack size}
   \synoptopt{-nsegment}{k}{maximum simple nesting depth}
   \synoptopt{-nstack}{k}{maximum eval nesting depth}
   \synoptopt{-buser}{initial user dict capacity}
   \synoptopt{-bzoem}{initial zoem dict capacity}
   \synoptopt{-tl}{k}{tab length}
   \synoptopt{-l}{<str>}{list items}
   \synoptopt{-h}{show options}

\par
   If the input file is specified using the \optref{-i}{\genopt{-i} option} and
   is a regular file (i.e. not STDIN - which is specified by using a
   single hyphen), it must have the extension \v{.azm}.
   This extension can but need not be specified.  The zoem key \z{__fnbase__}
   will be set to the file name stripped of the \v{.azm} extension.  If the
   input file is specified using the \optref{-I}{\genopt{-I} option}, no
   extension is assumed, and \z{__fnbase__} is set to the file name, period.

\par
   If neither \useopt{-i} nor \useopt{-o} is specified, zoem enters
   interactive mode. Zoem should fully recover from any error it encounters
   in the input. If you find an exception to this rule, consider
   filing a bug report.
   In interactive mode, zoem start interpreting once it encounters
   a line containing a single dot. Zoem's input behaviour can be
   modified by setting the key \z{__parmode__}.
   See the section \secref{session} for the details.

   In interactive mode, zoem does \it{not} preprocess the interactive
   input, implying that it does not accept inline files and it does not
   recognize comments. Both types of sequence will generate syntax errors.

\par
   Refer to the \sibref{zoemzoem}{zoemzoem} manual page for an overview
   of available zoem documentation.

\sec{description}{DESCRIPTION}

\par
   Zoem is a macro/programming language for writing macro packages that enable
   easy authoring of documents.  Examples are the \bf{man} and \bf{faq}
   packages on the one hand, and the \bf{doc} package on the other hand.  The
   former two define small, easy-to-use, and extendible mark-up languages.
   Manual pages and FAQs written in the respective languages can be converted
   to both HTML (for reading in browsers) and troff (for reading in terminals).
   The \bf{doc} package offers auxiliary support for writing largish documents
   in HTML - for example automatic section numbering and TOC generation.  All
   three languages have access to the same powerful \it{itemize} environment.
   The \lref{zum.html}{Zoem User Manual} \${roff}{(zum.html)}
   is a comprehensive tutorial and reference guide
   for the zoem language. It is currently available in HTML only.
   
\par
   If the input file (also called entry file) is a regular file specified with
   the \genopt{-i} option, then the \it{base} name of this file is the input
   file stripped of its \v{.azm} extension (mandatory with \genopt{-i}).  If
   the input file is specified using the \genopt{-I} option, the base name is
   simply the file name itself.  The base name is accessible via the
   \z{__fnbase__} key.

\par
   Create your own manual pages by copying the \it{buzzz} examples
   shipped with every zoem distribution and modifying it to your needs.  The
   \sibref{../mac/man_zmm}{man_zmm} manual page contains a list of the macros
   provided by the Zoem \bf{man} package.  The \sibref{../mac/faq_zmm}{faq_zmm}
   manual page contains a list of the macros provided by the Zoem \bf{faq}
   package.

\par
   From within the entry file and included files it is possible to open and
   write to arbitrary files using the \z{write#3} primitive.  Arbitrary files
   can be read in various modes using the \z{dofile#2} macro (providing four
   different modes with respect to file existence and output), \z{finsert#1},
   and \z{zinsert#1}.
   Zoem will write the default output to a single file, the name of which is
   either specified by the \genopt{-o} option, or constructed as described
   below.  Zoem can split the default output among multiple files.  This is
   governed from within the input files by issuing \z{writeto#1} calls. Refer
   to the \optref{--split}{\genopt{--split} option} and the
   \lref{zum.html}{Zoem User Manual}.

\par
   If none of \genopt{-i} or \genopt{-o} is given, then zoem will enter
   interactive mode. In this mode, zoem interprets by default chunks of
   text that are ended by a single dot on a line of its own.  This can be
   useful for testing or debugging.  In interactive mode, zoem should recover
   from any failure it encounters. Interactive mode can also be accessed from
   within a file  by issuing \v{\\zinsert{stdia}}, and it can be triggered as
   the mode to enter should an error occur (by adding the
   \optref{-x}{\genopt{-x} option} to the command line).


\par
   If \genopt{-o} is given and \genopt{-i} is not,
   zoem reads input from STDIN.

\par
   If \genopt{-i} is given and \genopt{-o} is not, zoem will construct an
   output file name as follows.  If the \genopt{-d} option was used with
   argument \v{<dev>}, zoem will write to the file which results from
   expanding \z{__fnbase__.<dev>}.  Otherwise, zoem writes to (the expansion
   of) \z{__fnbase__.ozm}.

\par
   For \genopt{-i} and \genopt{-o}, the argument \v{-}
   is interpreted as respectively \v{stdin} and \v{stdout}.

\sec{options}{OPTIONS}

\begin{itemize}

\item{\defopt{-i}{<file name>[.azm]}{entry file name}}
   Specify the entry file name. The file must have the \v{.azm}
   extension, but it need not be specified.

\item{\defopt{-I}{<file name>[.azm]}{entry file name}}
   Specify the entry file name, without restrictions on the file name.

\item{\defopt{-o}{<file name>}{output file name}}
   Specify the output file name.

\item{\defopt{-d}{<device>}{set key \\__device__}}
   Set the key \z{__device__} to \v{<device>}.
   If you have created a manual page or FAQ with either
   the Zoem \bf{man} or \bf{faq} package, you need to use
   either \v{html} or \v{roff} as argument to the \genopt{-d} flag.

\item{\defopt{-x}{enter interactive mode on error}}
   The afterlife option. If zoem encounters an error during
   regular processing, it will emit error messages as usual,
   and then enter interactive mode. This allows you e.g.
   to inspect the values of keys used or defined within
   the problematic area.

\item{\defopt{-s}{key=val}{set key to val}}
   Set the key \z{key} to \bf{val}. Any type of key can be set,
   including keys taking arguments and keys surrounded in quotes.
   Beware of the shell's quote and backslash interpolation.

\item{\defopt{-e}{<any>}{evaluate any, exit}}
   This causes zoem to evaluates \v{<any>},
   write any result text to stdout, and exit.

\item{\defopt{-E}{<any>}{evaluate any, proceed}}
   This causes zoem to evaluates \v{<any>},
   write any result text to stdout, and proceed e.g. with
   the entry file or an interactive session.

\item{\defopt{-chunk}{<num>}{process chunks of size num}}
   Zoem reads its input in chunks. It fully processes a chunk before moving on
   with the next one.  The \genopt{-chunk}{<num>} option defines the
   (minimum) size of the chunks.  The size or count of the
   chunks does not at all affect zoem's output.

\par
   Zoem will read files in their entirety before further processsing
   if \useopt{-chunk}{0} is specified.

\par
   Zoem does not chunk input files arbitrarily. It will append to
   a chunk until it is in the outermost scope (not contained within
   any block) and the chunk will end with a line that was fully read.

\par
   Consequently, if e.g. a file contains a block (delimited by
   balanced curlies) spanning the entire file then zoem is forced
   to read it in its entirety.

\item{\defopt{--trace}{trace mode, default}}
   Trace in default mode.

\item{\defopt{--trace-all-long}{long trace mode}}
   Sets on \it{most} trace options in long mode.
   Trace options \v{xxx} not set
   have their own \genopt{--trace-xxx} entry (see below).

\item{\defopt{--trace-all-short}{short trace mode}}
   Sets on \it{most} trace options in short mode.
   Trace options \v{xxx} not set
   have their own \genopt{--trace-xxx} entry (see below).

\item{\defopt{--trace-keys}{trace keys}}
   Trace keys.

\item{\defopt{--trace-regex}{trace regexes}}
   Trace regexes (i.e. the \z{inspect#4} primitive).

\item{\defopt{-trace}{k}{trace mode, explicit}}
   Set trace options by adding their representing bits.

\item{\defopt{--stress-write}{stress test using write}}
   This makes \z{write#3} recover from errors.
   It is a special purpose option used for creating zoem
   stress test suites, such as \v{stress.azm}
   in the zoem distribution \v{/examples} subdirectory.

\items{
   {\defopt{--unsafe}{prompt for \\system#3}}
   {\defopt{--unsafe-silent}{simply allow \\system#3}}
}
   With \useopt{--unsafe} system calls are allowed but the user
   is prompted for each invocation. The command and its arguments (if any)
   are shown, but the STDIN information (if any) is withheld.
   With \useopt{--unsafe-silent} system calls are allowed and
   the user is never prompted.

\item{\defopt{--system-honor}{require \\system#3 to succeed}}
   With this option any \v{\\system#3} failure (for whatever reason,
   including safe behaviour) is regarded as a zoem failure.
   By default, failing system calls are ignored under either
   safe mode, unsafe mode (--unsafe), or silent unsafe mode
   (--unsafe-silent).

\item{\defopt{--split}{assume split output}}
   This assumes zoem input that allows output to multiple files (e.g.
   chapters).  It sets the default output stream to \v{stdout} (anticipating
   custom output redirection with \z{writeto#1}) and sets the session macro
   \z{__split__} to \v{1}.

\item{\defopt{--stats}{show symbol table stats after run}}
   Show symbol table chacteristics. Symbol tables are
   maintained as hashes.

\item{\defopt{-tl}{k}{set tab length}}
   Set the tab length. HTML output can be indented according
   to nesting structure, using tabs which are expanded
   to simple spaces. By default, the tab length is zero,
   meaning that no indent is shown.
   The maximum value the tab length can be set to is four.

\items{
   {\defopt{-nsegment}{k}{level of macro nesting allowed}}
   {\defopt{-nstack}{k}{stack count}}
   {\defopt{-nuser}{k}{user dictionary stack size}}
   {\defopt{-ndollar}{k}{dollar dictionary stack size}}
   {\defopt{-buser}{k}{initial user dict capacity}}
   {\defopt{-bzoem}{k}{initial zoem dict capacity}}
}
   Probably needed only if you have some obscure and extreme use
   for zoem. The segment limit applies to simple nesting of macros. The
   stack limit applies to nesting of macros that evaluate an argument before
   use. Each such evaluation creates a new stack.  The user limit applies to
   \z{push{user}}, the dollar limit applies to \z{push{dollar}}.  The user
   dict capacity pertains to the initial number of buckets allocated for
   user and dollar dictionaries, and the zoem dict capacity pertains to the
   dictionary containing the zoem primitives.

\item{\defopt{-l}{<str>}{list items}}
   List items identified by \v{<str>}. It can be any of
   \bf{all},
   \bf{filter}.
   \bf{legend},
   \bf{macro},
   \bf{session},
   \bf{trace}, or
   \bf{zoem},

   Multiple identifiers
   can be joined in a string, e.g.  \v{-l legendzoem} prints a legend
   followed by a listing of zoem primitives.

\item{\defopt{-h}{show options}}
   Show short synopsis of options.

\end{itemize}

\sec{session}{SESSION MACROS}

\begin{itemize}
\item{\z{__parmode__}}
   This macro affects zoem's read behaviour in interactive mode.
   It can be set on the command line using the \genopt{-s} option.
   Bits that can be set:

\verbatim{\
1    chomp newlines (remove the newline character)
2    skip empty newlines
4    read paragraphs (an empty line triggers input read)
8    newlines can be escaped using a backslash
16   read large paragraphs (a single dot on a line
     triggers input read)}

\item{\z{__device__}}
   The current output device, set by \optref{-d}{the command line option
   \genopt{-d}}.  The \bf{man} and \bf{faq} packages support \bf{html} and
   \bf{roff} as its values.

\item{\z{__fnbase__}}
   The base name of the entry file.

\item{\z{__fnentry__}}
   The name of the entry file.

\item{\z{__fnin__}}
   The file currently being processed.

\item{\z{__line__}}
   The line number in the file currently being processed.

\item{\z{__fnout__}}
   The name of the default output file.

\item{\z{__zoemstat__}}
   Set to one of \v{ok}, \v{towel} (that one is a bit lame),
   or \v{error} by either the interpreter, an occurrence of \v{\\catch#2},
   or \v{\\try#1}.

\item{\z{__zoemput__}}
   Set by \v{\\try#1} to the possibly truncated result of processing
   its argument.

\item{\z{__searchpath__}}
   A vararg containing a list of paths to search when a file is to be
   included/imported/read/loaded.  When you start zoem, this key should
   contain the location of the \bf{man.zmm} and \bf{faq.zmm} package files.
   It is advisable not to overwrite this key but to append to it instead.

\item{\z{__lc__}}
   Expands to a left curly. It is hard to find a need for this \- the zoem
   stress suite uses it to generate a particular syntax error at a deeper
   interpretation level.

\item{\z{__rc__}}
   Expands to a right curly.

\end{itemize}

\sec{files}{FILES}
\par
   Example files are shipped with the distribution.  Use \bf{buzzz.azm} as a
   template for creating manual pages, and see the
   \sibref{../mac/man_zmm}{man_zmm} manual page for a listing of Zoem man
   macros.  Similarly, use \bf{faq_zmm.azm} as a template for creating FAQs,
   and refer to the corresponding \sibref{../mac/faq_zmm}{faq_zmm} manual page
   for a listing of Zoem faq macros.

\sec{environment}{ENVIRONMENT}
\par
   The environment variable ZOEMSEARCHPATH may contain a colon and/or
   whitespace separated list of paths. It will be used when searching
   for files included via one of the \v{dofile} aliases
   \v{\\input}, \v{\\import}, \v{\\read}, and \v{\\load}.
   Note that the zoem macro \v{\\__searchpath__} contains the location where
   the zoem macro files were copied at the time of installation of zoem.

\sec{diagnostics}{DIAGNOSTICS}
\par
   On error, Zoem prints a file name and a line number to which it was able to
   trace the error. This will usually be correct, but the error may have
   occurred in a macro deeply nested in a macro found in the line reported by
   zoem.  If in despair, use one of the tracing modes, \bf{--trace-keys} is one
   of the first to come to mind. Another possibility
   is to supply the \optref{-x}{\genopt{-x} option}.

\sec{bugs}{BUGS}
\par
   No known bugs. \z{inspect#4} has not received thorough stress-testing,
   and the more esoteric parts of its interface will probably change.

\sec{author}{AUTHOR}
\par
   Stijn van Dongen.

\sec{history}{HISTORY}
\par
   Zoem was born from a desire for decent manual pages in HTML
   and troff from a single compact source file in a powerful and
   extendible macro language.

\={eekzoo}
\write{stderr}{device}{In file eekzoo at line count \__line__\@{\N}}
\write{stderr}{device}{In file eekzoo at line count \__line__\@{\N}}
\==

\={foobar}
\write{stderr}{device}{In file foobar at line count \__line__\@{\N}}
\write{stderr}{device}{In file foobar at line count \__line__\@{\N}}
\==

\input{eekzoo}
\input{foobar}

\"man::postamble"
