"Linux Gazette...making Linux just a little more fun! "

YODL: A New, Easy-To-Use Text Formatting Language

by Larry Ayers

Published in Issue 9 of the Linux Gazette

Introduction

Linux/un*x is rich in difficult-to-learn, intricate text formatting systems. Though the quality of printed output can be extremely high, the learning curve can be concomitantly steep.

This has led to the development of "meta-formatting" systems, which allow one common text mark-up system to be output in several formats. An example is SGML, which is very capable but hardly intuitive.

Karel Kubat, a Dutch programmer, has written a new text formatting system which he calls YODL, for Yet OneOther Document Language. (I get the impression that the awkward "oneother" word construct exists because Mr. Kubat wanted to have .yo as a filename suffix, rather than .ya.)

Origins

Karel Kubat had found himself spending an inordinate amount of time marking up documents for HTML, then having to repeat the process for Latex; in other words, he wanted to have a nicely formatted printout of a document and also make it available on a web-page. For various reasons SGML was not satisfying his needs so he set out to write an easy to use document language. His criteria included a minimum of awkward-to-type tags and the ability to include or reference other files in one master file. I think he succeeded remarkably well.

Features

A sample document will give you a good idea of what a .yo file looks like:


COMMENT(File for testing purposes.)

htmlbodyopt(fgcolor)(#0000E0)
htmlbodyopt(bgcolor)(#E0E0C0)

article(Test article for YODL)
       (Karel Kubat)
       (1996)
       
sect(First section) label(first)

This is the first section. Now for a subsection:

subsect(Subsection of first section.)
   
This is the subsection.
    
sect(Second section.)

This is the second section, but ref(first) is the first one.
Lets try some verbatim text.

verb(
 #include 

 int main ()
 {
     printf ("Hello World!\n");
     return (0);
 })

Now some weird characters: !@#$%^*[]{}\|"~`'.

Accents? em(Ich m\"ochte bitte \"uberhaupt ein Bier!)
bf(Apr\`es moi la d\'eluge.) 

subsect(Some lists.)

subsubsect(An itemized list.)

itemize(

    it() Item one.
    
    it() Item two.
    
)
 
subsubsect(A descriptive list.)

description(

    dit(First:) Item one.
    
    dit(Second:) Item two.
    
)

subsubsect(An enumerated list.)

enumerate(

    eit() Item one.
    
    eit() Item two.
    
)

This test file shows you what some of the tagging is like. Here's a brief excerpt from a .yo file showing how other files from the current directory can be included:

sect(Using the yodl program)
includefile(using)

subsect(Language elements)
includefile(elements)

As you can see the tags are in an abbreviated verbal form, which makes them easier to remember. The included files can be completely devoid of tagging. This allows you to concentrate more on content rather than structure; the structure can be mostly contained within the master document. YODL documents are noticeably easier to read in their source format than either HTML or Latex source. Format-specific tags are also allowed, as in the above HTML body tags. They will be ignored by the Latex parser, for example.

YODL is very well documented, and the installation of the docs is an effective demonstration of the system. The docs come in .yo source form; these files are copied to /usr/local/yodl/doc, and then YODL is run on them during the installation, with the end result being several HTML files.

As is true with any "meta-formatter", a user is better-off knowing something about the output format. I think it's necessary to at least glance through the output, just to catch any obvious errors. The advantage of a program like YODL is that it will enable you to avoid the grunt-work of starting from scratch.

Package Contents

The main YODL program is written in C, and it works in conjunction with several shell scripts and macro files. The main supported formats are HTML, Latex, and the troff/groff man and ms formats. There is limited support for conversion to plain ASCII and SGML, as well. As previously mentioned, the documentation is unusually extensive, being about sixty pages worth of well-written material.

Availability

YODL can be downloaded from its home site under the filename yodl-X.YY.tar.gz, with X.YY being a version number. It is also available from ftp://sunsite.unc.edu and its mirrors, as of this writing in the /pub/Linux/Incoming directory.

Larry Ayers<layers@vax2.rain.gen.mo.us>