Yodl

Yodl — originally “Yet oneOther Document Language”, later re-explained as “Your Own Document Language” — is a lightweight document preprocessing language created in 1996 by Dutch programmer Karel Kubat. A Yodl document is a plain-text file sprinkled with simple macro commands like sect(Introduction) and em(emphasized); the yodl processor expands those macros against a chosen macro package to produce HTML, LaTeX, troff man pages, or plain text — one source, many outputs. That idea is unremarkable today, in a world of Markdown, Sphinx, and Pandoc, but Yodl arrived years before any of them, and it is still quietly doing the job it was built for: every time a distribution builds the Z shell’s manual, Yodl is the tool that turns the master sources into man pages and Texinfo.

History & Origins

In the mid-1990s Karel Kubat, then working at the ICCE institute of the University of Groningen in the Netherlands, faced a problem familiar to anyone who wrote documentation in that era: every document had to be marked up once in LaTeX for printing and again in HTML for the department’s web site. The obvious standard answer — SGML with its heavyweight toolchains — did not satisfy him. So in late 1995 and early 1996 he wrote his own general-purpose document language for personal use, initially calling it DOM, for “document maintainer.”

Colleagues at ICCE adopted the tool almost immediately, which pushed Kubat into rewriting it properly, adding converters and documentation, and releasing it as Yodl. The self-deprecating name — Yet oneOther Document Language — acknowledged how crowded the field already was. A September 1996 review in Linux Gazette and Kubat’s own November 1997 article in Linux Journal brought the tool to the wider free-software community, and it was distributed from the ICCE FTP server at the University of Groningen. Debian packaged it in 1998, and in 1999 the Samba project shipped version 2.0 with its man pages maintained in Yodl.

The language’s second life began in 2004, when Frank B. Brokken — Kubat’s University of Groningen colleague and co-author of the original C++ Annotations — released Yodl 2.00, a complete rewrite, and took over as primary developer. Yodl has been Brokken’s project ever since, and under his maintenance the acronym was recast as the friendlier Your Own Document Language.

Design Philosophy

Yodl occupies a deliberate middle ground between two extremes of 1990s documentation tooling:

• Lighter than SGML. Where SGML demanded DTDs, validating parsers, and verbose angle-bracket markup, Yodl documents are ordinary readable text with occasional command(argument) calls. Kubat’s stated goal was a document language that was easy to use — something you could teach a colleague in an afternoon.
• More structured than raw formats. Unlike writing LaTeX or troff directly, a Yodl source encodes intent (sect(), em(), footnote()) rather than formatting, so the same file can be rendered faithfully by very different back ends.
• Format-agnostic by construction. The yodl binary itself knows nothing about HTML or LaTeX. It is a pure macro processor; all output-format knowledge lives in replaceable macro packages. The standard distribution targets HTML, LaTeX, man, and plain text, and adding a new format means writing a new macro set, not modifying the program.
• Your own document language, literally. Because users can define macros (DEFINEMACRO), include files, set counters, and perform substitutions, each project can grow a small domain-specific vocabulary on top of the core — which is exactly what zsh did with its own macro layer for shell documentation.

What Yodl Looks Like

A minimal Yodl article looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

article(A Short Yodl Example)
       (Jane Author)
       (July 2026)

sect(Introduction)

This is plain running text. Words can be em(emphasized),
set in bf(boldface), or shown as tt(teletype code).

sect(A List)

itemization(
    it() the first item
    it() the second item, with a footnote(like this one)
)

verb(
    // verbatim text: nothing in here is expanded
    int main()
)

Commands take their arguments in parentheses, uppercase names (DEFINEMACRO, INCLUDEFILE, SUBST) are built into the processor itself, and everything else comes from macro packages. Running the source through the wrapper scripts produces the different outputs:

1
2
3
4

yodl2html example.yo    # -> example.html
yodl2latex example.yo   # -> example.latex
yodl2man example.yo     # -> troff man page
yodl2txt example.yo     # -> plain text

Key Features

Evolution

Yodl’s history divides cleanly into two eras. The Kubat era (1996–early 2000s) produced the 1.x series: the original C implementation, the standard converters, and the language’s moment of greatest visibility, when Samba adopted it for man pages and zsh made it the master format for its documentation. During these years Yodl passed through the hands of several Debian maintainers and settled into its niche as a documentation build tool.

The Brokken era (2004–present) began with the ground-up rewrite released as 2.00 in August 2004 — old sources “usually require minor modifications,” the changelog noted. Major versions 3.00 (November 2010) and 4.00 (June 2017) followed, the latter pruning macros that had been deprecated since 2.0 and adding new substitution builtins. Development has never stopped: 2025 alone saw three releases, and 4.05.02 arrived in February 2026. Few tools from 1996 can show a thirty-year unbroken maintenance record under essentially two developers.

What changed around Yodl matters as much as what changed in it. The problem Yodl solved — single-source documentation rendered to multiple formats — was later attacked by DocBook, then reStructuredText and Sphinx, then Markdown and Pandoc. Samba itself migrated from Yodl to DocBook with version 2.2. Yodl never tried to compete for that mainstream; it stayed small and dependency-light, which is precisely why the projects that adopted it early have had little reason to leave.

Current Relevance

Yodl today is a healthy niche tool with one very large invisible footprint. Its flagship user is zsh: the master source of the Z shell’s manual is written in Yodl, and building zsh’s documentation — the man pages and Texinfo files consulted by millions of users of the shell that macOS ships as its default — requires the yodl package. That single dependency keeps Yodl in the repositories of Debian, Ubuntu, Arch Linux, and other distributions.

Its second constituency is Frank Brokken’s own ecosystem: the C++ Annotations (a free, book-length C++ text maintained since 1994 and used in university courses), the Bobcat library, and the bisonc++ and flexc++ generators all keep their documentation in Yodl. The project lives on GitLab with current documentation and steady releases. Nobody would call Yodl a growth technology — new projects overwhelmingly reach for Markdown-based toolchains — but as actively maintained, purpose-built infrastructure, it is in better shape than most of its 1990s contemporaries.

Why It Matters

Yodl is an early, working answer to a question the industry spent the next two decades re-answering: how do you write documentation once and publish it everywhere? Its design — readable plain-text source, semantic rather than presentational markup, pluggable output back ends — anticipated the architecture of Sphinx, AsciiDoc, and Pandoc by years. It also demonstrates the quiet longevity of well-scoped tools: by refusing to become a platform, Yodl has outlived far grander documentation systems, and it still sits in the build path of one of the most widely used programs on Earth. Every freshly built zsh man page is, in 2026, still a Yodl document that got compiled — a thirty-year-old Dutch solution to the two-markups problem, doing its job.