\: thoughts/todo
\:----------------------------------------------------------------------
\: o  mention 9-arg limit.
\: o  ref point for white space munge rules.
\: ?  let maketoc have an argument which is the reference for the toc.


\if{\defined{key}{__device__}}{}{\def{__device__}{html}}
\import{../mac/doc.zmm}

\set{"doc::html-title"}{Zoem User's Manual}
\set{"doc::title"}{Zoem User's Manual}
\set{"doc::author"}{Stijn van Dongen}

\apply{_#3\!{{
   \set{"doc::day"}{\1}
   \set{"doc::month"}{\2}
   \set{"doc::year"}{\3}
}}}{
   {\system{date}{{+%e}}}
   {\system{date}{{+%B}}}
   {\system{date}{{+%Y}}}
}

\"doc::preamble"

\def{builtins}{\mc{\\}, \mc{\{}, \mc{\}}, \mc{,},
\mc{~}, \mc{|}, and \mc{-}}

\def{pr#1}{\iref{\1}{\v{\\\1}}}
\def{xmlpr1ref}{\iref{xmlpr1}{\v{\\<>#1}}}
\def{xmlpr2ref}{\iref{xmlpr2}{\v{\\<>#2}}}
\def{mc#1}{\v{\\\1}}
\def{capref#1}{\iref{\1}{\refcaption{\1}}}
\def{refto#2}{\@{<a href="#\1">}\2\@{</a>}}
\def{zarg#1}{\v{<\1>}}

\begin{spacing}{{pleft}{60}}
\par
 The size of this manual is getting ridiculous. Working on it (the doc
 macros need chapter mode).
\end{spacing}

\sec1{intro}{Introduction}

\par
\bf{Zoem:} <Dutch> The sound made by electrical devices and flying bugs.
Pronounced: \it{zoom} or \it{zum}; the vowel is short.

\if{0}{
\hrule
\par
 Zoem is an interpretive macro language with substantial facilities for
 programming. It supports a two-stage process, consisting of macro
 interpretation (featuring inside-out evaluation if needed), followed by a
 simple and powerful application of stream character filtering.

 Its syntax is reminiscent of \it{TeX}'s, it has dictionary stacks like
 \it{PostScript}, and various resemblances to \it{m4} and \it{info}.  It has
 interfaces to modules making life easy \- counters, references, arithmetic,
 multi-dimensional data storage, input/output operations, and regular
 expressions.

\par
 Zoem is used for creating extendible dummy mark-up languages and mapping those
 to real mark-up languages.  The dummy languages have all the power of the zoem
 primitives available to them.  A prime application is the creation of little
 mark-up languages that allow easy preparation of documents for use with
 different devices.  Two examples are the zoem \bf{faq} language and the zoem
 \bf{man} language.  Both provide a concise and easily extendible format with
 which FAQs and manual pages can be written in a single source file for output
 in either HTML or troff. The two languages are compact and easy to type.  This
 document itself was generated using the zoem \bf{doc} language.  And yes, I
 was tempted to call zoem TUAT instead,
 \iref{ecosphere}{The Umpteenth Authoring Tool}.
}{}

\if{1}{
\par
Zoem is a general macro/programming language with filtering
capabilities. One of its uses is
the creation of little high-level mark-up languages.
It is a new inhabitant of two niches swarming with creatures already.

\par
Zoem was first created to make mark-up languages that solve particular problems.
One such problem is posed by the wish to create good-looking cross-referenced
manual pages for output with either troff, html, or yet other devices, while
having the ease of control and brevity of expression as in TeX, as opposed to,
say, DocBook.  Other problems descend from similar desiderata for FAQ authoring
and technical documentation in general.  Some software developers need brevity
and control, lest the documentation suffers in its evolution.
Zoem itself has virtually no features supporting mark-up.  It has two
components.

\par
One compoment is a macro/programming language with many constructs put
together in a coherent design.
A few to name are dictionary stacks, IO facilities, an arithmetic environment,
delayed and inside-out evaluation, multi-dimensional data storage, iteration
and control support, system interaction, regular expressions,
and an interactive environment. An interesting feature is the combination
of anonymous macros, lists, and the \mc{apply#2} primitive, constituting
a kind of callback mechanism in zoem. Another feature is the automatic
popping and pushing of dictionaries with the begin/end environment,
providing shadowing and localization.

\par
The other component is a simple filtering language that distinguishes
between two types of zoem scopes. Device scope is used to encode
device specific mark-up sequences. Plain scope is used to encode
running text. Filtering mechanisms are provided for both.

\par
Zoem processes text by first applying the macro component, followed
by applying the filtering component.
Macro packages use the zoem primitives to construct mark-up languages
that are designed to map to different devices in a bottom-up fashion.
The resulting languages are generally clean, extendible, and perform well.

\cpar{Examples}
The zmm_generic package provides generic support for both
troff and html (lists, paragraphs, typefaces, references).
It contains some 550 spacious lines, with 25 characters on average.
The intended substance conveyed by those counts is that the package is small.
The man.zmm package consists of 300 additional lines.  The faq.zmm package
(which uses the man.zmm package) contains 200 additional lines.

\par
Zoem has a rigorous syntax similar to TeX's with no more than a single
first-level meta character.
The syntax's rigor combined with the callback mechanism enables
a near-complete separation of mark-up and content, maximizing flexibility.
Here is an example from the section
\iref{ecosphere}{\refcaption{ecosphere}}.
Take note that the itemize environment seen below and all macros
except \mc{apply} do not belong to the zoem language; they are part
of packages built on top of zoem.


\verbatim{\protect{\:/
\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
   {margintop}{1}
   {marginleft}{4}
}
\apply{_#3\!{{
   \item{\aref{\1}{\bf{\2}}}
      \3
   }
}}{
 {http://www.google.com/search?q=aft+almost+free+text}
 {aft}
 {almost free text}

 {http://www.google.com/search?q=chakotay+chpp+macro+preprocessor}
 {chakotay}
 {chakotay/chpp}

 {http://www.google.com/search?q=empy+template+embedding+python+text}
 {EmPy}
 {embedded python [in text]}

 \""{ some thirty-odd triples omittted. }

 {http://www.google.com/search?q=yodl+yet+oneOther+Documentation+Language}
 {yodl}
 {yet oneOther Documentation Language}
}
\end{itemize}}}
}{}

\par
 This manual covers the whole zoem language. A large part of it is only
 interesting for someone writing a reusable macro package. A smaller part is
 still interesting for someone who is just using such a package, but might
 want to add some utilities and shortcuts of his own. The part where file
 inclusion, macro definitions, and macro expansions are explained is required
 reading for anyone considering or planning to use zoem.  The manual also
 covers an example manual page written using the zoem manual macros, and the
 results after conversion to html and (PostScript generated from) troff
 (\iref{manexample}{Section\~\refnumber{manexample}}, see the table of
 contents below).

\sec2{}{Other documentation}

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
   {margintop}{0}
   {align}{right}
   {mark}{\*{bullet}}
}
\item
   \sibref{zoem}{The manual page of the zoem interpreter}

\item
   \sibref{../mac/man_zmm}{The zoem manual macros documented}

\item
   \sibref{../mac/faq_zmm}{The zoem faq macros documented}

\item
   \sibref{../mac/generic_zmm}{The zoem \it{generic} macros documented}
\end{itemize}

\sec2{}{Examples}
\par
Small examples are littered throughout this manual.
If you want to see examples of what can be achieved using zoem,
visit \iref{manexample}{Section\~\refnumber{manexample}}.

\sec2{}{The habitat}
\par
Information about comparable and related applications is collected
in section\~\refnumber{ecosphere},
\iref{ecosphere}{\refcaption{ecosphere}}.
It lists a number of macro processors, authoring tools,
mark-up languages, and software documentation projects.

\par
Some more itchy prose about documentation tools can be found
in \iref{itches}{Section\~\refnumber{itches}}.


\sec2{click}{About this document}
\par
 Clicking on the number to the left of a section title (e.g.
 the \refnumber{click} to the left of the title \bf{About this document} of
 this section) will get you to the corresponding section of the table of
 contents.

\par
 Zoem input and zoem output are \it{both} generally shown in a typeface
 font, \v{like this}.

\par
\enref{colours}{}
 Links that point to locations within this document are shown in
 \iref{colours}{blueish colors}.  Links that point to documents originating
 from the same package (project) or perhaps the same site are shown in in
 \lref{zum.html}{greenish colors}.  Links that point to other stations on the
 internet or perhaps other packages on the same site are shown in in
 \aref{http://www.google.com}{reddish colors}.

\sec3{}{About this subsection}
\par
 The zoem doc macros provide arbitrarily deeply nesting sections.
 This silly section is a level 3 section.

\sec1{toc}{Table of Contents}

\"doc::maketoc"

\sec1{nutshell}{Zoem in a nutshell}

\par
 Zoem was first used for generating manual pages and FAQ documents in both HTML
 and troff from the same source.  A table of contents is automatically added if
 desired and cross-references show up as links in HTML.

 This functionality is not directly supported by Zoem; it is obtained by
 assembling Zoem primitives into higher-level units. These particular units
 comprise one possible set of Zoem man or FAQ macros.  Normally, not a single
 zoem primitive is encountered in a zoem manual page or FAQ - it should consist
 of high-level macros only.  The largest part of this manual is concerned with
 the zoem primitives and how to assemble them into macro packages that
 facilitate mapping input to different devices.

\par
 A \iref{hello}{simple hello world example} shows the basic idea behind zoem.
 For an example manual page view (in this document) \iref{manzoem}{the zoem
 source}, \iref{manhtml}{the rendered html resulting from that source}, and
 (external document) \aref{buzzz.ps}{the rendered PostScript compiled from the
 troff source compiled from the zoem source}. An annotated
 list of the manual macros is given in the
 \sibref{../mac/man_zmm}{man_zmm manual page}.

\par
 Zoem supports several programming constructs, immediate and postponed
 expansions, stream character filtering, easy I/O facilities, integer
 arithmetic, and a whole lot more.
 Its four main aims are:

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
   {align}{right}
}
\item
   Providing the building blocks for a structural and programmable approach.
   \iref{features}{Section \refnumber{features}}
   contains an overview of the zoem primitives and their use.

\item
   Accepting a pleasant syntax that does not require much thinking,
   favouring simplicity and rigor over looseness and context dependent
   rules.

\item
   Creation from the keyboard while minimizing on key-strokes.

\item
   Few meta characters. Zoem achieves this by having a single first-level
   meta character.

\item
   Adding filtering capabilities so that multiple devices can be
   addressed.

\end{itemize}

\par
 Zoem's biggest advantage: you can accomplish almost anything you
 want. One price you pay is that the source document must obey zoem syntax.
 One price that you \it{don't} pay is that zoem is not a mark-up language in
 itself. Zoem knows nothing whatsoever about paragraphs, lay-out, font
 weights, slant, sections, and headers.
 There are two sides to this.

\par
 On the one hand, \it{every} aspect of authoring has to be encoded somewhere,
 e.g. lists, verbatim environments, et cetera. Making this work for multiple
 devices can be quite challenging.

 You have to teach zoem, or perhaps somebody else has already taught it
 before, or perhaps someone has already done something similar that only
 needs a little adjusting.  Zoem distinctly enables and promotes reuse and
 the creation of macro packages.  All the same, making a zoem paragraph macro
 or a zoem boldface macro and mapping those to both html and troff is quite
 easy; making a general purpose zoem list macro and mapping \it{that}
 is a lot more difficult.

\par
 On the other hand, this difficulty is exactly what makes most authoring
 solutions for multiple devices fail somewhere.  By keeping authoring issues
 out of the core zoem language, and focussing on small and powerful building
 blocks, zoem makes the playing field very large. If two devices
 support the same kind of authoring construct, then you really should
 be able to unify them in zoem.

\par
 One can (and should) isolate device specific instructions from
 authoring specific instructions, and those should again be encapsulated
 in macro packages.

 Reuse is essential: I use the same set of zoem man macros for
 all the manual pages that I write. The macro definitions themself
 are not too pretty (nor horrid) to look at, but the zoem source
 for the manual pages themself (importing the macros) looks a lot
 like TeX and may even be somewhat easier on the eye.

\par
 In general, low-end macros have to be defined and mapped onto each output
 device.  Device-specific macros must be written by someone whose knowledge
 about output devices matches the desired level of typesetting
 sophistication.  This is a pain on the one hand, on the other hand, this
 will ensure that you succeed in what you are aiming at. Moreover, high-end
 macros generally do not need device-specific instructions, so these need
 only be defined once.

\par
 If the output device has no macro facilities (HTML) or has interesting
 syntax and whitespace restrictions (troff), zoem may be a gain even if you
 need only one device.  It is very easy to (conditionally) include
 device-specific material in the running zoem text itself.

\sec2{itches}{Itches}
\par
 Zoem was created because several of the author's itches were scratched
 by other approaches.

 I disliked existing ways of generating manual pages in both troff and html.
 These are always about converting from one mark-up language to one or more
 others, and they are invariably broken. More often than not it is a hugely
 unwieldy Perl script. Zoem was designed with the explicit goal of device
 forking, and zoem is not a mark-up language. It's a way of \it{creating}
 dummy mark-up languages with a TeX-like syntax. The notion of mapping the
 dummy language to a real mark-up language is built into the very DNA of
 zoem.  For small mark-up languages, such as a (UNIX) \it{manual}
 language or a \it{FAQ} language, this is a feasible approach.

\par
 I was inspired by the leaden-footed approach of the SGML/XML/DocBook setup,
 which makes me nearly crave for a GUI because the typing is so cumbersome,
 with tags all over the place and no good macro facilities.
 That does something to a vim/tex/mutt/nn user, wondering whether he
 should use a GUI for flushing his writings. It's more like pulling a leg
 than scratching an itch.
 \bf{I need to type my documents and I need to have powerful macro
 facilities} \- as I need semantic mark-up that will do
 multiple things at the same time.

 So I disagree somewhat with what demigod James Clark (of groff, expat,
 SP, and XML fame) has to say about this:

\begin{quote}
   One lesson I drew from TeX and groff is that you want a real programming
   language, not a macro processing language. When you look at the thousands of
   lines of TeX macros or troff macros that people produce, it's a monument to
   the human intellect, but it's not really the right way to solve the problem.
\end{quote}

\par
 For my everyday document, I don't think I need something that has all the
 generality, power, and inconvenience of attribute grammars and feature
 structures mixed with relational databases.
 Of course, using zoem to output XML is a very viable option - for my everyday
 document again, I do understand that publishers and the likes have different
 needs.

\par
 I was inspired in a positive way by the TeX syntax and design.  TeX really
 enables the rapid creation of documents over which the creator is able to
 maintain powerful control by creating his own \it{semantic} mark-up -
 I am not even mentioning TeX's superb typesetting capabilities here.
 Zoem syntax
 was copied in a \iref{nomenclature}{modified form} from TeX (please note
 that zoem is absolutely infinitesimal in aim and scope [then perhaps note
 that zoem's macro facilities go a lot further]).
 
\par
 Then there is troff, the language I would love to love.  The more I get to
 know it, the more I marvel at its insane syntax. It goes much deeper than just
 being terse. It is, with all due respect, plain raving mad at all levels.  I
 know, it was conceived by the Egyptians in the age when papyrus was at an all
 time scarcity high.  But hey, how can anyone in their right mind and of their
 free will enter a document in raw troff as we speak?  I am not being fair
 though, and must admit being awed by people who write their books in troff
 (they probably hand-assemble the circuitry of their computers as well).
 Troff \it{is} very powerful, and it has a charm very much missed by the
 following listee.  The zoem macros map to troff macros that are really
 somewhat feeble and totally wanting of troff's true might. That is the price
 for using troff as a dumb mark-up device (as most of the clever stuff is done
 inside the zoem macros).

\par
 Finally, info was a big itch on its own. If ever I saw an attitude problem
 matched only by the absence of achievement (that's a gripe about info, not
 texinfo, mind you). Admittedly, RMS is a giant and me just a dwarf squashed
 beneath his feet, which may explain why I cannot look any further.  Count me
 in with all the other dwarfs squeaking they don't like info one bit.

\: A notable feature is the distinction between device space and plain space
\: or content space.

\sec2{}{Examples}
\par
 The zoem man macros for the two devices HTML and roff were written by Stijn
 van Dongen and use a straightforward subset of HTML and the troff man macros
 plus a little additional plain troff (thanks go to Jan van der Steen for
 teaching me the first insights).  Zoem input written in these macros yields
 cross-referenced html including a table of contents if desired, while at the
 same time a classic-style manual page can be produced.  The good thing of zoem
 is that you can easily modify, improve, and replace these macros to suit your
 own needs.  The page you are currently reading was created using macros which
 were morphed from the man macros.  See the \capref{hello} and
 \capref{manexample} sections.

\sec2{features}{Expressive power (features)}

\par
 Below you find some features of the zoem primitives. Note that there are in
 practice two kinds of zoem files. The first is a zoem macro file, which should
 contain macros defined in terms of lower-level macros, with zoem primitives at
 the lowest level. The second is a zoem document file, which should import such
 a macro file and only use the high-level macros defined in that macro file.
 Additionally, a document file can define some high-level macros of its own, in
 terms of low-level macros, zoem primitives, or a mixture of both.

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
   {align}{right}
}
\item
   Macros with arguments, overloading of key names allowed (i.e. different
   keys with the same name are distinguished by the number of arguments they
   take). (\pr{def#2}, \pr{set#2}, and \pr{setx#2}).
   Zoem primitives look like regular macros, but
   usually they expand their arguments before use. User macros
   can be equipped with this behaviour by wrapping them in \pr{apply#2}.

\item
   Support for variable number of arguments - see the
   \iref{vararg}{vararg} section.

\item
   Easy file, STDIN, STDOUT, and STDERR input/output,
   nested file inclusion (\pr{dofile#2}, \pr{write#3}, \pr{finsert#1},
   and \pr{zinsert#1}).

\item
   A separate namespace for integer counters.  Extensive support for arithmetic
   with the primitives \pr{let#1}, \pr{f#2}, \pr{f#3},  \pr{fv#2}, and
   \pr{eqt#3}.

\item
   A separate namespace for references. References can have
   up to five members: caption, number, level, type, and misc.
   They are set using \pr{refload#6}, and got using \pr{ref#2}
   (or one of the non-primitives \mc{refcaption#2}, \mc{refnumber#2} etc).

\item
   Operators returning booleans (\pr{defined#2}, \pr{cmp#3}, \pr{eqt#3}),
   control operators acting on those (\pr{while#2}, \pr{if#3}).

\item
   The \it{for}-like primitives \pr{apply#2} and \pr{table#5}.

\item
   Match and substitution capabilities using POSIX regexes (\pr{inspect#4}).

\item
   The switch primitive \pr{switch#2},
   employing the \iref{vararg}{vararg construct}.
   Yes, zoem has a switch statement, and it takes arbitrary expressions too!

\item
   Localized expansions (\pr{eval#1})
   and meta-zoem (\pr{!} and \pr{!#1}).

\item
   A user dictionary stack that can be manipulated using \pr{push#1} and
   \pr{pop#1}.  An environment environment for doing \mc{begin{stuff}} \v{..}
   \mc{end{stuff}} stuff (see \pr{env#3}).  This environment creates name
   scopes by pushing and popping to/from the \iref{dictionary}{dollar
   dictionary stack}. Environments may take arguments,
   one particular useful application is that local variables (e.g. local
   to an \it{itemize} environment) can thus be specified by the user.

\item
   Storage of data by multiple string indexing \- arbitrary data can be stored
   in a tree by indexing nodes with (arbitrary) strings.
   Refer to the \secref{grape} section.

\item
   The ability to nicely format macros (see \pr{formatted#1}).

\item
   \iref{xmlsugar}{Syntactic sugar}
   for writing SGML-style mark-up and having it checked.

\item
   Executing system commands, possibly sending data to STDIN and
   receiving data from STDOUT \- \pr{system#3}.

\item
   And more.
\end{itemize}

\sec2{}{Limitations and difficulties}
\par
 If you want to do arbitrarily complex stuff, it will be difficult
 to map it onto multiple devices. That is true for any system however,
 and zoem can still be very useful for example when you like the TeX
 way of creating documents whereas you need HTML output.

\par
 Tables are notoriously difficult to maintain along multiple devices.  With
 zoem one should be able to aim for a least common denominator.  I have not
 yet attempted to create such a forked table enviroment (which would likely
 benefit from the \pr{table#5} and \pr{apply#2} primitives), mostly because
 tables are neither common nor easily implemented in manual pages that are
 meant to be read in terminals.  The usual approach towards tables in manual
 pages is to use a verbatim environment like so:

\verbatim{\
   .-------.-------.-------.
   |       |       |       |
   |   8   |   1   |   6   |
   |       |       |       |
   .-------.-------.-------.
   |       |       |       |
   |   3   |   5   |   7   |
   |       |       |       |
   .-------.-------.-------.
   |       |       |       |
   |   4   |   9   |   2   |
   |       |       |       |
   .-------.-------.-------.}

\car
 The zoem manual page macros provide a \v{verbatim} environment and a
 \v{verbatix} environment for this. The former will not be split over two pages
 by troff (if it fits on a single page).

\par
 The zoem manual pages posed interesting difficulties when I looked further
 than html under Netscape and troff under groff.  Making things work for both
 Netscape and Internet Explorer (with respect to spacing in lists) and for
 both GNU troff (groff) and other (older and proprietary) troff versions
 (with respect to the \v{verbatim} environment) was interesting, to say the
 least.  Some issues sprang from my own mistakes, and I learned a couple of
 things along the road. Notably the existence of\~\mc{e} and\~\mc{&} in troff,
 and the power of the \v{<div>} and \v{<span>} elements in HTML.  The list
 issue seems unsolvable using orthodox methods, as the list environments are
 broken in different ways and degrees in the various browsers (e.g. mangling
 the margin attributes).  The solution currently in use is that all zoem
 \it{itemize} variants are mapped onto html tables.

\par
 One unfortunate matter is the following. I have become quite attached to
 using \it{italics} in manual pages, as groff does a good job (in terminals)
 of rendering italic text as underlined - when groff produces PostScript it
 will simply render italics of course.  Other and older versions of troff
 seem to render italics by switching to reverse video, which gives a
 horrendous effect.  Beware of this, and avoid italics if you want to
 optimize the worst case user experience.  Another thing is that older troffs
 don't seem to justify paragraphs as groff does.


\sec2{}{Premises and generalizing zoem}
\par
 The usefulness of zoem depends on the  premise that mark-up languages like
 troff, html, and TeX possess certain orthogonality properties.  One such
 property is that environments like lists can be nested freely.
 Luckily this is what everyone expects from a sane mark-up language, and most
 mark-up languages try to be sane. If a language fails to meet this
 requirement, you will have to work within the restricted area of the language
 that \it{does} meet the requirement.

\par
 Zoem's behaviour right now is pretty straightforward.
 It distinguishes \iref{dichotomy}{two kinds of parse scopes}, plain scope and
 device scope. When plain scope is output, any character that is special to the
 output device is translated to the corresponding 'magic sequence' for that
 device.  Zoem has efficient provisions for different levels of magicality and
 the ability to switch between them.  When device scope is output, nothing is
 mapped, and some additional primitives for regulating the output of white
 space are available.  Parse scope is subject to macro expansion; device scope
 is not.

\par
 For example, the zoem manual macros map every period\~'\v{.}' encountered by
 zoem in plain scope onto the sequence '\mc{&.}' [sic], if the output device is
 troff. They map every ampsersand\~'\v{&}' onto the sequence\~'\v{&amp;}' if the
 output device is html.  However, the first example is slightly overdoing it.
 In troff, a dot only has magic powers if it is the first character on a line.
 Zoem currently provides no way of recognizing this kind of subtlety.  The
 natural generalization of the present scope model would be to equip zoem's
 output behaviour with a finite state automaton.  I hope that this will never
 be necesary though, as the simplicity of the present model is gratifying and
 promotes robustness when constructing high-level macros.

\sec2{ecosphere}{Inhabitants of the authoring ecosphere}

\par
 If zoem is not what you are looking for, you might be interested in one of
 the following. The links are to Google searches, as I am lazy and the items
 are in varying states of being supported.

\input{ecosphere.azm}

\par
 Really, the number of inhabitants is stupifyingly mindboggling.  Even when
 restricting attention to proposed solutions for the \it{manual/troff/html}
 problem, there are many applications. A few Net searches turn up
 plenty (more).

\par
 Christopher Browne has a section on macro languages:
 \httpref{http://www.cbbrowne.com/info/macros.html}

\par
 You might also be interested in these Freshmeat sections:
 \aref{http://software.freshmeat.net/browse/853/?topic_id=853}{Text-Processing::Markup},
 \aref{http://software.freshmeat.net/browse/852/?topic_id=852}{Text-Processing::General},
 \aref{http://freshmeat.net/browse/847/?topic_id=847}{Software-Development::Documentation}, and
 \aref{http://freshmeat.net/browse/905/?topic_id=905}{Documentation},

\par
 The Debian text section
 \httpref{http://packages.debian.org/unstable/text/} has many interesting
 entries.


\sec1{hello}{zzello world}

\par
 A not entirely trivial hello world example, featuring the concepts of
 \it{plain scope} and \it{device scope}. The latter should only be seen in
 macro packages. The distinction between these parse scopes is essential to
 zoem, and is thoroughly explained in the \capref{dichotomy} and \capref{dscope}
 sections.  The sequence \mc{@{..}} encloses device scope,
 the sequence\~\mc{:}
 introduces a comment until the end of line. \pr{switch#2}, \pr{def#2},
 and \pr{special#1} are zoem primitives. \mc{__device__} is a normal
 macro conventionally used to divide and rule over different devices.
 The mappings defined by \pr{special#1} live in device scope.

\sec2{}{The macro file}

\par
Say this macro file is named \v{simple.zmm}.

\prule
\verbatim{\
\\: -----------------------------------------------------------------
\\: Stuff such as this belongs in a (reusable) macro file.
\\: \\bf#1 and \\par need device specific sequences.
\\: \\special#1 maps characters with meta meaning in plain scope.
\\: \\@{..} encloses device scope: nothing is mapped therein.
\\: -----------------------------------------------------------------
\\switch{\\__device__}{
   {html}{
      \\def{bf#1}{\\@{<b>}\\1\\@{</b>}}
      \\def{par}{\\@{<p>\\N}}
      \\special{             \\: how to map characters in plain scope.
         {38}  {&amp;}      \\: 38 is ascii character '&'
         {60}  {&lt;}       \\: 60 -> '<'
         {62}  {&gt;}       \\: 62 -> '>'
      }
   }
   {roff}{
      \\def{bf#1}{\\@{\\\\fB}\\1\\@{\\\\fP}}
      \\def{par}{\\@{\\P}}
      \\special{             \\: how to map characters in plain scope.
         {46}  {\\\\&.}       \\: a dot.
         {96}  {\\\\&`}       \\: backquote.
         {39}  {\\\\&'}       \\: quote

         {92}  {\\\\e}        \\: backslash (default troff escape character).
                            \\: escaping by backslash may fail in
                            \\: diversions [for old roffs].

      }
   }
}\
}

\sec2{}{The document file}

\hrule

\verbatim{\
\\import{simple.zmm}
\\def{greet}{\\bf{greetings}} 
\\def{greet#1}{\\bf{hello \\1!}} 
\\def{greet#2}{\\bf{\\1 \\2!}} 

\\: Use the keys just defined. Some kind of overloading there.
\\: the '&' will be automatically mapped and so will '<' and '>'.

\\par
The other day I said \\greet{Venus & Serena},
and they said cheerfully
\\greet{<morning>}{Truman},
give Laura our best \\greet please.}

\sec2{}{The output}

\par
This is the html output:

\verbatim{\
<p>
The other day I said <b>hello Venus &amp; Serena!</b>,
and they said cheerfully
<b>&lt;morning&gt; Truman!</b>,
give Laura our best <b>greetings</b> please.}

\car
which renders of course as
\@{<p>
The other day I said <b>hello Venus &amp; Serena!</b>, and they said cheerfully
<b>&lt;morning&gt; Truman!</b>, give Laura our best <b>greetings</b> please.}

\par
The troff output is not shown here.  You can look at several comprehensive and
much more sophisticated examples in the
\iref{manexample}{\refcaption{manexample}} section.  The output formats shown
in that section are html, PostScript, troff, and plain t(e)xt.

\sec1{cline}{Invoking zoem from the command line}

\par
 You use zoem by invoking it from the command line. The normal mode of
 operation is that you specify a file for zoem to chew up and spit out.  This
 is called the \it{entry file}, and its name usually has the extension
 \v{.azm}.  The other thing you normally specify is the device, which will
 just assign a value to the \mc{__device__} key.
 A common invocation thus looks as follows:
 
\verbatim{zoem -i mcl.azm -d html}

\car
 The \v{-i} flag specifies the entry file and the \v{-d} flag
 sets the \mc{__device__} key. It is not necessary to write the \v{.azm}
 extension, zoem will append it for you. The preceding could also
 have been entered as

\verbatim{zoem -i mcl -d html}

\car
 In either case, zoem will set the session key \mc{__fnbase__} to the base name of
 the entry file, i.e. the name stripped of its \v{.azm} suffix. In this
 example, the key \mc{__fnbase__} will get the value \v{mcl}.  If you have an
 input file without the \v{.azm} extension, you need to use the \v{-I}
 option.

\par
 Zoem writes its output to a default output
 file which is named according to three
 rules.  The rules are:

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
   {align}{right}
}
\item
   If the \v{-o} flag was given the value say \v{somestr},
   zoem will write to the file named \v{somestr}.

\item
   If \v{-o} was not supplied but the \v{-d} flag was used with argument say
   \v{zyx}, zoem will write to the file named \mc{__fnbase__.zyx}.

\item
   If neither \v{-d} nor \v{-o} was given, zoem will write to the
   file named \mc{__fnbase__.ozm}.
\end{itemize}

\par
 It is possible to change the default output file from within the document;
 this is achieved with the \pr{writeto#1} primitive.  Zoem can mingle default
 output with output to other files, use the \pr{write#3} primitive for that.

\par
 Both the \v{-i} and \v{-o} flag accept a hyphen as argument,
 meaning respectively that zoem will read from STDIN and write
 to STDOUT.

\par
 Specifying just zoem and entering a return will cause zoem
 to enter interactive mode, in which it reads from STDIN and writes to STDOUT.
 Interactive mode currently should catch any errors occurring,
 so it is a good way of experimenting and testing.
 By default, interactive mode reads chunks that are ended by a single
 dot on a line by itself. This behaviour can be changed by setting
 the session variable \mc{__parmode__} using the \v{-s} option.
 Using \v{zoem -l parmode} shows the bits that can be set in this variable.
 It is for example possible to make zoem read paragraphs (ended by two
 or more consecutive newlines).

\cpar{NOTE}
 There is a difference between specifying \it{no} output stream
 (i.e. not using the \v{-o} option) and explicitly specifying \v{-o -}.
 In the latter case, zoem will never enter interactive mode. Should
 you need to insert zoem into some pipe sequence, then you need to
 use \v{-o -}.

\cpar{TRACING ERRORS}
 If your document contains erroneous input (e.g. using a macro
 that was never defined), zoem will by default print the approximate
 corresponding line number of the current input file and the last key it saw,
 and then exit.  If that does not suffice in tracking down the error, you have
 a choice of options. One possibility is to use one of the various tracing
 modes described below and in the zoem interpreter manual. Another possibility
 is to specify the \v{-x} option which says to enter interactive mode should an
 error occur. This enables you to inspect the values of keys defined or used in
 the problematic area.

\par
 A selection of other options is given below. For the full story,
 consult \sibref{zoem}{the manual page of the zoem interpreter}.

\: mq
\begin{itemize}


\item{\v{-h}}
   lists all flags accepted by zoem with a short description for each.


\item{\v{-s <foo>=<bar>}}
   Sets key \mc{foo} to \v{bar}.


\item{\v{-e <any>}}
   Zoem will evaluate \v{<any>}, writing any result text to STDOUT,
   and then exit.


\item{\v{-E <any>}}
   Zoem will evaluate \v{<any>}, writing any result text to STDOUT,
   and then proceed.

\item{\v{-x}}
   If an error occurs, zoem stops processing and enters interactive mode.

\item{\v{-l <str>}}
   lists all entities specified by \v{<str>}. It can be any of
   \v{all},
   \v{filter},
   \v{legend},
   \v{macro},
   \v{session},
   \v{trace}, or
   \v{zoem}.

   Repeated use is allowed. In fact, zoem will only check whether
   the target is present as a substring, so

\verbatim{zoem -l legendzoem}

\car
   will print the legend and the list of zoem primitives. 


\item{\v{--trace}}
   This traces (prints) all keys encountered, and  prints
   possibly truncated arguments.
   Zoem has several other tracing flags, use the \v{-h} flag
   or refer to the zoem manual page for more information.

\par
   Tracing can be set from within the document using the
   \pr{trace#1} primitive. Part or whole of the data tree
   can be output from within the document using the \mc{%dump} primitive
   (refer to the \secref{grape} section).


\item{\v{--stats}}
   When zoem is done, it prints statistics about the primitive name
   table and about the user name table.
\end{itemize}

\sec1{syntax}{Zoem syntax and parsing}

\sec2{nomenclature}{Syntax and nomenclature}
\par
 Zoem parses text which may contain zoem \bf{escape sequences}, these are
 sequences that have special meaning and cause zoem to do special
 processing. Each and every escape sequences starts with a backslash, no
 exceptions.  There are three kinds of sequences that are \it{macros}, which
 may or may not take arguments.  These are zoem primitives, user keys, and
 dollar keys.

 There are currently about sixty zoem primitives, these are listed in the
 \capref{language} section. Sixty is quite a lot; it includes oddball
 entries such as \pr{roman#1}, convenience sibling sets such
 as \pr{set#2}, \pr{setx#2}, \pr{def#2}, and \pr{def#2},
 and entries covering a variety of areas such as I/O, arithmetic, testing,
 control, string conversions, formatting, shadowing (scopes), counters, and all
 the other stuff listed in the \secref{topicindex} section.

 User keys and dollar keys are discussed in the
 \capref{macro} section. Arguments are shipped by delimiting them with curly
 braces, as in

\verbatim{\mc{thiskey{takes}{\\bf{two}\\it{arguments}}}.}

\car
 No characters are allowed inbetween (the delimiting curlies of) two
 arguments (but take note of the handy \pr{formatted#1} primitive).  See the
 \capref{macro} section for more information.

 Zoem is very strict in the syntax it accepts, but it \it{garantuees} to
 accept a text in which each backslash \mc{} is escaped as \mc{\\} (i.e. a
 text in which all consecutive runs of backslashes have even length).

\par
 An \bf{active backslash} is any backslash that is not made inactive by an
 active backslash immediately preceding it. The first backslash seen by zoem
 (proceeding sequentially through the text) is active.  This is one
 incomprehensible way of stating the obvious, and I bet you know what I mean
 anyway.  An active backslash must always have a meaning known to zoem.  If
 zoem does not get it, it will complain and exit.  The meaning (i.e. class)
 of the escape sequence introduced by an active backslash is determined by
 the character immediately following it. A list is given below.

\par
 Within arguments, curlies not functioning as argument delimiters must also
 be escaped if they are not balanced. It is best practice to escape all
 non-argument-delimiting curlies, but I never do so myself unless they are
 not balanced.
 
 An \bf{escaped curly} is a curly preceded by an active
 backslash.
 
 An \bf{active curly} is a curly that is not escaped.
 
 A pair of
 \bf{balanced curlies} consists of an active left curly that matches an active
 right curly, where inbetween all escaped curlies are disregarded.
 
 A \bf{block} is anything delimited by balanced curlies.
 
 The word \bf{scope} is most often used to distinguish between \bf{device
 scope} and \bf{plain scope}, these are the two kinds of \bf{parse scopes}.

 An \bf{environment scope} refers to the stuff enclosed by instances of the
 \pr{begin#2} and \pr{end#1} primitives.

 So called \bf{name scopes} are entered and exited by \pr{push#1} and \pr{pop#1}.

\: \par
\: A macro invocation is started with an active backslash, followed by an
\: admissible macro name. This can be either a zoem primitive, or a
\: user defined macro. The next section defines which names are
\: admissible. This macro invocation (the active backslash followed
\: by the macro name) can be followed by one or more blocks.

\sec2{escape}{List of escape sequence classes}
\par
 This is a list of escape sequence classes recognized by zoem, indexed
 by the (set of) character(s) triggering the class(es) \- this assumes
 that the character in question is preceded by an active backslash.

\begin{itemize}


\item{\v{$[_a-zA-Z]*}}
   [dollar key]
   A sequence starting with a dollar sign possibly continued with
   underscores and alphanumeric characters.  Introduces a dollar key. No
   dollar signs are allowed in the remainder, and the first non-alphanumeric
   non-underscore character terminates the sequence.  The primary use of dollar
   keys is that they are set by \pr{begin#2} and \pr{end#1}.  Dollar keys live
   in the dollar dictionary stack, which is pushed and popped by \pr{begin#2}
   and \pr{end#1}.  Nested \v{begin/end} scopes can thus safely associate
   different values with the same key name.  Refer also to the \capref{macro}
   section, the \capref{language} section, and the \capref{dictionary} section.

   \par
   Note: \pr{$#2} is a zoem primitive.


\item{\v{[_a-zA-Z][_a-zA-Z0-9]*}}
   [user key/zoem primitive]
   A sequence starting with an underscore or an alphabetic character, with
   only underscores and alphanumeric characters in the remainder.  Introduces a
   user key or a zoem primitive.  The first non-alphanumeric non-underscore
   character terminates the sequence.  These keys live in the \it{user
   dictionary stack}, which the user can control with the \pr{push#1} and
   \pr{pop#1} primitives. Refer also to the \capref{macro}, \capref{language},
   and \capref{dictionary} sections.

   \par
   A sequence consisting of a single underscore (i.e. not followed
   by an alphanumeric character) introduces an
   \iref{anonymous}{anonymous key}.

\item{\v{"}}
   [user key]
   Starts a user key, which is only different from the user keys mentioned
   above in that it looks different. The sequence is terminated by
   a closing\~\v{"}. Inbetween, anything is allowed except
   a backslash or curly. This is used for creating mnemonic names such as 

\verbatim{\
   \\"man::author"
   \\"man::section"
   \\"man::version"
   \\"html::title"
   \\"html::charset"}

   These keys live in the \it{user dictionary stack}.
   See the \capref{macro} section and the \capref{dictionary} section.

\item{\v{%}}
   [grape key]
   A sequence starting with a percent sign. The percent sign is
   followed by a number of scopes. This is used to access multi-dimensional
   data storage. Such data is stored using the \pr{def#2}  primitive or one
   of its siblings.

\item{\v{[1-9]}}
   [positional parameter]
   A single (character encoding a) positive digit. The sequence
   backslash followed by digit is called a \it{positional parameter}.
   It is only interpreted in the second argument of \pr{set#2}, \pr{setx#2},
   \pr{def#2}, and \pr{defx#2}, and in the definition part of an
   \iref{anonymous}{anonymous key} (which can be an argument to \pr{apply#2}
   and \pr{inspect#4}). In all these instances, the sequence denotes a
   positional parameter into which the corresponding argument will be
   interpolated when a key with arguments is used. It is allowed in other
   places though, as it is possible in zoem to create key definitions
   dynamically (see e.g.  the \pr{setx#2} primitive).
   \bf{NOTE} during interpolation, positional parameters that are enclosed by
   the \it{delay scope} \v{\\!{..}} will not be interpolated (see \pr{!#1}).
   The status of this feature is not entirely clear.

\item{\v{<newline>}}
   [strip newline] The newline will be stripped during the
   interpretation stage. If you want the newline to be stripped during
   the file-read preprocessing stage use the sequence \v{\\:/},
   which is a special case of the comment sequence (see below).

\item{\v{:}}
   [preprocessing sequence]
   There are a few preprocessing sequences, which are evaluated during file
   read (cf the \capref{fileread} section).
   The most important preprocessing sequence is simply the sequence \mc{:}
   followed by whitespace, an alphanumeric character, or a backslash. It
   introduces a comment up till and excluding the next newline, which is
   stripped.

\item{\v{|}}
   [zoem glyph]
   Comprises a special two-character sequence that can be given a
   device-specific meaning. It is customarily used to encode a line break. To
   zoem, this sequence is more or less the same as a 'normal' character. See
   the \pr{special#1} primitive.

\item{\v{~}}
   [zoem glyph]
   It is customarily used to encode a non-breaking space. See the entry above.

\item{\v{-}}
   [zoem glyph]
   It is customarily used to encode a long dash. See two entries back.

\item{\mc{}}
   [backslash] Denotes a literal backslash.

\item{\v{\{}}
   [left curly] Denotes a literal left curly.

\item{\v{\}}}
   [right curly] Denotes a literal right curly.

\item{\v{*}}
   [glyph sequence] Starts a glyph sequence or constant sequence.
   Refer to the \capref{dscope} section and to the \pr{constant#1} primitive.

\items{
   {\v{<}}
   {\v{>}}
}
   [syntactic sugar]
   This introduces syntactic sugar for directly writing SGML-style mark-up,
   such as HTML and XML (e.g. DocBook).
   Refer to the \iref{xmlsugar}{anchor section} for that topic.

\item{\v{@}}
   [at scope] \it{Typically seen in macro package files only}.
   Starts a special instance of device scope called \it{at scope}.  The
   sequence\~\mc{@} \it{must} immediately be followed by a pair of balanced
   curlies, so at scope always appears as \mc{@{..}}.  Refer to the
   \capref{dichotomy} and \capref{dscope} sections for more information.

\item{\v{&}}
   [and scope] \it{Typically seen in macro package files only}.
   May only be used within device scope, and implements a limited
   form of macro expansion within that scope.
   The sequence\~\mc{&} \it{must} immediately be followed by a pair of balanced
   curlies. so and scope always appears as \mc{&{..}}.  Refer to the
   \capref{dichotomy} and \capref{dscope} sections for more information.

\item{\v{`}}
   [back quote - formatting escape]
   \it{Typically seen in macro package files only}.
   Starts a formatting sequence (that is terminated by another\~\v{`}).
   This is only recognized within the \pr{formatted#1} primitive.
   This primitive removes all literal whitespace it encounters in its
   argument; the formatting sequences are transformed to the
   whitespace character encoded by them.

\item{\v{,}}
   [comma - atomic separator] \it{Typically seen in macro package files only}.
   This is interpreted during filter time, and is
   always mapped to nothing. Use it for glueing things as in \mc{foo\\,1},
   which will result in \v{theresultoffoo1}.

\item{\v{!}}
   [delay sequence] \it{Typically seen in macro package files only}.
   Introduces a zoem meta sequence.  Such a sequence consists of a maximal run
   of consecutive backslashes, possibly followed by a single block.  It can be
   used to delay interpretation during any number of interpretation stages, and
   is useful to delay interpretation, perhaps even in a nested fashion, for
   arguments in keys such as \pr{apply#2} that expand one or more of their
   arguments before use.  The run of exclamation marks (or 'bangs' as they are
   internally called) actually comprises an argument to the underlying
   primitive, so the two primitives (one taking a single block argument)
   internally have respective signatures \v{!#1} and \v{!#2}.  Externally
   though, they are just refered to as \pr{!} and \pr{!#1}.

\item{\v{=}}
   [inline files] \it{Rarely used feature}.
   Starts either a sequence of the form \mc{={fname}}, which begins a so called
   inline file named \v{fname}, or a sequence of the form \mc{==}, which
   ends such an inline file. Refer to the \capref{fileread} section.

\end{itemize}

\par
 This leaves \v{0'()[]?^#/.;} for future use, hopefully
 very few of these will ever acquire meaning.
 If the sequence\~\mc{#} acquires meaning, it will probably be for encoding
 Unicode scalar values.

\sec2{stages}{Parsing stages}

\par
 Parsing is separated into three stages, conceptually.
 Zoem knows two different parse scopes, plain scope and device scope.
 These are mentioned below, and explained in the \secref{dichotomy}
 section. The three stages are:

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
   {align}{right}
}
\item
   File read

\item
   Macro expansion / file inclusion - only plain scope is seen.

\item
         Filtering - both plain scope and device scope are filtered.
            Device directives that lay hidden in device scope
            are interpreted during output.
\end{itemize}

\par
 In reality, as soon as a piece of text is no longer subject
 to the second stage, it is immediately filtered and output.

\par
 Macro expansion is done recursively. Whenever a macro is encountered, it is
 replaced by its expansion, and the result is again fed to the parser.
 Evaluatation is not necessarily lazy, that is, during macro expansion the
 expander may expand arguments before they are interpolated and substituted in
 the macro definition. This inside-out evaluation can recurse if necessary.
 Many zoem primitives evaluate one or more of their arguments before use. The
 default behaviour for user macros is lazy evaluation. This can be changed
 however by wrapping both the macro and its arguments in \pr{apply#2}.
 Expansion can be delayed using \pr{!} and \pr{!#1}, so different arguments
 can be treated differently.

\par
 Important is that the result from the second stage is still
 valid zoem input.

 If you re-feed it to zoem, file read and macro expansion are usually no-ops
 (unless some interpretation delay-magic was used), and the syntax is
 garantueed to be acceptable to zoem.  This is because device scope is not
 touched during the first two stages, and device specific text (which is most
 likely not conforming to zoem syntax) lies always hidden in that scope. There
 are three kinds of escape sequences introducing device scope; these are
 described in the \secref{dscope} section.

\par
 This is used for example when creating a table of contents; you can write
 expanded but unfiltered content to a file and read it in during the
 following run. It is important that such content is fully expanded,
 because you want things like index numbers and references as
 they are at the time of macro invocation. It is equally important that what
 you read back in is still valid zoem  input; this is simply achieved by
 witholding filtering. When the table of contents is read in, it can be
 subjected to filtering, and this is the right way to do toc stuff in Zoem.


\sec2{fileread}{File read}
\par
   File read - stripping comments, reading inline files.

\par
   Zoem searches for files included via
   \pr{dofile#2} or one of its aliases in a number of places if
   it cannot find the file in the current directory.
   The precise way of searching is documented in section \secref{searchpath}.

\begin{itemize}{
   {compact}{1}
}

\item{\mc{:}}
   In most cases, this sequence introduces a comment, namely
   where it is followed by whitespace, an alphanumeric character, or a
   backslash. It introduces a comment up until and excluding the next newline,
   which is stripped.

\par
   The sequence  \v{\\:/} introduces a comment up till and including
   the newline. This feature can be
   useful within the \pr{protect#1} primitive, as it is the only way to delete
   actual newlines within the argument of that primitive.

\par
   The sequence  \v{\\:!} is replaced by a backslash. The single
   use currently known is to make it easy to quote zoem input containing
   comment sequences. This

\verbatim{\\foo
   \\bar  
   \\zut     \:!\:!:  this will end up as a comment.
}

\car
   will result in the following

\verbatim{\\foo
   \\bar  
   \\zut     \:!\:  this will end up as a comment.
}

\set{$compact}{0}
\item{\mc{={fname}}}
   starts inline file named fname at the next line,
   removes remainder of line after the \mc{={fname}} sequence.
   When using the \pr{dofile#2} primitive or one of its
   four aliases, an inline file takes precedence over regular files
   in the file system, whether it is present (as a regular file)
   or not. See below. This feature can be used to ship zoem
   input in one piece while putting the macro parts at the end.
   Currently, \pr{finsert#1} and \pr{zinsert#1} cannot refer
   to inline files.

\par
   The future will probably bring a zoem option that creates
   such a self-contained file automatically from the zoem
   entry file.
\set{$compact}{1}


\item{\mc{==}}
   ends inline file, removes remainder of line.
\end{itemize}

\par
 The above applies to any file read at any stage.  Inline files may occur in
 any file included at any time, but they do not nest.

\par
 The \it{zoem entry file} is the single file that is specified
 on the command line. This is the main file, from which other
 files can be included if desired.

\par
 Zoem entry files usually have the extension \v{.azm}, which is memnonic
 for \bf{A ZoeM} file.  This is required if the \v{-i} option is used.
 Arbitrary entry file names can be specified using the \v{-I} option.
 It is not uncommon to generate sibling files with
 \v{.roff}, \v{.html}, \v{.zmt} (zoem table of contents), and
 \v{.zmr} (zoem references) extensions \- however, this is all configurable
 in user space and not part of zoem itself.  There are no restrictions on
 names of files that are included from the entry file. Inclusion is done
 recursively.

\par
 The future will probably bring a second extension that is allowed,
 namely \v{.ezm} for \bf{Expanded ZoeM} file, which is a self-contained
 file in which every included file is present as an inline file.

\sec2{searchpath}{File search path}

\car
   If zoem cannot find a file in the current directory, it attempts
   to find the file in one of three different ways. These are,
   in the order  in which they are attempted:

\begin{itemize}{{align}{right}{compact}{1}}
\item
   The environment variable \v{$ZOEMSEARCHPATH} is checked. It may
   contain a listing of paths separated by whitespace or colons.

\item
   The zoem variable \mc{__searchpath__} is checked. It must contain a listing
   of paths stored as a vararg, i.e. a sequence of paths where each path is
   delimited by curly brackets.  \bf{DO NOT} overwrite this variable, but
   rather append or prepend to it. Most likely zoem was configured and compiled
   locally on your system, in which case \mc{__searchpath__} contains the path
   necessary to find the macro packages \v{man.zmm}, \v{faq.zmm}, and
   \v{doc.zmm}.

\item
   The path of the file currently being parsed is used.
   Assume that file \v{foo} contains \mc{import{/a/b/c/bar}}.
   If file \v{bar} wants to include file \v{zut}, which is in
   the same \v{/a/b/c/} directory, it need not prepend a path
   but can just issue \mc{import{zut}}. Should the
   previous search mechanisms fail to find zut, then zoem will
   as a last resort deduce the path from \v{/a/b/c/bar}.
   This feature is probably rarely needed, if ever at all.

\end{itemize}
   

\sec2{macro}{Macro expansion}
\par
 Macro expansion consists of recursive file inclusion and macro expansion.

 All zoem primitives and user keys are recursively expanded
 until none remains. Zoem primitives and user keys take one
 of the following forms:

\begin{itemize}

\item{\mc{abc_0123_}}
   A key with alphanumerics and underscores only. Ends with
   any other character. All zoem primitives but one have this form.
   
   \par
   Note: \mc{_} denotes an anonymous key, see the \capref{anonymous} section.

   \par
   These keys live in the \it{user} dictionary stack. Initially, there is
   only one dictionary. The stack can be manipulated using the \pr{push#1}
   and \pr{pop#1} primitives.


\item{\mc{"abc::def-ghi.jkl,mno+qrs"}}
   A quoted key. Almost anything inbetween quotes is allowed. Always
   ends with a quote. No zoem primitive has this form.
   These keys live in the same \it{user} dictionary stack
   as the keys above.


\item{\mc{$abc_0123_}}
   A key introduced with a dollar sign. The name may further consist
   of alphanumerics and underscores and it ends with any other character.
   These keys live in the \it{dollar} dictionary stack.
   A dictionary is pushed with every occurrence of
   \pr{begin#2}, and that dictionary is popped with the corresponding
   occurrence of \pr{end#1}.

   \par
   Further note: \pr{$#2} is a zoem primitive.
\end{itemize}

\par
 All three types of keys may take arguments, and overloading is allowed:

\verbatim{\
   \\foo                          \\: signature foo
   \\foo{bar}                     \\: signature foo#1
   \\foo{bar}{bop}                \\: signature foo#2
   \\$foo{bar}{baz}               \\: signature $foo#2
   \\"foo::oof"{zut}{zit}{zot}    \\: signature "foo::oof"#3}

\car
 is an ensemble of valid and unique keys, which can be defined for
 example by

\verbatim{\
   \\def{foo}{FOO}
   \\def{foo#1}{The FOO of \\1}
   \\def{foo#2}{The FOO of \\1 and \\2}
   \\def{$foo#2}{The $FOO of \\1 and \\2}
   \\def{"foo::oof"#3}{\\foo{\\1}{\\2}\\foo{\\2}{\\3}}}

\car
 Additionally, zoem allows the definition of \it{constant keys} that map
 directly into device space and are ignored during macro expansion. Usage of
 such keys looks like \mc{*{'e}} or \mc{*{(c)}} and is detailed later on.

\par
 A sequence\~\mc{k} where k is in 1-9 is allowed within anonymous keys (as used
 for example in \pr{apply#2} and \pr{inspect#4}) and in the definition argument
 of the \pr{def#2} primitive and its siblings \pr{defx#2}, \pr{set#2}, and
 \pr{setx#2}.  It indicates the position(s) where arguments should be
 interpolated.
   \bf{NOTE} during interpolation, positional parameters that are enclosed by
   the \it{delay scope} \v{\\!{..}} will not be interpolated (see \pr{!#1}).
   The status of this feature is not entirely clear.

\par
 A feature that should only rarely be needed is that zoem allows
 name scopes. Refer to the \capref{dictionary} section.

\sec2{}{File inclusion}

\par
 There is one zoem primitive which has four different uses. For each
 of those uses, an alias exists.

\verbatim{\
\\dofile#2 use      alias          meaning

\\dofile{expr}{!+}  \\input{expr}   require file, interpret and output
\\dofile{expr}{!-}  \\import{expr}  require file, interpret only
\\dofile{expr}{?+}  \\read{expr}    permit absence, interpret and output
\\dofile{expr}{?-}  \\load{expr}    permit absence, interpret only}

\car
 The \pr{dofile#2} primitive and its four aliases are perhaps a little funny
 interface-wise \- better ideas are welcome.  The \v{expr} argument is
 \it{digested}, that is, expanded until no macro's remain. It is thus possible
 to specify \mc{__fnbase__.zmt} and include a table of contents file that has
 been written to in a previous run.  \pr{dofile#2} and its aliases have the
 property that zoem really descends into the files, and on error will emit a
 message containing the approximate line number where it occurred.

\par
 Additionally, the contents of a file can be placed inline using
 \pr{finsert#1} and \pr{zinsert#1}.

\par
 Note: wherever \v{key} is written, it means that something
 of the form \mc{foo}, \mc{$foo}, or \mc{"foo"} has to
 be provided, so you would use \pr{setx#2} e.g. as
 \mc{setx{foo}{\\finsert{\\__fnbase__.zyx}}}.


\sec2{protection}{Protection}

\par
  The \pr{dofile#2} primitive requires that the files to be  included
  satisfy zoem syntax. It will descend into the files and proceed parsing
  them.

\par
  The \pr{finsert#1} and \pr{zinsert#1} primitives do not descend,
  but rather act as if the contents of the file specified were pasted
  into the place of macro invocation.

\par
  \pr{finsert#1} will \it{protect} the contents of the inserted file,
  that is, all backslashes and curlies are escaped by preprending
  them with a backslash.
  \pr{zinsert#1} will include the file unchanged, assuming that its
  contents satisfy zoem syntax.

\par
  The \pr{system#3} primitive is able to pipe data to a system command's
  STDIN stream and retrieve data from the command's STDOUT stream.
  This primitive will \it{unprotect} the data it sends, and it will
  protect the data it receives.
  \bf{NOTE} the security implications of this feature
  as discussed at the \pr{system#3} entry.

\par
  Data can be explicitly protected using the \pr{protect#1} primitive.

\par
  Protected data can (currently) never result in it being expanded
  again. This is because escaped backslashes are only interpreted
  at filter time, and never during expansion.
  If you only need \it{temporary} delay of expansion, use
  the \pr{!} primitive or the \pr{!#1} primitive.

\sec2{dichotomy}{Scope dichotomy}
\par
 Zoem knows two parse scopes: \bf{plain scope} and \bf{device scope}.  The
 latter is also called 'at scope' because \mc{@{..}} is one (but not the only)
 way of entering device scope. In plain scope, every character
 represents itself as a glyph, i.e. as something that should show that way in
 print/on screen (after the zoem output/device input is fed to the device
 interpreter).

\par
 For example, if you write the less than sign\~\v{<} in plain scope,
 it should show up as a readable less than glyph, like in
 this very sentence. In order to make this happen, zoem provides
 the \pr{special#1} primitive, so that the less than sign can be
 automatically mapped to the html entity sequence \v{&lt;}.

\par
 In device scope, nothing is mapped except for a double backslash should it
 occur.  If you enter this particular sequence of mixed scope:
 \mc{@{<b>}<hello world>\\@{</b>}} as zoem input,
 the zoem output/device input is (provided the \pr{special#1}
 primitive was correctly used for the html device):
 \v{<b>&lt;hello world&gt;</b>}
 and what you finally see on screen is:
 \@{<b>}<hello world>\@{</b>}.
 In device scope, every character (except for the escape sequences available
 in that scope) represents itself as the ASCII character that should be
 present in the zoem output/device input.  Device scope should normally only
 be seen in macros and not in running zoem input.

\par
 In plain space you type characters just as you want to see them eventually
 \- when you read the document after the zoem output was run through a device
 interpreter (such as a browser or printer, or postscript previewer).
 The only exceptions are the backslash and the two curlies, these should
 be entered as\~\mc{\}}, \mc{\{}, and\~\mc{\}}, respectively.
 Those escape sequences are interpreted as the characters or glyphs
 \mc{}, \v{\{}, and\~\v{\}}.  For all characters, including these
 three, it is checked whether they should be further mapped according to the
 \pr{special#1} primitive. If a mapping is found, it is retrieved
 and interpreted by the device scope filter. Read on.

\sec2{dscope}{Device scope}

\par
 There are three kind of strings which are interpreted by the
 generic device filter, and which are said to live in device scope:

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
   {align}{right}
}
\item
   The strings embedded in \mc{@{..}} sequences.\|

\item
   The strings mapped to by the \pr{special#1} primitive, including
   mappings of the zoem glyphs\~\mc{~}, \mc{|}, and\~\mc{-}.

\item
   The strings mapped to by the \pr{constant#1} primitive.
\end{itemize}

\par
 In a macro package that is meant to work for multiple devices, every use of
 any of these constructs will typically be embedded in something that tests the
 value of the active device.  This can be done using either
 \pr{cmp#3} with \pr{if#3},
 \pr{switch#1}, or \pr{$#2}, in conjuction with the pre-defined zoem key
 \mc{__device__}, containing the name of the active device (which can be
 specified on the command-line).  The following are equivalent:

\verbatim{\
   \\if{\\cmp{eq}{\\__device__}{html}}{ \\@{<!-- (c) foo bar -->} }{}

   \\: is equivalent with

   \\${html}{ \\@{<!-- (c) foo bar -->} }}

\car
 The \pr{$#2} primitive is used if something needs to be done for one
 device only, and it may occasionally appear in documents.  For example, the
 zoem man macros enable the creation of a table of contents (for both html
 and troff).  My own convention is to have a table of contents only in html,
 and I specify this using the sequence

\verbatim{\mc{${html}{\\"man::maketoc"}}}

\car
 When zoem enters device scope, it
 outputs all characters literally, except that the backslash still has
 special meaning. It is used for encoding the backlash itself (as
 \mc{\\}), and for encoding the two curlies\~\v{\{} and\~\v{\}} (as
 \mc{\{} and\~\mc{\}}).  This is the same as in plain scope (except that
 in plain scope the resulting character may again be mapped onto something
 else, for example, in troff the backslash also needs encoding as
 \mc{\\}).

\par
 In device scope the sequence\~\mc{"} maps to a double quote.
 This is an additional feature to allow zoem input to be more susceptible to
 some editors moving features.  It is not \it{necessary} though; simply using
 the double quote without escaping it is sufficient.

\par
 Additionally, the backslash can be followed by a single letter from a
 prescribed set listed below.  Such a backslash+letter combination is called a
 \it{device directive}.  By default, zoem will never print consecutive
 newlines, and it will never print consecutive spaces or spaces at the
 beginning of a line.  The device directives allow this to be altered.

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
}
\item{N} garantuee a newline
\item{P} garantuee a paragraph skip (two consecutive newlines)
\item{S} garantuee a space (except if next char is newline)
\item{I} increase indent by one (indent is printed after each newline)
\item{J} decrease indent by one
\item{C} set indent to zero
\item{n} print newline
\item{s} print space
\item{t} print tab
\item{w} stop managing white space (squashing spaces and newlines)
\item{W} start managing white space (use after\~\v{w})
\item{&} start \it{and} scope (see further below)
\item{+} set the special level (see further below)
\end{itemize}

\par
 Note that the directives mainly affect the lay-out of the device text (which
 is zoem output), not the look of the interpreted device text.  The '\v{N}'
 directive is rather important when constructing troff macros, as many
 special troff commands are encoded by a dot as the first character on a
 line, i.e. a newline followed by a dot. Since troff attaches special meaning
 to two consecutive newlines as well (interpreting it as a paragraph break),
 zoem needs to be able to specify \it{print a newline only if the previous
 character was not a newline}. This is exactly what the \v{N}\~directive
 means.  The '\v{W}' and '\v{w}' directives are required for enabling
 the construction of a verbatim environment.

\par
 The sequence \mc{&{<almost any>}} can be used to avoid
 overly cumbersome constructions. It is for example illegal
 to write

\verbatim{\protect{\@{<table width="\width">}}}

\car
 In the early days of zoem, you had to write

\verbatim{\protect{\@{<table width="}\width\@{">}}}

\car
 \- ugly by most standards. Today you write

\verbatim{\protect{\@{<table width="\&{\width}">}}}

\car
 Which is not any shorter, but more pleasant to read.
 What happens is that the contents of \it{and} scope \v{\\&{..}} is first
 fully expanded in plain scope, after which the result is passed back to
 device scope.  You have to be careful though.  The content of \v{\\&{..}}
 should never expand to something containing the \it{at} sequence \v{\\@{..}},
 because device scope is not allowed to nest.  It should also not expand to
 something containing the \it{and} sequence \v{\\&{..}} either, as this
 sequence is illegal in plain scope.

\sec3{special}{Device scope resulting from mapping special characters}
\par
 The first kind of zoem escape introducing device scope is \mc{@{..}}.
 The second kind comprises the \pr{special#1} mappings, including the
 three zoem glyphs\~\mc{~}, \mc{|}, and\~\mc{-}. Conventionally, these
 are used to encode a non-breaking space (\v{&nbsp;} in html), a line break
 (\v{<br>} in html), and a long dash (emdash, not present in html).
 You would for example put

\verbatim{\
\\if{\\cmp{eq}{\\__device__}{html}}{
   \\special{
      {38}  {&amp;}           \\: 38 is ascii character '&'
      {60}  {&lt;}            \\: 60 -> '<'
      {62}  {&gt;}            \\: 62 -> '>'
      {256} {&nbsp;}          \\: the zoem escape \\~
      {257} {<br>\\N}          \\: the zoem escape \\|
      {258} {-}               \\: the zoem escape \\-
   }
}{  
}\
}

\car
 All \pr{special#1} definitions are interpreted in device scope. For every
 character encountered in plain scope, it is checked whether a
 \pr{special#1} definition exists, if so, the corresponding string is
 retrieved and this is filtered through the device scope filter.
 Note that the three zoem glyphs described here
 may not be used in device scope, they can only be used in plain scope.  In
 device scope you will have to write the explicit, device-specific sequence
 such as \v{<br>} (in html).

\par
 The \pr{special#1} primitive allows different levels of mappings
 to be defined simultaneously. Several definitions of the same
 character are allowed; these are placed on a stack particular
 to that character (cf. the
 \pr{special#1} entry).
 When zoem encounters a character for which
 one or more mappings exist, it retrieves a mapping
 using the \it{special level}. This is an integer that has by
 default the value\~\v{1}. Each open output stream has a unique
 special level associated with it. [Output streams exist
 for the \it{default output file} (see e.g. \pr{writeto#1}) and
 for each file openend by \pr{write#3}].
 A mapping is retrieved using this rule: \it{The deepest element
 is fetched for which the depth does not exceed the level}.
 The most visible element (which is the element first occurring
 in the \pr{special#1} invocation) has depth\~\v{1}.

\par
 The presence of different levels comes in handy e.g. when the troff
 device is used. In some contexts, the double quote
 is a special character in troff (and a printable quote is then
 mysteriously represented by \it{two consecutive double quotes}),
 in most contexts it is not.
 This is combatted by including these two specifications in the
 \mc{special#1} call preparing for troff output (note that 34 is
 the ASCII value representing the double quote):

\verbatim{\\special{
   ...
   {34}{"}
   {34}{""}
   {92}{\\e}
   ...
}}

\car
 The first pair shown simply maps the double quote onto itself, and the second
 pair maps it onto a double double quote.  As long as the special level
 is\~\v{1}, the second definition is not used. The backslash (with ASCII value
 \v{92}) needs only one definition as it is escaped in the same way in all
 troff contexts.

\par
 The special level can 
 be set using the \mc{+}\~directive, which must be followed
 immediately by a digit in the range \v{0-9} enclosed by curly brackets,
 e.g. \v{\\@{\\+{2}}} will set the special level to \v{2}.
 The special level \it{can} be set to\~\v{0} (zero) and this means
 that no character will be mapped.
 
\cpar{Example}
 Whenever a troff context is entered where the quotes needs escaping,
 the controlling zoem macro issues a sequence

\verbatim{\\@{\\+{2}"} ... funny quote context ... \\@{"\\+{1}}}

\car
 Such a macro is typically defined in a package and its definition
 should never be visibile to the user of the package.
 Note that the double quotes embedded in \it{at} scope in the example
 above are not susceptible to special mapping -- mapping is only
 applied in plain scope.
 

\sec3{glyph}{Device scope resulting from glyph definitions}

\par
 The third kind of device scope strings are those mapped to by the
 \pr{constant#1} primitive. An example of (toy) usage is this:

\verbatim{\
\\constant{
   {'e}  {&eacute;}     \\: Use e.g. as \\*{'e}l\\*{`e}ve (\*{'e}l\*{`e}ve)
   {(c)} {&copy;}       \\: Use e.g. as \\*{(c)} DEEDEE (\*{(c)} DEEDEE)
   {+-}  {&plusmn;}     \\: Use e.g. as \\*{+-} a few (\*{+-} a few)
}}

\car
 This is largely convenient syntactic sugar. These constants
 could also have been defined as

\verbatim{\
   \\def{"'e"}{\\@{&eacute;}}
   \\def{"(c)"}{\\@{&copy;}}
   \\def{"+-"}{\\@{&plusmn;}}}

\car
 The idea is that the \mc{*{..}} namespace is used for glyph-like
 device-specific bindings, whereas the \mc{".."} namespace is used for
 semantic purposes that are device-independent, but nothing prohibits you
 from fiddling with this.

\sec2{xmlsugar}{SGML/HTML/XML syntactic sugar cubes}
\par
   Zoem provides a shorthand for entering SGML-style tags.
   It is checked by zoem for well-formedness of the resulting SGML code,
   and it can be freely mixed with other modes of entering tags.

   Normally you would
   have to enter SGML-style tags in device scope,
   or write a macro for doing that.
   For example,
   a macro \v{x#2} that expands \mc{x{b}{be bold}} to
   \mc{@{<b>}be bold\\@{</b>}} is a likely candidate.
   However, this would be inelegant for constructions that span
   a long distance, and it does not provide for letting zoem expressions
   expand within an xml tag.

\par
   Zoem provides the \mc{<}\~and \mc{>}\~tokens.
   The \mc{<}\~token can be used in several ways:

\verbatim{\protect{
   \<foo>            \:!: foo can be an expression.
      Some <content> \:!: of course, expressions may occur here as well.
      over here.
      \<bar>{zut}    \:!: bar can be an expression too;
                     \:!: this syntax will close itself.
      Some <content> \:!: again, expressions may occur here as well.
      over there.
   \<>               \:!: this is a closing tag for the first foo.

   \<tim x=y/>       \:!: zoem knows this closes itself.
   \<br!>            \:!: zoem converts this to <br>}
}

\car
   Suppose that foo, bar, and zut are zoem expressions expanding
   to strings FOO, BAR, and ZUT respectively (FOO and BAR might be of the form
   \v{tag a="b" c="d"}).  Provided that the characters\~\v{<}, \v{>},
   and\~\v{&} are automatically mapped in plain scope (as a result of correct
   \pr{special#1} usage), the above will result in

\verbatim{\
   <FOO>
      Some &lt;content&gt;
      over here.
      <BAR>
         ZUT
      </BAR>
      Some &lt;content&gt;
      over there.
   </FOO>

   <tim x=y/>
   <br>}

\car
   The \v{foo} part inside the \mc{<foo>} syntax should never expand to
   something containing a\~\v{>}. This is entirely the responsibility of the
   user or macro package author.


\par
   Both kinds of syntax, \mc{<foo>} and \mc{<bar>{zut}}, are kept as they are
   during the expansion stage, and they can be subjected to multiple levels of
   expansion (which may be the case if such syntax is used inside e.g.
   \pr{setx#2} or \pr{apply#2}).  It is only at the output stage that the
   syntax is transformed to actual SGML code and that well-formedness is
   checked.  So, the two examples just seen will first transform to \mc{<FOO>}
   and \mc{<BAR>{ZUT}} (please note that foo, bar, and zut all denote
   expressions here). If they are at that point no longer subject to expansion
   they enter the output stage where they are converted to \v{<FOO>} and
   \v{<BAR>ZUT</BAR>} (plus some additional formatting/indenting) respectively.

\par
   Zoem pushes on a stack of opening tags whenever it encounters \mc{<foo>}
   syntax during the output stage. It naturally
   knows that a tag can be followed by attributes.
   It also knows that a tag such as \mc{<tag a=b/>} closes itself (XML syntax).
   As a special case, \mc{<tag foo bar zut!>} is converted to
   \v{<tag foo bar zut>} to allow encoding of HTML tags such as \v{<br>}.
   These two kinds of tags are not considered opening tags.
   Note that you should only use \mc{<p>} if you are going to
   use \mc{</p>} or \mc{<>} as well (because zoem requires closing
   tags for opening tags).

\par
   Zoem does not know about other ways of entering tags, so
   \mc{@{<body>}} would not affect the stack just mentioned.

   \mc{<>} automatically closes
   the top level opening tag from the stack.  Again, syntax such as
   \mc{@{</body>}} does not interact with the stack.
   This is actually useful; I mainly use the \mc{<foo>} syntax
   for more complicated stuff such as nested material in tables (e.g.
   the \iref{toc}{table of contents} in this document).

\par
   It is possible to explicitly close a tag by simply using \mc{</foo>}
   syntax. Zoem will check whether the closing tag matches the top level
   opening tag.  As seen before, \mc{<>} does the same thing, but rather than
   doing a check, zoem will use the top level opening tag to construct the
   corresponding closing tag.  Finally, \mc{>}\~does the same as \mc{<>}.

\sec1{}{Zoem miscellanea}

\sec2{signature}{Key signatures}

\par
 Several keys take another key as argument, e.g. they store a value in a second
 key or check whether the second key exists.  The full list of these meta keys
 is \pr{def#2},  \pr{defx#2}, \pr{set#2}, \pr{setx#2}, \pr{undef#1},
 \pr{defined#2}, \pr{apply#2}, and \pr{inspect#4}. In all cases, the argument
 key is passed as the first argument, by means of the \bf{key signature}.

\par
 For a key \mc{key} taking \v{k}\~(\v{k}>0) arguments its signature is
 \v{key#k}.  The signature of a key \mc{key} taking no arguments is simply
 \v{key}. The rule is: Key usage always includes a single
 leading backslash (this activates the key). When a key is subject
 of inspection, it is always referred to by its signature.

\par
 Throughout this text, a key with signature \v{key#k} is mentioned
 by means of its \bf{key mention} \mc{key#k}, that is, for extra clarity
 the backslash is prepended to the signature.

\sec2{anonymous}{Anonymous keys}

\par
 A single underscore introduces an \bf{anonymous key}.  It is optionally
 followed by a \v{#k} tag (for\~\v{k} in\~\v{1..9}), denoting the number of
 arguments the anonymous key takes. An occurrence of the latter is called a
 \bf{tagged anonymous key}.  The first argument to the key should be a key
 definition, the other arguments are the arguments for that key definition.
 If a tag is present, it is used for verifying that the anonymous key is used
 properly.

\: hierverder: this used to be useful because:
\: This feature may be helpful when an anonymous key is the result of
\: expanding the first argument to \pr{meta#3}.
\:    and now? -- the example below does not work with \!:
\: \begin{vbt}
\:    \\def{foo}{#2{\\1 the \\2}}
\:    \\def{bar}{#3{\\1 the \\2 and \\3}}
\: 
\:    \\meta{_\\foo}{x}{{billy}{kid}}
\:    \\meta{_\\bar}{x}{{william}{fourth}{maxima}}
\:    \\meta{_\\bar}{x}{{william}{fourth}}
\: \end{vbt}
\:
\:  results in
\: 
\: \begin{vbt}
\:    billy the kid
\:    william the fourth and maxima
\: \end{vbt}
\:    
\:  and the third will fail.

\verbatim{\
   \\_{\\1 the \\2}{row}{boat}
   \\_#2{\\1 the \\2}{row}{boat}}

\car
 results in

\verbatim{\
   row the boat
   row the boat}

\car
 Anonymous keys may occur in the first argument of \pr{apply#2}, within the
 first argument of \pr{inspect#4}, and they may occur freely in running text.
 The presence of a tag is required when an anonymous key is used
 within either of \pr{apply#2} and \pr{inspect#4}.
 An example of usage in \pr{apply#2}:

\verbatim{\
\\apply{_#2{\\1 kisses \\2\\|}}{{bill}{max}{max}{bill}}
bill kisses max
max kisses bill}
   
\car
 or even

\verbatim{\
\\set{%foo}{{{\\1 hugs \\2\\|}}}
\\apply{_#2\\%{foo}}{{bill}{max}{max}{bill}}
bill hugs max
max hugs bill}

\car
 Note that in order to store a block with \pr{set#2}, an extra pair of
 curlies has to be used, as blocks can only be passed as a sub-argument of a
 single-element \iref{vararg}{vararg}.  Also note that in a vararg it is
 allowed to put white space inbetween the constituting elements.


\sec2{grape}{Tree data}

\par
 Data can be organized in a global tree with a specialized use of
 \pr{set#2} and its siblings, as shown further below.
 The data is retrieved from the tree using so called grape keys.
 Such a key is started using a percent sign, immediately followed
 by zero, one, or more blocks, e.g. \mc{%}, \mc{%{..}}, and
 \mc{%{...}{...}{...}} would all be allowable invocations.
 If more than one block follows the percent sign,
 there must be no interleaving white space.

\par
 The underlying primitive has signature \v{%#1}, as the trailing scopes are
 congregated into a single argument before they are further processed.  The two
 sibling primitives \v{%free#1} and \v{%dump#1} serve for freeing and dumping parts
 or whole of the tree, as described further below.

\par
 When applied to grape keys, \pr{set#2} and its siblings
 set one or more values in a global multi-dimensional associative
 array that we shall refer to here as \v{ROOT}. Please note that \v{ROOT} is
 for explanatory purposes only. This associative array is best viewed as a
 tree, in which every node can have branches to higher nodes. A node may or may
 not contain a value.

 Let us denote the value contained by a node \v{some-node} as \v{*(some-node)}.

 The fact that \v{beta} is a node one branch higher than \v{alpha}, which is in
 turn one branch higher than \v{ROOT}, is denoted as \v{ROOT->"alpha"->"beta"}.

 In this \it{path} notation, strings indexing nodes in the trees are written
 inbetween quotes. This has the advantage that the empty string, which is a
 valid index string, has the representation \v{""}.  Combining these
 conventions, we write the value associated with \v{beta} as
 \v{*(ROOT->"alpha"->"beta")}.
 
 Consider these examples.


\verbatim{\
\\set{%{foo}{bar}{zut}}{lez}
      \\: now *(ROOT->"foo"->"bar"->"zut") is "lez"

\\set{%{foo}{bar}{zut}}{{a}{b}{x}{y}}
      \\: now *(ROOT->"foo"->"bar"->"zut"->"a") is "b"
      \\: and *(ROOT->"foo"->"bar"->"zut"->"x") is "y"
      \\: and *(ROOT->"foo"->"bar"->"zut") still is "lez"

   \\: some special cases
\\set{%{foo}{bar}{zut}}{{{c}}}
      \\: now *(ROOT->"foo"->"bar"->"zut") is "{c}"
\\set{%{foo}{bar}{zut}}{{c}}
      \\: now *(ROOT->"foo"->"bar"->"zut") is "c"
\\set{%{foo}{bar}{zut}}{c}
      \\: now *(ROOT->"foo"->"bar"->"zut") is "c"

\\set{{foo}{bar}{zut}}{{c}{d}{e}}
      \\: This does nothing, because the second argument
      \\: must either be an *even* vararg, a 1-element vararg,
      \\: or a simple argument.

\\set{%{{tiger}}}{in the woods}
      \\: now *(ROOT->"{tiger}") is "in the woods"
\\set{%{tiger}}{in the woods}
      \\: now *(ROOT->"tiger") is "in the woods"
\\set{%tiger}{on the loose}
      \\: now *(ROOT->"tiger") is "on the loose"
      \\: stripping curlies from a vararg with one argument
      \\: does not make a difference with the exception of
      \\: the case shown below.

\\set{%{}}{empty}
      \\: now *(ROOT->"") is "empty".
\\set{%}{root}
      \\: now *(ROOT) is "root".}

\car
 Take note  of the rule  governing the  second argument. If  the first
 non-white space  character is  a left  curly, \pr{set#2}  expects a
 vararg. The vararg must either be even or it must contain exactly
 \it{one} argument.

 An even vararg is interpreted as a sequence  of key-value pairs.
 Each key  induces a new branch  from the node specified  in the first
 argument, and  each value is associated  with the node at  the end of
 that branch.

 If the vararg contains exactly one argument, that argument is simply used as
 a value.  This is the only way to specify a block as the value.

 If the first non-white space character is not a curly, \mc{set#2} will
 simply interpret the second argument as  a value  to append  to the node
 specified in  the first argument.


\par
 If you want the data to be stored to be expanded before it is bound,
 use \pr{setx#2} or \pr{defx#2}.


\par
 Data is retrieved simply by prefixing the path with the \mc{%} token.
 Example:

\verbatim{\
\\set{%{foo}{bar}{zut}}{{a}{b}{x}{y}}
\\%{foo}{bar}{zut}{a}
\\%{foo}{bar}{zut}{x}}

 will print \v{b} and \v{y}.
 If the path is not an existing path in the current tree it will simply
 be ignored, although an error message will be emitted.

\par
 Whole or part of the data tree can be freed using the \mc{%free} primitive.  Again,
 simply append the access sequence in which you are interested.  For freeing
 the entire tree, use \mc{%free} without trailing scopes.  The \mc{%free} primitive
 largely exists for testing purposes to ensure that zoem gets its internal
 data manipulation right.

\par
 Whole or part of the data tree can be output for debugging purposes using the
 \mc{%dump} primitive. Simply append the access sequence in which you are
 interested.  For printing the entire tree, use \mc{%dump} without trailing
 scopes. This can be used for debugging if your data manipulation does not work
 out as expected.  There is no result text as far as usual processing is
 concerned. The underlying primitive dumps its findings to STDOUT in a
 line-based textual representation of the data-tree.

\par
 The future might bring support for using localized data trees, e.g.
 by means of \mc{push{grape}} and \mc{pop{grape}}.
 It should also become possible to specify the behaviour if a grape
 key access sequence does not exist.

\sec2{vararg}{Of blocks and varargs}

\par
 A \bf{block} is a string beginning with a left curly and ending with a right
 curly, the curlies being balanced.  This is a convenient naming
 convention. Blocks can be used in constructing anonymous keys; refer to the
 \capref{anonymous} section.

\par
 Some keys take a \it{vararg} argument, which is a single argument (enclosed
 by curlies as are all arguments), which can contain any number of
 sub-arguments, that is, a list consisting of blocks. Inbetween the blocks
 white space may occur.  The \pr{special#1} and \pr{constant#1} keys both
 take a single vararg argument, and the \pr{apply#2} and  \pr{switch#2} keys
 each take a vararg as their second argument. For \pr{apply#2} the first
 argument is a key that is applied to subsequent batches of arguments from
 that vararg.  The \pr{table#5} primitive takes a vararg as its last
 argument.  For examples, see the \capref{tour} section and the \pr{apply#2}
 entry.

\par
 An \bf{even vararg} is a vararg with an even number of elements,
 An \bf{odd vararg} is a vararg with an odd number of elements.

\sec2{session}{Session keys}

\verbatim{\
   \\__device__           \\: the session's output device
   \\__fnbase__           \\: the base name of the entry file
   \\__fnentry__          \\: the name of the entry file
   \\__fnin__             \\: the name of the current input file
   \\__fnout__            \\: the current default output file
   \\__lc__               \\: expands to a left curly (only for magic)
   \\__line__             \\: the line number in the file currently parsed
   \\__parmode__          \\: slurp setting for interactive mode
   \\__rc__               \\: expands to a right curly (only for magic)
   \\__searchpath__       \\: search path for included files
   \\__split__            \\: user space chapter mode indicator
}

\car
 This manual is littered with examples of the usage of \mc{__device__}.  The
 \mc{__fnbase__} key is useful for creating sibling files of the entry file,
 i.e. a table of contents file or a file containing reference information.  I
 have the habit of naming those \mc{__fnbase__.zmt} and \mc{__fnbase__.zmr},
 respectively.  The \mc{__fnin__} key is useful for emitting log, warning, or
 error messages particular to the file currently being parsed.

\par
 The \mc{__parmode__} macro affects the way in which zoem reads chunks
 in interactive mode (refer to Section\~\secref{cline}).

\par
 The \mc{__searchpath__} macro is one of the ways in which zoem can be
 instructed to search for files in a set of locations, when confronted
 with \pr{dofile#2} or one of its aliases.
 Refer to Section\~\secref{searchpath}.

\sec2{builtin}{Built-in macros}

\par
This is the result from doing \v{zoem -l macro}:
\verbatim{\system{zoem}{{-l}{macro}}}

\car
 Cf \pr{dofile#2}, \pr{ref#2}, \pr{ctradd#2}, \pr{f#2},
 \pr{f#3}, \pr{fv#2}, and \pr{system#3}.

\sec2{dictionary}{Dictionary stacks}

\par
 By default, when using \pr{def#2} and \pr{set#2}, keys and their values are
 put in a global user dictionary. It could be useful to shadow keys by entering
 a new name scope. Zoem facilitates this by providing the \pr{push#1} and
 \pr{pop#1} keys. These push and pop a new dictionary onto the user dictionary
 stack.

\par
 A second dictionary stack is the \it{dollar dictionary stack}, which
 contains all keys that start with a dollar sign.
 The \pr{begin#2} primitive pushes a dollar dictionary each
 time it is invoked, and that dictionary is popped by the corresponding
 \pr{end#1} invocation.  This is typically useful for creating nested
 environments that need access to the same type of information - by storing
 such information in dollar keys, it can be shadowed and recovered.  Refer to
 the \pr{begin#2} entry.

\par
 When a key is used its definition is searched in all dictionaries, starting
 from the top-level dictionary.  The key \pr{undef#1} has only access to the
 top-level dictionary, and will never delete a key in any other dictionary.

\sec1{tour}{A zoem tour}
\par
 What follows is an informal tour through zoem's offerings. The next
 section contains a comprehensive overview of the zoem primitives.

\par
 Let us start with how filtering in plain space is configured.
 An example was given above for a single device (namely html).
 A more realistic approach, used in the zoem man macros, is this.

\verbatim{\
\\switch{\\__device__}{
   {html}{
      \\special{
         {38}  {&amp;}
         {60}  {&lt;}
         {62}  {&gt;}
         {256} {&nbsp;}          \\: the zoem escape \\~
         {257} {<br>\\N}          \\: the zoem escape \\|
         {258} {-}               \\: the zoem escape \\-
      }
   }
   {roff}{
      \\special{
         {46}  {\\\\.}
         {96}  {\\\\`}
         {92}  {\\\\\\\\}            \\: a single backslash
         {256} {\\\\ }             \\: the zoem escape \\~
         {257} {\\N.br\\N}         \\: the zoem escape \\|
         {258} {\\\\-}             \\: the zoem escape \\-
      }
   }
   {\\write{stderr}{txt}{No such device: \\__device__\\|}
    \\write{\\__fnbase__.err}{txt}{No such device: \\__device__\\|}
    \\exit
   }
}\
}

\car
 Take note of the number of backslashes. In order to print a backslash
 in troff, the troff input must contain two consecutive backslashes.
 In order to specify a backslash in zoem, we must also provide two,
 thus we need four backslashes in all (in order to create this example
 I needed eight backslashes in the zoem input).

\par
 Also note the use of the \pr{switch#2} primitive, which takes
 an expression in the first argument and an arbitrary number of pairs plus an
 optional clause in the second argument. The optional clause was in this case
 used as a failure test.

\par
 \pr{special#1} is an example of a zoem key taking an argument that may
 contain arbitrarily many sub-arguments
 (i.e. a \iref{vararg}{vararg}).
 In this particular case the
 sub-arguments must be paired, each pair defining how certain ascii
 characters that are special to the device must be represented.  There is a
 very limited number of additional tokens that can be mapped in this way:

\par
 The \pr{write#3} and \pr{exit} need little comment, they work as
 expected. Zoem opens output files as needed, and closes them when it is
 done. The file name \v{-}\~is equivalent to
 either \v{STDOUT} or \v{STDIN}, depending on the context,
 the file name \v{stderr} denotes \v{STDERR}.

\: The \pr{dofile#2} input primitive and its aliases
\: \pr{input#1}, \pr{import#1}, \pr{read#1}, and \pr{load#1} (you
\: may abhor if you wish)

\par
 \pr{exit} is considered a failure (and will cause zoem to stop and
 complain), but \pr{done} is not.  \pr{done} will merely quit
 parsing the current stack, so if you specify it at top level in a file \-
 not nested in a key that does its own parsing such as \pr{setx#2}, zoem
 will stop parsing the current file and transfer control back to the file
 from which it was included.

\par
 The previous example introduces the keys \mc{__device__} and
 \mc{__fnbase__}. They are so called session  variables
 described in section \capref{session}.

\par
 A sibling primitive to \pr{special#1} is \pr{constant#1}. The
 following is an example of use.

\verbatim{\
\\constant{
   {'e}  {&eacute;}     \\: Use e.g. as \\*{'e}l\\*{`e}ve (\*{'e}l\*{`e}ve)
   {(c)} {&copy;}       \\: Use e.g. as \\*{(c)} DEEDEE (\*{(c)} DEEDEE)
   {+-}  {&plusmn;}     \\: Use e.g. as \\*{+-} a few (\*{+-} a few)
}\
}


\car
 The main thing to note here is that the target string (e.g. \v{&eacute;})
 is \it{always interpreted in device space}.
 Inbetween the asterisks almost anything is allowed, except a backslash
 or a curly, and it is obviously not allowed to use an asterisk
 in one of the definition parts of \pr{constant#1}.

\par
 There are three zoem tokens representing the characters that have meaning to
 zoem syntax, the backslash and the two curlies.  Those zoem tokens are just
 like any other plain characters: they can be mapped in plain space, and they
 are printed literally in device space.

\verbatim{\
   \\\\            \\: A backslash; possibly mapped in plain space.
   \\{            \\: A curly; possibly mapped in plain space.
   \\}            \\: A curly; possibly mapped in plain space.
   \\,            \\: The atomic separator (vanishes).}

\car
 These tokens are mapped only during the (final) filter stage.
 The atomic separator can be useful when you want to glue together
 items some of which will be the result of macro expansion.

\verbatim{\
   \\def{foo}{bar}
   \\foo\\,1                    \\: \\foo1 would be the key \\foo1}

\car
 This will result in bar1. The tokens\~\mc{\\}, \mc{\{}, and\~\mc{\}}
 are really the corresponding ordinary ASCII characters.
 They can be mapped in plain space via \pr{special#1} using their
 ASCII values 92, 123, and 125 as was seen above for the backslash.
 In device space, they will result in\~\mc{}, \v{\{}, and\~\v{\}}.

\par
 Let us now continue with device scope by implementing a \mc{bf#1} key.
 Below you find two possible definitions:

\verbatim{\
   \\def{bf}{1}{\\@{<b>} \\1 \\@{</b>}}    \\: Ok
   \\def{bf}{1}{\\@{<b> \\1 </b>}}        \\: Wrong! Wrong!}

\car
 The second is wrong because the contents of\~\mc{1} end up in device
 space. If the expansion of\~\mc{1} still contains keys they will not be
 expanded (and cause a fatal syntax error when device space is filtered),
 and additionally any special characters in\~\mc{1} will not be
 mapped.

\sec1{language}{The zoem language}

\sec2{}{Alphabetic index}

\: this stuff constructs a 'Paragraph Of Contents'.
\${roff}{\write{stderr}{txt}{no support for roff device!}\exit}
\def{zzarg#1}{\{<\1>\}}
\formatted{
   \: third arg is a vararg in which all arguments of a key are stuffed.
   \def{zprim#3}
   {  
      \set{keyref}{\if{\cmp{eq}{\2}{0}}{\1}{\1#\2}}
      \set{keysig}{\if{\cmp{eq}{\2}{0}}{\mc{\1}}{\mc{\1#\2}}}
      \set{keycall}{\if{\cmp{eq}{\2}{0}}{}{:\~\~\mc{\1\apply{zzarg#1}{\3}}}}
      \@{\N<a name="}\keyref\@{">\N}
      \@{\N</a>\N}
      \keysig\keycall
      \write{\__fnbase__.prm}{copy}
      {\@{\N<a href=\"#}\keyref\@{\">\N}
         \keysig
       \@{\N</a>\N}\`n`
      }
   }
}

\read{\__fnbase__.prm}

\sec2{topicindex}{Topic index}

\par
 This is an overlapping categorization in topics.

\begin{itemize}

\item{\bf{Using and inspecting keys}}
   \pr{apply#2}
   \pr{constant#1}
   \pr{def#2}
   \pr{defx#2}
   \pr{defined#2}
   \pr{inspect#4}
   \pr{pop#1}
   \pr{push#1}
   \pr{set#2}
   \pr{setx#2}
   \pr{table#5}
   \pr{undef#1}

\par
 These primitives affect or use either \it{user keys} that are
 stored in the user dictionary,
 \it{dollar keys} that are stored in the dollar dictionary,
 or \it{anonymous keys}.  Dictionaries are discussed in
 \iref{dictionary}{Section\~\refnumber{dictionary}}.


\item{\bf{Control, booleans, testing and comparison}}
   \pr{$#2}
   \pr{apply#2}
   \pr{branch#1}
   \pr{cmp#3}
   \pr{eqt#3}
   \pr{defined#2}
   \pr{dowhile#2}
   \pr{if#3}
   \pr{length#1}
   \pr{switch#2}
   \pr{undef#1}
   \pr{while#2}

\item{\bf{Expansion, delay}}
   \pr{!}
   \pr{!#1}
   \pr{eval#1}
   \pr{apply#2}
   \pr{defx#2}
   \pr{setx#2}

\item{\bf{Meta-zoem, introspection, exceptions, errors}}
   \pr{try#1}
   \pr{catch#2}
   \pr{throw#2}
   \pr{done}
   \pr{exit}

\item{\bf{Execution, tracing}}
   \pr{trace#1}

\item{\bf{Input/output}}
   \pr{dofile#2}
   \pr{write#3}
   \pr{finsert#1}
   \pr{format#1}
   \pr{zinsert#1}
   \pr{vanish#1}
   \pr{writeto#1}

\item{\bf{Filtering}}
   \pr{special#1}
   \pr{vanish#1}

\item{\bf{Environment scopes}}
   \pr{begin#2}
   \pr{end#1}
   \pr{env#3}

\item{\bf{Name scopes}}
   \pr{pop#1}
   \pr{push#1}


\item{\bf{Data storage}}
   \mc{%}, \mc{%free}, and \mc{%dump} are primitives described elsewhere
   \- refer to the \secref{grape} section.

\item{\bf{String conversions}}
   \pr{alpha#1}
   \pr{format#2}
   \pr{inspect#4}
   \pr{length#1}
   \pr{roman#1}
   \pr{tr#4}
   \pr{ucase#1}

\item{\bf{Arithmetic}}
   \pr{f#2}
   \pr{f#3}
   \pr{fv#2}
   \pr{let#3}

\item{\bf{Counters}}
   \pr{ctradd#2}
   \pr{ctrput#1}
   \pr{ctrset#2}

\item{\bf{References}}
   \pr{ref#2}
   \pr{refload#6}

\item{\bf{Glyphs}}
   \pr{constant#1}

\item{\bf{Syntactic sugar}}
   \pr{formatted#1}
   \pr{vanish#1}
   \xmlpr1ref
   \xmlpr2ref

\end{itemize}


\sec2{}{Primitives}

\par
Zoem primitives may expand (which is the same as evaluate) one, several, or all
of their arguments before using them. Such arguments are enclosed by double
angle brackets in the listing below. The inside-out type evaluation is done
recursively and works for arbitrary levels of nesting.  An argument which is
first expanded and is then interpreted as a label is thus written
\zarg{<label>} in the primary entry. In the definition text accompanying the
entry, the expanded argument is simply refered to as \zarg{label}, so the extra
pair of brackets is dropped.

\par
Each primitive below has a little paragraph with the caption
\bf{Result text}. It gives a summary of 'what comes out'.
Note that the result of macro expansion is always passed to the parser
again, so the result text is again subject to expansion.


\begin{itemize}

\items{
   {\enref{xmlpr1}{\mc{<>#1}}}
   {\enref{xmlpr2}{\mc{<>#2}}}
}
   These are special. Refer to section \capref{xmlsugar}.
   The angle brackets are part of the syntax, do not confuse them
   with the angle brackets used below to enclose arguments.
   These primitives are respectively used as \mc{<*any*>} and
   \mc{<*any*>{*any*}},
   so the positioning of arguments is different from all other
   zoem primitives.

\item{\zprim{!}{0}{}}
   This primitive is triggered by an active backslash followed by a consecutive
   run of exclamation marks, which is \it{not} followed by an opening curly.
   The sequence is called a \it{delay sequence}, and its \it{arity} is the
   count of backslashes. A single exclamation mark is stripped (i.e. the arity
   is decremented) and the sequence is no longer subject to the current
   expansion stage.  It is used to construct valid zoem input, which is usually
   redirected to file with the copy filter, stored using \pr{setx#2}, or used
   in nested occurrences of \pr{apply#2}, \pr{inspect#4}, and other primitives.
   Other uses are possible, the main thing is that one should keep a clear view
   of the meta-programming implied by\~\mc{!}.
   Refer also to the \pr{eval#1} primitive.

\cpar{Example}
   The primitive \pr{eval#1} evaluates its argument a single time,
   and passes it on for further evaluation.
   The following are fully equivalent: 

\verbatim{\protect{\set{foo}{zut}
\eval{\!foo}
\foo}}

   \car
   whereas \v{\\!foo} would pass the sequence \v{\\foo} to the filtering stage,
   where it will yield a (non-fatal) error message.
   Similarly, \v{\\eval{\\eval{\\!!foo}}} is equivalent to the above.

\cpar{Result text}
   A delay sequence of decremented arity.


\item{\zprim{!}{1}{{any}}}
   This primitive is triggered by an active backslash followed by a consecutive
   run of exclamation marks, which is in turn followed by a block.  The block
   is called a \it{delay} scope.  The arity of the delay scope is the count of
   backslashes found in the run.  A single exclamation mark is stripped (i.e.
   the arity is decremented); if no further exclamation marks remain (i.e. the
   arity becomes zero) then the introducing backslash and the delimiting
   curlies are stripped as well.  The result (including the contents of the
   block) is passed on and is no longer subject to the current expansion stage.
   The same observations hold as those made for the previous entry.
   Refer also to the \pr{eval#1} primitive.

\par
   Additionally, blocks that are protected by the delay primitive will be
   skipped during parameter interpolation.

\cpar{Result text}
   \zarg{any}, if the arity of the delay scope just found was equal to one,
   otherwise, \zarg{any} put in a decremented delay scope.  \zarg{any} will in
   both case no longer be subject to the current expansion stage.

\item{\zprim{$}{2}{{str}{any}}}
   This is a shortcut for activating output for a particular device.
   If \mc{__device__} expands to \zarg{str}, \zarg{any}
   is passed on for expansion, otherwise it is ignored.
   The following two are equivalent:

\verbatim{\
\\${html}{Seen only in the html device}

\\if{\\cmp{eq}{\\__device__}{html}}{Seen only in the html device}{}}

\ccar{Result text}
   Either none or \zarg{any}.


\item{\zprim{alpha}{1}{{<int>}}}
   Transforms the integer to a string over the alphabet \v{_a-z}, i.e.
   all the set of all lowercase letters with the underscore added.
   This set is simply used for counting in base\~27, with the underscore
   playing the role of zero.

\cpar{Result text}
   The integer written down in base\~27 using symbols in the set
   \v{_a-z}.

\item{\zprim{apply}{2}{{<key-sig|anon-key>}{<vararg>}}}
 The first argument is expanded before use.
 It should expand either to the signature of a user key taking
 arguments, or to  a \iref{anonymous}{tagged anonymous key}.
 Examples of the first are \v{foo#k} and \v{"bar::baz"#k}, the latter
 takes the form \v{_#k{..}}.
 If you use an anonymous key containing macro sequences, be sure to
 escape whole or part of the anonymous key, depending on your needs.
 The expansion of \v{_#2\\!{{<any>}}} for example, will result
 in \v{_#2{<any>}}.

\par
 The second argument should result in a vararg.  \pr{apply#2} extracts
 \v{k}\~elements at a time from \zarg{vararg},
 and applies the key resulting from
 the first argument to each vector of \v{k}\~elements successively.
 Any elements remaining in \zarg{vararg} are ignored.

\par
 \v{apply#2} has really turned out to be an all-round workhorse.
 For an interesting application see Example II in
 the  \pr{begin#2} entry below.

\cpar{Result text}
 Entirely depending on the key specified in the first argument.

\item{\zprim{begin}{2}{{label}{<vararg>}}}
 \pr{begin#2} pushes a new dictionary onto the dollar dictionary stack which is
 popped by the matching \pr{close#1}.

\par
 \mc{begin#1} is an alias which invokes \pr{begin#2} with an empty
 \zarg{vararg} argument.

\par
 \pr{begin#2} pushes the begin expression associated with \zarg{label} via
 \pr{env#3}.  The \v{<label>} part is \it{not} expanded.  The second argument
 \zarg{vararg} consists of consecutive scopes denoting key-value pairs.  It is
 expanded before use and is allowed to be empty.  The keys (which are the
 odd-numbered scopes, starting with one) in \zarg{vararg} must be such that
 prepending a dollar sign (\v{$}) to them yields a valid key signature.  That
 signature will be used to set a dollar key in the newly pushed dollar
 dictionary that expands to the \v{value} part associated with the key
 (specified as the consecutive even-numbered scope in \zarg{vararg}).

\par
 The pushing of a dictionary provides a means for shadowing and localization
 with nested \pr{begin#2} statements.  By associating dollar keys with an
 environment, these keys can be given different meanings in nested environments
 - the previous meaning will be restored once an environment is closed. The
 advantages are that the environment does not have to exercise \pr{push#1} and
 \pr{pop#1} itself, that the user dictionary stack is not unnecessarily
 extended (saving look-up time), and that the 'dollar' look of a key such as
 \mc{$align} signals that it will automagically work in nested enviroments. Of
 course, the latter is still the responsibility of the author of the
 environment.

\par
 The begin \it{definition} (as created by \pr{env#3}) must use
 \mc{defined{lkey}{...}} rather than \mc{defined{key}{...}} when it wants to
 check whether a \pr{begin#2} invocation did set a particular key.

\cpar{Result text}
 The string associated with \zarg{label} via \pr{env#3}.

\cpar{Example I}
 The zoem faq macros define a \v{faqsec} environment, for which
 two additional arguments are required. It is used for example as

\verbatim{\
\\begin{faqsec{ref}{misc}{cap}{Miscellaneous questions}}
 ...
\\end{faqsec}}

\car
 The \v{ref} key introduces the label, the \v{cap} key introduces the caption.

\cpar{Example II}
 The itemize environment in the zoem \it{generic} package allows one additional
 and optional argument. This argument, if present, must contain a vararg, and
 is used to set options related to the itemize environment.  It is used for
 example as

\verbatim{\
\\begin{itemize}{
   {contiguous}{1}
   {compact}{1}
   {mark}{\\*bullet*}
   {align}{right}
}
 ...
\\end{itemize}}

\car
 Internally, the itemize environment maps these options to dollar keys.
 Because a unique dollar dictionary is associated with each environment, this
 makes it possible for nested itemize instances to have separate namespaces.
 Several more options than those given here are supported by the \it{itemize}
 environment. All listings in the  present text were created with it.  This is
 approximately how the itemize environment does initialization:

\verbatim{\protect{
      \apply{_#2\!{{\if{\defined{lkey}{\1}}{}{\def{\1}{\2}}}}}{
         {$contiguous}{0}
         {$compact}{0}
         {$w1}{2}
         {$w2}{1}
         {$f1}{16}
         {$f2}{8}
         {$mark}{\*{bullet}}
         {$margintop}{1}
         {$align}{left}
         {$debug}{0}
         {$lp}{}
         {$rp}{}
         {$type}{mark}
         {$itemcount}{0}
      }
}}

\car
 This is clearly programming close to the metal, but it works very well.

\cpar{Result text}
   Either the first block associated with a condition evaluating to true (c.q.
   nonzero), the else clause (if present), or nothing at all.


\item{\zprim{catch}{2}{{type}{any}}}
   This will process \zarg{any}. Depending on \zarg{type} the
   result is accepted as succesful.
   If \zarg{type} is \v{towel},
   any occurrence of \mc{throw{towel}} in \zarg{any} is caught, and
   the truncated result is further processed. For \v{towel},
   zoem \it{errors} are not caught but cascade/escalate further down/up.
   If \zarg{type} is \v{error},
   any error in \zarg{any} is caught, and
   the truncated result is further processed.
   If \zarg{type} is \v{ok}, no exception is accepted.
   See also \pr{throw#2}.

\par
   Output will be truncated in case an error or exception was caught.
   The status, currently one of \v{ok}, \v{towel}, or \v{error},
   is written in the session macro \mc{__zoemstat__}.

\cpar{Result text}
The possibly truncated result of expanding \zarg{any} in case
of a caught exception or error, else the full result.


\item{\zprim{cmp}{3}{{str}{<any>}{<any>}}}
   The last two arguments are expanded.  Their results are compared as
   strings.  The first argument must be one of the labels
   \v{lt|lq|eq|gq|gt|ne|cp}.  In case it equals one of the six labels
   \v{lt|lq|eq|gq|gt|ne}, this primitive puts in place
   the associated boolean as
   a string (i.e. either\~\v{0} or\~\v{1}).  In case the label equals \v{cp},
   it puts in place the result of the string compare (as a string),
   namely one of\~\v{-1}, \v{0}, or\~\v{1}.

\cpar{Result text}
   Either the string enconding of a boolean (\v{0} or\~\v{1})
   or the string encoding of the ternary value resulting from a string compare
   (\v{-1}\~or \v{0} or\~\v{1}).


\item{\zprim{constant}{1}{{vararg}}}
 \zarg{vararg} must have an even number of arguments. These are
 interpreted as pairs. The first of each pair must enclose a string
 that does not contain any of the characters\~\v{*}, \mc{}, \v{\{}, or\~\v{\}},
 say string \zarg{keystr}.  The second encloses a string that will be
 interpreted in device space, say string \zarg{valstr}.  When a sequence
 \mc{*}\zarg{keystr}\v{*} is encountered, it is interpreted as
 \mc{@\{}\zarg{valstr}\v{\}}. This is done at filter time only, the sequence
 is skipped during macro expansion.  It is not allowed to use a sequence
 \mc{*}\zarg{keystr}\v{*} in device scope, e.g.
 \mc{@\{\\*}\zarg{keystr}\v{*\}} is illegal.
 For furtherh information see section \capref{dscope}.

\cpar{Result text}
 None.


\item{\zprim{ctradd}{2}{{<label>}{<amount>}}}
 The first argument is expanded, yielding some string \zarg{label}.
 This string is used as a counter and \zarg{amount} is added to
 this counter. If the counter does not exist, it is first autovivified with
 a value of zero.

\par
 The expansion of the first argument is useful, because it allows counters that
 otherwise count the same thing to be attached to different scopes, simply by
 appending a string representing the level to the counter.

\cpar{Result text}
 None.


\item{\zprim{ctrset}{2}{{<label>}{<quantity>}}}
 The first argument is expanded, yielding some string \zarg{label}.
 This string is used as a counter which is set to the value
 \zarg{quantity}. The counter may or may not exist beforehand.

\cpar{Result text}
 None.


\item{\zprim{ctrput}{1}{{<label>}}}
 Puts in place the counter associated with \zarg{label} as a string.
 If counter does not exist, the value zero is assumed.

\cpar{Result text}
 The string encoding of an integer.


\item{\zprim{def}{2}{{key-sig|grape-seq}{any}}}
 Bind second argument to the key or access sequence
 in the first argument.  This primitive will
 complain if a binding exists already, but it will overwrite the
 previous binding and continue anyway.  Use \pr{set#2} if you do no want to be
 warned for overwriting.  Examples of usage:

\verbatim{\
   \\def{foo}{FOO}
   \\def{foo#1}{The FOO of \\1}
   \\def{foo#2}{The FOO of \\1 and \\2}
   \\def{$foo#2}{The $FOO of \\1 and \\2}
   \\def{"foo::oof"#3}{\\foo{\\1}{\\2}\\foo{\\2}{\\3}}}

\car
 These examples are all of type \v{key-sig}.
 See the \secref{grape} section for examples of type \v{grape-seq}
 (this pertains to multi-dimensional data storage).
 See the \secref{macro} section for the forms that keys may take.  A key
 signature is the name of a key with appended to
 it the number of argument that the key takes, if any.  If the key takes no
 arguments, than the key signature is identical to the key name.

\par
 If you want the value to be bound to be expanded before binding it,
 use either \pr{defx#2} or \pr{setx#2}. This works the same for
 grape keys.

\cpar{Result text}
None.

\item{\zprim{defx}{2}{{key-sig}{<any>}}}
 The second argument is expanded and stored in the key \zarg{key-name}.  This
 primitive will complain if a binding for that key exists already, but it will
 overwrite the previous value anyway.

\cpar{Result text}
None.


\item{\zprim{defined}{2}{{type}{<access>}}}
   \zarg{type} is one string of \v{key}, \v{lkey}, or \v{data}.  The
   second argument is expanded before use.  For the type \v{key}, the result is
   looked up as a key signature in either the user dictionary stack or the
   dollar dictionary stack.  For the type \v{lkey}, it is looked up only in the
   top level dictionary. For the type \v{data}, the result is interpreted as a
   data access sequence.  This primitive pushes the string\~\v{1} if the result
   is indeed a valid reference,  it pushes the string\~\v{0} otherwise.

\cpar{Result text}
The string encoding of a boolean (\v{0} or\~\v{1}).


\item{\zprim{dofile}{2}{{<file name>}{char[!?]><char[+-]}}}
 Open a file and process its contents while keeping track of line numbers.
 Depending on the second argument, absence of the file is either allowed or
 not, and its interpreted contents are output or not.  The fact
 that \zarg{file name} is first expanded allows you to specify
 file names such as \mc{__fnbase__.zyx}.

\par
 Zoem may search for a file in several locations until it is found.
 The process of locating a file is described in section \secref{searchpath}.

\par
 When found, the file is opened according to the
 specification in the second argument.  This argument must contain exactly two
 characters, the first one of [\v{!?}], the second one of [\v{+-}]. The first
 character indicates whether the file is allowed to be absent. A ´\v{!}'
 implies that absence is fatal, a '\v{?}' permits absence. The latter is useful
 e.g. when creating a Table Of Contents file.  The second character indicates
 whether the interpreted file should be filtered and output or not ('\v{+}' for
 yes and '\v{-}' for no). Macro packages typically need interpretation only,
 whereas concatenation of document parts (c.q. chapters) stored in different
 files requires that the interpreted content is also filtered and output.
 The following aliases are available:

\verbatim{\
\: alias             equivalent with
\\input{fname}        \\dofile{fname}{!+}
\\import{fname}       \\dofile{fname}{!-}
\\read{fname}         \\dofile{fname}{?+}
\\load{fname}         \\dofile{fname}{?-}}

\car
 The contents of \zarg{file name} cannot be captured. If you need to
 capture the contents of a file, use \pr{finsert#1} or \pr{zinsert#1}.

\cpar{Result text}
 Technically none. Of course the processing of \zarg{file name}
 may result in output, depending on the mode of opening.
 However, this result text cannot be captured.
 For example,

\verbatim{\\setx{foo}{\\dofile{bar}{!+}}}

\car
 will result in the file \zarg{bar} being processed and output via
 the standard output mechanisms, while the key \mc{foo} will have
 the empty string as value.
\: mq the standard output mechanisms.


\item{\zprim{done}{0}{}}
 Be done with parsing current stack.
 Use this primarily to quit parsing the current file, meaning
 that one can pile up heaps of obsolete rubbish following this primitive,
 without needing to outcomment it.

\cpar{Result text}
 None, affects result text of the current interpretation stack.

\item{\zprim{dowhile}{2}{{any}{condition}}}
   \zarg{any} is expanded and concatenated to the result text
   until \zarg{condition} exands to something that is nonzero when interpreted
   as an integer.  \zarg{any} is expanded at least one time.

\item{\zprim{end}{1}{{label}}}
 Expands the end definition associated with \zarg{label} via \pr{env#3}.

\cpar{Result text}
 The string associated with \zarg{label} via \pr{env#3}.

\item{\zprim{env}{3}{{label}{any1}{any2}}}
   Stores unexpanded \zarg{any1} for later use with \pr{begin#2} (when
   given argument \zarg{label}) and
   unexpanded \zarg{any2} for later use with \pr{end#1} (when
   given argument \zarg{label}).

\cpar{Result text}
 None.


\item{\zprim{eqt}{3}{{str}{<num1>}{<num2>}}}
   The last two arguments are expanded.  Their results are compared as
   numbers.  The first argument must be one of the labels
   \v{lt|lq|eq|gq|gt|ne|cp}.  In case it equals one of the six labels
   \v{lt|lq|eq|gq|gt|ne}, this primitive pushes the associated boolean as a
   string (i.e. either\~\v{0} or\~\v{1}).  In case the label equals\~\v{cp},
   this primitive pushes the result of the integer compare,
   namely one of \v{-1} (if the result of \zarg{any1} is
   smaller than the result of \zarg{any2}),
   \v{0} (equal to), or\~\v{1} (greater than).

\cpar{Result text}
   Either the string enconding of a boolean (\v{0} or\~\v{1})
   or the string encoding of the ternary value resulting from a string compare
   (\v{-1} or\~\v{0} or\~\v{1}).

\item{\zprim{branch}{1}{{<vararg>}}}
   Two arguments are successively
   taken from \zarg{vararg}. The first is expanded and then evaluated as
   an integer.
   If the integer is nonzero, the second argument is expanded and everything
   else is ignored.  Otherwise the procedure is repeated.  If no
   (odd) argument matches, and the \zarg{vararg} has an odd number of
   arguments, the last argument is put in place.  It can be considered a
   default, else, or failure clause.

\item{\zprim{eval}{1}{{<any>}}}
 Expands \zarg{any} and passes it on for further evaluation.
 This can come in handy when complicated requirements demand
 zoem acrobatics. This primitive used to be implemented as a macro;
 it is fully equivalent to

\verbatim{\protect{\set{eval#1}{\apply{_#1{\!1}}{\1}}}}

\car
 The above macro works as follows. First, \pr{apply#2} expands
 both of its arguments. The second argument is the data it received
 from \mc{eval}, i.e. the latter's single argument. At this stage, the data
 is thus expanded for the first time. \pr{apply#2} also expands its first
 argument.
 The sequence \mc{!1} is contracted to the sequence\~\mc{1}. The\~\mc{1} needed by
 \pr{apply#2} needs to be protected by the interpolation that occurs when
 \v{eval#1}'s argument is interpolated.  Expansion of \pr{apply#2}'s first
 argument thus yields the anonymous key \v{_#1{\\1}} \- a key that simply
 copies it argument and passes it on for further expansion.

\cpar{Example}
\v{\\foo} and \v{\\eval{\\!foo}} are fully equivalent.
\v{\\!foo} on the other hand, expands to \v{\\foo} and is then
passed to the filter stage.

\cpar{See also}
\pr{!}, \pr{!#1}.

\cpar{Result text}
 \zarg{any} gone through \it{two} stages of interpretation.


\item{\zprim{exit}{0}{}}
goodbye world. This is a disgraceful exit for use when some error test
presumably yields true.

\cpar{Result text}
 None.

\item{\zprim{f}{2}{{fun}{<num1>}}}
   Expand the last argument, interprets the result as a number,
   applies the operand specified by \zarg{fun}, and puts the
   result in place.
   \zarg{fun} can be one of

\par
\apply{_#1{\!v{\1}, }}{
   {floor} {ceil} {round} {abs} {sign} {inc} {dec} {not}
} and that's about it.

\par
For a wider range of mathematical functions, refer to
the \pr{let#1} primitive.

\cpar{Result text}
 The string encoding of a number.

\item{\zprim{f}{3}{{fun}{<num1>}{<num2>}}}
   Expands the last two arguments, interprets the results as
   numbers, applies the operand specified by \zarg{fun}, and puts the
   result in place.

\par
   Most arithmetic is done using floating point arithmetic (with the C double
   type). Integers are preserved if possible.  Since nearly everything is
   treated as a string in zoem, this simply means that no decimal fraction is
   printed when the number is output. A number is considered integer if the
   difference with the integer nearest by is less than the precision (1e-8)
   \it{and} if it can be represented as an integer using the C long type.
   Otherwise it is output in decimal representation of the underlying floating
   point representation.

\par
   \zarg{fun} can be one of
   \begin{itemize}{{compact}{1}{contiguous}{1}}
   \item{*} Multiplication.
   \item{+} Addition.
   \item{-} Subtraction.
   \item{/} Does true division, returns real.
   \item{%} Modulus.
   \item{and} Boolean \it{and}, results in\~\v{0} or\~\v{1}.
   \item{or} Boolean \it{or}, results in\~\v{0} or\~\v{1}.
   \item{div} Does integer division.
   \item{mod} Same as\~\v{%}.
   \item{pow} Power.
   \item{max} Maximum.
   \item{min} Minimum.
   \item{ceil} Nearest by higher multiple, e.g. \mc{f{ceil}{12}{5}=15}.
   \item{floor} Nearest by lower multiple, e.g. \mc{f{floor}{12}{5}=10}.
   \end{itemize}

\par
For a wider range of mathematical functions, refer to
the \pr{let#1} primitive.

\cpar{NOTE}
\v{and} and \v{or} short-circuit.

\cpar{Result text}
 The string encoding of a number.


\item{\zprim{fv}{2}{{fun}{<vararg>}}}
   Expands the second argument and interprets it as vararg,
   and applies the operator specified by \zarg{fun} to the elements of vararg.

\par
   \zarg{fun} can be one of
   \begin{itemize}{{compact}{1}{contiguous}{1}}
   \item{*} Multiplication.
   \item{+} Addition.
   \item{and} Boolean and.
   \item{or} Boolean or.
   \item{max} Maximum.
   \item{min} Minimum.
   \end{itemize}

\cpar{NOTE}
\v{and} and \v{or} short-circuit.

\cpar{Result text}
 The string encoding of a number.


\item{\zprim{finsert}{1}{{file name}}}
   The argument is expanded and interpreted as file name.  The file is read,
   and every\~\mc{}, \v{\{}, and\~\v{\}} is escaped (resulting in one of
   \mc{\\}, \mc{\{}, and\~\mc{\}}) The altered contents are then put in
   place.  See also \pr{zinsert#1}.
   If file can not be opened, the empty string results.

\cpar{Result text}
 The escaped contents of \zarg{file name} or the empty string if
 file can not be opened.


\item{\zprim{format}{2}{{<fmt>}{<varag>}}}
   Formats elements from \zarg{vararg} according to the format
   specification in \zarg{fmt}.
   A format string may contain normal characters that will be output,
   and meta sequences. A meta sequence is started with the percent
   character \v{%}.
   For each \zarg{arg} in \zarg{vararg}, the next applicable meta sequence
   is sought in \zarg{fmt}. A meta sequence consisting of two consecutive
   percent signs (\v{%%}) will be skipped and result in the output
   of a single percent sign.

\par
   Otherwise, the meta sequence may consists of a number of subsequences
   that may occur in any order. These are

\begin{itemize}
\item{\v{~{..}{..}}}
   i.e. a tilde followed by two blocks.  The content of the
   first block is used as the padding string. By default spaces are used
   for padding.
   Padding is applied if the width of the field exceeds the width of
   \zarg{arg} plus the width of the optional delimiter(s) encoded in
   the second block.
   The content of the second block is inserted inbetween the padding and
   \zarg{arg}. If centered alignment is used, this will be done on both sides.
   By default no such delimiter is used.
   
\item{one of \v{<}, \v{>}, or \v{=}}
   These respectively denote left, centered, and right alignment.

\item{<num>}
   A positive integer number denoting the desired width of the field on which
   \zarg{arg} is to be printed.

\item{\v{*{..}{..}}}
   i.e. an asterisk sign followed by two blocks.
   This is for when you want to use a virtual length.
   The second block should contain a string. The length of this string
   will be used to do the computations, but the actual string that
   is inserted into the formatted result is taken from \zarg{vararg}.
   This allows you for example to do alignment in \v{<pre>} formatted
   blocks in html, while keeping the possibility to insert elements
   that do not take up any width (e.g. links).
   The first block should contain the name of a macro, which is
   used to compute the length of the string in the second block.
   A likely candidate is \pr{length#1}, which should be specified
   simply as \v{length}.

\item{\v{@{..}{..}}}
   i.e. an at sign followed by two blocks.
   This is used to specify alignment.
   The content of the first block is used as the string on which to align.
   The content of the second block is used as the width on which
   the first part of \zarg{arg} (up to and including the alignment substring)
   will be right-aligned.
   If the asterisk sequence is used, the length macro specified therein
   will be used to compute the width of the string specified in the
   first block.
\end{itemize}

\par
   The meta sequence must currently end with the character \v{.} (a dot).

\cpar{Result text}
   The formatted string.


\item{\zprim{formatted}{1}{{any}}}
   This removes and adds white space from its arguments
   via the following rules:

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
   {align}{right}
}
\item
   It skips any \mc{@{..}} enclosed sequence.

\item
   It skips any \mc{<..>} enclosed sequence - note that the contents
   eventually will end up in \mc{@{..}} (at) scope.

\item
   It removes all spaces, tabs, and newlines it encounters otherwise.

\item
   It inspects and (after inspection) removes all \mc{`..`} enclosed
   sequences it encounters.  During inspection, \pr{formatted#1} maps
   '\v{s}' to a space, '\v{t}' to a tab, and '\v{n}' to a newline.

\item
   If the sequence \mc{`[`} is encountered (not in at scope),
   \mc{formatted#1} starts copying literally without munging
   whitespace; it resumes its normal mode of operation
   after encountering the sequence \mc{`]`}.
\end{itemize}
   
\par
 This is useful for writing legible macro files while exercising full control
 over whitespace (modulo Zoem's white space munging rules).

\cpar{Result text}
 The argument in its unformatted form.


\item{\zprim{if}{3}{{<condition>}{any1}{any2}}}
   The first argument is expanded and interpreted as an integer.
   If it is nonzero, \zarg{any1} is pushed on the interpretation stack
   and \zarg{any2} is ignored, vice versa if it is zero.

\cpar{Result text}
   Either \zarg{any1} or \zarg{any2}.


\item{\zprim{inspect}{4}{{mods{<reg>}{<any|anon key>}}{<any>}}}
 All arguments except \v{mods} are expanded before use.  The expansion of
 \zarg{reg} is
 followed by an unprotect and should result in a POSIX regular expression.  The
 unprotect action unescapes escaped backslashes and curlies, so that those can
 be passed to the regex engine (although it interprets backslashes, so you need
 to quadruple those if you don't want them interpreted).

 The expansion of \zarg{any|anon key} can either result in plain data or in an
 anonymous key.  The third expansion results in data to which the regex
 \zarg{reg} is successively applied.

 If the second expansion results in something recognizable as an anonymous key,
 then the subpatterns from the matched pattern are interpolated by the key, and
 the entire matched pattern is substituted by the interpolation.
 Else, the matched pattern is simply replaced by the expansion.

\par
 \v{mods} \it{must} contain the keyword \v{posix}, it
 may further contain a subset of the keywords
 \v{count dotall grep grepc icase lines look skip snip vararg}.
 This primitive has not yet been blessed by exhaustive stress-testing,
 so perhaps not all of these work flawlessly.

\par
 \v{skip} prohibits non-matching part from being output.
 \v{icase} induces case insensitive matching.
 \v{dotall} makes the dot\~\v{.} match any character, including the newline.
 \v{lines} causes matching to be applied to lines shifted from the data (i.e.
   data is split on newlines).
 \v{vararg} causes matching to be applied to blocks shifted from the data (which
   should obviously be a vararg).
 \v{count} replaces the data by the count of matches, and works in conjunction
   with both \v{lines} and \v{vararg}.
 \v{snip} removes any lines or blocks which are empty after inspect
   is done with it.
 \v{grep} outputs only matching elements (only in conjunction
   with \v{lines} or \v{vararg}).
 \v{grepc} outputs only non-matching elements (only in conjunction
   with \v{lines} or \v{vararg}).
 \v{look} does not substitute, works in conjunction with grep -- matching
   elements are kept intact.

\cpar{Example}
 Section \refnumber{manhtml}, \iref{manhtml}{\refcaption{manhtml}}
 contains an example of html output generated from the Zoem man macros.
 This section is automatically included from an external file by
 matching the contents inbetween the \v{<body>}, \v{</body>} tags.
 Those contents are then entered in device scope so that no further
 interpretation by Zoem would occur. This is how it is done:

\verbatim{\protect{
\formatted{
   \setx{buzzz}{
      \inspect
         {posix, dotall, skip}
         {DOCTYPE(.*)PUBLIC}
         {_#1{\1}}
         {\finsert{buzzz.html}}
   }
}}

\\<div class=indent>
\\apply{_#1{\\@{\\w\\1\\W}}}{{\\buzzz}}
\\</div>
}

\car
 Note the use of \pr{apply#2} in order to get the contents of a macro
 into device scope, and note that in device scope white space
 munging is turned off using\~\mc{w} (and resumed using\~\mc{W}).
 This is done so that verbatim environments are preserved in
 the included text.

\cpar{Bugs}
The GNU implementation of POSIX regexes is known to be very buggy for
long strings and/or long matches.

\par
 There are many possible combinations of modifiers, and not all of them
 work together. It is mainly a bug in this documentation that forbidden
 combinations are not yet listed here. It is possible that certain
 combinations should work together but fail to do so. However, no such
 cases are known at the moment.

\par
 A search pattern consisting of a single word boundary or the start-of-string
 token (\v{^}) will match at each position, because after a succesful match
 \pr{inspect#4} simply resumes searching for a new match by skipping to the
 end of the previous match (and adding a single position if the match had
 width zero and offset zero).  Similar but not yet noticed bugs may exist.

\par
 Nevertheless, this can be a very useful primitive for the occasional
 odd job, and it should always work except for the cases just mentioned.
 If you have a complicated instance of \pr{inspect#4}, test it first
 in isolation. Consider sending a bug report in case you find one (a bug,
 or a bug report).

\cpar{Result text}
   Depending on the presence of a match and the modifiers given.


\item{\zprim{length}{1}{{<any>}}}
 Computes the length of \zarg{any} and puts this in place.
 It takes into account the zoem escape sequences \mc{\\}, \mc{\{},
 and \mc{\}}. The future may bring a generalized \mc{length#2} primitive
 that provides different ways of measuring string length.

\cpar{Result text}
   The length of any \zarg{any}.

\item{\zprim{let}{1}{{<let expression>}}}
 The \pr{let#1} primitive puts zoem in arithmetic mode and the contents are
 parsed accordingly.  All of C's operators are supported  including the
 logical, bitwise, and comparison operators as well as the ternary operator.
 The operators \v{**} and \v{//} are added, which respectively denote
 exponentiation and integer division.
 Operations or functions resulting in integers are tracked, and
 the result will be stored in the integer type used (typically
 long) if possible. Thus one may find that

\verbatim{\
\protect{\let{2**42}}
\protect{\let{2**22}}
}

\car
 respectively result in \v{4398046511104.0} and \v{2097152}.

\par
 The precedence rules used by Zoem are simpler than C's. The respective groups
 of logical, bitwise, and comparison operators all have identical precedence
 internally, and associate from left to right.

\par
 Most of the ANSI C math functions are supported, with in addition
 \v{max} and \v{min}. The functions \v{round}, \v{sign}, and \v{abs} behave
 slightly different from their C counterparts, as they result in integer
 results if no overflow occurs.

\par
 At any place where an atomic type is expected one is allowed to insert
 a zoem macro invocation. It will be evaluated and the result will be
 interpreted as a number. Evaluation will take place in the order
 as dictated by the precedence rules governing the expression.

\par
 The logical operators shortcircuit and the ternary operator evaluates
 only one of its branches. This can be used to create side effects, such
 as in

\verbatim{\protect{
   \let{\bar && \group{\set{foo}{zut}1}}
}}

\car
 This sets \v{foo} only if \v{bar} evaluates to a non-zero number.
 The trailing\~\v{1} in the \v{group} macro is good practice because
 \pr{let#1} expects a number to be the result of any macro it encounters.
 It could have been any other number, or a macro or sequence of macros
 evaluating to a number.
 The \v{group} macro is a predefined macro that does nothing except
 passing its arguments. It is necessary in this concocted example
 because any occurrence of
 a macro within \pr{let#1} is interpreted as a number by itself.
 The sequence \v{\\bar \\bar} would for example be syntactically
 identical to \v{1 1}, which is incorrect.


\cpar{Result text}
 A number.

\item{\zprim{pop}{1}{{label}}}
   Pops a dictionary from the user dictionary stack if \zarg{label}
   is the character\~\v{u}.

\cpar{Result text}
   None.


\item{\zprim{protect}{1}{{<any>}}}
   The argument is expanded. Subsequently, all backslashes and curlies
   are escaped. The resulting text is put in place.

\cpar{Result text}
   \zarg{any} with backslashes and curlies escaped.


\item{\zprim{push}{1}{{label}}}
   Pushes a new dictionary onto the user dictionary stack if \zarg{label} is
   the character\~\v{u}.  Note that \pr{defined#2} with the \v{lkey} label
   checks only the top-level dictionary, whereas \pr{defined#2} with the
   \v{key} label checks the whole stack of dictionaries.  Also, \pr{undef#1}
   only removes a key from the top-level dictionary. There is currently not a
   way to remove a key from all dictionaries.

\cpar{Result text}
   None.

\par
   Example of usage:

\verbatim{\
\\def{num}{1}
\\push{u}
   \\def{num}{2}
   \\push{u}
      \\def{num}{3}
      \\push{u}
         \\def{num}{4}
      \\pop
      num is \\num
   \\pop
   num is \\num
\\pop
num is \\num}

\car
   results in

\verbatim{\
num is 3
num is 2
num is 1}


\item{\zprim{ref}{2}{{str}{char[ltncm]}}}
   Put one of the fields associated with the label \zarg{str}
   in place.  The second argument is a single character identifying
   the field to retrieve.  Use \bf{l} for the level field, \bf{t} for the
   type field, \bf{n} for the number field, \bf{c} for the caption field,
   and \bf{m} for the misc field.

\cpar{Result text}
The stored field if the label is found, some funny string otherwise.


\item{\zprim{refload}{6}{{a}{l}{t}{n}{c}{m}}}
   Associates several fields with an anchor for later retrieval using \pr{ref#2}.
   Here \zarg{a}, \zarg{l}, \zarg{t}, \zarg{n}, \zarg{c}, and \zarg{m} stand
   for anchor, level, type, number, caption, and misc respectively.  For a
   section, the fields other than the anchor field could for example be\~\v{3},
   \v{Section}, \v{6.2.1}, \v{How to peel potatoes}, \v{this field not used}.
   This primitive is clearly meant to support index and table of content
   macros.

\cpar{Result text}
None.

\item{\zprim{roman}{1}{{<int>}}}
   Puts the corresponding letter in place, e.g. \mc{roman{1999}} results in
   \v{mcmxcix}. Used in the \it{itemize} environment defined in the
   \sibref{../mac/generic_zmm}{generic package}.
   Use \pr{ucase#1} to obtain capitals.


\item{\zprim{set}{2}{{key-sig}{any}}}
   As \pr{def#2} above, except that \pr{set#2} will not complain
   if the key labeled by \zarg{key-sig} already exists.

\cpar{Result text}
None.


\item{\zprim{setx}{2}{{key-sig}{<any>}}}
 The second argument is expanded and stored in the key \zarg{key-name}.
 Besides simply storing the expansion of an expression, it can
 also be used to do trickier things as

\verbatim{\
   \\def{bar}{klaas}
   \\setx{foo#2}{\\bar says \\1 and \\2}
   \\foo{x}{y}
   klaas says x and y}

\car
 If you need lambda-like capabilities, take note that you can use \mc{!k} or
 \mc{!{\\k}} to construct a positional parameter\~\mc{k}, if you want to
 interpolate arguments into a key that will later take other arguments. Like
 this:

\verbatim{\
   \\: is there any use for this wacky stuff?
   \\def{lambda#2}{\\setx{\\1#1}{\\2 says \\!1}}
   \\lambda{foo}{bar}
   \\foo{moo}
   bar says moo}

\car
 Take care: the \pr{dofile#2} key outputs
 to the default output file. If you need to include the contents of
 a file within a \pr{setx#2} call, you need to use \pr{finsert#1} or \pr{zinsert#1}
 in conjunction with \pr{setx#2}.

\cpar{Result text}
None.


\item{\zprim{special}{1}{{vararg}}}
   \zarg{vararg} must have an even number of arguments.  These are
   interpreted as pairs. The first of each pair must enclose an integer in
   the range 0-258.  The first 256 integers in this range are interpreted as
   character indices according to the ASCII (American Standard Code for
   Information Interchange) standard.  The characters indexed 256, 257, and
   258 correspond with the zoem glyphs\~\mc{~}, \mc{|}, and\~\mc{-}
   respectively.  The second element in each pair defines the string to
   which the character specified by the first element must be mapped.  This
   string is interpreted in device scope.  See the
   \capref{hello} and \capref{dscope} sections for simple uses.

\par
   A key may occur multiple times. The corresponding definitions
   are stacked away and will be accessed according to the current
   \it{special level}
   (cf. the section on \iref{special}{mapped characters in device scope}).

\par
   Repeated use of \mc{special#1} does not cause the removal of previous
   definitions, with one exception: If \mc{special#1} is invoked
   with no arguments at all then all definitions are removed.

\cpar{Result text}
None.


\item{\zprim{switch}{2}{{<pivot>}{vararg}}}
   The first argument is expanded. Subsequently, two arguments are successively
   taken from \zarg{vararg}. The first is expanded and string compared with
   \zarg{pivot}. If they match, the second argument is expanded and everything
   else is ignored.  If they do not match, the procedure is repeated.  If no
   (odd) argument matches, and the \zarg{vararg} has an odd number of
   arguments, the last argument is put in place.  It can be considered a
   failure clause.  This primitive does not have fall-through behaviour; at
   most one branch will be handed to the parser.

\cpar{Result text}
Either the first block associated with a matching case of \zarg{pivot},
the failure clause, or nothing at all.


\item{\zprim{system}{3}{{cmd}{<args>}{<data>}}}
   \it{By default this primitive is disallowed.}
   The first argument is the name of a system command. The environment variable
   PATH is used in tracing the location of the command.  If \zarg{data} is
   non-empty, it is first \it{unprotected}, that is, escaped backslashes and
   curlies are unescaped.  The resulting text is then fed to command \zarg{cmd}
   with arguments \zarg{args}. The latter, if non-empty, must be
   specified as a vararg, even if only a single argument is present.
   Should execution of the command (be it with or
   without data) result in output on STDOUT then the latter is captured,
   backslashes and curlies are escaped (i.e. the output is protected), and the
   result is put in place. STDERR is the same as it is for the parent (zoem).

\par
   \bf{NOTE} the security implications of this feature. By default
   zoem will \it{ignore} \mc{system}. The
   command line option \v{--unsafe} will cause zoem to prompt for user
   confirmation (if prompting is not possible it will ignore again) for
   each encountered \mc{system} invocation. The option \v{--unsafe-silent}
   will silently allow all \mc{system} invocations. The option
   \v{--allow=cmd[:cmd]*} explicitly specifies which commands to allow silently.
   It is also possible to use this option repeatedly rather than separate
   different commands by colons.

\par
   If the zoem command line option \v{--system-honor} is used, zoem will
   exit if a system command fails or is ignored.

\par
   A simple exit status is written in the variable \mc{__sysval__}:
   it is zero (\v{0}) on success, and one (\v{1}) on failure.

\par
   Refer to \sibref{zoem}{the manual page of the zoem interpreter} for
   more information on \v{--unsafe}, \v{--unsafe-silent},
   \v{--allow=}, and \v{--system-honor}.

\par
   Built-in macros \mc{system#2} and \v{system#1} exist. The former
   drops the \zarg{data} argument, the latter also drops the \zarg{args}
   argument.

\cpar{Example}
\verbatim{\\system{sort}{{-n}}{\\finsert{foo}}
\\system{ls}{{-l}{-a}}
\\system{date}}

\cpar{Result text}
The output captured (and then protected) from \zarg{cmd}'s STDOUT, if any.


\item{\zprim{table}{5}{{<row length>}{any1}{any2}{any3}{<vararg>}}}
   The first argument is expanded and interpreted as an integer, say\~\v{k}.
   Successively, vectors of \v{k}\~elements are shifted from
   \zarg{vararg}. Each vector is bordered on the left with
   \zarg{any1}, bordered on the right with \zarg{any3}, and
   all elements in the vector are separated with \zarg{any2}.

\par
   This primitive is perhaps not really needed as its functionality
   is largely covered by \pr{apply#2}.

\cpar{Result text}
The blocks from \zarg{vararg} interspersed in a table-like
manner with \zarg{any1}, \zarg{any2}, and \zarg{any3}.


\item{\zprim{throw}{2}{{towel|error}{<any>}}}
   Quit parsing, unwind stacks until some occurrence of
   \pr{catch#2} or \pr{try#1} captures this throw.

\par
   \zarg{any} is digested; if it has positive length the result
   is issued as error message. 

\cpar{Result text}
   None, affects the result text of the embedding scopes.
 
\item{\zprim{tr}{4}{{[cds]*}{<list1>}{<list2>}{<any>}}}
   If no modifiers (one or more of \v{[cds]}) are specified, map characters
   from \zarg{any} which are in \zarg{list1} to the corresponding character in
   \zarg{list2}.  \zarg{list1} and \zarg{list2} may contain ranges of
   characters such as \v{a-z} and \v{0-9}, but syntactically the two lists
   must be identical, i.e. the combination {1a-z}{A-Z0} is illegal.  There is
   one exception, namely \zarg{list1} is allowed to be longer than
   \zarg{list2}. The characters for which no mapping is specified will be
   deleted.
   An example of legal use would be {A-Z #@$%}{a-z_} which maps uppercase
   to lowercase, space to underscore, and removes some ugly characters.

\par
   Characters can be specified using octal notation, e.g.
   \mc{012} encodes the newline. Use \mc{173} for the opening curly,
   \mc{175} for the closing curly, and \mc{134} for the backslash.
   \it{DON'T} use \mc{\\}, \mc{\{}, or\~\mc{\}} in this case!

\par
   The \v{s}\~modifier squashes translated sequences
   consisting of the same character repeated into one occurrence
   of that character.

\par
   The \v{d}\~modifier simply deletes all entries in \zarg{list1} found
   in \zarg{any}.

\par
   The \v{c}\~modifier only works in conjunction with one
   of the other two modifiers. It means that the complement is
   taken of \zarg{list1}. When using this in conjunction with\~\v{s},
   \zarg{list2} must have at least one character
   and only the first character is considered.

\cpar{Result text}
The expanded \zarg{any} subjected to the \v{tr} operator as specified.


\item{\zprim{trace}{1}{{<int>}}}
   The argument is expanded and interpreted as an integer.  This integer
   encodes an ensemble of flags controlling the trace output. The different
   modes are exactly the same as those that can be set from the command line.
   Refer to the \iref{cline}{corresponding section} for more information.
   Special values are\~\v{0} (switch off all tracing),
   \v{-1} (switch on all tracing modes in short mode),
   \v{-2} (switch on all tracing modes in long mode),
   \v{-3} (switch to the previous tracing value),
   and \v{-4} emit a listing of tracing bits.
   The third can be useful to switch tracing on for a short while and then off
   again if you need to debug your document.
   Additionally and redundantly, \mc{trace#1} puts the previous tracing
   value in place.

\cpar{Result text}
The previous tracing value.


\item{\zprim{try}{1}{{any}}}
   This will process the content and
   output is written in the macro \mc{__zoemput__}.  Output will
   be truncated in case \pr{throw#2} was used or an error occurred.
   The status, currently one of \v{ok}, \v{towel}, or \v{error},
   is written in the session macro \mc{__zoemstat__}.

\cpar{Result text}
None.


\item{\zprim{ucase}{1}{{<any>}}}
   Translates \v{a-z} to \v{A-Z} in (the expansion of) \zarg{any}.
   This is a special case of \pr{tr#4}

\cpar{Result text}
   The translated text.


\item{\zprim{undef}{1}{{key-sig}}}
   Deletes the key with signature \zarg{key-sig} from the
   top level dictionary. Complains (but does not fail) if the key
   does not exist in that dictionary.

\cpar{Result text}
None.


\item{\zprim{vanish}{1}{{any}}}
   This will only process the content for its side effects. Any result text is
   disregarded.  This allows easy free-style commenting of sequences of
   definitions.  By comparison, \pr{formatted#1} provides the means to give a
   formatted presentation of the definitions themselves.

\cpar{Result text}
None.


\item{\zprim{while}{2}{{condition}{any}}}
   While \zarg{condition} exands to something that is nonzero when interpreted
   as an integer, \zarg{any} is expanded and concatenated to the result text.
   The following piece of zoem asks the user for an integer and writes all
   Fibonacci numbers smaller than that integer plus one extra to STDOUT.

\verbatim{\
\\def{fib#1}{
   \\ctrset{a}{1}
   \\ctrset{b}{1}
   \\ctrset{c}{0}
   \\while{\\eqt{lq}{\\ctrput{c}}{\\1}}{
      \\ctrset{c}{\\ctrput{a}}
      \\ctrset{a}{\\"+"{\\ctrput{a}}{\\ctrput{b}}}
      \\write{-}{txt}{\\ctrput{c}\\|}
      \\ctrset{b}{\\ctrset{c}}
   }
}

\\write{-}{txt}{Enter a number please, }
\\write{-}{txt}{then press <cr> and <ctl-d>\\|}
\\setx{num}{\\finsert{-}}    \\:  this reads from STDIN.
\\fib{\\num}}

\ccar{Note}
   The strings built up by \pr{while#2} are internally concatenated
   until it is done, so the result from \pr{while#2} \it{can} be captured.
   This will make \pr{while#2} work for \pr{setx#2}.  If you want to output
   100M worth of lines or paragraphs in a while loop, embed the stuff to be
   output in a \pr{write#3} call, and make sure that no whitespace results
   from the loop (for example by using \pr{formatted#1}).

\cpar{Result text}
Whatever is built up in the while loop.


\item{\zprim{write}{3}{{<file name>}{str}{<any>}}}
   The first argument is expanded and used as a file name.  It is a fatal error
   if the file has either not been opened by a previous \mc{write#3} call or
   cannot be opened for writing.  Two special file names or 'streams' are
   recognized, namely \v{-} and \v{stderr}. They map to \v{STDOUT}
   and \v{STDERR}.
   The third argument is expanded, filtered, and written to file.  The second
   argument indicates the filter to be used. It must be one of the (literal)
   strings \v{copy}, \v{device}, or \v{txt}.

\par
   The \v{copy} filter does not filter anything at all (neither plain scope
   nor device scope) and does not touch any of the zoem escape sequences
   remaining after expansion.

\par
   The \v{device} filter does a full-fledged filtering of both parse scopes.
   It respects the settings according to the \pr{special#1}
   primitive. The write primitive associates unique metadata with each
   file it opens, so \it{at directives} such as\~\mc{N}, \mc{W}, and \mc{+}
   for different output files do not interfere with one another.
   Refer to the \secref{dscope} section for more information on
   at directives.

\par
   The \v{txt} filter maps \mc{\\} to \mc{} (i.e. a single
   backslash), \mc{~}\~to a single space, \mc{-}\~to a single hyphen,
   \mc{,} (the atomic separator) to nil, \mc{|}\~to a newline,
   \mc{\{}\~to\~\v{\{}, and\~\mc{\}} to\~\v{\}}. It copies everything
   else verbatim.

\cpar{Result text}
Technically none, as the output of \pr{write#3} cannot be captured.

\item{\zprim{writeto}{1}{{<file-name>}}}
Closes the current default output stream, and changes it to point to file
\zarg{file name}. Useful when splitting a document into chapters, or god
forbid, nodes.

\cpar{Note}
Zoem will recognize if \mc{writeto#1} is issued more than once for the same
file \zarg{file-name}. On the first occassion, it will simply open the file and
truncate any previous contents.  On the second occasion and onwards, it will
append to the file.  There is currently no option to vary this behaviour.

\cpar{Result text}
None.

\item{\zprim{zinsert}{1}{{<file name>}}}
   The contents of file \zarg{file name} are put in place unaltered
   enclosed by the \pr{!#1} delay primitive.  The contents must necessarily
   satisfy zoem syntax.  If the file can not be opened, the empty
   string results.
   See also \pr{finsert#1}.

\cpar{Example}
\verbatim{\protect{\setx{foo}{\zinsert{mydata}}}
\protect{\setx{foo}{\eval{\zinsert{mydata}}}}
}
\par
   In the first case, \mc{foo} will contain the exact contents
   of file \v{mydata}. Those contents are first
   enclosed within the \pr{!#1} primitive by \pr{zinsert#1}.
   The resulting text is evaluated by \pr{setx#2} - the only
   thing this does is strip the enclosing \v{\\!{}} scope.

\par
   In the second case, \mc{foo} will contain the \it{evaluated}
   contents of file \v{mydata}, as \pr{eval#1} adds an additional
   layer of evaluation.

\cpar{Result text}
   The contents of file \v{file name} or the empty string if
   file can not be opened.

\end{itemize}

\sec1{manexample}{The zoem manual macros}

\par
 This section contains a manual page for the fictitious \it{buzzz} utility.
 Several things are shown, including references to options and sections
 that show up as hyperlinks in html, while resulting in normal text
 in troff.  This requires some authoring discipline, as one has to write
 the text such that it makes sense in the absence of hyperlinks.
 This section contains the following subsections:

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
}
\apply{_#1\!{{
         \item{\iref{\1}{\refnumber{\1}}}
         \iref{\1}{\refcaption{\1}}
      }
   }
}{
   {manzoem}
   {manhtml}
   {manps}
   {manmcl}
}
\end{itemize}

\par
The last section has several links
to the full-fledged \it{mcl} manual page and the mcl FAQ.


\sec2{manzoem}{An example zoem manual page}

\par
 The \it{buzzz} manual page is shipped with the zoem source, as are the manual
 macros. They are in the files respectively named \v{buzzz.azm} and
 \v{man.zmm}.


\hrule

\:
\: read in buzzz.azm, and put it in a verbatim env.
\:

\verbatim{\finsert{buzzz.azm}}


\sec2{manhtml}{What it looks like in html}

\: the two paragraphs below are reasonably advanced zoem (though not
\: complex). buzzz.html is read in and protected by finsert, and the
\: <body> content is then extracted. This is then plummetted into device
\: scope, which needs inside out evaluation using apply, because user
\: keys are not allowed in device scope. note that both apply#2 and
\: inspect#4 evaluate all of their arguments before use.


\: \NEED TO WORK AROUND REGEXP BUG
\if{0}{
   \formatted{
      \setx{buzzz}{
         \inspect
            {posix, dotall, skip}
            {DOCTYPE(.*)PUBLIC}
            {_#1{\1}}
            {\finsert{buzzz.html}}
      }
   }
   \if{\__sysval__}{\write{stderr}{txt}{buzzz inclusion failed\|}
   \exit}{}
   \write{-}{txt}{BUZZZ: \buzzz\|---\|}
}{
   \setx{buzzz}{
        \system{./inc-buzzz.pl}
   }
}

\<div class=box style="padding:1em">
\<div class=indent>
\apply{_#1{\@{\w\1\W}}}{{\buzzz}}
\</div>
\</div>

\:
\: end of advanced zoem :)
\:


\sec2{manps}{What it looks like as PostScript generated from troff}

\par
 A link to the PostScript version of the manual page was provided in the buzzz
 document itself and \aref{buzzz.ps}{here is another one}.  Note that this
 PostScript was compiled by groff from the troff output that was compiled by
 zoem from the zoem input.
 
\sec2{manmcl}{Full fledged manual pages and FAQ}
\par
 The example from the previous sections is not so impressive as the manual page
 is a bit skinny. A full fledged (and not necessarily impressive) manual page
 written in zoem is for example the mcl manual page.  If you like, have a look
 at

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
}
\item{\aref{http://micans.org/mcl/src/mcl-latest/src/doc/mcl.azm}{mcl.azm}}
   The source for the manual.

\item{\aref{http://micans.org/mcl/src/mcl-latest/src/doc/mcx.zmm}{mcx.zmm}}
   A resource file used by \it{mcl} and its sibling applications.

\item{\aref{http://micans.org/mcl/src/mcl-latest/src/doc/mcl.html}{mcl.html}}
   The html generated from the source by zoem.

\item{\aref{http://micans.org/mcl/src/mcl-latest/src/doc/mcl.1}{mcl.1}}
   The troff generated from the source by zoem.

\item{\aref{http://micans.org/mcl/src/mcl-latest/src/doc/mcl.ps}{mcl.ps}}
   The PostScript generated from \it{mcl.1} by groff.

\item{\aref{http://micans.org/mcl/src/mcl-latest/src/doc/mcl.txt}{mcl.txt}}
   The text version generated from \it{mcl.1} by groff.

\itemskip

\item{\aref{http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.azm}{mclfaq.azm}}
   The source for the mcl FAQ.

\item{\aref{http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.html}{mclfaq.html}}
   The html generated by zoem.

\item{\aref{http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.ps}{mclfaq.ps}}
   The PostScript generated by groff from the zoem troff output.

\end{itemize}

\sec1{pitfalls}{Pitfalls}
\car
   This is a young section, with only few entries yet.

\begin{itemize}{{compact}{1}{align}{right}}
\item
   [\pr{system#3}] Beware that the argument/option list (the second
   argument of \mc{system#3}) is encoded
   as a vararg. If you have a single argument, it is easy to
   forget the enclosing curlies. In that case, zoem ignores the
   argument altogether.

\par
   Zoem protects the data returned by \mc{system#3}. So you may
   e.g. think (as I once did) that

\verbatim{\protect{\system{date}{{%e}{%B}{%Y}}}}

\car
   Is a neat way to create a vararg, but you will end up with
   something like

\verbatim{\protect{\{24\}\{April\}\{2004\}}}


\item
   [Package authors] Beware of using \it{and} scope within \it{at} scope
   within a \mc{write#3} invocation that uses the copy filter.

\verbatim{\protect{\write{file}{copy}{ foo \\@{ zut \\&{ bar }}}}}

\par{
   The \v{bar} part will not be evaluated as the copy filter does not apply the
   filtering stage. If the stuff written is read back in from some other part
   of the document, or from another document alltogether, the \v{bar} part will
   be evaluated in a different context than the one in which it was created.
}

\end{itemize}


\sec1{glossary}{Glossary}

\car
 For \bf{user keys}, \bf{dollar keys}, and \bf{dictionary stacks},
 refer to the \capref{dictionary} section and the \capref{macro} section.
 For \bf{grape keys}, refer to the \secref{grape} section.

\par
 For \bf{key signatures} and \bf{key mention}, refer to the \capref{signature}
 section.  For \bf{anonymous keys}: the \capref{anonymous} section.

\par
 \bf{Session variables} are described in the \capref{session} section.
 
\: funky looking macros such as \mc{__searchpath__}
\: that either affect zoem's runtime behaviour (as  \mc{__searchpath__} does)
\: or provide some information to the user
\: (e.g. \mc{__fnin__} and \mc{__fnbase__}).

\par
 For \bf{varargs}, arguments in which a variable number of sub-arguments
 can be stored, and for \bf{blocks}: the \capref{vararg} section.

\par
 For \bf{plain scope}, \bf{device scope}, \bf{at scope}, and \bf{glyph
 sequences}: The \capref{dichotomy} and \capref{dscope} sections.

\par
 For file read and  \bf{inline files}: the \capref{fileread} section.

\par
 Sometimes zoem \it{protects} or \it{unprotects} data. Refer to the
 \capref{protection} section.


\: mq
\"doc::postamble"

