- 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: What's new since version 4.00.00?

In `Yodl` Version 4.02.00 several new features were introduced.

- Three new builtin commands were implemented:
  STRLEN
  returns the length of its argument, or the length of a symbol's text if the symbol's name is passed as argument to `STRLEN`.
  SUBSTR
  returns a substring of a specified length, starting at a specified offset of its first argument (or returns a substring of a symbol's text if the symbol's name is passed as argument to `SUBSTR`).

- End-of-line comment is now available as the triplet `\``//`. Following `\``//` all subsequent characters on its line as well as initial blanks on the next line are skipped.

- Redesigned `yodlverbinsert`, which now also concatenates multiple identically marked sections.

- Added the macro, writing a non-breaking space character.

- Added the macro ``tbl'` (and support macros ``tr, tc, tnc, ta, tnac`' and ``tline`') as alternative to ``table`' (and support macros). The ``tbl`' macro extends ``table`', and simplifies defining tables.

In `Yodl` Version 4.00.00 some old features were removed, and several new ones were introducted.

- The following builtin commands, considered obsolete since `Yodl` 2.00.00, were removed:
  DUMMY
  no replacement.
  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;

- Three new builtin commands were implemented:
  PUSHSUBST
  allows temporary suppression (or activation) of `SUBST` definitions;
  POPSUBS
  restores the activation type of `SUBST` definitions that was active just before the last `PUSHSUBST` call;
  XXSUBST
  internally used builtin command.

- The `verb` macro now starts with `PUSHSUBST(0)` and ends with `POPSUBST()`.

- The following macros, considered obsolete since `Yodl` 2.00.00, were removed: `endcenter enddit endeit endit endmenu endtable itemize menu mit node startcenter startdit starteit startit startmenu starttable`

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

- Table of Contents
- Next Chapter