YODL or Yet Oneother Document Language

Would you like to publish the texts you write in more than one format—PostScript for printing, plain ASCII for e-mail, and HTML for the a web page? YODL could be just the language you need.
Using YODL

The macro package that comes with YODL defines four main types of documents: articles, reports, books and man pages. A YODL source file must always mention what type of document is being processed. The difference between the document types is that different top-sectioning commands are defined for each (e.g., an article has no chapters, a report has no parts and a man page has its own specific sections) and how the HTML converter splits the resulting HTML file into different sub-files. The HTML output is split by chapters, which are reached via a clickable table of contents and by “next chapter” links. The statement that defines the document type also sets the document title, the author and the date. (If you're familiar with LaTeX then all this probably rings a huge bell. Yes, I'm guilty of “borrowing” wherever I can.)

Before stating the document type, several optional commands can be specified to alter the appearance of the document. Examples are mailto, a macro that sets the default e-mail address for HTML output, or htmlbodyopt, a macro that is used to define the foreground or background colors. A sample document could therefore be started as:

report(XWatch: Watcher of logfiles
        under an X session)
        (Karel Kubat)

These statements would be followed by the document. Reports are divided into chapters, chapters into sections, sections into subsections, etc. When labels are used following the sectioning commands, references can be made to those labels. In HTML the references are clickable links:

This is the introductory chapter. Specific
information about the installation is in
chapter ref(install).
chapter(Installation) label(install)
This chapter describes the installation in
As an example of user-defined macros, consider the following. Let's say that you want to typeset 1/4 either as shown here, or as a fraction with the 1 above the 4. The layout of this fraction will depend on the output format, with only LaTeX supporting the latter notation. The way to accomplish this would be to define a new macro, say quart:
This statement defines a macro called quart having zero arguments. Macros can have up to thirty-five arguments. The macro expands to a command in each output format, LaTeX, HTML, man or plain ASCII—one per conversion. Now, the new command can be used as:
a quart is quart() gallon
Also, note that the backslash character can be used to split long lines into readable source code, as in shell script programming. It's just one more feature that I considered handy and, therefore, implemented.

The YODL language has tons of other useful macros—there's not space for a complete enumeration. However, here's a couple just for the fun of it. You can use footnotes in a document by specifying:


Depending on the output format, the text is either a real footnote or it is placed in the running text. Similarly, the macro:

puts a clickable URL in a HTML document or mentions the description and location in other types of output. And there's lots more, including the way YODL handles accent characters. All can be found by reading the documentation that comes with the YODL archive.

YODL's Macro Files

What YODL Still Needs

As I said before, I now consider YODL to be in a beta state, and I've released it to whoever wants it. One of the great things about the Linux community is that it is a pool of millions of beta-testers. I expect YODL to continue to evolve over the next few months.

In any case, what YODL still needs is a flawless converter to plain ASCII via the groff route. I wrote two converters: one that interfaces to the man format and one that interfaces to the ms format. That's at least a good start; though the man and ms packages can do more than just what I've picked out. Furthermore, the HTML converter only supports “standard” HTML, no nifty features such as frames, although there is some rudimentary table support. And, of course, converters to other formats would be welcome, like a converter to the texinfo format for the creation of info files, etc.

All in all, YODL has already proven itself in our department, where almost all documents that accompany our software are now written in the YODL language. I hope you won't find YODL worthwhile looking at, or I'll be swamped emptying my mailbox for the next few months and improving the YODL package. All kidding aside, I hope this article has tickled your curiosity enough, that you'll try out YODL and discover its usefulness.

Karel Kubat lives in the northern part of the Netherlands with his family, cats and 1967 Volvo Amazon. He's a full-time Linux fanatic, who can be reached via e-mail at karel@icce.rug.nl.