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:

Some aspects of the Zoem language highlighted

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

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}

The Zoem User Manual

View the Zoem User Manual.

Author

zoem the language and zoem the interpreter were written by Stijn van Dongen. zoem's build environment was created by Joost van Baal.

Mailing list

For subscribing to or searching the archives from the zoem-devel mailing list, go here. zoem-devel is a forum where anything zoem-related can be asked.