21 Jun 2004 zoem 1.001, 04-173
1. | ||
2. | ||
3. | ||
4. | ||
5. | ||
6. | ||
7. | ||
8. | ||
9. | ||
10. | ||
11. |
zoem - interpreter for the Zoem macro/programming language.
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)] [-chunk <num> (process chunks of size num)] [--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.
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. 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.
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.
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.
\__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.
|
||
\__zoemstat__ | ||
Set to one of ok, towel (that one is a bit lame),
or error by either the interpreter, an occurrence of \catch#2,
or \try#1.
|
||
\__zoemput__ | ||
Set by \try#1 to the possibly truncated result of processing
its argument.
|
||
\__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.
|
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.
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 dofile aliases \input, \import, \read, and \load. Note that the zoem macro \__searchpath__ contains the location where the zoem macro files were copied at the time of installation of zoem.
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.
No known bugs. \inspect#4 has not received thorough stress-testing, and the more esoteric parts of its interface will probably change.
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.