YODL or Yet Oneother Document Language

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:

htmlbodyopt(fgcolor)(#0000B7)
mailto(karel@icce.rug.nl)
report(XWatch: Watcher of logfiles
        under an X session)
        (Karel Kubat)
        (1996)

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:

chapter(Introduction)
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
detail.

DEFINEMACRO(quart)(0)(\
  latexcommand(\frac{1}{4})\
  txtcommand(1/4)\
  htmlcommand(1/4)\
  mancommand(1/4))

a quart is quart() gallon

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:

footnote(

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

url(

YODL's Macro Files

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.