Introduction	Release log	Features
Language examples	Download	Some TODO items
Usage examples		Author
The Zoem User Manual		Mailing list

Zoem

an interpretive macro/programming language

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.

Some aspects of the Zoem language highlighted

two-stage processing: macro evaluation and character filtering

simplicity in design

-		a single first-level meta character
-		a single way of delimiting strings and scopes
-		generic building blocks
-		macros can be easily treated as data
-		strict syntax, no fuzzy context rules

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.

Some TODO items

-		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, split, pack macros (requires demand first)
-		doc package: could be made much more modular, more hooks for user.

Examples of usage

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.

Other people exist writing stuff using zoem. Not many yet. Joost van Baal has used the faq package and the man package to create documentation for GnuPG (in Dutch), caspar, and the strong (fire)walls of uruk. The links point to directory listings; the zoem source files have .azm suffixes. The Makefile(.am) files might be of interest as well.

Download Zoem

Download from micans.org and install from source.

Look at the ChangeLog.

Debian Zoem is also available as a package for Debian GNU/Linux, packaged by Joost van Baal who created Zoem's autotooled build environment as well. If you are Debianista and interested:

add

   deb http://mdcc.cx/debian local contrib

to /etc/apt/sources.list, and run

   dselect update && apt-get install zoem

OpenBSD Andreas Kahari built an OpenBSD port. Hopefully that link is sufficient to get interested OpenBSD people going.

Release log

Here is the zoem ChangeLog.

The People - Packages standing continues to be the main focus of this section (note that its structure is sequentially bottom-up paragraph based). The OpenBSD port (courtesy Andreas Kahari) has fully materialized, so packages are leading 2.0 to 1.0. (The 1.0 people using zoem have used it to document no less than three different projects so far).

Mon Oct 27 22:37:34 CET 2003 zoem-03-300 is the present stable zoem release. The People - Packages standing is now at an exciting 1.0-1.75 (the odds of the OpenBSD port are looking better with every release). These are people and packages known to me, mind you. The actual numbers could be even larger. The first zoem user (external to me) has already made a significant number of documents. He seems a much more balanced person now.

This release has one known bug. The recently introduced \:/ sequence (which introduces a comment up till and including the following newline) messes up the line count supplied during error reporting. It's high on the TODO list. You can remove newlines as well by simply preceding them with a backslash. The difference is that this happens at processing time rather than pre-processing time. A normal comment (\: followed by an alphanumeric, whitespace, or backslash character) works just fine.

Sun Oct 12 20:51:29 CEST 2003 zoem-03-285 was released. Perhaps a zoem OpenBSD port will be made, so let's say 1.5 zoem packages exist versus 1.0 people other than me using zoem (that's a 0.5 decrease). People - Packages: 1.0 - 1.5.

Sat Oct 11 16:06:22 CEST 2003 At Mon 22 Sep 2003, zoem-03-265 was released.

Wed Aug 13 12:31:34 CEST 2003 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 :)

Examples of zoem

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{\a <= \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}