Zoem: <Dutch> The sound made by electrical devices and flying bugs. Pronounced: zoom or zum; the vowel is short.
Zoem is an interpretive macro/programming language. It can be used as an allround macro language, but has more specialized uses as well. One such specific use is its support for creating small mark-up languages that map to different devices (creating manual pages and FAQs for html, roff - and PostScript). Zoem has character filtering capabilities tailored to this application. It can also be used for general practical document creation, allowing semantic mark-up, abstraction from repeated (mark-up) elements, centralized control, automatic generation of TOC sections, and more of that cruft. Examples:
| i |
The zoem manual language
for creating html and troff manual pages from a single source.
(see further below).
|
|
| ii |
The zoem FAQ language for the same purpose faqwise.
(see further below).
|
|
| iii |
The doc package providing general HTML support.
The Zoem User Manual
uses this package, which is auxiliary rather than universal.
|
| - |
two-stage processing: macro evaluation and character filtering
|
||||||||||||||||
| - |
simplicity in design
|
||||||||||||||||
| - |
inside out evaluation if needed
|
||||||||||||||||
| - |
arithmetic environment
|
||||||||||||||||
| - |
regexp environment
|
||||||||||||||||
| - |
data storage environment
|
||||||||||||||||
| - |
iteration/list construct (apply macro)
|
||||||||||||||||
| - |
interactive mode fully recovering from errors
|
||||||||||||||||
| - |
interactive mode can be started from the command line,
from within a file, or triggered when an error occurs during processing.
|
||||||||||||||||
| - |
easy and comprehensive IO,
control operators, dictionary stacks, system commands, comprehensive
tracing
|
||||||||||||||||
| - |
fast
|
||||||||||||||||
| - |
autotooled (courtesy Joost van Baal), should build on all Unix platforms
|
Zoem is a language with a lot of low-level programming and macro facilities. These are assembled into high-level macro packages serving a particular purpose. The three examples mentioned before are the man package, the faq package, and the doc package. A document imports one or more macro packages, and is then able to use the high-level constructs defined in the package(s), as well as all the low-level primitives. In this respect, zoem works like many other text-based authoring tools.
| - |
customizable escape character (requires demand first)
|
|
| - |
more power in the filtering language (requires demand first)
|
|
| - |
separate macro packages from zoem package
|
|
| - |
man and FAQ macros depend on ascii character encoding
(in specifying filter rules)
|
|
| - |
too large doc manual (pending on writing chapter mode macros).
|
|
| - |
printf, substr, length macros (requires demand first)
|
|
| - |
doc package: could be made much more modular, more hooks for user.
|
Witness the MCL manual page (html), the MCL manual page (PostScript generated from troff), the MCL FAQ (html), and the MCL FAQ (PostScript generated from troff). And if you are at it, witness The MCL zoem manual source and The MCL zoem FAQ source as well. Those are easy on the eye IMHO. Note that by using the venerable col program, the troff output can be converted to nice looking plain txt format; behold mcl.txt and mclfaq.txt. If you are really getting into this, you are probably interested in the gorier-looking zoem manual language definition the zoem FAQ language definition (that one needs better documentation), and the zoem DOC language definition. If that scared you, their usage is documented in the respective manual pages: behold zoem manual language manual, zoem FAQ language manual, and uh, the doc macros don't have a manual page just yet. Let us finish this documentation link fest with the zoem interpreter manual.
Wed Aug 13 12:31:34 CEST 2003 The present stable zoem release: zoem-02-224. I've now heard of 1.5 people using zoem.
Sun Jun 15 21:29:37 CEST 2003 The present zoem release is a stable release. I have used zoem for nearly two years now, and created 10K+ lines of zoem source. This was transformed into 20K+ lines of html output and 6K+ lines of troff output. I have not yet heard of anyone else using it. Perhaps nobody will! Then such is life :)
Two tiny and playful examples to get an idea of the zoem language. They are from the respective files fib.azm and reverse.azm in the zoem examples directory. Note that your manual page or FAQ will look nothing like the stuff below; visit the examples of usage for a taste of that.
\: test with 'zoem -i fib -o -'
\def{fib#1}{
\set{a}{1}
\set{b}{1}
\set{c}{0}
\while{\let{\c <= \1}}{
\: equivalent:
\: \while{\eqt{lq}{\c}{\1}}{
\setx{c}{\a}
\setx{a}{\let{\a + \b}}
\write{-}{txt}{\c\|}
\setx{b}{\c}
}
}
\write{-}{txt}{Enter a number please, then press <cr> and <ctl-d>\|> }
\setx{num}{\zinsert{-}}
\fib{\num}
\formatted{
\def{reverse#1}{
\push{user} \: being paranoid.
\set{_a}{}
\apply{_#1{\!setx{_a}{{\!1}\!_a}}}{\1}
\: apply creates _#1{\setx{_a}{{\1}\_a}}
\_a
\pop{user}
}}
\set{list}{{1}{2}{3}{\!reverse{{a}{b}{c}}}{4}{5}{6}}
before: \apply{protect#1}{{\list}}
after : \reverse{\eval{\list}}
These examples were included directly from file. Here is how:
\verbatim{\finsert{../examples/fib.azm}}
\verbatim{\finsert{../examples/reverse.azm}}
finsert is a zoem primitive that ensures that all input is no longer subject to zoem evaluation. verbatim is a user space macro defined by the generic zoem package, which is used by each of the man, faq, and doc packages.
Among the things I like best about zoem is the combination of apply#2, anonymous keys, and varargs. It can be used to totally abstract content from lay-out. For example, here is how the Inhabitants of the authoring ecosphere section from the Zoem User Manual is made.
\begin{spacing{{left}{2}}}
\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]}
..
{http://www.google.com/search?q=yodl+yet+oneOther+Documentation+Language}
{yodl}
{yet oneOther Documentation Language}
}
\end{itemize}
\end{spacing}
zoem the language and zoem the interpreter were written by Stijn van Dongen. zoem's build environment was created by Joost van Baal.
Pending a zoem mailing list; here is Stijn's spam-encrypted contact info.