• Table of Contents
• Next Chapter

Chapter 1: Introduction

Yodl was designed in 1996 by Karel Kubat when he needed a good document preprocessor to convert output to either LaTeX (for printing) or to HTML for publishing via a WWW site. Although SGML does this too, he wanted something that is used `intuitively' and with greater ease. This is reflected in the syntax of the Yodl language, in the available macros of the Yodl macro package, and very probably also in other aspects of Yodl. However, Yodl is designed to convert to any output format; so it is possible to write a macro package that converts Yodl documents to, say, the man format for manual pages.

Some highlights of Yodl:

• Yodl allows the inclusion of files. This makes it easier to split up a document into `logical' parts, each kept in a separate file. Thus, a `main document' file can include all the sub-parts. (Imagine that you're the editor of a journal. Authors are likely to send in their submissions in separate files; inclusion can then be very handy!)
• Files which are included are searched for either `as-is', or in a given `system-wide include' directory, similar to the workings of the C preprocessor. Therefore, it is possible to create a set of include files holding macros, and to place them into one macro directory. (See also chapter 4, where a macro package that is distributed with Yodl is described.)
• For all the handled files (either stated on the commandline or included), Yodl supplies an extension if none is present. The default extension is .yo, but can be defined to anything in the compilation of the Yodl program.
• Yodl supports conditional parsing of its input, controlled by defined symbols. This resembles the #ifdef / #else / #endif preprocessor macros of the C language. Yodl also supports other if clauses, e.g., to test for the presence of an argument to a macro.
• Yodl offers hooks to define counters, to modify them, and to use them in a document. Thereby Yodl offers the possibility for automatic numbering of e.g., sections. Of course, some document languages (e.g., LaTeX) offer this too; but some don't. When converting a Yodl document to, say, HTML, this feature is very handy.
• Yodl is designed to be easy to use: Yodl uses `normal' characters to identify commands in the text, instead of insisting weird-looking tags or escape characters. Editing a document in the Yodl macro language is designed to be as easy as possible.
• Similar to other document languages, Yodl supports `character conversion tables' which define how a character should appear in the output.

1.1: From 1.xx to 2.00: what's new?

• Changed Yodl's name expansion. From `Yet Oneother Document Language' to:
  Your Own Document Language
• The following commands are now obsolete and should/must be avoided. Alternatives are always offered.

  ENDDEF

  DECWSLEVEL should be used;

  INCLUDELIT

  NOEXPANDINCLUDE should be used;

  NEWCOUNTER

  DEFINECOUNTER should be used;

  STARTDEF

  INCWSLEVEL should be used;

  UNDEFINEMACRO

  DELETEMACRO should be used;

  WRITEOUT

  FPUTS should be used;

• Several new commands were implemented:

  ADDTOSYMBOL

  adds text to a symbol's value;

  DEFINESYMBOLVALUE

  defines a symbol and its initial value;

  DELETECOUNTER

  opposite from NEWCOUNTER: removes an existing counter;

  IFBUILTIN

  checks whether the argument is a builtin macro;

  IFCOUNTER

  checks whether the argument is a defined counter;

  IFEQUAL

  checks whether two numerical values are equal;

  IFGREATER

  checks whether the first numerical value exceeds the second numerical value;

  IFMACRO

  checks whether the argument is a defined macro;

  IFSMALLER

  checks whether the first numerical value is smaller than the second numerical value;

  IFSYMBOL

  checks whether the argument is a defined symbol;

  PATHINCLUDELIT

  includes literaly a file found in the XXincludepath path;

  POPCOUNTER

  pops a previously pushed countervalue;

  POPMACRO

  pops a previously pushed macrodefinition;

  POPSYMBOL

  pops a previously pushed symbolvalue;

  PUSHCOUNTER

  pushes the current value of a counter, initilaizes the active counter to 0;

  PUSHCOUNTERVALUE

  pushes the current value of a counter, initilaizes the active counter to any value;

  PUSHMACRO

  pushes the current definition of a macro, activates a local redefinition;

  PUSHSYMBOL

  pushes the current value of a symbol, initializing the active value to an empty string;

  SETSYMBOL

  assigns a new value to a symbol;

  SYMBOLVALUE

  returns the value of a symbol as text.

• Several macros were deprecated. Alternatives are suggested in the `man yodlmacros' manpage:
  • enddit();
  • endeit();
  • endit();
  • endmenu();
  • endtable();
  • enumerate(list);
  • itemize(list);
  • menu(list);
  • mit();
  • node(previous)(this)(next)(up);
  • startcenter();
  • startdit();
  • starteit();
  • startit();
  • startmenu();
  • starttable(nColumns)(LaTexAllignment);
• XXincludePath: Symbol installed by Yodl itself, but modifiable by the user: It holds the value of the current :-separated list of directories that are visited (sequentially) by the INCLUDEFILE command. XXincludePath may contain $HOME, which will be replaced by the user's home directory if the `home' or `HOME' environment variable is defined. It may also contain t($STD_INCLUDE), which will be replaced by the compilation defined standard include path. The standard includepath may be overruled by either (in that order) the command line switch -I or the tt(Yodl)_INCLUDE_PATH environment variable. By default, the current directory is added to the standard include path. When -I or tt(Yodl)_INCLUDE_PATH is used, the current directory must be mentioned explicitly. The individual directories need not be terminated by a /-character. In the distributed .deb archive, the standard directory is defined as the current working directory and /usr/share/yodl, in that order.
• Initial blank lines in the generated document are suppressed by default.
• Command line argument -D also allows the assignment of an initial value to a symbol
• Command line argument -P is now -p, the previously defined -p argument is now -n (--max-nested-files), defining the maximum number of nested files yodl will process.
• Command line argument -r (--max-replacements) defines the maximum number of macro and/or subst replacements accepted between consecutive characters read from s.
• All assignents to counters (SETCOUNTER, ADDTOCOUNTER, etc.) not only accept numerical arguments, but also counter names.
• Rewrote several awkwardly coded macros, using the new SYMBOL and COUNTER facilities
• Added experimental, very limited, xml support to help me generating xml for the horrible `webplatform' of the university of Groningen. But at least Yodl now offers xml support as well.
• The default extension for figures in the HTML and XML conversions is now .jpg rather than .gif. The sethtmlfigureext() macro can be used the change the default figure extension.
• There is no limit to the number of conversion-options that can be specified: macros like htmlbodyopt() and latexoption() can be specified as often as required resulting in one concatenated specification.
• Upgraded most of the documentation.
• Separated yodl-macro files for the various formats. While this might not strictly be necessary, I feel this is better than using big fat generic macro definition files which are bloated with `, ' macros. I introduced a generic frame, mentioning the macros that must at least be defined by the individual formats.
• Internally, the software was VASTLY reorganized. I feel that generally programs written in C don't benefit from approaches that have become quite natural for C++ programmers. I had the choice to either rewrite Yodl to a C++ program or to reprogram Yodl in the line of C++, but still using C. I opted for the latter. So, now the src section contains `object-like' function families, like `countermap_...()' handling all counte-related operations, `textvector_...()', handling all text-vector like operations, and other. Other functions reveived minor modifications. E.g., xrealloc() now requires you to specify both the number of elements and the size of the elements. By doing so, it is sheer impossible to overlook the fact that you have to specify the size of the elements, thus preventing the allocation of chars when, e.g., ints are required.
• An old inconvenience was removed: line number counting is now using natural numbers, starting at 1, rather than line indices, starting at 0.
• My old @icce.rug.nl e-mail address has been changed into my current e-mail address:
  "Frank B. Brokken" <f.b.brokken@rug.nl>
• The post processing is now performed by the program `yodlpost'. This program again used Design Patterns originally developed for object oriented contexts, resulting in an program that is easy to maintain. modify and expand.
• The post-processor doesn't use .tt(Yodl)TAGSTART. and .YODTAGEND. anymore.
• The basic conversion formats now supported are html, latex, man, and text. Xml support is experimental, other formats are no longer supported, mainly because my personal unfamiliarity with the format (texinfo), or because the format appears to be somewhat obsolete (sgml).
• Added a Yodl document type `letter', indended to be used with the `brief.cls' LaTeX documentclass
• Yodl 2.00 converts documents much faster than earlier versions.

1.2: Why use Yodl?

First of all, Yodl may lower the threshold of new users to start writing documents. An example of an excellent, though not very user-friendly document language is LaTeX. Typing all the backslash and curly brace characters in LaTeX and remembering that an asterisk must be typed as $*$ may be hard at first. In such situations, a properly configured Yodl macro set removes these obstacles and thereby helps novices. Yodl is designed to be easy to learn. As the Yodl package is growing, so is the manual. The ease of `learning Yodl' may thus somewhat diminish, but just keep in mind: as long as you need just plain texts, Yodl does OK. If you want more functionality, e.g., the composition of manual pages for Unix, dig into the documentation.

Second, Yodl permits to create more than one macro set, defining the same commands, but leading to different output actions. Thereby, the same input file can be converted to several output formats, depending on the loaded macro set. In this, Yodl is a `general front' document language, which converts a Yodl document to a specialized language for further processing. This was of course one of my reasons to write Yodl: I needed a good converter for either LaTeX or HTML.

Third, Yodl always allows an `escape route' to the output format. Most situations can be handled with Yodl macros, but sure enough, some users will want special actions for a given output format. A typical example for the necessity of such an escape route is the typesetting of mathematical formulas. Say you want to use Yodl for a document that is converted either to LaTeX (being a very good mathematical typesetter) or to HTML (a very poor mathematical typesetter). An approach might be to decide inside the document how to typeset a mathematical formula. Yodl provides conditional command processing to accomplish this. The decision would be based on the output format: for LaTeX, you'd typeset the formula using all the facilities that LaTeX offers, and for HTML you'd use poor-mans typesetting. Typically, other pre-processors for documents don't allow such escape routes. Well, Yodl does.

1.3: Copying Yodl

The original author and brainfather of Yodl Karel Kubat would very much like to to hear from you, if you use Yodl in a commercial setting (beats me why).

Also, he likes to receive postcards, preferably from far-away places (i take it that's from outside, or near the edges of, Europe).

His snailmail address:

Karel Kubat
...
Zwolle
The Netherlands

• Table of Contents
• Next Chapter