- Table of Contents
- Next Chapter

# Chapter 1: Introduction

`Yodl` stands for `Your Own Document Language' (originally: `Yet Oneother Document Language`) and is basically a pre-processor to convert document files in a special macro language (the `Yodl` language) to any output format. The `Yodl` language is not a `final' language, in the sense that it can be viewed or printed directly. Rather, a document in the `Yodl` language is a `pre-document', that is converted with some macro package to an output format, to be further processed.

`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.

This document first describes `Yodl` from the point of the user: how can macros be defined, how is the program used etc.. Next, my own macro package is presented and the macros therein described. Finally, this document holds technical information about the installation and the inner workings of `Yodl`.

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

Compared to earlier versions, `Yodl` Version 2.00 is a complete rebuilt, and offers many new features.

- 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?

Yodl is not a word processor, not even an editor. At first glance you might say, yeah, why should I learn Your Own Document Language? The answer is exactly that: because it can be Your own document language!

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

Yodl is free software; it is distributed under the terms of the GNU General Public Licence. For details, please refer to the file COPYING.

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