.\" Copyright (c) 2004 Stijn van Dongen
.TH "zoem" 1 "21 Jun 2004" "zoem 1\&.001, 04-173" "USER COMMANDS"
.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
zoem \- interpreter for the Zoem macro/programming language\&.
.SH SYNOPSIS

\fBzoem\fP
\fB[-i\fP <file name>[\&.azm] (\fIentry file name\fP)\fB]\fP
\fB[-I\fP <file name> (\fIentry file name\fP)\fB]\fP
\fB[-o\fP <file name> (\fIoutput file name\fP)\fB]\fP
\fB[-d\fP <device> (\fIset device key\fP)\fB]\fP

\fBzoem\fP
.br
(enter interactive mode - happens when none of \fB-i\fP,
\fB-I\fP, \fB-o\fP is given)

\fBzoem\fP
\fB-i\fP <file name>[\&.azm] (\fIentry file name\fP)
\fB-I\fP <file name> (\fIentry file name\fP)
\fB[-o\fP <file name> (\fIoutput file name\fP)\fB]\fP
\fB[-d\fP <device> (\fIset device key\fP)\fB]\fP
\fB[-x\fP (\fIenter interactive mode on error\fP)\fB]\fP
\fB[-s\fP <key>=<val> (\fIset key to val\fP)\fB]\fP
\fB[-e\fP <any> (\fIevaluate any, exit\fP)\fB]\fP
\fB[-E\fP <any> (\fIevaluate any, proceed\fP)\fB]\fP
\fB[-chunk\fP <num> (\fIprocess chunks of size num\fP)\fB]\fP
\fB[--trace\fP (\fItrace mode, default\fP)\fB]\fP
\fB[--trace-all-long\fP (\fIlong trace mode\fP)\fB]\fP
\fB[--trace-all-short\fP (\fIshort trace mode\fP)\fB]\fP
\fB[--trace-regex\fP (\fItrace regexes\fP)\fB]\fP
\fB[--show-tracebits\fP (\fIshow trace bits\fP)\fB]\fP
\fB[-trace\fP k (\fItrace mode, explicit\fP)\fB]\fP
\fB[--stats\fP (\fIshow symbol table stats after run\fP)\fB]\fP
\fB[--split\fP (\fIassume \ewriteto usage, set \e__split__\fP)\fB]\fP
\fB[--stress-write\fP (\fImake \ewrite#3 recover\fP)\fB]\fP
\fB[--unsafe\fP (\fIprompt for \esystem#3\fP)\fB]\fP
\fB[--unsafe-silent\fP (\fIsimply allow \esystem#3\fP)\fB]\fP
\fB[--system-honor\fP (\fIrequire \esystem#3 to succeed\fP)\fB]\fP
\fB[-nuser\fP k (\fIuser dict stack size\fP)\fB]\fP
\fB[-ndollar\fP k (\fIdollar dict stack size\fP)\fB]\fP
\fB[-nsegment\fP k (\fImaximum simple nesting depth\fP)\fB]\fP
\fB[-nstack\fP k (\fImaximum eval nesting depth\fP)\fB]\fP
\fB[-buser\fP (\fIinitial user dict capacity\fP)\fB]\fP
\fB[-bzoem\fP (\fIinitial zoem dict capacity\fP)\fB]\fP
\fB[-tl\fP k (\fItab length\fP)\fB]\fP
\fB[-l\fP <str> (\fIlist items\fP)\fB]\fP
\fB[-h\fP (\fIshow options\fP)\fB]\fP

If the input file is specified using the \fB-i\fP option and
is a regular file (i\&.e\&. not STDIN - which is specified by using a
single hyphen), it must have the extension \fC\&.azm\fR\&.
This extension can but need not be specified\&. The zoem key \fB\e__fnbase__\fP
will be set to the file name stripped of the \fC\&.azm\fR extension\&. If the
input file is specified using the \fB-I\fP option, no
extension is assumed, and \fB\e__fnbase__\fP is set to the file name, period\&.

If neither \fB-i\fP nor \fB-o\fP 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 \fB\e__parmode__\fP\&.
See the section \fBSESSION MACROS\fP for the details\&.
In interactive mode, zoem does \fInot\fP 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\&.

Refer to the \fBzoemzoem\fP manual page for an overview
of available zoem documentation\&.
.SH DESCRIPTION

Zoem is a macro/programming language for writing macro packages that enable
easy authoring of documents\&. Examples are the \fBman\fP and \fBfaq\fP
packages on the one hand, and the \fBdoc\fP 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 \fBdoc\fP 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 \fIitemize\fP environment\&.
The Zoem User Manual (zum\&.html)
is a comprehensive tutorial and reference guide
for the zoem language\&. It is currently available in HTML only\&.

If the input file (also called entry file) is a regular file specified with
the \fB-i\fP option, then the \fIbase\fP name of this file is the input
file stripped of its \fC\&.azm\fR extension (mandatory with \fB-i\fP)\&. If
the input file is specified using the \fB-I\fP option, the base name is
simply the file name itself\&. The base name is accessible via the
\fB\e__fnbase__\fP key\&.

Create your own manual pages by copying the \fIbuzzz\fP examples
shipped with every zoem distribution and modifying it to your needs\&. The
\fBman_zmm\fP manual page contains a list of the macros
provided by the Zoem \fBman\fP package\&. The \fBfaq_zmm\fP
manual page contains a list of the macros provided by the Zoem \fBfaq\fP
package\&.

From within the entry file and included files it is possible to open and
write to arbitrary files using the \fB\ewrite#3\fP primitive\&. Arbitrary files
can be read in various modes using the \fB\edofile#2\fP macro (providing four
different modes with respect to file existence and output), \fB\efinsert#1\fP,
and \fB\ezinsert#1\fP\&.
Zoem will write the default output to a single file, the name of which is
either specified by the \fB-o\fP 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 \fB\ewriteto#1\fP calls\&. Refer
to the \fB--split\fP option and the
Zoem User Manual\&.

If none of \fB-i\fP or \fB-o\fP 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 \fC\ezinsert{stdia}\fR, and it can be triggered as
the mode to enter should an error occur (by adding the
\fB-x\fP option to the command line)\&.

If \fB-o\fP is given and \fB-i\fP is not,
zoem reads input from STDIN\&.

If \fB-i\fP is given and \fB-o\fP is not, zoem will construct an
output file name as follows\&. If the \fB-d\fP option was used with
argument \fC<dev>\fR, zoem will write to the file which results from
expanding \fB\e__fnbase__\&.<dev>\fP\&. Otherwise, zoem writes to (the expansion
of) \fB\e__fnbase__\&.ozm\fP\&.

For \fB-i\fP and \fB-o\fP, the argument \fC-\fR
is interpreted as respectively \fCstdin\fR and \fCstdout\fR\&.
.SH OPTIONS

.ZI 3m "\fB-i\fP <file name>[\&.azm] (\fIentry file name\fP)"
\&
.br
Specify the entry file name\&. The file must have the \fC\&.azm\fR
extension, but it need not be specified\&.
.in -3m

.ZI 3m "\fB-I\fP <file name>[\&.azm] (\fIentry file name\fP)"
\&
.br
Specify the entry file name, without restrictions on the file name\&.
.in -3m

.ZI 3m "\fB-o\fP <file name> (\fIoutput file name\fP)"
\&
.br
Specify the output file name\&.
.in -3m

.ZI 3m "\fB-d\fP <device> (\fIset key \e__device__\fP)"
\&
.br
Set the key \fB\e__device__\fP to \fC<device>\fR\&.
If you have created a manual page or FAQ with either
the Zoem \fBman\fP or \fBfaq\fP package, you need to use
either \fChtml\fR or \fCroff\fR as argument to the \fB-d\fP flag\&.
.in -3m

.ZI 3m "\fB-x\fP (\fIenter interactive mode on error\fP)"
\&
.br
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\&.
.in -3m

.ZI 3m "\fB-s\fP key=val (\fIset key to val\fP)"
\&
.br
Set the key \fB\ekey\fP to \fBval\fP\&. 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\&.
.in -3m

.ZI 3m "\fB-e\fP <any> (\fIevaluate any, exit\fP)"
\&
.br
This causes zoem to evaluates \fC<any>\fR,
write any result text to stdout, and exit\&.
.in -3m

.ZI 3m "\fB-E\fP <any> (\fIevaluate any, proceed\fP)"
\&
.br
This causes zoem to evaluates \fC<any>\fR,
write any result text to stdout, and proceed e\&.g\&. with
the entry file or an interactive session\&.
.in -3m

.ZI 3m "\fB-chunk\fP <num> (\fIprocess chunks of size num\fP)"
\&
.br
Zoem reads its input in chunks\&. It fully processes a chunk before moving on
with the next one\&. The \fB-chunk\fP\ \fI<num>\fP option defines the
(minimum) size of the chunks\&. The size or count of the
chunks does not at all affect zoem\&'s output\&.

Zoem will read files in their entirety before further processsing
if \fB-chunk\fP\ \fB0\fP is specified\&.

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\&.

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\&.
.in -3m

.ZI 3m "\fB--trace\fP (\fItrace mode, default\fP)"
\&
.br
Trace in default mode\&.
.in -3m

.ZI 3m "\fB--trace-all-long\fP (\fIlong trace mode\fP)"
\&
.br
Sets on \fImost\fP trace options in long mode\&.
Trace options \fCxxx\fR not set
have their own \fB--trace-xxx\fP entry (see below)\&.
.in -3m

.ZI 3m "\fB--trace-all-short\fP (\fIshort trace mode\fP)"
\&
.br
Sets on \fImost\fP trace options in short mode\&.
Trace options \fCxxx\fR not set
have their own \fB--trace-xxx\fP entry (see below)\&.
.in -3m

.ZI 3m "\fB--trace-keys\fP (\fItrace keys\fP)"
\&
.br
Trace keys\&.
.in -3m

.ZI 3m "\fB--trace-regex\fP (\fItrace regexes\fP)"
\&
.br
Trace regexes (i\&.e\&. the \fB\einspect#4\fP primitive)\&.
.in -3m

.ZI 3m "\fB-trace\fP k (\fItrace mode, explicit\fP)"
\&
.br
Set trace options by adding their representing bits\&.
.in -3m

.ZI 3m "\fB--stress-write\fP (\fIstress test using write\fP)"
\&
.br
This makes \fB\ewrite#3\fP recover from errors\&.
It is a special purpose option used for creating zoem
stress test suites, such as \fCstress\&.azm\fR
in the zoem distribution \fC/examples\fR subdirectory\&.
.in -3m

.ZI 3m "\fB--unsafe\fP (\fIprompt for \esystem#3\fP)"
\&
'in -3m
.ZI 3m "\fB--unsafe-silent\fP (\fIsimply allow \esystem#3\fP)"
\&
'in -3m
'in +3m
\&
.br
With \fB--unsafe\fP 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 \fB--unsafe-silent\fP system calls are allowed and
the user is never prompted\&.
.in -3m

.ZI 3m "\fB--system-honor\fP (\fIrequire \esystem#3 to succeed\fP)"
\&
.br
With this option any \fC\esystem#3\fR 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)\&.
.in -3m

.ZI 3m "\fB--split\fP (\fIassume split output\fP)"
\&
.br
This assumes zoem input that allows output to multiple files (e\&.g\&.
chapters)\&. It sets the default output stream to \fCstdout\fR (anticipating
custom output redirection with \fB\ewriteto#1\fP) and sets the session macro
\fB\e__split__\fP to \fC1\fR\&.
.in -3m

.ZI 3m "\fB--stats\fP (\fIshow symbol table stats after run\fP)"
\&
.br
Show symbol table chacteristics\&. Symbol tables are
maintained as hashes\&.
.in -3m

.ZI 3m "\fB-tl\fP k (\fIset tab length\fP)"
\&
.br
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\&.
.in -3m

.ZI 3m "\fB-nsegment\fP k (\fIlevel of macro nesting allowed\fP)"
\&
'in -3m
.ZI 3m "\fB-nstack\fP k (\fIstack count\fP)"
\&
'in -3m
.ZI 3m "\fB-nuser\fP k (\fIuser dictionary stack size\fP)"
\&
'in -3m
.ZI 3m "\fB-ndollar\fP k (\fIdollar dictionary stack size\fP)"
\&
'in -3m
.ZI 3m "\fB-buser\fP k (\fIinitial user dict capacity\fP)"
\&
'in -3m
.ZI 3m "\fB-bzoem\fP k (\fIinitial zoem dict capacity\fP)"
\&
'in -3m
'in +3m
\&
.br
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
\fB\epush{user}\fP, the dollar limit applies to \fB\epush{dollar}\fP\&. 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\&.
.in -3m

.ZI 3m "\fB-l\fP <str> (\fIlist items\fP)"
\&
.br
List items identified by \fC<str>\fR\&. It can be any of
\fBall\fP,
\fBfilter\fP\&.
\fBlegend\fP,
\fBmacro\fP,
\fBsession\fP,
\fBtrace\fP, or
\fBzoem\fP,
Multiple identifiers
can be joined in a string, e\&.g\&. \fC-l legendzoem\fR prints a legend
followed by a listing of zoem primitives\&.
.in -3m

.ZI 3m "\fB-h\fP (\fIshow options\fP)"
\&
.br
Show short synopsis of options\&.
.in -3m
.SH SESSION MACROS

.ZI 3m "\fB\e__parmode__\fP"
\&
.br
This macro affects zoem\&'s read behaviour in interactive mode\&.
It can be set on the command line using the \fB-s\fP option\&.
Bits that can be set:

.di ZV
.in 0
.nf \fC
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)
.fi \fR
.in
.di
.ne \n(dnu
.nf \fC
.ZV
.fi \fR

.in -3m

.ZI 3m "\fB\e__device__\fP"
\&
.br
The current output device, set by the command line option
\fB-d\fP\&. The \fBman\fP and \fBfaq\fP packages support \fBhtml\fP and
\fBroff\fP as its values\&.
.in -3m

.ZI 3m "\fB\e__fnbase__\fP"
\&
.br
The base name of the entry file\&.
.in -3m

.ZI 3m "\fB\e__fnentry__\fP"
\&
.br
The name of the entry file\&.
.in -3m

.ZI 3m "\fB\e__fnin__\fP"
\&
.br
The file currently being processed\&.
.in -3m

.ZI 3m "\fB\e__line__\fP"
\&
.br
The line number in the file currently being processed\&.
.in -3m

.ZI 3m "\fB\e__fnout__\fP"
\&
.br
The name of the default output file\&.
.in -3m

.ZI 3m "\fB\e__zoemstat__\fP"
\&
.br
Set to one of \fCok\fR, \fCtowel\fR (that one is a bit lame),
or \fCerror\fR by either the interpreter, an occurrence of \fC\ecatch#2\fR,
or \fC\etry#1\fR\&.
.in -3m

.ZI 3m "\fB\e__zoemput__\fP"
\&
.br
Set by \fC\etry#1\fR to the possibly truncated result of processing
its argument\&.
.in -3m

.ZI 3m "\fB\e__searchpath__\fP"
\&
.br
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 \fBman\&.zmm\fP and \fBfaq\&.zmm\fP package files\&.
It is advisable not to overwrite this key but to append to it instead\&.
.in -3m

.ZI 3m "\fB\e__lc__\fP"
\&
.br
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\&.
.in -3m

.ZI 3m "\fB\e__rc__\fP"
\&
.br
Expands to a right curly\&.
.in -3m
.SH FILES

Example files are shipped with the distribution\&. Use \fBbuzzz\&.azm\fP as a
template for creating manual pages, and see the
\fBman_zmm\fP manual page for a listing of Zoem man
macros\&. Similarly, use \fBfaq_zmm\&.azm\fP as a template for creating FAQs,
and refer to the corresponding \fBfaq_zmm\fP manual page
for a listing of Zoem faq macros\&.
.SH ENVIRONMENT

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 \fCdofile\fR aliases
\fC\einput\fR, \fC\eimport\fR, \fC\eread\fR, and \fC\eload\fR\&.
Note that the zoem macro \fC\e__searchpath__\fR contains the location where
the zoem macro files were copied at the time of installation of zoem\&.
.SH DIAGNOSTICS

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, \fB--trace-keys\fP is one
of the first to come to mind\&. Another possibility
is to supply the \fB-x\fP option\&.
.SH BUGS

No known bugs\&. \fB\einspect#4\fP has not received thorough stress-testing,
and the more esoteric parts of its interface will probably change\&.
.SH AUTHOR

Stijn van Dongen\&.
.SH HISTORY

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\&.