27 Oct 2003    zoem 1.001, 03-300

1.  
2.  
3.  
4.  
5.  
6.  
7.  
8.  
9.  
10.  
11.  

NAME

zoem - interpreter for the Zoem macro/programming language.

SYNOPSIS

zoem [-i <file name>[.azm] (entry file name)] [-I <file name> (entry file name)] [-o <file name> (output file name)] [-d <device> (set device key)]

zoem
(enter interactive mode - happens when none of -i, -I, -o is given)

zoem -i <file name>[.azm] (entry file name) -I <file name> (entry file name) [-o <file name> (output file name)] [-d <device> (set device key)] [-x (enter interactive mode on error)] [-s <key>=<val> (set key to val)] [-e <any> (evaluate any, exit)] [-E <any> (evaluate any, proceed)] [--trace (trace mode, default)] [--trace-all-long (long trace mode)] [--trace-all-short (short trace mode)] [--trace-regex (trace regexes)] [--show-tracebits (show trace bits)] [-trace k (trace mode, explicit)] [--stats (show symbol table stats after run)] [--split (assume \writeto usage, set \__split__)] [--stress-write (make \write#3 recover)] [--unsafe (prompt for \system#3)] [--unsafe-silent (simply allow \system#3)] [--system-honor (require \system#3 to succeed)] [-nuser k (user dict stack size)] [-ndollar k (dollar dict stack size)] [-nsegment k (maximum simple nesting depth)] [-nstack k (maximum eval nesting depth)] [-buser (initial user dict capacity)] [-bzoem (initial zoem dict capacity)] [-tl k (tab length)] [-l <str> (list items)] [-h (show options)]

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

If neither -i nor -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 \__parmode__. See the section SESSION MACROS for the details. In interactive mode, zoem does 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.

Refer to the zoemzoem manual page for an overview of available zoem documentation.

DESCRIPTION

Zoem is a macro/programming language for writing macro packages that enable easy authoring of documents. Examples are the man and faq packages on the one hand, and the 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 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 itemize environment.

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

The Zoem User Manual 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 -i option, then the base name of this file is the input file stripped of its .azm extension (mandatory with -i). If the input file is specified using the -I option, the base name is simply the file name itself. The base name is accessible via the \__fnbase__ key.

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

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

If -o is given and -i is not, zoem reads input from STDIN.

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

For -i and -o, the argument - is interpreted as respectively stdin and stdout.

OPTIONS

-i <file name>[.azm] (entry file name)
   
Specify the entry file name. The file must have the .azm extension, but it need not be specified.
   
-I <file name>[.azm] (entry file name)
   
Specify the entry file name, without restrictions on the file name.
   
-o <file name> (output file name)
   
Specify the output file name.
   
-d <device> (set key \__device__)
   
Set the key \__device__ to <device>. If you have created a manual page or FAQ with either the Zoem man or faq package, you need to use either html or roff as argument to the -d flag.
   
-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.
   
-s key=val (set key to val)
   
Set the key \key to 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.
   
-e <any> (evaluate any, exit)
   
This causes zoem to evaluates <any>, write any result text to stdout, and exit.
   
-E <any> (evaluate any, proceed)
   
This causes zoem to evaluates <any>, write any result text to stdout, and proceed e.g. with the entry file or an interactive session.
   
--trace (trace mode, default)
   
Trace in default mode.
   
--trace-all-long (long trace mode)
   
Sets on most trace options in long mode. Trace options xxx not set have their own --trace-xxx entry (see below).
   
--trace-all-short (short trace mode)
   
Sets on most trace options in short mode. Trace options xxx not set have their own --trace-xxx entry (see below).
   
--trace-keys (trace keys)
   
Trace keys.
   
--trace-regex (trace regexes)
   
Trace regexes (i.e. the \inspect#2 primitive).
   
-trace k (trace mode, explicit)
   
Set trace options by adding their representing bits.
   
--stress-write (stress test using write)
   
This makes \write#3 recover from errors. It is a special purpose option used for creating zoem stress test suites, such as stress.azm in the zoem distribution /examples subdirectory.
   
--unsafe (prompt for \system#3)
--unsafe-silent (simply allow \system#3)
   
With --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 --unsafe-silent system calls are allowed and the user is never prompted.
   
--system-honor (require \system#3 to succeed)
   
With this option any \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).
   
--split (assume split output)
   
This assumes zoem input that allows output to multiple files (e.g. chapters). It sets the default output stream to stdout (anticipating custom output redirection with \writeto#1) and sets the session macro \__split__ to 1.
   
--stats (show symbol table stats after run)
   
Show symbol table chacteristics. Symbol tables are maintained as hashes.
   
-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.
   
-nsegment k (level of macro nesting allowed)
-nstack k (stack count)
-nuser k (user dictionary stack size)
-ndollar k (dollar dictionary stack size)
-buser k (initial user dict capacity)
-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 \push{user}, the dollar limit applies to \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.
   
-l <str> (list items)
   
List items identified by <str>. It can be any of all, filter. legend, macro, session, trace, or zoem, Multiple identifiers can be joined in a string, e.g. -l legendzoem prints a legend followed by a listing of zoem primitives.
   
-h (show options)
   
Show short synopsis of options.

SESSION MACROS

\__parmode__
   
This macro affects zoem's read behaviour in interactive mode. It can be set on the command line using the -s option. Bits that can be set:
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)
   
\__device__
   
The current output device, set by the command line option -d. The man and faq packages support html and roff as its values.
   
\__fnbase__
   
The base name of the entry file.
   
\__fnentry__
   
The name of the entry file.
   
\__fnin__
   
The file currently being processed.
   
\__line__
   
The line number in the file currently being processed.
   
\__fnout__
   
The name of the default output file.
   
\__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 man.zmm and faq.zmm package files. It is advisable not to overwrite this key but to append to it instead.
   
\__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.
   
\__rc__
   
Expands to a right curly.

FILES

Example files are shipped with the distribution. Use buzzz.azm as a template for creating manual pages, and see the man_zmm manual page for a listing of Zoem man macros. Similarly, use faq_zmm.azm as a template for creating FAQs, and refer to the corresponding faq_zmm manual page for a listing of Zoem faq macros.

ENVIRONMENT

Currently, no environmental issues with zoem.

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

BUGS

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

AUTHOR

Stijn van Dongen.

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.