\documentclass{report}
\usepackage{a4,epsf}

\usepackage[T1]{fontenc}
\usepackage{makecell}
\hfuzz=4pt % don't fuss when less than 4pt
\input{../../../../../wip/macros/xlatin1.tex}
\setlength{\parskip}{3mm} % height between par
\setlength{\parindent}{0mm} % no par indent

\title{Yodl 4.05.02}
\author{Frank B. Brokken (f.b.brokken@rug.nl)\ \\ 
        initially by Karel Kubat\ \\ 
Center for Information Technology, University of Groningen}
\date{1996-NOW}
\begin{document}\maketitle

\abstract{ 
    Yodl is a package implementing a pre-document language and tools to
process it.  The idea of Yodl is that you write up a document in a
pre-language, then use the tools (e.g. yodl2html) to convert it to some final
document language.  Current converters are for HTML, man, LaTeX, a poor-man's
text converter and an experimental XML converter.  Main document types are
`article', `report', `book', `letter' and `manpage'.  The Yodl document
language is designed to be easy to use and extensible.
    }


\tableofcontents


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

\texttt{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
\texttt{Yodl} language, in the available macros of the \texttt{Yodl} macro package, and very
probably also in other aspects of \texttt{Yodl}. However, \texttt{Yodl} is designed to convert
to \emph{any} output format; so it is possible to write a macro package that
converts \texttt{Yodl} documents to, say, the \texttt{man} format for manual pages. 

Some highlights of \texttt{Yodl}:
    \begin{itemize}
    \item  \texttt{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!)
    \item  Files which are included are searched for either `as-is', or in a
given `system-wide include' directory, similar to the workings of the \textbf{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
\ref{MACROPACKAGE}, where a macro package that is distributed with \texttt{Yodl} is
described.)
    \item  For all the handled files (either stated on the commandline or
included), \texttt{Yodl} supplies an extension if none is present. The default
extension is \texttt{.yo}, but can be defined to anything in the compilation of the
\texttt{Yodl} program.
    \item  \texttt{Yodl} supports conditional parsing of its input, controlled by defined
symbols. This resembles the \texttt{\#ifdef} / \texttt{\#else} / \texttt{\#endif} preprocessor
macros of the \textbf{C} language. \texttt{Yodl} also supports other \texttt{if} clauses, e.g.,
to test for the presence of an argument to a macro.
    \item  \texttt{Yodl} offers hooks to define counters, to modify them, and to use them
in a document. Thereby \texttt{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 \texttt{Yodl} document to, say, HTML, this
feature is very handy.
    \item  \texttt{Yodl} is designed to be easy to use: \texttt{Yodl} uses `normal' characters to
identify commands in the text, instead of insisting weird-looking tags or
escape characters.  Editing a document in the \texttt{Yodl} macro language is designed
to be as easy as possible.
    \item  Similar to other document languages, \texttt{Yodl} supports `character
conversion tables' which define how a character should appear in the output.
    \end{itemize}
    This document first describes \texttt{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 \texttt{Yodl}.

\section{What's new since version 4.00.00?}
    In \texttt{Yodl} Version 4.02.00 several new features were introduced.

\begin{itemize}
    \item  Three new builtin commands were implemented:
        \begin{description}
        \item[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
            \texttt{STRLEN}. 
        \item[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
            \texttt{SUBSTR}).
        \end{description}

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

\item  Redesigned \texttt{yodlverbinsert}, which now also concatenates multiple
        identically marked sections.

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

\item  Added the macro `\texttt{tbl'} (and support macros `\texttt{tr, tc, tnc, ta,
        tnac}' and `\texttt{tline}') as alternative to `\texttt{table}' (and support
        macros). The `\texttt{tbl}' macro extends `\texttt{table}', and simplifies
        defining tables.
    \end{itemize}

In \texttt{Yodl} Version 4.00.00 some old features were removed, and several new ones
were introducted.

\begin{itemize}
    \item  The following builtin commands, considered obsolete since \texttt{Yodl}
        2.00.00, were removed:
        \begin{description}
        \item[DUMMY] no replacement.
        \item[ENDDEF] DECWSLEVEL should be used;
        \item[INCLUDELIT] NOEXPANDINCLUDE should be used;
        \item[NEWCOUNTER] DEFINECOUNTER should be used;
        \item[STARTDEF] INCWSLEVEL should be used;
        \item[UNDEFINEMACRO] DELETEMACRO should be used;
        \item[WRITEOUT] FPUTS should be used;
        \end{description}

\item  Three new builtin commands were implemented:
        \begin{description}
        \item[PUSHSUBST] allows temporary suppression (or activation) of
            \texttt{SUBST} definitions;
        \item[POPSUBS] restores the activation type of \texttt{SUBST} definitions
        that was active just before the last \texttt{PUSHSUBST} call;
        \item[XXSUBST] internally used builtin command.
        \end{description}    

\item  The \texttt{verb} macro now starts with \texttt{PUSHSUBST(0)} and ends with
        \texttt{POPSUBST()}.

\item  The following macros, considered obsolete since \texttt{Yodl}
        2.00.00, were removed:
        \texttt{
        endcenter
        enddit
        endeit
        endit
        endmenu
        endtable
        itemize
        menu
        mit
        node
        startcenter
        startdit
        starteit
        startit
        startmenu
        starttable
        }
    \end{itemize}

\section{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 \emph{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 \texttt{\$$*$\$} 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 \emph{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.

\section{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.

\cleardoublepage\chapter{Yodl User Guide}
This section describes the \texttt{yodl} program from the point of a meta-user, 
one who is interested in how macro files work, or one who wants to write a new 
converter. If you're just interested in using Yodl with the pre-existing 
converters and macro files, skip this chapter and continue with the macro 
package description (chapter \ref{MACROPACKAGE}).

The \texttt{Yodl} program the main converter of the Yodl package. The basic usage 
of the \texttt{yodl} program, \texttt{yodl}'s built-in macros, and the syntax of the
Yodl language is described here.

\section{Using the yodl program}
    \texttt{Yodl} reads one or more input files, interprets the commands therein, and
writes one output file. The program is started as:
    \begin{center}
    yodl \emph{options} \emph{inputfile} \emph{{[}inputfile...{]}}
    \end{center}
    In this specification, the options are optional. Most options have `long
variants' also, which are mentioned in the following list. In this list,
\texttt{-x, +NOTRANS(-\{\}-\{\})optionname} are two alternate ways to specify option x. If \texttt{-x}
takes an argument, it may be specified immediately following the \texttt{-x}, but
separating blanks may also be used. Options not taking arguments can be
combined (e.g., \texttt{-a -b -c} may be combined to \texttt{-abc}). Arguments specified
with long options should be separated from the long option using a \texttt{=}
character.

The following options are currently available:

\typeout{Original Yodl file: userguide/optionlist.yo}\begin{itemize}
    \item  \texttt{-D, +NOTRANS(-\{\}-\{\})define=NAME{[}=VALUE{]}}: Defines \emph{name} as a symbol. This
option is acts like \texttt{DEFINESYMBOL(NAME)()}. If \texttt{=VALUE} is added, \texttt{NAME}
is initialized to \texttt{VALUE} (identically to \texttt{DEFINESYMBOL(NAME)(VALUE)}).
    \item  \texttt{-d, +NOTRANS(-\{\}-\{\})definemacro=NAME=EXPANSION}: Defines \texttt{NAME} as macro
expanding to \texttt{EXPANSION}
    \item  \texttt{-h, +NOTRANS(-\{\}-\{\})help}: usage information is written to the standard error
stream, describing all of Yodl's options.
    \item  \texttt{-i, +NOTRANS(-\{\}-\{\})index{[}=file{]}}: `file' is the name of the index file. By
default \texttt{$<$outputbase$>$.idx} is used. No default when output is written to
stdout. The index file is processed by Yodl's post-processor, \texttt{yodlpost}.
    \item  \texttt{-I, +NOTRANS(-\{\}-\{\})include=DIR}: This defines the system-wide include directory
where \texttt{Yodl} searches for its input files. E.g. a statement to include a
given file, like:
        \begin{verbatim}
INCLUDEFILE(latex)
\end{verbatim}

    Yodl now searches for the file \texttt{latex} in the current directory,
and when that fails, in the system-wide include directory. The system-wide
include directory is typically the place where the maintainer of a system
stores macro-files for Yodl. This searching process applies to files that are
included inside a document but also applies to filenames on the command line
when invoking the \texttt{Yodl} program.

The name of the included file (\texttt{latex} in the above example) is the bare
name, \texttt{Yodl} supplies a default extension (\texttt{.yo}), if necessary. 

The \texttt{-I} option overrules Yodl's built-in name for the system-wide
include directory. The built-in name is defined when compiling Yodl, and is,
e.g., \texttt{/usr/share/yodl}. Furthermore, the definition may contain \$HOME,
which is replaced by the user's home directory if the `home' or `HOME'
environment variable is defined. It may also contain \$STD\_INCLUDE, which 
is replaced by the compilation defined standard include path. The standard
includepath may be overruled by either (in that order) the command line switch
\texttt{-I} or the \texttt{tt(Yodl)\_INCLUDE\_PATH} environment variable. By default, the
current directory is added to the standard include path. Hewver, when \texttt{-I}
or \texttt{tt(Yodl)\_INCLUDE\_PATH} is used, the current directory must be mentioned
explicitly.  The individual directories need not be terminated by a
/-character.  In distributed \texttt{.deb} archives, the standard directory is
defined as \texttt{/usr/share/yodl} (prefixed by the current working directory).
   \item  \texttt{-k, +NOTRANS(-\{\}-\{\})keep-ws}: Since \texttt{Yodl} version 2.00 blanks at the begin and end
of lines are ignored, even without a trailing \textbackslash{}, when the `white space level'
is non-zero. Earlier versions kept these blanks. The legacy handling of white
space at end of lines can by obtained using the \texttt{-k} flag. Note that white
space are always kept when using verbatim copying, and when the white-space
level is zero.
    \item  \texttt{-m, +NOTRANS(-\{\}-\{\})messages=SET}: Set the so-called `message level' 
to a combination of the SET \texttt{acdeinw}. The letters of this set have the
following meanings:
    \begin{itemize}
    \item  \texttt{a}: alert. When an alert-error occurs, Yodl terminates. Here Yodl
requests something of the system (like a \texttt{get\_cwd()}), but the system fails.
    \item  \texttt{c}: critical. When a critical error occurs, Yodl terminates.  The
message itself can be suppressed, but exiting can't. A critical condition is,
e.g., the omission of an open parenthesis at a location where a parenthesized
argument should appear, or a non-existing file in an \texttt{INCLUDEFILE}
specification (as this file should be parsed). A non-existing file with a
\texttt{NOEXPANDINCLUDE} specification is a plain (non-critical) error.
    \item  \texttt{d}: debug. Probably too much info, like getting information about 
each character that was read by Yodl.
    \item  \texttt{e}: error. An error (like doubly defined symbols). Once an error
has been encountered the remainder of the input is still parsed (up to a
maximum number of errors), but no output is generated.
    \item  \texttt{i}: info. Not as detailed as `debug', but still very much info,
like information about media switches.
    \item  \texttt{n}: notice. Information about, e.g., calls to the builtin
function calls.
    \item  \texttt{w}: warning. Something you should know about, but probably not
affecting Yodl's proper functioning
    \end{itemize}
    Non-configurable is the handling of an \emph{emergency} message. These
messages can't be suppressed, but shouldn't happen, as they point to some
internal error. It would be appreciated to 
        \texttt{receive information}\footnote{mailto:f.b.brokken@rug.nl} 
    about these messages if they ever occur.
    \item  \texttt{-n, +NOTRANS(-\{\}-\{\})max-nested-files=NR}: This option causes Yodl to abort when
the number of nested input files exceeds \texttt{NR}, which is 20 by
default. Exceeding this number usually means a circular definition somewhere
in the document. This is the case when, a file \texttt{a.yo} includes \texttt{b.yo},
while \texttt{b.yo} includes \texttt{a.yo} etc.. It does not prevent recursive macro- or
subst-replacements. For that the \texttt{-r} (\texttt{+NOTRANS(-\{\}-\{\})max-replacements}) option is
available.
    \item  \texttt{-o, +NOTRANS(-\{\}-\{\})output=FILE}: This option causes Yodl to write its output to
\texttt{FILE}. By default, the output goes to the standard output stream. E.g.,
you can use \texttt{Yodl} to read a file \texttt{input} and to write to
\texttt{output} with the following two commands:
    \begin{verbatim}

        yodl input > output
        yodl -ooutput input
    
\end{verbatim}

    The difference being that in the latter case an index file is generated,
but not in the former case. Notice that writing an index file can be forced
when the \texttt{+NOTRANS(-\{\}-\{\})index} option is specified.
    \item  \texttt{-p, +NOTRANS(-\{\}-\{\})preload=CMD}: This option `pre-loads' the string \texttt{cmd}. It
acts as though \texttt{cmd} was the first command in the first input file that is
processed by \texttt{Yodl}.

More than one \texttt{+NOTRANS(-\{\}-\{\})preload=CMD} options may be present on the command
line.  Each of the commands is then processed in turn, before reading 
any file.
    \item  \texttt{-r, +NOTRANS(-\{\}-\{\})max-replacements=NR}: This option causes Yodl to abort when
the number of macro calls or subst-replacements exceeds \texttt{NR $*$ 10,000}. 
By default, \texttt{NR} equals 1. Setting \texttt{+NOTRANS(-\{\}-\{\})max-replacements=0} implies that 
no macro- or subst-replacement checks are performed.
    \item  \texttt{-t, +NOTRANS(-\{\}-\{\})trace}: This option enables tracing: while parsing, Yodl
writes its output to the standard error stream. As is the case with the \texttt{-k}
option, this option is defined for debugging purposes only.
    \item  \texttt{-V, +NOTRANS(-\{\}-\{\})version}. This option shows \texttt{Yodl}'s actual version.
    \item  \texttt{-v, +NOTRANS(-\{\}-\{\})verbose}: This option increases Yodl's `verbosity level' and
may occur more than once. By default yodl shows alerting, critical,
emergency and error messages. Each \texttt{+NOTRANS(-\{\}-\{\})verbose} option adds a next
message level. In order, warning, notice, info and debug messages are
added to this set. It is also possible to suppress messages. The
\texttt{VERBOSITY} builtin can be used for that.
    \item  \texttt{-W, +NOTRANS(-\{\}-\{\})warranty}. This option shows a warranty disclaimer and a
copyright notice. 
    \item  \texttt{-w, +NOTRANS(-\{\}-\{\})warn}: The presence of this option caused Yodl to warn when,
e.g., symbols are redefined.
\end{itemize}

The \emph{inputfile} elements on the command line specify which files Yodl should
process. All names are supplied with an extension\footnote{this extension is
defined in the installation of Yodl and is usually \texttt{.yo}}. The files are then
searched for in the directories mentioned in the include-path. Files may also
be specified using absolute pathnames.

Note that all filenames on the command line are input files. To define an
output file, either use the \texttt{+NOTRANS(-\{\}-\{\})output} option or redirect the output. 

\section{The Yodl grammar}
    The grammar which is used by \texttt{Yodl} mixes `real' text that should appear on the
output with \emph{markups}: commands for \texttt{Yodl}. The markups must follow a certain
grammar, which is described in this section. \texttt{Yodl} therefore falls in the
category of `markup languages', in contrast to `WYSIWYG'-programs. As a
consequence, \texttt{Yodl} promotes concept-oriented writing.

Basically, Yodl only does `something special' when it encounters the name of a
builtin function or the name of a user-defined macro, followed by a
parenthesized argument. Sometimes a function or macro requires multiple
arguments, which must then be specified in sequence.  All required parameter
lists, however, must be specified within the same input file. It is not
allowed to split the activation of a builtin function or macro over multiple
input files. Plain text, on the other hand, may be split over multiple files.

In this section the elements of \texttt{Yodl}'s grammar are briefly discussed.

\subsection{Language elements}
        At the lowest level, \texttt{Yodl}'s lexical scanner returns small pieces of
information to its parser. These pieces of information are called \emph{tokens},
and consist of elements like a blank space, a non-blank character, or an
end-of-ile flag. These tokens are at too small an aggregation level to be
useful for the current user-guide, so here we concentrate our discussion 
on the next aggregation level: compound elements and conceptual elements. 

Compound elements relate to the basic tokens as words in a sentence to the
individual letters of the words. These compound elements are identifiers,
names, numbers, parameter lists and arguments.

Conceptual elements are found at the next higher aggregation levels:
\emph{builtin functions} are the buildin blocks for all of \texttt{Yodl}'s functionality,
\emph{symbols} and \emph{counters} are \texttt{Yodl}'s \emph{variables}, and (user defined)
\emph{macros} extend \texttt{Yodl}'s functionality beyond those of the basic builtin
functions.

In the coming sections these basic and conceptual elements are discussed in
greater detail.

\subsubsection{Identifiers and Names}
            \emph{Identifiers} are names that can have a special meaning in the \texttt{Yodl}
language. E.g., the sequence \texttt{INCLUDEFILE} is an identifier: when
followed by a filename in parentheses, \texttt{Yodl} will take some special action (in
this case, read the file as a \texttt{Yodl}-source file).

Identifiers may consist of uppercase or lowercase characters. No other
characters may appear in them. 

In particular, \emph{note} that this diverts from the well known definition for
identifiers used in most programming languages: identifiers may not contain
underscores, nor digits. \texttt{Yodl}, therefore, won't accept identifiers like
\texttt{run4} or \texttt{under\_score}.

\emph{Names} are sequences of characters, not containing white space characters.
(i.e., any series of characters not containing spaces, tabs or
newlines). Names are allowed with certain builtin functions, like the
\texttt{INCLUDEFILE} function, expecting the name of a file as its argument.

\subsubsection{Numbers}
            \emph{Numbers} consist of digits and an optional minus sign. They are most
often used for so-called \emph{counters}. In some contexts (e.g. with the builtin
function VERBOSITY \ref{VERBOSITY}, \emph{hexadecimal}
numbers are allowed. Hexadecimal numbers have 16 `digits': the familiar 0-9,
but also \texttt{a-f} (or \texttt{A-F}), representing the decimal values 10 until 15,
respectively. Hexadecimal values are usually prefixed by \texttt{0x}, for example
\texttt{0x4e}.  

In other contexts (in particular, with character tables \ref{CHARTABLES}),
octal numbers or character constants are allowed too.

An octal number only consists of the digits 0-7. In \texttt{Yodl}, octal values
\emph{must} consist of three digits, and \emph{must} be preceded by a backslash.

Character constants may very well be considered numerical values. Character
constants consist of a character value between single quotes, for example
\texttt{'a'}. 

Refer to section \ref{CHARTABLES} for more detailed information about the use
of octal values and character constants.

\texttt{Yodl} has no concept of floating point values nor does it have facilities for 
performing floating point arithmetic.

\subsubsection{Arguments to builtin functions and macros}
            Arguments that are passed to \texttt{Yodl} builtin functions or user-defined macros
must be surrounded by a pair of matching open- and close-parentheses.  Each
parameter list contains exactly \emph{one} argument.

An argument is recognized when it immediately follows the name of a builtin
function or user-defined macro. Some functions or macros expect multiple
arguments. In those cases, the required number of arguments must be provided,
possibly separated from each other by white-space.

For example, the following shows how to call the builtin function
\texttt{DEFINECOUNTER}, expecting two arguments:
        \begin{verbatim}

    DEFINECOUNTER(MyCounter)()
    DEFINECOUNTER(MyCounter)    ()
    DEFINECOUNTER(MyCounter)(12)
        
\end{verbatim}


\texttt{Yodl} recognizes the arguments of macros when delimited by \texttt{(} and
\texttt{)} characters. As long as the numbers of opening and closing
parentheses match, \texttt{Yodl} correctly recognizes the list. E.g., given a
hypothetical macro \texttt{somemacro}, the following code sample shows the macro
followed by one argument:
        \begin{verbatim}

    somemacro(Here is a chunk of text.)
    somemacro(Here is a some (more) text.)
        
\end{verbatim}
 
    An error occurs when the parentheses aren't balanced: i.e., when the
argument consists of more opening than closing parentheses or \emph{vice versa}
To handle such situations, Yodl offers a `literal-character' mechanism (see
the \texttt{CHAR} macro in \ref{CHAR}) and a `global substitution' mechanism (see
the \texttt{SUBST} macro in \ref{SUBST}). For example, to send the text
        \begin{verbatim}
here's a ")" closing parenthesis
\end{verbatim}
 
    as an argument to our hypothetical macro \texttt{somemacro}, the following can
be used:
        \begin{verbatim}

    COMMENT(-- Alternative 1: using CHAR --)
    somemacro(here's a "CHAR(41)" closing parenthesis)

    COMMENT(-- Alternative 2: using SUBST --)
    SUBST(closepar)(CHAR(41))
    somemacro(here's a "closepar" closing parenthesis)
        
\end{verbatim}

    Both methods have disadvantages: the \texttt{CHAR} method requires you to
remember that an ASCII 41 is a closing parenthesis. The \texttt{SUBST} method
defines a string \texttt{closepar} that is \emph{always} expanded to a closing
parenthesis, wherever it may occur in the text. But whatever method is used,
it should be clear by now that unbalanced arguments can be handled by
Yodl. Also, remember that unbalanced parenthesis pairs are only relevant in
argument lists. Yodl handles parentheses in normal text as ordinary
characters.

\subsubsection{Builtin functions}
            The building blocks of \texttt{Yodl}'s functionality are its \emph{builtin
functions}. Builtin functions exists to manipulate all of \texttt{Yodl}'s builtin types
(character tables, counters, macros and symbols) and to do basic bookkeeping
and flow-control: it is possible to test values of counters and symbols, to
include other input files, to generate warning and error messages, and to
start child- or subprocesses. Each builtin function is described in a separate
subsection of section BUILTIN \ref{BUILTIN}.

\subsubsection{Character translation tables}
            Character translation tables exist to perform conversion specific
transformations. For example, in \texttt{html}, the \textbackslash{}\texttt{'e} is written as
\texttt{\&eacute;}, but in LaTeX it's written as \textbackslash{}\texttt{'e}. Rather than
using a potentially long if-else ladder to determine how to set a particular
character, a character translation table can be used. The character
translation table of a particular conversion is then activated only for that
type of conversion. 

Character table translations are used very late during the processing of
\texttt{Yodl}'s input \texttt{s}: it is the output generator that handles the character
translations. Consequently, macros or builtin function calls that might appear
in a character's redefinition element of a character table are not
expanded. In practice this never is a point of concern. In section
\ref{CHARTABLES} the use of character translation tables is discussed in
detail.

\subsubsection{Counters}
            Some document languages (notably LaTeX) automatically prefix numbers when
typesetting sections, subsections, tables, figures etc..  Other document
languages (e.g. \texttt{html}) don't. 

Therefore, a macro package that converts a Yodl document to LaTeX doesn't need
to provide the numbering of sections etc.. However, if you do want the
numbering and if you want to convert documents to, say, \texttt{html}, then you
must take care of the numbering yourself.

Counters exist to make this possible. Counters can be incremented, can be
given a particular value, can be given a new value temporarily and can be
removed. They always contain integral values, which may be negative.

Section \ref{COUNTERS} describes the use of counters in more detail.

\subsubsection{Macros}
            Macros are comparable to builtin functions, but they can be defined in \texttt{Yodl}
input files. Macros add functionality to \texttt{Yodl} exceeding the basic
functionality of the builtin functions. Macros can have arguments, and they
are used in exactly the same way as builtin functions are used.

When \texttt{Yodl} encounters a macro, it acts as follows:
    \begin{itemize}
    \item  Its arguments are obtained, by reading its argument lists. These 
arguments are not interpreted in any way. They are simply removed from the
input, and stored for further processing;
    \item  References to arguments in the macro's definition (using the \texttt{ARG\#}
notation, where \texttt{\#} is the sequence number of a particular argument) are
replaced by the literal text of the corresponding macro's arguments.
    \item  The thus modified definition text is now pushed back into the input
stream, to be processed by \texttt{Yodl}'s lexical scanner.
    \end{itemize}

Defining macros is described in section \ref{DEFINEMACRO}. Macros may be
defined, deleted, renamed, and temporarily given other definitions.

\subsubsection{Nousermacros}
            When \texttt{Yodl} is started using the \texttt{-w} flag on the command line, then warnings
are generated when Yodl encounters a possible macro name, followed by a
parenthesized argument, without finding a macro by that name.  Yodl then
prints something like \texttt{cannot expand possible user macro}.

Examples of such sequences are, \texttt{The necessary file(s) are here}, or \texttt{see
the manual page for sed(1)}. The candidate macros are \texttt{file} and \texttt{sed}, as
these names could very well have been `valid' user macros followed by their
arguments.

A \emph{nousermacro} can be defined to suppress these warnings, by informing \texttt{Yodl}
that \texttt{file} and \texttt{sed} aren't macros. Nousermacros may be defined and
undefined. See sections \ref{NOUSERMACRO} and \ref{DELETENOUSERMACRO} for
details). 

\subsubsection{Symbols}
            \texttt{Yodl} symbols contain text. They were introduced to allow the flexible
expansion of text, the length and/or content of which cannot be determined in
advance. In particular, symbols are useful to store a series of LaTeX document
options, or a series of \texttt{html} body options. In earlier versions of \texttt{Yodl}
complex and confusing constructions using nested definitions of macros were
used for this. These macros were not only confusingly complex, but they also
suffered from a hard-coded maximum. Symbols solve these drawbacks, and now
that they are available, they are used for all natural situations in which an
initially unknown piece of text must be stored. National language specific
strings are another useful area in which symbols can be used. The symbol
\texttt{CONTENTSHEADING} can be set to the name of the contents heading (e.g.,
\texttt{Contents} in English, \texttt{Inhoud} in Dutch, \texttt{Contenido} in Spanish, and
macros can simply insert the value of the symbol \texttt{CONTENTSHEADING} at the
appropriate location. 

Symbols can be defined \ref{DEFINESYMBOL}, removed \ref{DELETESYMBOL},
(temporarily \ref{PUSHSYMBOL} or permanently \ref{SETSYMBOL}) be given
another value; pushed symbol values can be restored \ref{POPSYMBOL} at a
later point. Of course, their values can also be inserted \ref{SYMBOLVALUE}
into \texttt{Yodl}'s output file.

\subsection{Line continuation}
        To make the typing of input easier, \texttt{Yodl} allows you to end a line with a
backslash character \textbackslash{} and to continue it on the next line. That way you can
split long lines to fit your screen. When processing its input, \texttt{Yodl} treats
these lines as one long line, and ignores the final \textbackslash{} character. This
feature only works when the \textbackslash{} character is the last one on the line (only a
physical newline may follow).

When the line \textbf{following} the one with the \textbackslash{} character has leading spaces,
then these are omitted. This allows you to `indent' a file as you wish, while
the space characters of the indentation are ignored by the \texttt{Yodl} program. 

A trivial example is the following:
    \begin{verbatim}

    Grandpa and\ 
    grandma are sitting on the sofa.
        
\end{verbatim}

    Due to the occurrence of the \textbackslash{} character in the sequence \texttt{and\textbackslash{}}, \texttt{Yodl}
combines the lines to
        \begin{verbatim}

    Grandpa andgrandma are sitting on the sofa.
        
\end{verbatim}

    Note that the spaces before \texttt{grandma} are ignored, since this is the
second line following a \textbackslash{} character.

If you \textbf{do} want one or more spaces while joining lines with \textbackslash{}, put the
spaces \textbf{before} the \textbackslash{} character.
    \ \\ 
    Summarizing:
    \begin{itemize}
    \item  A Line ending in a backslash character is merged with the next
line. 
    \item  This only happens if the \textbackslash{} character is the \textbf{last} character of the 
line, no spaces may appear behind the \textbackslash{}.
    \item  When merging lines, \texttt{Yodl} ignores leading spaces of the second line.
    \end{itemize}
    The question is of course, how do you accomplish that a line really ends
with a \textbackslash{}, when you do \textbf{not} want \texttt{Yodl} to merge it with the following line?
In such a case, type a space character following your \textbackslash{}: \texttt{Yodl} won't combine
the lines.  Or set the \textbackslash{} character as \texttt{CHAR(\textbackslash{})} or \texttt{CHAR(92)}
(see section \ref{CHAR} for the \texttt{CHAR} macro).

When \texttt{Yodl} processes input files, and the white-space level exceeds zero
(see section \ref{INCWSLEVEL}), then all lines are processed as if they
terminated by a \textbackslash{}. This behavior was implemented first with \texttt{Yodl} version
2.00. It can be suppressed using \texttt{Yodl}'s \texttt{-k} flag.

\subsection{The +identifier sequence}\label{PLUSIDENT}
        There may be situations in which you must type a macro name right after a
sequence of characters, while Yodl should recognize this. Imagine that someone
wrote a great macro \texttt{footnote} for you\footnote{someone did, in fact, see
the next chapter}, to typeset footnotes. If you'd type in a document:

\begin{verbatim}
The C Programming Languagefootnote(as defined by 
Kernighan and Ritchie) ...
\end{verbatim}


then of course Yodl would fail to see the start of a macro in the sequence
\texttt{Languagefootnote}. You could say

\begin{verbatim}
The C Programming Language footnote(as defined by 
Kernighan and Ritchie) ...
\end{verbatim}


but that would introduce a space between \texttt{Language} and the footnote.
Probably you don't want that, since spaces between a word and a footnote
number look awful and because of the fact that the footnote number might be
typeset on the following line.

For these special situations, Yodl recognizes the \texttt{+identifier} sequence as
the start of a macro, while the \texttt{+} sign is effectively ignored. In the
above example you could therefore use

\begin{verbatim}
The C Programming Language+footnote(as defined by 
Kernighan and Ritchie) ...
\end{verbatim}


The \texttt{+identifier} recognition only works when the identifier following the
\texttt{+} sign is a macro. In all other situations, a \texttt{+} is just a plus-sign.

(The \texttt{+identifier} sequence furthermore plays an important role in macro
packages. If you're interested, see the file \texttt{shared.yo} which is by default
installed to \texttt{/usr/local/lib/yodl}.)

\subsection{Preventing macros from being expanded}
        One more feature of the Yodl language remains to be described. In the previous
section it was described how a macro may be called immediately following
alphabetical characters. What about the opposite situation where we do \emph{not}
want a macro to be expanded in a particular situation? The \texttt{NOUSERMACRO}
builtin command (cf. section \ref{NOUSERMACRO}) may be used to suppress the
interpretation of a character sequence (e.g., \texttt{file(...)}) as a macro, but
what if a macro should not be expanded in the occasional situation? For this
case various solutions are available:
    \begin{itemize}
    \item  First, the \texttt{tt(...)} and \texttt{verb(...)} macros may be used to
suppress macro expansion. These macros also temporarily alter the
typesetting font, though.
    \item  Second, \texttt{NOEXPAND()} builtin command may be used: the macro name
may be passed to \texttt{NOEXPAND()}, immediately followed by the `argument list':
        \begin{verbatim}
Like this: NOEXPAND(NOEXPAND)(hello world)
\end{verbatim}

    \item  Third, the \texttt{nop()} macro may be used to separate a macro name from
its argument list:
        \begin{verbatim}
Like this: NOEXPAND+nop()(hello world)
\end{verbatim}

    \end{itemize}

\section{Character tables}\label{CHARTABLES}
    The Yodl language provides a way to define character translation tables, to
activate them, and to deactivate them. A character translation table defines
how a character in the input will appear in the output.

There are two main reasons for the need of character translation tables.
First, a document language becomes much easier to use when you can type an
asterisk as $*$ instead of \texttt{\$$*$\$} or \texttt{\textbackslash{}verb/$*$/} (these are sequences from the
LaTeX document language). Hence, a mechanism that expands a $*$ in the input to
to \texttt{\textbackslash{}verb/$*$/} on the output, saves the users a lot of typing.

Second, forcing users to type weird sequences won't work if you're planning on
converting the same Yodl document to a different output format. If the user
types \texttt{\textbackslash{}verb/$*$/} in the input to typeset an asterisk in the output, how
should he or she arrive at a single $*$ in the output in another output format? 

The solution is of course to define the translation for an input character
like $*$ given the output format.

\subsection{Defining character tables}
        
The built-in macro \texttt{DEFINECHARTABLE} defines a character translation table.
It takes two arguments: the name of the table and the character
translations. Hence, each table is defined by its own name.

As an example of a table, consider the following fragment.  It defines a table
that translates the upper case characters \texttt{A} to \texttt{E} to their lower case
equivalents:

\begin{verbatim}
DEFINECHARTABLE(tolower)(
    'A' = "a"
    'B' = "b"
    'C' = "c"
    'D' = "d"
    'E' = "e"
)
\end{verbatim}


Each \texttt{DEFINECHARTABLE} statement \textbf{must} have a non-empty second
parameter. "Empty" character tables cannot be defined, though one
non-translation table is built-in.

The syntaxis of the second argument is as follows:

\begin{itemize}

\item  On separate lines, input characters are mapped to a sequence to
    appear on the output.

\item  Per line, the input character is specified as \texttt{'c'}, \texttt{c} being
    any character. Escape-sequences from the \textbf{C} programming language can be
    used in this specification; Yodl supports the sequences \texttt{\textbackslash{}a} (alert),
    \texttt{\textbackslash{}b} (beep), \texttt{\textbackslash{}f} (formfeed), \texttt{\textbackslash{}n} (newline), \texttt{\textbackslash{}r} (carriage
    return), \texttt{\textbackslash{}t} (tab), and \texttt{\textbackslash{}v} (vertical tab). Octal and hexadecimal
    constants may also be used. E.g., character \texttt{Y} may also be specified
    using the octal value \texttt{\textbackslash{}131} or the hexadecimal value \texttt{\textbackslash{}x59}. Any
    other character following a \textbackslash{} defines itself: \texttt{\textbackslash{}\textbackslash{}} represents a single
    backslash character.

\item  Following the character specification, a \texttt{=} must appear.

\item  Following that, a sequence of one or more characters appears,
    enclosed in double quotes, defining the translation. Again, escape
    sequences can be used, as in:

\begin{verbatim}
'\n' = "End of line\n"
\end{verbatim}


Such a mapping adds the text \texttt{End of line} to each line, since each
    newline character in the input is replaced by the text \texttt{End of line},
    followed by the newline itself.

Starting with Yodl 2.14.0 octal and hexadecimal constants may also be used
    within the double quoted string. E.g., character \texttt{Y} may also be
    specified using the octal value \texttt{\textbackslash{}131} or the hexadecimal value
    \texttt{\textbackslash{}x59}.  As an example where the octal/hexadecimal values may be useful
    consider the processing of a man-page. The character representations for
    the literal double quote (\texttt{"}) in \texttt{troff} is
    \texttt{\textbackslash{}(dq\textbackslash{}\&}. However, since \texttt{(} cannot be written literally
    in the character translation table since that would result in unbalanced
    parentheses while processing the character table's definition. Also,
    \texttt{CHAR}\texttt{(40)} cannot be used, since character table conversiond are
    performed by the output generator, which is called after the macro
    expansions have been performed. This it would result in the literal text
    \texttt{CHAR}((40)) appearing in the manual page.

Using the octal character representation in the chartable specification
    for the \texttt{"} character appearing in man-page the problem can now be
    solved. The actual specification used is: \begin{verbatim}
 '"' = "\\\050dq\\&" 
\end{verbatim}

\end{itemize}

Translations which are \textbf{not} specified in the table are left to the default,
which is to output the character as-is.

Note that the character table translation is something that the \texttt{yodl}
program does as one of its last actions, just before sending text to the
output file. The expansion text is not further processed by \texttt{yodl}, except
for the conversion of \textbf{C}-type escape sequences to ordinary characters. The
expansion text should therefore not be protected by, e.g., \texttt{NOTRANS}
(unless of course you want some character to generate the text \texttt{NOTRANS}
on the output).

\subsection{Using character tables}\label{USING}
        
A defined translation table is activated by the macro \texttt{USECHARTABLE}. This
macro takes one argument, which may be:

\begin{itemize}
    \item  empty, in which case the default mapping is restored,
    \item  a name of a previously defined character table.
\end{itemize}

The default mapping, selected when an empty argument is given, means that Yodl
enters its `zero translation state', meaning no character translation at all.

\subsection{Pushing and popping character tables}\label{PUSHINGTABLES}
        Besides the previously described macro \texttt{USECHARTABLE()}, Yodl has one other
mechanism of activating and deactivating character translation tables. This
mechanism uses a stack, and hence, the related macros are appropriately named
\texttt{PUSHCHARTABLE()} and \texttt{POPCHARTABLE()}.

\begin{itemize}

\item  \texttt{PUSHCHARTABLE(name)} \emph{pushes} the currently active translation
    table onto a stack, and activates the table identified by \texttt{name}. The
    argument may be empty; in that case, the zero-translation table is
    activated (analogously to \texttt{USECHARTABLE()}).

\item  \texttt{POPCHARTABLE()} activates the translation table that was last
    pushed. There is no argument to this macro.

\end{itemize}

Using the push/pop mechanism is handy when a table must be temporarily
activated, but when it is not known which table exactly is active prior to the
temporary activation. E.g., imagine that you need to use a character table
called \texttt{listing} to typeset a listing, but that you do not know the current
table. The pushing and popping mechanism is then used as follows:

\begin{verbatim}
COMMENT(First, we save the current table on the stack and
        we activate our "listing" table.)
PUSHCHARTABLE(listing)

COMMENT(Now the text is question is typeset.)
...

COMMENT(The previously active table is re-activated, whatever its name.)
POPCHARTABLE()
\end{verbatim}


\section{Sending literal text to the output}
    The Yodl program has several built-in macros that can be used to send literal
text to the output file. The macros are listed in the chapter \ref{BUILTIN} and
are briefly described here:
    \begin{itemize}
    \item  \texttt{CHAR} takes one argument: the ASCII number of a 
character or the character itself. The character is sent to the output 
file without being translated with the currently active character 
translation table.
    \item  \texttt{NOTRANS} takes one argument: the text in question. The 
text is neither parsed (i.e., macros in it are not expanded), nor 
translated with the current character translation table.
    \ \\     
The \texttt{NOTRANS} macro is conceptually like a series of \texttt{CHAR} macros.
    \item  \texttt{NOEXPAND} takes one argument: the text in question. The 
text is not parsed, but it \textbf{is} translated with the current character 
translation table.
    \item  \texttt{POPSUBST} takes no argument, and restores the \texttt{SUBST}
interpretation status that was active just before the most recently called
\texttt{PUSHSUBST} builtin macro call.
    \item  \texttt{PUSHSUBST} takes one argument: 0 or a non-zero value (commonly
1). Following \texttt{PUSHSUBSTS(0) SUBST}-definitions are ignored; following
\texttt{PUSHSUBSTS(1) SUBST}-definitions are used.
    \end{itemize}
    To illustrate the need for the distinction between \texttt{NOTRANS} and 
\texttt{NOEXPAND}, consider the following. The \texttt{HTML} converter (described in  
chapter \ref{MACROPACKAGE}) must be able to send HTML commands to the output 
file, but must also be able to send literal text (e.g., a source file 
listing). The HTML commands of course must be neither translated with any 
character table, nor must they be expanded in regard to macros. In contrast, a 
source file listing must be subject to character translations: the \texttt{\&}, 
\texttt{$<$} and \texttt{$>$} characters can cause difficulties. Two possible macros for a 
HTML converter are:
        \begin{verbatim}

    COMMENT(--- htmlcommand(cmd) sends its argument as a HTML command 
                to the output ---)
    DEFINEMACRO(htmlcommand)(1)(NOTRANS(ARG1))
        
    COMMENT(--- verb(listing) sends the listing to the output ---)
    DEFINECHARTABLE(list)(
        '&'     =   "&amp;"
        '<'     =   "&lt;"
        '>'     =   "&gt;"
    )
    
    DEFINEMACRO(verb)(1)(
        USECHARTABLE(list)
        NOTRANS(<listing>)
        NOEXPAND(ARG1)
        NOTRANS(</listing>)
        USECHARTABLE(standard)
    )
        
\end{verbatim}

    In this example it is assumed that a character translation table
\texttt{standard} exists, defining the `normal' translations. This table is
re-activated in the \texttt{verb} macro.

The currently defined \texttt{verb} macro for, e.g., html conversion looks like
this:
    \begin{verbatim}

    DEFINEMACRO(verb)(1)(
        PUSHSUBST(0)
        NOTRANS(<pre>)
        XXnl()
        NOEXPAND(ARG1)
        XXnl()
        NOTRANS(</pre>)
        XXnl()
        POPSUBST()
    )
    
\end{verbatim}

    Here, the surrounding \texttt{PUSHSUBST(0)} and \texttt{POPSUBST()} pair prevent the
interpretation of multi-char \texttt{SUBST} definitions like 
        \begin{verbatim}

    SUBST(\"e)(+NOTRANS(&euml;))
        
\end{verbatim}

    inside \texttt{verb} environments, causing unexpected translations in pieces of
code like
        \begin{verbatim}

    cout << "\"evil\" code\n";
        
\end{verbatim}

    which, if the \texttt{PUSHSUBST} command isn't used,  is converted to 
        \begin{verbatim}

    cout << "&eacute;vil\" code\n";
        
\end{verbatim}


\section{Counters}\label{COUNTERS}
        Some document languages (notably LaTeX) automatically prefix numbers when
typesetting sections, subsections, tables, figures etc..  Other document
languages (e.g. HTML) unfortunately don't.

Therefore, a macro package that converts a Yodl document to LaTeX doesn't
need to provide the numbering of sections etc.. However, if you do want the
numbering and if you want to convert documents to, say, HTML, then you must
take care of the numbering yourself.

This section describes the counters in Yodl: how to create counters,
how to use them, etc..

\subsection{Creating counters}
        Before a counter can be used, it must be created using \texttt{DEFINECOUNTER} or
\texttt{PUSHCOUNTER}. These functions expects two arguments: the name of the
counter and an (optional) integral additive expression. When provided, the
expression may contain binary + and unary or binary - operators; its operands
may be integral values or the names of existing counters. Additive expressions
may not contain white space characters. If an additive expression is provided
it is evaluated and its value is then used to initialize the named counter. If
the second argument is empty then the counter is initialized to zero (0).

For example, let's say that our macro package should provide two
sectioning commands: \texttt{section} and \texttt{subsection}. The sections should be
numbered 0, 1, 2, etc., and the subsections 1.1, 1.2, 1.3 etc.. For this we
can define two counters:
        \begin{verbatim}

    DEFINECOUNTER(sectcounter)()\//       initialized to 0
    DEFINECOUNTER(subsectcounter)(1)\//   initialized to 1
    
\end{verbatim}


\subsection{Using counters}
        The builtin function  \texttt{COUNTERVALUE(somecounter)} expands to the value of
\texttt{somecounter}. E.g., if the current value is 2, then the value 2 is inserted
into the output object. It is an error to use \texttt{COUNTERVALUE} on a
non-existing counter or on a counter not having a defined value (see below).

Yodl has several functions to modify and/or to set the values of counters. The
counter's value, named \texttt{expression} below, is an additive expression: it may
contain binary + and unary or binary - operators. The operands may be integral
values of the names of existing counters. Additive expressions may not
contain blank spaces.

The functions modifying values of counters are:    
    \begin{itemize}
    \item  \texttt{POPCOUNTER(somecounter)}: This function pops the most recently
pushed value off the counter's stack, assigning it to \texttt{somecounter}. An
error occurs when \texttt{somecounter} doesn't exist. If the counter was never
pushed, it still exists following \texttt{POPCOUNTER}, but its value is
undefined: using \texttt{COUNTERVALUE(somecounter)} in that case generates an
error. 

\item  \texttt{PUSHCOUNTER(somecounter)(expression)}: This function pushes the
current value of the counter \texttt{somecounter} on the counter's stack, making
\texttt{expression's} value its new value. Its second argument may be empty in
which case the counter is initialized to 0. When \texttt{somecounter} doesn't yet
exist, it is created with an initial value of \texttt{expression}.

\item  \texttt{SETCOUNTER(somecounter)(expression)}: This function sets the value
of \texttt{somecounter} to \texttt{expression's} value. The function does not expand to
anything; i.e., it does not write to the output file.

\item  \texttt{ADDTOCOUNTER(somecounter)(expression)}: This function adds
\texttt{expression's} value to \texttt{somecounter}.

\item  \texttt{USECOUNTER(somecounter)}: This function first increments
\texttt{somecounter's} value, and then writes the value of the counter to the
output file.

This function is particularly useful in combination with
\texttt{DEFINECOUNTER}: since \texttt{DEFINECOUNTER} initializes a counter to zero,
\texttt{USECOUNTER} can be used to increment the value and to output it. The first
time that \texttt{USECOUNTER} is used on a new counter, the value 1 appears on
the output file. The next time, expression 2 appears on the output file etc..
    \end{itemize}

Given the numbering requirements of the hypothetical commands \texttt{section} and
\texttt{subsection} (see the previous section), we can now complete the
definitions:

\begin{verbatim}
DEFINECOUNTER(sectcounter)
DEFINECOUNTER(subsectcounter)

DEFINEMACRO(section)(1)(\ 
SETCOUNTER(subsectcounter)(0)\ 
USECOUNTER(sectcounter) ARG1)

DEFINEMACRO(subsection)(1)(\ 
COUNTERVALUE(sectcounter).USECOUNTER(subsectcounter) ARG1)
\end{verbatim}


\cleardoublepage\chapter{All builtin functions}
\section{Yodl's builtin commands}\label{BUILTIN}
\typeout{Original Yodl file: userguide/builtin}As mentioned previously, \texttt{Yodl}'s input consists of text and of commands.  \texttt{Yodl}
supports a number of built-in commands which may either be used in a \texttt{Yodl}
document, or which can be used to create a macro package.

Don't despair if you find that the description of this section is too
technical. Exactly for this reason, \texttt{Yodl} supports the macro packages to make
the life of a documentation writer easier. E.g., see chapter \ref{MACROPACKAGE}
that describes a macro package for \texttt{Yodl}. 

Most built-in functions and macros expand the information they receive the way
they receive the information. I.e., the information itself is only evaluated
by the time it is eventually inserted into an output medium (usually a
file). However, some builtin functions \emph{evaluate} their argument(s)
once the argument is processed. They are:
    \begin{itemize}
    \item  The \texttt{ERROR} built-in function (see section \ref{ERROR});
    \item  The \texttt{EVAL} built-in function (see section \ref{EVAL});
    \item  The \texttt{FPUTS} built-in function (see section \ref{FPUTS});
    \item  The \texttt{INTERNALINDEX} built-in function (see section
            \ref{INTERNALINDEX});
    \item  The \texttt{PUSHSUBST} built-in function (see section \ref{PUSHSUBST});
    \item  The \texttt{TYPEOUT} built-in function (see section \ref{TYPEOUT});
    \item  The \texttt{UPPERCASE} built-in function (see section \ref{UPPERCASE});
    \item  The \texttt{WARNING} built-in function (see section \ref{WARNING});
    \item  The \texttt{XXSUBST} internal use only built-in function;
    \end{itemize}
    All other built-in functions will \emph{not} evaluate their arguments. 
See the mentioned functions for details, and in particular \texttt{EVAL()} for a
description of this evaluation process.

\subsection{ADDTOCOUNTER}\label{ADDTOCOUNTER}
    \typeout{Original Yodl file: userguide/builtin/addtocounter}The \texttt{ADDTOCOUNTER} function adds a given value to a counter. It expects two
arguments: the counter name, and an additive expression defining the value to
add. The counter must be previously created with \texttt{DEFINECOUNTER}.

The additive expression may not contain blank spaces and may use + and -
operators, its operands may either be integral numeric values or names of
(defined) counters.  The resulting value can be negative; in that case, a
value is subtracted from the destination counter.

For example, if \texttt{one} and \texttt{two} are counters, then 
        \begin{verbatim}

    ADDTOCOUNTER(one)(-two)\//    subtracts two's value from one
    ADDTOCOUNTER(one)(two+two)\// adds 2 x two's value to one
        
\end{verbatim}


See further section \ref{COUNTERS}.

\subsection{ADDTOSYMBOL}\label{ADDTOSYMBOL}
    \typeout{Original Yodl file: userguide/builtin/addtosymbol}Since Yodl version 2.00 symbols can be manipulated. To add text to an existing
symbol the builtin \texttt{ADDTOSYMBOL} is available. It expects two parameter
lists: the symbol's name, and the text to add to the symbol.  The symbol must
have been created earlier using DEFINECOUNTER (see section
\ref{DEFINECOUNTER}). The macro's second argument is not evaluated while
\texttt{ADDTOSYMBOL} is processed. Therefore, it is easy to add the text of another
symbol or the expansion of a macro to a symbol value. E.g.,
        \begin{verbatim}

    ADDTOSYMBOL(one)(SYMBOLVALUE(two)XXnl())
        
\end{verbatim}

    This adds the text of symbol \texttt{two}, followed by a new line, to the
contents of symbol \texttt{one} only when symbol \texttt{one} is evaluated, not when 
\texttt{ADDTOSYMBOL} is evaluated.

Example:
        \begin{verbatim}

    ADDTOSYMBOL(LOCATION)(this is appended to LOCATION)
        
\end{verbatim}


\subsection{ATEXIT}\label{ATEXIT}
    \typeout{Original Yodl file: userguide/builtin/atexit}\texttt{ATEXIT} expects one argument. The argument is appended to the output
file. Note that this text is subject to character table translations etc..

An example using this function is the following. A document in the
LaTeX typesetting language requires \texttt{\textbackslash{}end\{document\}} to occur at the end of
the document. To automatically append this string to the output file, the
following specification can be used:
        \begin{verbatim}

    ATEXIT(NOEXPAND(\end{document}))
        
\end{verbatim}

    Several \texttt{ATEXIT} lists can be defined. They are appended to the output
file in the \textbf{reverse} order of specification; i.e., the first \texttt{ATEXIT}
list is appended to the output file last. That means that in general the
\texttt{ATEXIT} text should be specified when a `matching' starting command is sent
to the output file; as in:
        \begin{verbatim}

    COMMENT(Start the LaTeX document.)
    NOEXPAND(\begin{document})
    
    COMMENT(Ensure its proper ending.)
    ATEXIT(NOEXPAND(\end{document}))
        
\end{verbatim}


\subsection{CHAR}\label{CHAR}
    \typeout{Original Yodl file: userguide/builtin/char}The command \texttt{CHAR} takes one argument, a number or a character, and outputs
its corresponding ASCII character to the final output file.  This command is
built for `emergency situations', where you need to typeset a character
despite the fact that it may be redefined in the current character table (for
a discussion of character tables, see \ref{CHARTABLES}). Also, the \texttt{CHAR}
function can be used to circumvent Yodl's requirement that open- and
close-parentheses must match.

The following arguments may be specified with \texttt{CHAR} (attempted in this
order):
    \begin{itemize}
    \item  A decimal number indicating the number of the character in the
        ascii-table (for example \texttt{CHAR}\texttt{(41)});
    \item  A plain, single character  (for example \texttt{CHAR}\texttt{(\#)}).
    \end{itemize}

So, when you're sure that you want to send a printable character that is
not a closing parenthesis to the output file, you can use the form
\texttt{CHAR}\texttt{(c)}, \texttt{c} being the character (as in, \texttt{CHAR}\texttt{(;)}).
To send a non-printable character or a closing parenthesis to the output file,
look up the ASCII number of the character, and supply that number as argument
to the \texttt{CHAR} command.

Example: The following two statements send an \texttt{A} to the output file.
        \begin{verbatim}

    CHAR(65)
    CHAR(A)
        
\end{verbatim}

    The following statement sends a closing parenthesis:
        \begin{verbatim}

    CHAR(41)
        
\end{verbatim}

    Another way to send a string to the output file without expansion by
character tables or by macro interpretation, is by using the function \texttt{NOTRANS}
(see section \ref{NOTRANS}). If you want to send a string to the output
\textbf{without} macro interpretation, but \textbf{with} character table translation,
use \texttt{NOEXPAND} (see section \ref{NOEXPAND}).

\subsection{CHDIR}\label{CHDIR}
    \typeout{Original Yodl file: userguide/builtin/chdir}The command \texttt{CHDIR} takes one argument, a directory to change to. This
command is implemented to simplify the working with \texttt{includefile} (see
\texttt{includefile} in \texttt{yodlmacros(7)}).  As a demonstration,
consider the following fragment:
        \begin{verbatim}

    includefile(subdir/onefile)
    includefile(subdir/anotherfile)
    includefile(subdir/yetanotherfile)
        
\end{verbatim}

    This fragment can be changed to:
        \begin{verbatim}

    CHDIR(subdir)
    includefile(onefile)
    includefile(anotherfile)
    includefile(yetanotherfile)
    CHDIR(..)
        
\end{verbatim}

    The current directory, as given to \texttt{CHDIR}, only affects how
\texttt{includefile} searches for its files. 

Note that this example assumes that the current working directory is a
member of Yodl's include-path specification (cf., Yodl's \texttt{+NOTRANS(-\{\}-\{\})include}
option). 

\subsection{COMMENT}\label{COMMENT}
    \typeout{Original Yodl file: userguide/builtin/comment}The \texttt{COMMENT} function defines one parameter list. The text that is passed
as argument is treated as comment. I.e., it is ignored; it is not copied to
the final output file.

As an alternative to (short) \texttt{COMMENT} the triplet \texttt{\textbackslash{}}\texttt{//} can be
used. It starts `end of line' comment, ignoring all characters on a line
starting at \texttt{\textbackslash{}}\texttt{//} up to the first non-blank character encountered on the
next line. If the next line's first non-blank characters are \texttt{\textbackslash{}}\texttt{//}, then
that begins another end of line comment, which will therefore also be skipped.

To actually write
    \texttt{\textbackslash{}}\texttt{//} or, using the current font: \textbackslash{}//
in a yodl-converted document, write, e.g., 
    \texttt{tt(\textbackslash{})tt(//)} or, using the current font: nop(/)// 
in a yodl-source file, and write \texttt{\textbackslash{}CHAR}\texttt{(/)/} in \texttt{verb} sections.

Example:
        \begin{verbatim}

    Hello world\// producess Hello world, skipping the rest
        \// this line is completely ignored
       s\// at this point Hello worlds has been produced.
        
\end{verbatim}


\subsection{COUNTERVALUE}\label{COUNTERVALUE}
    \typeout{Original Yodl file: userguide/builtin/countervalue}\texttt{COUNTERVALUE's} argument expands to the value of a counter. Its single
argument must contain the name of a counter.  The counter must have been
created earlier using the builtin \texttt{DEFINECOUNTER}.
    \ \\    
    Example:
        \begin{verbatim}

    The counter has value COUNTERVALUE(MYCOUNTER).
        
\end{verbatim}

    See also section \ref{COUNTERS}.

\subsection{DECWSLEVEL}\label{DECWSLEVEL}
    \typeout{Original Yodl file: userguide/builtin/decwslevel}\texttt{DECWSLEVEL} requires one (empty) argument. 
It reduces the current white-space level. The white-space level typically is
used in files that only define Yodl macros. When no output should be generated
while processing these files, the white-space level can be used to check for
this. If the white-space level exceeds zero, a warning is generated if
the file produces non-whitespace output. The builtin function \texttt{DECWSLEVEL}
is used to reduce the whitespace level following a previous call of
\texttt{INCWSLEVEL}. 

Once the white space level exceeds zero, no output will be
generated. White space, therefore effectively is ignored. The white space
level cannot be reduced to negative values. A warning is issued if that would
have happened if it were allowed.

Example:
        \begin{verbatim}

    INCWSLEVEL()
    DEFINESYMBOL(....)
    DEFINEMACRO(...)(...)(...)
    DECWSLEVEL()
        
\end{verbatim}

    Without the \texttt{INCWSLEVEL} and \texttt{DECWSLEVEL}, calls, 
the above definition would generate four empty lines to the output stream.

The \texttt{INCWSLEVEL} and \texttt{DECWSLEVEL} calls may be nested. The best
approach is to put an \texttt{INCWSLEVEL} at the first line of a macro-defining
Yodl-file, and a matching \texttt{DECWSLEVEL} call at the very last line.

\subsection{DEFINECHARTABLE}\label{DEFINECHARTABLE}
    \typeout{Original Yodl file: userguide/builtin/definechartable}\texttt{DEFINECHARTABLE} is used to define a character translation table.
The function expects two parameterlists, containing the name of the 
character table and character table translations
on separate lines. These character table  translations are of the form 
        \begin{verbatim}

    character = quoted-string
        
\end{verbatim}

    Here, character is always a value within single quotes. It may be a single
character, an octal character value or a hexadecimal character value. The
single character may be prefixed by a \textbackslash{}-character (e.g., \texttt{'\textbackslash{}\textbackslash{}'}). The octal
character value must start with a backslash, followed by three octal digits
(e.g., \texttt{'\textbackslash{}045'}. The hexadecimal character value starts with \texttt{0x},
followed by two hexadecimal characters. E.g., \texttt{'0xbe'}. The double quoted
string may contain anything (but the string must be on one line), possibly
containing escape-sequences as well: in the double quoted string the standard
\textbf{C} escape sequences \texttt{\textbackslash{}a} (alert), \texttt{\textbackslash{}b} (beep), \texttt{\textbackslash{}f} (formfeed),
\texttt{\textbackslash{}n} (newline), \texttt{\textbackslash{}r} (carriage return), \texttt{\textbackslash{}t} (tab), and \texttt{\textbackslash{}v} (vertical
tab) are recognized and automatically converted to their special
meanings. Starting with Yodl 2.14.0 octal and hexadecimal constants may also
be used. E.g., character \texttt{Y} may also be specified using the octal value
\texttt{\textbackslash{}131} or the hexadecimal value \texttt{\textbackslash{}x59}. Any other character following a
backslash character (\texttt{\textbackslash{}}) defines itself: \texttt{\textbackslash{}\textbackslash{}} represents a single
backslash character.

Example:
        \begin{verbatim}

    DEFINECHARTABLE(demotable)(
        '&'     = "&amp;"
        '\\'    = "\\backslash"
        '\045'  = "oct(45)"
        '0xa4'  = "hex(a4)"
    )
        
\end{verbatim}

    The builtin function \texttt{DEFINECHARTABLE} does not \emph{activate} the
table. The table is merely defined. To activate the character translation
table, use \texttt{USECHARTABLE}. The discussion of character tables is postponed
to section \ref{CHARTABLES}.

\subsection{DEFINECOUNTER}\label{DEFINECOUNTER}
    \typeout{Original Yodl file: userguide/builtin/definecounter}\texttt{DEFINECOUNTER} creates a new counter. This builtin function expects two
arguments: the name of the counter and an additive expression whose value is
used to initialize the counter.

The additive expression may not contain blank spaces and may use + and -
operators, its operands may either be integral numeric values or names of
(defined) counters.  The resulting value can be negative; in that case, a
value is subtracted from the destination counter.

Examples:
        \begin{verbatim}

    DEFINECOUNTER(year)(1950)
    DEFINECOUNTER(nTimes)(year+12)\// initializes nTimes to 1962
        
\end{verbatim}


See also section \ref{COUNTERS} and the \texttt{USECOUNTER} and \texttt{ADDTOCOUNTER}
builtin functions.

\subsection{DEFINEMACRO}\label{DEFINEMACRO}
    \typeout{Original Yodl file: userguide/builtin/definemacro}\texttt{DEFINEMACRO} is used to define new macros. This function expects
three arguments: 
    \begin{itemize}
    \item  An identifier, being the name of the macro to define. This identifier
may only consist of uppercase or lowercase characters. Note that it can
\emph{not} contain numbers, nor underscore characters.

\item  A number, stating the number of arguments that the macro will require
once it's used. The number must be in the range 0 to 61.

\item  The text that the macro expands to, once used. This text may
contain the strings \texttt{ARG}\emph{x}, \emph{x} being 1, 2, etc.. At these places the
arguments to the macro are pasted in. The numbers that identify the
arguments are 1 to 9, then A to Z and finally a to z. This gives a range of 61
expandable arguments, which is enough for all real-life applications.
    \end{itemize}
    For example, the following fragment defines a macro \texttt{bookref}, which can
be used to typeset a reference to a book. It requires three arguments; say, an
author, a title and the name of a publisher:
        \begin{verbatim}

    DEFINEMACRO(bookref)(3)(
        Author(s):           ARG1
        Book title:          ARG2
        Published by:        ARG3
    )
        
\end{verbatim}

    Such a macro could be used as follows:
        \begin{verbatim}

    bookref(Sobotta/Becher)
           (Atlas der Anatomie des Menschen)
           (Urban und Schwarzenberg, Berlin, 1972)
        
\end{verbatim}

    When called, it would produce the following output:
        \begin{verbatim}

        Author(s):           Sobotta/Becher
        Book title:          Atlas der Anatomie des Menschen
        Published by:        Urban und Schwarzenberg, Berlin, 1972
        
\end{verbatim}

    While applying a macro, the values of the three arguments are pasted to
the places where \texttt{ARG1}, \texttt{ARG2} etc. occur in the definition.

Note the following when defining new macros:
    \begin{itemize}
    \item  The argument containing the name of the new macro, \texttt{(bookref)} in
the above example, must occur right after \texttt{DEFINEMACRO}. No spaces are
allowed in between. Space characters and newlines may however occur following
this first argument.

This behavior of the \texttt{yodl} program is similar to the usage of the
defined macro: the author information must, enclosed in parentheses, follow
right after the \texttt{bookref} identifier. I implemented this feature to improve
the distinguishing between macros and real text. E.g., a macro \texttt{me} might be
defined, but the text
        \begin{verbatim}

    I like me (but so do you)
        
\end{verbatim}

    still is simple text; the macro \texttt{me} only is activated when a
parenthesis immediately follows it.

\item  Be careful when placing newlines or spaces in the definition of a new
macro. E.g., the definition, as given:
        \begin{verbatim}

    DEFINEMACRO(bookref)(3)(
        Author(s):           ARG1
        Book title:          ARG2
        Published by:        ARG3
    )
        
\end{verbatim}

    introduces extra newlines at the beginning and ending of the macro, which
are copied to the output each time the macro is used. The extra newline
occurs, of course, right before the sequence \texttt{Author(s):} and following the
evaluation of \texttt{ARG3}. A simple backslash character at the end of the
\texttt{DEFINEMACRO} line would prevent the insertion of extra newline
characters:
        \begin{verbatim}

    DEFINEMACRO(bookref)(3)(\ 
        Author(s):           ARG1
        Book title:          ARG2
        Published by:        ARG3
    )
        
\end{verbatim}


\item  Note that when a macro is used which requires no arguments at all,
one empty argument still must be specified. E.g., my macro package (see
chapter \ref{MACROPACKAGE}) defines a macro \texttt{it} that starts a bullet item in
a list. The macro takes no arguments, but still must be typed as \texttt{it()}.

This behavior is consistent: it helps distinguish which identifiers are
macros and which are simple text.

\item  Macro arguments may evaluate to text. When a \textbackslash{} is appended to the
macro-argument, or in the default input handling within a non-zero white-space
level (see section \ref{INCWSLEVEL}) this may invalidate a subsequent macro
call. E.g., the macro
        \begin{verbatim}

    DEFINEMACRO(oops)(1)(
        ARG1
        XXnl()
    )
        
\end{verbatim}

    when called as \texttt{oops(hello world)}, produces the output:
        \begin{verbatim}

    hello worldXXnl()
        
\end{verbatim}

    To prevent this gluing to arguments to subsequent macros, a single \texttt{+}
should be prepended to the macro call:
        \begin{verbatim}

    DEFINEMACRO(oops)(1)(
        ARG1
        +XXnl()
    )
        
\end{verbatim}

    See also section \ref{PLUSIDENT} obout the `+identifier'-sequence.

\item  Note the preferred layout of macro definitions and macro
calls. Adhere to this form, to prevent drowning in too many parentheses. In
particular:
        \begin{itemize}
        \item  Put all elements of the macro definition on one line, except for
the macro-expansion itself. Each expansion element should be on a line by
itself.
        \item  When calling macros put the macro's arguments underneath each
other. If the macrolists themselves contain macro-calls, put each call again
on a line of its own, indenting one tab-position beyond the location of the
opening parenthesis of the argument.
        \item  No continnuation backslashes are required between arguments.
        \item  With complex calls, indent just the arguments, and put the
parentheses in their required of logical locations.
        \end{itemize}
    Example of a complex call:
        \begin{verbatim}

        complex(
            first(
                ARG1
            )(
                ARG2
                +XXnl()
            )
            ARG3
            +nop()
            ARG4
            +XXnl()
        )
            
\end{verbatim}

    \item  Macro expansion proceeds as follows:
        \begin{itemize}
        \item  The arguments are read from the input
        \item  The contents of the arguments then replace their \texttt{ARGx}
references in the macro's definition (in some exceptional cases, clearly
indicated as such when applicable, the arguments themselves are evaluated
first, and then these evaluated arguments are used as replacements for their
corresponding \texttt{ARGx} references).
        \item  The now modified macro is read by Yodl's lexical scanner. This
may result in yet another macro expansion, which will then be evaluated
recursively. 
        \item  Eventually, all expansion is completed (well, should complete,
since Yodl doesn't test for eternal recursion) and scanning of the input
continues beyond the original macro call.
        \end{itemize}
    For example, assume we have the following two macros:
        \begin{verbatim}

    DEFINEMACRO(First)(1)( 
        Hello ARG1 
        +XXnl() 
    )
    DEFINEMACRO(Second)(1)( 
        First(ARG1) 
        First(ARG1) 
    )
        
\end{verbatim}

    and the following call is issued:
        \begin{verbatim}

    Second(Yodl)
        
\end{verbatim}

    then the following happens:
        \begin{itemize}
        \item  \texttt{Second(Yodl)} is read as encountered.
        \item  \texttt{ARG1} in \texttt{Second} is replaced by \texttt{Yodl}, and the resulting
macro body is sent to the lexical scanner for evaluation: It will see:
        \begin{verbatim}

    First(Yodl)First(Yodl)
        
\end{verbatim}

        \item  The first call to \texttt{First()} is now evaluated. This puts
(after replacing \texttt{ARG1} by \texttt{Yodl}) the following on the scanner's input:
        \begin{verbatim}

    Hello Yodl+XXnl()First(Yodl)
        
\end{verbatim}

        \item  \texttt{Hello Yodl} contains no macro call, so it is written to the
output stream. Remains:
        \begin{verbatim}

    +XXnl()First(Yodl)
        
\end{verbatim}

        \item  Assume \texttt{XXnl()} merely contains a newline (represented by
\texttt{\textbackslash{}n}, here), so \texttt{+XXnl()} is now replaced by \texttt{\textbackslash{}n}. This results in the
following input for the lexical scanner: 
        \begin{verbatim}

    \nFirst(Yodl)
        
\end{verbatim}

        \item  The \texttt{\textbackslash{}n} is now written to the output stream, and the scanner
sees: 
        \begin{verbatim}

    First(Yodl)
        
\end{verbatim}

        \item  The second call to \texttt{First()} is now evaluated. This puts
the following on the scanner's input:
        \begin{verbatim}

    Hello Yodl+XXnl()
        
\end{verbatim}

        \item  \texttt{Hello Yodl} is written to the output stream. Remains:
        \begin{verbatim}

    +XXnl()
        
\end{verbatim}

        \item  \texttt{+XXnl()} is now replaced by \texttt{\textbackslash{}n}. The lexical scanner sees:
        \begin{verbatim}

    \n
        
\end{verbatim}

        \item  The newline is printed and we're done.
        \end{itemize}
    \end{itemize}

\subsection{DEFINESYMBOL}\label{DEFINESYMBOL}
    \typeout{Original Yodl file: userguide/builtin/definesymbol}\texttt{DEFINESYMBOL} expects two arguments. An identifier, which is the name of
the symbol to define, and the textual value of the symbol. If the second
argument is empty, the symbol is defined, but has an empty value.

The earlier interpretation of a Yodl symbol as a logical flag can still be
used, but allowing it to obtain textual values greatly simplifies various Yodl
macros. 

Example:
        \begin{verbatim}

    DEFINESYMBOL(Yodl)(Your own document language)
    DEFINESYMBOL(Options)()
        
\end{verbatim}


\subsection{DELETECHARTABLE}\label{DELETECHARTABLE}
    \typeout{Original Yodl file: userguide/builtin/deletechartable}\texttt{DELETECHARTABLE} removes a definition of a character table that
was defined by \texttt{DEFINECHARTABLE}. This function expects one argument: the
name of the character table remove.

It's an error to attempt to delete a character table that is currently in
use or to attempt to delete a non-existing character table.

Example:
        \begin{verbatim}

    DELETECHARTABLE(mytable)
        
\end{verbatim}


\subsection{DELETECOUNTER}\label{DELETECOUNTER}
    \typeout{Original Yodl file: userguide/builtin/deletecounter}\texttt{DELETECOUNTER} removes a definition of a counter that
was defined by \texttt{DEFINECOUNTER}. This function expects one argument: the
name of the counter to remove.

If the counter does not exist, a warning is issued. It is not considered an
error to try to delete a counter that has not been defined earlier.

Example:
        \begin{verbatim}

    DELETECOUNTER(mycounter)
        
\end{verbatim}


\subsection{DELETEMACRO}\label{DELETEMACRO}
    \typeout{Original Yodl file: userguide/builtin/deletemacro}\texttt{DELETEMACRO} removes a definition of a macro that was defined by
\texttt{DEFINEMACRO}. This function takes one argument: the macro name to remove.

There is no error condition (except for syntax errors): when no macro with a
matching name was previously defined, no action is taken.

For example, the safe way to define a macro is by first undefining it. This
ensures that possible previous definitions are removed first:

Example:
        \begin{verbatim}
DELETEMACRO(mymacro)
        
\end{verbatim}


\subsection{DELETENOUSERMACRO}\label{DELETENOUSERMACRO}
    \typeout{Original Yodl file: userguide/builtin/deletenousermacro}\texttt{DELETENOUSERMACRO} removes a `nousermacro' definition. The
function expects one argument: the name of the `nousermacro' identifier to be
removed from the nousermacro-set.

There is no error condition (except for syntax errors): when the identifier
wasn't stored as a `nousermacro' no action is taken.

Example:
        \begin{verbatim}
DELETENOUSERMACRO(mymacro)
        
\end{verbatim}


\subsection{DELETESYMBOL}\label{DELETESYMBOL}
    \typeout{Original Yodl file: userguide/builtin/deletesymbol}\texttt{DELETESYMBOL} removes the definition of a symbol variable. It
expects one argument, holding the name of the variable to deleted.

This macro has no error condition (except for syntax errors): the symbol in
question may be previously defined, but that is not necessary.

Example:
        \begin{verbatim}

    DELETESYMBOL(Options)
        
\end{verbatim}


\subsection{ERROR}\label{ERROR}
    \typeout{Original Yodl file: userguide/builtin/error}The \texttt{ERROR} function takes one argument: text to display to the standard
error stream. The current input file and line number are also displayed. After
displaying the text, the \texttt{yodl} program aborts with an exit status of 1.

The text passed to the function is expanded first. See the example.

The \texttt{ERROR} function is an example of a function that evaluates its argument
itself.

This command can be used, e.g., in a macro package when an incorrect macro is
expanded. In my macro package (see chapter \ref{MACROPACKAGE}) the \texttt{ERROR}
function is used when the sectioning command \texttt{chapter()} is used in an
\texttt{article} document (in the package, \texttt{chapter}'s are only available in
\texttt{book}s or \texttt{report}s).

An analogous builtin function is \texttt{WARNING}, which also prints a message but 
does not exit (see section \ref{WARNING}).

Example:
    In the following call, \texttt{COUNTERVALUE(NTRIES)} is replaced by its actual
value: 
        \begin{verbatim}

    ERROR(Stopping after COUNTERVALUE(NTRIES) attempts)
        
\end{verbatim}


\subsection{EVAL}\label{EVAL}
    \typeout{Original Yodl file: userguide/builtin/eval}The \texttt{EVAL} function takes one argument: the text to be evaluated. This
function allows you to perform an indirect evaluation of Yodl commands. Assume
that there is a symbol \texttt{varnam} containing the name of a counter variable,
then the following displays the counter's value, after having incremented it:
        \begin{verbatim}

    EVAL(NOTRANS(USECOUNTER)(SYMBOLVALUE(varnam)))
        
\end{verbatim}


Here, \texttt{EVAL} performs the following steps:
    \begin{itemize}
    \item  First, \texttt{NOTRANS(USECOUNTER)} is evaluated, producing
        \texttt{USECOUNTER}.
    \item  Next, the open parenthesis is processed, producing the open
        parenthesis itself
    \item  Then, \texttt{SYMBOLVALUE(varnam)} is evaluated, producing the name of a
        counter, e.g. `\texttt{counter}'.
    \item  The closing parentheis is processed, producing the closing
        parenthesis itself.
    \item  All this results in the \emph{text}
        \begin{verbatim}

    USECOUNTER(counter)
        
\end{verbatim}

    \item  This text is presented to Yodl's lexical scanner, resulting in
        incrementing the counter, and displaying its incremented value.
    \end{itemize}

b(Caveat): macro arguments themselves are usually not evaluated. So, a
construction like
        \begin{verbatim}

    USECOUNTER(EVAL(SYMBOLVALUE(varnam)))
        
\end{verbatim}

    fails, as `\texttt{EVAL(SYMBOLVALUE(varnam))}' is not a legal name for a
counter. Here the \texttt{EVAL()} call is used as an argument, and is therefore not
expanded. 

The distinction is subtle, and is a consequence of the fact that builtin
functions receive unprocessed arguments. Builtin functions may impose certain
requirements on their arguments (like \texttt{USECOUNTER} requiring the name of a
counter) and these requirements are checked on the arguments as received.

Summarizing: \texttt{EVAL} acts as follows:
    \begin{itemize}
    \item  Its argument is presented to Yodl's lexical scanner
    \item  The output produced by the processing of the argument is then
inserted into the input stream \emph{in lieu of} the original \texttt{EVAL} call.
    \end{itemize}

Most built-in functions do \emph{not} evaluate their arguments. In fact, only
\texttt{ERROR, EVAL, FPUTS, INTERNALINDEX, PUSHSUBST, TYPEOUT, UPPERCASE, WARNING}
and the iinternally used \texttt{XXSUBST} functions evaluate their arguments.

Postponing evaluations allows you to write:
        \begin{verbatim}

    DEFINESYMBOL(later)(SYMBOLVALUE(earlier))
        
\end{verbatim}

    Eventually, and not when \texttt{later} is defined, a statement like
        \begin{verbatim}

    SYMBOLVALUE(later)
        
\end{verbatim}

    produces the value of \texttt{earlier} at the moment \texttt{SYMBOLVALUE(later)}
is processed. This is, in all its complex consequences, what would be expected
in most cases. It allows us to write general macros producing output that is
only evaluated when the text of symbols and values of arguments become
eventually, rather than when the macro is defined, available. 

Decisions like these invariably result in questions like `what if I have
to define variables using values of other variables?' In those cases
\texttt{EVAL()} must be used. The following example shows the definition of three
symbols: \texttt{one} receives an initial value, \texttt{two} returns \texttt{one}'s actual
value when \texttt{two}'s value is displayed, \texttt{three}, using \texttt{EVAL()}, stores
\texttt{one}'s initial value.

The example also shows yet another way to suppress macro calls, using the
macro \texttt{nop()} which is defined in the all standard conversion types:
        \begin{verbatim}

    DEFINESYMBOL(one)(One's first value)
    DEFINESYMBOL(two)(SYMBOLVALUE(one))
    EVAL(DEFINESYMBOL+nop()(three)(SYMBOLVALUE(one)))
    SETSYMBOL(one)(One's second value)
    "SYMBOLVALUE(two)"      COMMENT(displays "One's second value")
    "SYMBOLVALUE(three)"    COMMENT(displays "One's first value")
        
\end{verbatim}


\subsection{FILENAME}\label{FILENAME}
    \typeout{Original Yodl file: userguide/builtin/filename}The function \texttt{FILENAME()} produces an absolute path to the currently
processed Yodl file. This is not necessarily the \emph{canonical} path name, as
it may contain current- and parent-path directories.

\subsection{FPUTS}\label{FPUTS}
    \typeout{Original Yodl file: userguide/builtin/fputs}The function \texttt{FPUTS} expects two arguments: the first argument is
information to be appended to a file, whose name is given as the second
argument. The first argument is processed by Yodl before it is appended to the
requested filename, so it may contain macro calls.

For example, the following statement appends a countervalue to the
mentioned file:
        \begin{verbatim}

    FPUTS(There have been COUNTERVALUE(attempts) attempts)(/tmp/logfile)
        
\end{verbatim}

    The second argument (name of the file) is not evaluated, but is used as
received. 

\subsection{IFBUILTIN}\label{IFBUILTIN}
    \typeout{Original Yodl file: userguide/builtin/ifbuiltin}The \texttt{IFBUILTIN} function tests whether its first argument is the name of a
builtin function. If so, the second argument is evaluated, else, the third
argument is evaluated. All three arguments (the variable, the true-list and
the false-list) must be present; though the true-list and/or the false-list
may be empty.

Example:
        \begin{verbatim}

    IFBUILTIN(IFBUILTIN)(\ 
        `BUILTIN' is a builtin - function
    )(\ 
        `BUILTIN' is NOT a builtin - function
    )
        
\end{verbatim}

    Please note the preferred layout: The first argument immediately follows
the function name, then the second argument (the \emph{true list}) is indented,
as is the \emph{false list}. The layout closely follows the preferred layout of
\texttt{if-else} statements of many programming languages. 

\subsection{IFCHARTABLE}\label{IFCHARTABLE}
    \typeout{Original Yodl file: userguide/builtin/ifchartable}The \texttt{IFCHARTABLE} function tests whether its first argument is the name of a
character table. The character table needs not be active.  If the name is the
name of a character table, the second argument is evaluated, else, the third
argument is evaluated. All three arguments (the name, the true list and the
false list) must be present; though the true list and/or the false list may be
empty.

Example:
        \begin{verbatim}

    IFCHARTABLE(standard)(\ 
        `standard' is a character tablebuiltin - function
    )(\ 
        `standard' is NOT a character tablebuiltin - function
    )
        
\end{verbatim}

    Please note the preferred layout: The first argument immediately follows
the function name, then the second argument (the \emph{true list}) is indented,
as is the \emph{false list}. The layout closely follows the preferred layout of
\texttt{if-else} statements of many programming languages. 

\subsection{IFDEF}\label{IFDEF}
    \typeout{Original Yodl file: userguide/builtin/ifdef}The \texttt{IFDEF} function tests for the definition status of the argument in its
first argument. If it is a defined entity, the second argument is evaluated,
else, the third argument is evaluated. All three arguments (the entity, the
true list and the false list) must be present; though the true list and/or the
false list may be empty.

The true list is evaluated if the first argument is the name of:
    \begin{itemize}
    \item  a built-in function, or
    \item  a character table, or
    \item  a counter, or
    \item  a no-user-macro symbol, or
    \item  a symbol, or
    \item  a user-defined macro, or
    \end{itemize}
    Example:
        \begin{verbatim}

    IFDEF(someName)(\ 
        `someName' is a defined entity
    )(\ 
        `someName is not defined.
    )
        
\end{verbatim}

    Please note the preferred layout: The first argument immediately follows
the function name, then the second argument (the \emph{true list}) is indented,
as is the \emph{false list}. The layout closely follows the preferred layout of
\texttt{if-else} statements of many programming languages. 

\subsection{IFEMPTY}\label{IFEMPTY}
    \typeout{Original Yodl file: userguide/builtin/ifempty}\texttt{IFEMPTY} expects three arguments: a symbol, a true-list and a
false-list. \texttt{IFEMPTY} evaluates to the true-list if the symbol is an empty
string; otherwise, it evaluates to the false-list.

The function does not further evaluate its argument. Its use is primarily
to test whether a macro has received an argument or not. If the intent is to
check whether a symbol's value is empty or not, IFSTREQUAL \ref{IFSTREQUAL}
should be used, where the first argument is the name of a symbol, and the
second argument is empty.

Example:
        \begin{verbatim}

    IFEMPTY(something)(\ 
        `something' is empty...
    )(\ 
        `something' is not an empty string
    )
        
\end{verbatim}

    In the same way, \texttt{IFEMPTY} can be used to test whether an argument
expands to a non-empty string. A more elaborate example follows below. Say you
want to define a \texttt{bookref} macro to typeset information about an author, a
book title and about the publisher. The publisher information may be absent,
the macro then typesets \texttt{unknown}:
        \begin{verbatim}
\ 
    DEFINEMACRO(bookref)(3)(\  
        Author(s):      ARG1
        Title:          ARG2
        Published by:   \ 
        IFEMPTY(ARG3)
        (\ 
            Unknown\ 
        )(\ 
            ARG3\ 
        )
    )
        
\end{verbatim}

    Using the macro, as in:
        \begin{verbatim}
\ 
    bookref(Helmut Leonhardt)
           (Histologie, Zytologie und Microanatomie des Menschen)
           ()
        
\end{verbatim}

    would now result in the text \texttt{Unknown} behind the \texttt{Published by:}
line. 

Please note the preferred layout: The first argument immediately follows
the function name, then the second argument (the \emph{true list}) is indented,
as is the \emph{false list}. The layout closely follows the preferred layout of
\texttt{if-else} statements of many programming languages. 

\subsection{IFEQUAL}\label{IFEQUAL}
    \typeout{Original Yodl file: userguide/builtin/ifequal}\texttt{IFEQUAL} expects four argument lists. It tests whether its first argument
is equal to its second argument. If so, the third argument is evaluated,
else, the fourth argument is evaluated. All four argument lists must be
present, though all can be empty.

The first two arguments of \texttt{IFEQUAL} should be integral numeric
arguments. In order to determine whether the first two arguments are equal,
their values are determined:
    \begin{itemize}
    \item  If the argument starts with an integral numerical value, that value
is the value of the argument.
    \item  If the argument is the name of a counter, the counter's value is the
value of the argument
    \item  If the values of the first two arguments van be determined
accordingly, their equality determines whether the true list (when the values
are equal) or the false list (when the values are unequal) will be evaluated.
    \item  Otherwise, \texttt{IFEQUAL} evaluates the false list.
    \end{itemize}

Example:
        \begin{verbatim}

    IFEQUAL(0)()(\ 
        0 and an empty string are equal
    )(\ 
        0 and an empty string are not equal
    )
        
\end{verbatim}

    Please note the preferred layout: The first argument immediately follows
the function name, then the second argument (the \emph{true list}) is indented,
as is the \emph{false list}. The layout closely follows the preferred layout of
\texttt{if-else} statements of many programming languages. 

\subsection{IFGREATER}\label{IFGREATER}
    \typeout{Original Yodl file: userguide/builtin/ifgreater}\texttt{IFGREATER} expects four argument lists. It tests whether its first argument
is greater than its second argument. If so, the third parameter list is
evaluated, otherwise its fourth argument is evaluated. All four argument lists
must be present, though all can be empty.

The first two arguments of \texttt{IFGREATER} should be integral 
numeric arguments. In order to determine whether the first two arguments are 
equal, their values are determined:
    \begin{itemize}
    \item  If the argument starts with an integral numerical value, that value
is the value of the argument.
    \item  If the argument is the name of a counter, the counter's value is the
value of the argument
    \item  If the values of the first two arguments van be determined
accordingly, their order relation determines whether the true list (when
the first value is greater than the second value) or the false list (when the
first value is smaller or equal than the second value) is evaluated.
    \item  Otherwise, \texttt{IFGREATER} evaluates the false list.
    \end{itemize}

Example:
        \begin{verbatim}

    IFGREATER(counter)(5)(\ 
        counter exceeds the value 5
    )(\ 
        counter does not exceeds the value 5, or counter is no Yodl-counter.
    )
        
\end{verbatim}

    Please note the preferred layout: The first argument immediately follows
the function name, then the second argument (the \emph{true list}) is indented,
as is the \emph{false list}. The layout closely follows the preferred layout of
\texttt{if-else} statements of many programming languages. 

\subsection{IFMACRO}\label{IFMACRO}
    \typeout{Original Yodl file: userguide/builtin/ifmacro}The \texttt{IFMACRO} function tests whether its first argument is the name of a
macro. If the name is the name of a macro, the second argument is evaluated,
else, the third argument is evaluated. All three arguments (the name, the true
list and the false list) must be present; though the true list and/or the
false list may be empty.

Example:
        \begin{verbatim}

    IFMACRO(nested)(\ 
        `nested' is the name of a macro
    )(\ 
        There is no macro named `nested'
    )
        
\end{verbatim}

    Please note the preferred layout: The first argument immediately follows
the function name, then the second argument (the \emph{true list}) is indented,
as is the \emph{false list}. The layout closely follows the preferred layout of
\texttt{if-else} statements of many programming languages. 

\subsection{IFSMALLER}\label{IFSMALLER}
    \typeout{Original Yodl file: userguide/builtin/ifsmaller}\texttt{IFSMALLER} expects four argument lists. It tests whether its first argument
is smaller than its second argument. If so, the third parameter list is
evaluated, otherwise its fourth argument is evaluated. All four argument lists
must be present, though all can be empty.

The first two arguments of \texttt{IFSMALLER} should be integral numeric
arguments. In order to determine whether the first two arguments are equal,
their values are determined:
    \begin{itemize}
    \item  If the argument starts with an integral numerical value, that value
is the value of the argument.
    \item  If the argument is the name of a counter, the counter's value is the
value of the argument
    \item  If the values of the first two arguments van be determined
accordingly, their order relation determines whether the true list (when
the first value is smaller than the second value) or the false list (when the
first value is greater than or equal to the second value) is evaluated.
    \item  Otherwise, \texttt{IFSMALLER} evaluates the false list.
    \end{itemize}

Example:
        \begin{verbatim}

    IFSMALLER(counter)(5)(\ 
        counter is smaller than the value 5, or counter is no Yodl-counter
    )(\ 
        counter exceeds the value 5
    )
        
\end{verbatim}

    Please note the preferred layout: The first argument immediately follows
the function name, then the second argument (the \emph{true list}) is indented,
as is the \emph{false list}. The layout closely follows the preferred layout of
\texttt{if-else} statements of many programming languages. 

\subsection{IFSTREQUAL}\label{IFSTREQUAL}
    \typeout{Original Yodl file: userguide/builtin/ifstrequal}\texttt{IFSTREQUAL} tests for the equality of two strings. It expects
four arguments: two strings to match, a true list and a false list. The
true list is only evaluated when the contents of the two string arguments
exactly match. 

The first two arguments of \texttt{IFSTREQUAL} are partially evaluated:
    \begin{itemize}
    \item  If the argument is the name of a symbol, the symbol's value is the
value of the argument
    \item  Otherwise, the argument itself is used.
    \end{itemize}

In the degenerate case where the string to be compared is actually the name of
a \texttt{SYMBOL}, use a temporary \texttt{SYMBOL} variable containing the name of that
symbol, and compare it to whatever you want to compare it with. Alternatively,
write a blank space behind the arguments, since the arguments are then
interpreted `as is'. In practice, the need for these constructions seem to
arise seldom, however.

Example:
        \begin{verbatim}

    IFSTREQUAL(MYSYMBOL)(Hello world)(
        The symbol `MYSYMBOL' holds the value `Hello world'
    )(
        The symbol `MYSYMBOL' doesn't hold the value `Hello world'
    )
        
\end{verbatim}


\subsection{IFSTRSUB}\label{IFSTRSUB}
    \typeout{Original Yodl file: userguide/builtin/ifstrsub}\texttt{IFSTRSUB} tests whether a string is a sub-string of another 
string. It acts similar to IFSTREQUAL, but
it tests whether the second string is part of the first one. 

The first two arguments of \texttt{IFSTREQULA} are partially evaluated:
    \begin{itemize}
    \item  If the argument is the name of a symbol, the symbol's value is the
value of the argument
    \item  Otherwise, the argument itself is used.
    \end{itemize}

In the degenerate case where the string to be compared is actually the name of
a \texttt{SYMBOL}, use a temporary \texttt{SYMBOL} variable containing the name of that
symbol, and compare it to whatever you want to compare it with. Alternatively,
write a blank space behind the arguments, since the arguments are then
interpreted `as is'. In practice, the need for these constructions seem to
arise seldom, however.

Example:
    \begin{verbatim}

        IFSTRSUB(haystack)(needle)(
            `needle' was found in `haystack'
        )(
            `needle' was not found in `haystack'
        )
    
\end{verbatim}

    Note that both `haystack' and `needle' may be the names of symbols. If
they are, their contents are is compared, rather than the literal names
`haystack' and `needle'

\subsection{IFSYMBOL}\label{IFSYMBOL}
    \typeout{Original Yodl file: userguide/builtin/ifsymbol}The \texttt{IFSYMBOL} function tests whether its first argument is the name of a
symbol. If it is the name of a symbol, the second argument is evaluated,
otherwise the third argument is evaluated. All three arguments (the name, the
true list and the false list) must be present; though the true list and/or the
false list may be empty.

Example:
        \begin{verbatim}

    IFSYMBOL(nested)(\ 
        `nested' is the name of a symbol
    )(\ 
        There is no symbol named `nested'
    )
        
\end{verbatim}

    Please note the preferred layout: The first argument immediately follows
the function name, then the second argument (the \emph{true list}) is indented,
as is the \emph{false list}. The layout closely follows the preferred layout of
\texttt{if-else} statements of many programming languages. 

C(  FBB consider additive expressions   )
    \subsection{IFZERO}\label{IFZERO}
    \typeout{Original Yodl file: userguide/builtin/ifzero}\texttt{IFZERO} expects three arguments. If the first argument is zero (0)
the function expands to the true list (the second argument). Otherwise it
expands to the false list (the third argument).

The first argument of \texttt{IFZERO} should be an integral numeric value. Its
value is determined as follows:
    \begin{itemize}
    \item  If the argument starts with an integral numerical value, that value
is the value of the argument.
    \item  If the argument is the name of a counter, the counter's value is the
value of the argument
    \item  Otherwise, the first arguments evaluates as 0, and the false list is
used.
    \end{itemize}

Note that, starting with Yodl version 2.00 the first argument is not
evaluated. So \texttt{COUNTERVALUE(somecounter)} always evaluates as 0. If the
value of a counter is required, simply provide its name as the first argument
of the \texttt{IFZERO} function.

Example:
        \begin{verbatim}

    DEFINEMACRO(environment)(2)(\ 
        IFZERO(ARG2)(\ 
            NOEXPAND(\end{ARG1})\ 
        )(\  
            NOEXPAND(\begin{ARG1})\ 
        )\ 
    )    
        
\end{verbatim}

    Such a macro may be used as follows:
        \begin{verbatim}

    environment(center)(1)
        Now comes centered text.
    environment(center)(0)
        
\end{verbatim}

    which would of course lead to \texttt{\textbackslash{}begin} and \texttt{\textbackslash{}end\{center\}}. The numeric
second argument is used here as a on/off switch.

\subsection{INCLUDEFILE}\label{INCLUDEFILE}
    \typeout{Original Yodl file: userguide/builtin/includefile}\texttt{INCLUDEFILE} takes one argument, a filename. The file is processed by
Yodl. If a file should be inserted without processing the builtin function
NOEXPANDINCLUDE \ref{NOEXPANDINCLUDE} or
NOEXPANDPATHINCLUDE \ref{NOEXPANDPATHINCLUDE} should be used.

The \texttt{yodl} program supplies, when necessary, an extension to the filename.
The supplied extension is \texttt{.yo}, unless defined otherwise during the
compilation of the program. 

Furthermore, Yodl tries to locate the file in the Yodl's include path (which
may be set using the \texttt{+NOTRANS(-\{\}-\{\})include} option). The actual value of the include
path is shown in the usage information, displayed when Yodl is started without
arguments.

Example:
        \begin{verbatim}

    INCLUDEFILE(latex)
        
\end{verbatim}

    Here, Yodl attempts to include the file \texttt{latex} or \texttt{latex.yo} from the
current include path. When the file is not found, Yodl aborts.

\subsection{INCWSLEVEL}\label{INCWSLEVEL}
    \typeout{Original Yodl file: userguide/builtin/incwslevel}\texttt{INCWSLEVEL} requires one (empty) argument. 

It increments the current white-space level. The white-space level typically
is used in files that only define Yodl macros. When no output should be
generated while processing these files, the white-space level can be used to
check for this. If the white-space level exceeds zero, a warning is generated
if the file produces non-whitespace output. The builtin function
\texttt{DECWSLEVEL} is used to decrement the whitespace level following a previous
\texttt{INCWSLEVEL} call.

Once the white space level exceeds zero, no output is generated. White
space, therefore is effectively ignored. The white space level cannot be
reduced to negative values. A warning is issued if that would have happened if
it were allowed.

Example:
        \begin{verbatim}

    INCWSLEVEL()
    DEFINESYMBOL(....)
    DEFINEMACRO(...)(...)(...)
    DECWSLEVEL()
        
\end{verbatim}

    Without the \texttt{INCWSLEVEL} and \texttt{DECWSLEVEL}, calls, 
the above definition would generate four empty lines to the output stream.

The \texttt{INCWSLEVEL} and \texttt{DECWSLEVEL} calls may be nested. The best
approach is to put an \texttt{INCWSLEVEL} at the first line of a macro-defining
Yodl-file, and a matching \texttt{DECWSLEVEL} call at the very last line.

\subsection{INTERNALINDEX}\label{INTERNALINDEX}
    \typeout{Original Yodl file: userguide/builtin/internalindex}\texttt{INTERNALINDEX} expects one argument list. The argument list is evaluated
and written to the index file.

The index file is defined since Yodl version 2.00, and contains the fixup
information which was previously written to Yodl's output as the
\texttt{.tt(Yodl)TAGSTART.  ... .tt(Yodl)TAGEND.} sequence. 

The index file allows for greater processing speed, at the expense of an
additional file. The associated \texttt{yodlpost} postprocessing program reads
and processes the index file, and modifies the corresponding yodl-output
accordingly. 

The index file is not created when output is written to the standard output
name, since Yodl is unable to request the system for the current file offset.

The entries of the index file always fit on one line. \texttt{INTERNALINDEX}
changes newline characters in its argument into single blank spaces. Each line
starts with the current offset of Yodl's output file, thus indicating the
exact location where a fixup is requested. An example of a produced fixup line
could be
        \begin{verbatim}

    3004 ref MACROPACKAGE
        
\end{verbatim}

    indicating that at offset 3004 in the produced output file a reference to
the label \texttt{MACROPACKAGE} is requested. Assuming a html conversion, 
The postprocessor thereupon
writes something like 
        \begin{verbatim}

    <a href="outfile04.html#MACROPACKAGE">4.3.2.</a>
        
\end{verbatim}

    into the actual output file while processing Yodl's output up to 
offset location 3004.

Consequently, producing Yodl-output normally consists of two steps:
    \begin{itemize}
    \item  First, Yodl itself is started, producing, e.g., \texttt{out.idx} (the
index file) and \texttt{out.yodl} (Yodl's raw output).
    \item  Then, Yodl's post-processor processes \texttt{out.idx} 
and \texttt{out.yodl}, producing one or more final output files, in which the
elements of the index file have been properly handled. This may result in
multiple output file, like \texttt{report.html, report01.html, report02.html} etc.
    \end{itemize}

\subsection{NOEXPAND}\label{NOEXPAND}
    \typeout{Original Yodl file: userguide/builtin/noexpand}\texttt{NOEXPAND} is used to send text to the final output file without being
expanded by Yodl (the other methods are the \texttt{CHAR} macro, see section
\ref{CHAR}, and the \texttt{NOTRANS} macro, see section \ref{NOTRANS}).  \texttt{NOEXPAND}
takes one argument, the text in question. Whatever occurs in the
argument is not subject to parsing or expansion by Yodl, but is simply copied
to the output file (except for \texttt{CHAR} and (iinternally used) \texttt{XXSUBST}
functions in the argument, which \emph{are} expanded. If \texttt{CHAR}-expansion is
not required either NOTRANS \ref{NOTRANS} can be used).

Furthermore, the contents of the argument are also subject to
character table translations, using the currently active table. This should
come as no surprise. Ignoring character tables would make both the processing
of \texttt{CHAR} calls and the \texttt{NOTRANS} function superfluous. 

So, the following situations are recognized:
    \begin{center}
        \begin{tabular}{lll}
\hline

 & \multicolumn{2}{c}{support chartables} \\

 & \multicolumn{2}{c}{and CHAR} \\
 \cline{2-3}

    Macro expansion &  yes &  no \\
\hline

Yes &  (standard) &  Push chartable \\

 &      &            (standard) \\

 &      &            Pop chartable \\

No &   NOEXPAND &    NOTRANS \\
\hline

\end{tabular}\end{center}
E.g., let's assume that you need to write in your document the following text:
        \begin{verbatim}

    INCLUDEFILE(something or the other)
    IFDEF(onething)(
        ...
    )(
        ....
    )
    NOEXPAND(whatever)
        
\end{verbatim}


The way to accomplish this is by prefixing the text by \texttt{NOEXPAND} followed
by an open parenthesis, and by postfixing it by a closing parenthesis.
Otherwise, the text would be expanded by Yodl while processing it (and would
lead to syntax errors, since the text isn't correct in the sense of the Yodl
language).

For this function, keep the following caveats in mind:
    \begin{itemize}
    \item  There is only one thing that a \texttt{NOEXPAND} cannot protect from 
    expansion: an \texttt{ARG}\emph{x} in a macro definition. The argument specifier 
    is always processed. E.g., after
        \begin{verbatim}

    DEFINEMACRO(thatsit)(1)(
        That is --> NOEXPAND(ARG1) <-- it!
    )
    thatsit(after all)
        
\end{verbatim}

    the \texttt{ARG1} inside the \texttt{NOEXPAND} statement is replaced with 
        \texttt{after all}.
    \item  The \texttt{NOEXPAND} function must, as all functions, be followed by a 
    argument. The parentheses of the list must therefore be `balanced'. 
    For unbalanced lists, use \texttt{CHAR(40)} to set an open parenthesis, 
    or \texttt{CHAR(41)} to typeset a closing parenthesis.
    \end{itemize}

\subsection{NOEXPANDINCLUDE}\label{NOEXPANDINCLUDE}
    \typeout{Original Yodl file: userguide/builtin/noexpandinclude}\texttt{NOEXPANDINCLUDE} takes one argument, a filename. The file is
included. 

The filename is uses as specified. The include path is not used when locating
this file.

The argument to \texttt{NOEXPANDINCLUDE} is partially evaluated:
    \begin{itemize}
    \item  If the argument is the name of a symbol, the symbol's value is the
value of the argument
    \item  Otherwise, the argument itself is used.
    \end{itemize}
    The thus obtained file name is not further evaluated: in particular, it
is not affected by available character translations.

The contents of the file are included literally, not subject to
macro expansion. Character translations are performed, though. If character
translations are not appropriate, PUSHCHARTABLE can be
used to suppress character table translations temporarily.

The purpose of NOEXPANDINCLUDE is to include source code literally in the
document, as in:
        \begin{verbatim}

    NOEXPANDINCLUDE(literal.c)
        
\end{verbatim}

    The function NOEXPANDPATHINCLUDE can be used to
insert a file which \emph{is} located in one of the directories specified in
Yodl's include path.

\subsection{NOEXPANDPATHINCLUDE}\label{NOEXPANDPATHINCLUDE}
    \typeout{Original Yodl file: userguide/builtin/noexpandpathinclude}\texttt{NOEXPANDPATHINCLUDE} takes one argument, a filename. The file is
included. The file is searched for in the directories specified in Yodl's
includepath. 

The argument to \texttt{NOEXPANDPATHINCLUDE} is partially evaluated:
    \begin{itemize}
    \item  If the argument is the name of a symbol, the symbol's value is the
value of the argument
    \item  Otherwise, the argument itself is used.
    \end{itemize}
    The thus obtained file name is not further evaluated: in particular, it
is not affected by available character translations.

Like the \texttt{NOEXPANDINCLUDE} function, the contents of the file are included
literally, not subject to macro expansion. Character translations are
performed, though. If character translations are not appropriate,
PUSHCHARTABLE \ref{PUSHCHARTABLE} can be used to suppress character table
translations temporarily.

The purpose of NOEXPANDPATHINCLUDE is to include source code as defined in a
macro package literally into the document, as in:
        \begin{verbatim}

    NOEXPANDPATHINCLUDE(rug-menubegin.xml)
        
\end{verbatim}


\subsection{NOTRANS}\label{NOTRANS}
    \typeout{Original Yodl file: userguide/builtin/notrans}\texttt{NOTRANS} copies its one argument literally to the output file, without
expanding macros in it and without translating the characters with the current
translation table. The \texttt{NOTRANS} function is typically used to send commands
for the output format to the output file.

For example, consider the following code fragment:
        \begin{verbatim}

    COMMENT(--- Define character translations for \, { and } in LaTeX. ---)
    DEFINECHARTABLE(standard)(
        '\\'    =    "$\\backslash$"
        '{'     =    "\\verb+{+"
        '}'     =    "\\verb+}+"
    )
    
    COMMENT(--- Activate the translation table. ---)
    USECHARTABLE(standard)
    
    COMMENT(--- Now two tests: ---)
    
    NOEXPAND(\input{epsf.tex})
    NOTRANS(\input{epsf.tex})
        
\end{verbatim}

    \texttt{NOEXPAND} sends 
        \begin{verbatim}

    $\backslash$input\verb+{+epsf.tex\verb+}+
        
\end{verbatim}

    since the characters in its argument are translated with the \texttt{standard} 
translation table. In contrast, \texttt{NOTRANS} sends \texttt{\textbackslash{}input\{epsf.tex\}}.

The argument of \texttt{NOTRANS} \emph{must} be balanced with respect to its
parentheses. When using an unbalanced set of parentheses, use
\texttt{CHAR(40)} to send a literal (, or \texttt{CHAR(41)} to send a
\texttt{)}.

While converting Yodl-documents to target document types Yodl frequently uses
the (not further documented) builtin function \texttt{XXSUBST}. In the
unlikely event that the text \texttt{XXSUBST(...)} must be written
in a document, the sequence
    \begin{verbatim}

    XXSUBST+CHAR(40)...CHAR(41)
    
\end{verbatim}

    can be used.

The NOEXPAND description summarizes all combinations of
character translations and/or macro expansion, and how they are handled and
realized by Yodl.

\subsection{NOUSERMACRO}\label{NOUSERMACRO}
    \typeout{Original Yodl file: userguide/builtin/nousermacro}\texttt{NOUSERMACRO} controls \texttt{yodl}'s warnings in the following way: When Yodl
is started with the \texttt{-w} flag on the command line, warnings are generated
when Yodl encounters a possible macro name, i.e., a name that is followed by a
parenthesized argument, while no macro by that name has been defined.  Yodl
then prints something like \texttt{cannot expand possible user macro}.

Examples of such sequences are, \texttt{The necessary file(s) are in
/usr/local/lib/yodl}, or \texttt{see the manual page for sed(1)}. The candidate
macros are \texttt{file} and \texttt{sed}; these names could just as well be `valid'
user macros followed by their argument.

When a corresponding \texttt{NOUSERMACRO} statement appears \emph{before} \texttt{yodl} 
encounters the candidate macros, no warning is generated. A fragment might 
therefore be:
        \begin{verbatim}

    NOUSERMACRO(file sed)
    The necessary file(s) are in ...
    See the manual page for sed(1).
        
\end{verbatim}

    The \texttt{NOUSERMACRO} accepts one or more names in its argument, separated
by white space, commas, colons, or semi-colons.

\subsection{OUTBASE}\label{OUTBASE}
    \typeout{Original Yodl file: userguide/builtin/outbase}\texttt{OUTBASE} inserts the current basename of the output file into the output
file. The basename is the name of the file of which the directory components
and extension were stripped.

If the output file is the standard output file, \texttt{-} is inserted.

\subsection{OUTDIR}\label{OUTDIR}
    \typeout{Original Yodl file: userguide/builtin/outdir}\texttt{OUTDIR} inserts the current path name of the output file into the output
file. The path name is a, not necessarily absolute, designator of the
directory in which the output file is located. If the output file is indicated
as, e.g., \texttt{-o out}, then \texttt{OUTDIR} simply inserts a dot.

If the output file is the standard output file, a dot is inserted too.

\subsection{OUTFILENAME}\label{OUTFILENAME}
    \typeout{Original Yodl file: userguide/builtin/outfilename}\texttt{OUTFILENAME} inserts the current filename of the output file into the
output file. The filename is the name of the file of which the directory
components  were stripped.

If the output file is the standard output file, \texttt{-} is inserted.

\subsection{PARAGRAPH}\label{PARAGRAPH}
    \typeout{Original Yodl file: userguide/builtin/paragraph}\texttt{PARAGRAPH} isn't really a builtin function, but as Yodl handles 
paragraphs in a special way it is probably useful to describe paragraph
handling here nonetheless. 
Starting with Yodl 2.00  \texttt{PARAGRAPH} operates as follows:

If the macro is not defined, new paragraphs, defined as series of consecutive
empty lines written to the output stream, are not handled different from any
other series of characters sent to the output stream. I.e., they are inserted
into that stream.

However, if the macro has been defined, Yodl calls it
whenever a new paragraph (defined as a series of at least two blank lines)
has been recognized.

The empty lines that were actually recognized may be obtained inside the
\texttt{PARAGRAPH} macro from the \texttt{XXparagraph} symbol, \emph{if} this symbol has
been be defined by that time. If defined, it contains the white space that
caused Yodl to call the \texttt{PARAGRAPH} macro.

Note that, in order to inspect \texttt{XXparagraph} it must have been defined
first. Yodl itself does \emph{not} define this symbol itself.

The \texttt{PARAGRAPH} macro should be  defined as a macro not expecting arguments.
The macro is thus given a chance to process the paragraph in a way that's
fitting for the particular conversion type. If the \texttt{PARAGRAPH} macro
produces series of empty lines itself, then those empty lines do \emph{not}
cause Yodl to activate \texttt{PARAGRAPH}. So, Yodl itself will not recursively
call \texttt{PARAGRAPH}, although the macro could call itself recursively. Of
course, such recursive activcation of \texttt{PARAGRAPH} is then the sole
responsibility of the macro's author, and not Yodl's.

Some document languages do not need paragraph starts; e.g., LaTeX handles its
own paragraphs. Other document languages do need it: typically, \texttt{PARAGRAPH}
is then defined in a macro file to trigger some special action. E.g., a HTML
converter might define a paragraph as:
        \begin{verbatim}

    DEFINEMACRO(PARAGRAPH)(0)(
        XXnl()
        NOTRANS(<p>)
    )
        
\end{verbatim}

    A system like \texttt{xml} has more strict requirements. Paragraphs here must be
opened and closed using pairs of \texttt{$<$p$>$} and \texttt{$<$/p$>$} tags. In those cases an
auxiliary counter can be used to indicate whether there is an open paragraph
or not. The \texttt{PARAGRAPH} macro could check for this as follows, assuming the
availability of a counter \texttt{XXp}:
        \begin{verbatim}

    DEFINEMACRO(PARAGRAPH)(0)(
        XXnl()
        IFZERO(XXp)(
        )(
            NOTRANS(</p>)
        )
        NOTRANS(<p>)
        SETCOUNTER(XXp)(1)
    )
        
\end{verbatim}

    Note that the above fragment exemplifies an approach, not necessarily
\emph{the} implementation of the \texttt{PARAGRAPH} macro for an xml-converter.

\subsection{PIPETHROUGH}\label{PIPETHROUGH}
    \typeout{Original Yodl file: userguide/builtin/pipethrough}The builtin function \texttt{PIPETHROUGH} is, besides \texttt{SYSTEM}, the second
function with which a Yodl document can affect its
environment. \texttt{PIPETHROUGH} can be very useful. It uses an external program
to accomplish special features. The idea is that an external command is
started, to which a block of text from within a Yodl document is `piped'. The
output of that child program is piped back into the Yodl document; hence, a
block of text is `piped through' an external program.  Whatever is received
again in the Yodl run, is further processed.

The \texttt{PIPETHROUGH} function takes two arguments:

\begin{itemize}

\item  the command to run, and

\item  the text to send to that command.

\end{itemize}

Functionally, the occurrence of the \texttt{PIPETHROUGH} function and of its two
arguments is replaced by whatever the child program produces on its standard
output. 

An example might be the inclusion of the current date, as in:

\begin{verbatim}
The current date is:
PIPETHROUGH(date)()
\end{verbatim}


In this example the command is \texttt{date} and the text to send to that program is
empty.

The main purpose of this function is to provide a way by which external programs
can be used to create, e.g., tables or figures for a given output format.
Further releases of Yodl may contain such dedicated programs for the output
formats. 

\subsection{POPCHARTABLE}\label{POPCHARTABLE}
    \typeout{Original Yodl file: userguide/builtin/popchartable}Character tables which are pushed onto the table stack using
\texttt{PUSHCHARTABLE()} are restored (popped) using \texttt{POPCHARTABLE()}. For a
description of this mechanism please refer to section \ref{PUSHINGTABLES}.

\subsection{POPCOUNTER}\label{POPCOUNTER}
    \typeout{Original Yodl file: userguide/builtin/popcounter}\texttt{POPCOUNTER} is used to remove the topmost counter from the counter stack. 
The values of counters may be pushed on a stack using
PUSHCOUNTER \ref{PUSHCOUNTER}. To remove the topmost element of a counter's
stack \texttt{POPCOUNTER} is available. \texttt{POPCOUNTER} expects one argument: the
name of the counter to pop. The previously pushed value then becomes the new
value of the counter. A counter's value may be popped after defining it,
whereafter the stack is empty, but the counter will still be defined. In
that case, using the counter's value is considered an error. 

Examples:
        \begin{verbatim}

    DEFINECOUNTER(YEAR)(1950)
    POPCOUNTER(YEAR)
    COMMENT(YEAR now has an undefined value)
        
\end{verbatim}

    See also section \ref{COUNTERS}.

\subsection{POPMACRO}\label{POPMACRO}
    \typeout{Original Yodl file: userguide/builtin/popmacro}\texttt{POPMACRO} is used to remove the actual macro definition, restoring a
previously pushed definition.  The values of macros may be pushed on a stack
using PUSHMACRO. 

To remove the topmost element of a macro's stack \texttt{POPMACRO} is
available. \texttt{POPMACRO} expects one argument: the name of the macro to
pop. The previously pushed value then becomes the new value of the macro.

A macro's value may be popped after defining it, after which its stack is
empty. In that case, using the macro (although the macro's name is still
defined) is considered an error.

Example:
        \begin{verbatim}

    DEFINEMACRO(Hello)(1)(Hello, ARG1, this is a macro definition)
    Hello(Karel)
    PUSHMACRO(Hello)(1)(Hello, ARG1, this is the new definition)
    Hello(Karel)
    POPMACRO(Hello)
    Hello(Karel)
    COMMENT(The third activation of Hello() produces the same output
            as the first activation)
        
\end{verbatim}


\subsection{POPSUBST}\label{POPSUBST}
    \typeout{Original Yodl file: userguide/builtin/popsubst}\texttt{POPSUBST} is used to revert to a previous level of interpretation of
\texttt{SUBST} definitions. Refer to the descriptions of the \texttt{PUSHSUBST} and
\texttt{SUBST} builtin commands below for details. 

There is no limit to the number of times \texttt{POPSUBST} can be called. Once the
`\texttt{PUSHSUBST} stack' is empty \texttt{SUBST} definitions are automatically 
interpreted  (so no stack-underflow error is ever encountered).

\subsection{POPSYMBOL}\label{POPSYMBOL}
    \typeout{Original Yodl file: userguide/builtin/popsymbol}\texttt{POPSYMBOL} is used to remove the topmost symbol from the symbol stack. 
The values of symbols may be pushed on a stack using
PUSHSYMBOL \ref{PUSHSYMBOL}. To remove the topmost element of a symbol's
stack \texttt{POPSYMBOL} is available. 

\texttt{POPSYMBOL} expects one argument: the name of the symbol to pop. The
previously pushed value then becomes the new value of the symbol. 

A symbol's value may be popped after defining it, after which its stack is
empty. In that case, using the symbol (although the symbol's name is still
defined) is considered an error.

Example:
        \begin{verbatim}

    DEFINESYMBOL(YEAR)(This happened in 1950)
    POPSYMBOL(YEAR)
    COMMENT(YEAR now has an undefined value)
        
\end{verbatim}


\subsection{POPWSLEVEL}\label{POPWSLEVEL}
    \typeout{Original Yodl file: userguide/builtin/popwslevel}\texttt{POPWSLEVEL} is used to remove the topmost wslevel from the wslevel stack.
The values of wslevels may be pushed on a stack using
PUSHWSLEVEL \ref{PUSHWSLEVEL}. See also section DECWSLEVEL \ref{DECWSLEVEL}

To remove the topmost element of a wslevel's stack \texttt{POPWSLEVEL} is
available. \texttt{POPWSLEVEL} expects one argument: the name of the wslevel to
pop. The previously pushed value then becomes the new value of the wslevel. A
wslevel's value may be popped after defining it, emptying the stack, but the
wslevel will still be defined. In that case, using the wslevel's value is
considered an error.

Example:
        \begin{verbatim}

    COMMENT(Assume WS level is zero)
    
    PUSHWSLEVEL(1)
    COMMENT(WS level now equals 1)

    POPWSLEVEL()
    COMMENT(WS level now equals 0 again)
        
\end{verbatim}


\subsection{PUSHCHARTABLE}\label{PUSHCHARTABLE}
    \typeout{Original Yodl file: userguide/builtin/pushchartable}Once a character table has been defined, it can be \emph{pushed} onto a stack
using \texttt{PUSHCHARTABLE}. The pushed chartable may be \emph{popped}
later. \texttt{PUSHCHARTABLE} is described in more detail in section
\ref{PUSHINGTABLES}.

\subsection{PUSHCOUNTER}\label{PUSHCOUNTER}
    \typeout{Original Yodl file: userguide/builtin/pushcounter}\texttt{PUSHCOUNTER} is used to start another lifetime for a counter, pushing its
current value on a stack. A stack is available for each individual counter.

\texttt{PUSHCOUNTER} expects two arguments: the name of the counter to push and 
an additive expression whose value becomes the counter's new value (after
pushing the current value)

The additive expression may not contain blank spaces and may use + and -
operators, its operands may either be integral numeric values or names of
(defined) counters.  The resulting value can be negative; in that case, a
value is subtracted from the destination counter.

When the second argument is empty, then the new value will be zero.  Specify
the name of the counter twice to merely push its value, without modifying its
current value.

Examples:
        \begin{verbatim}

    DEFINECOUNTER(YEAR)(1950)
    PUSHCOUNTER(YEAR)(1962)
    COMMENT(YEAR now has the value 1962, and a pushed value of 1950)
        
\end{verbatim}

    See also section \ref{COUNTERS}.

\subsection{PUSHMACRO}\label{PUSHMACRO}
    \typeout{Original Yodl file: userguide/builtin/pushmacro}\texttt{PUSHMACRO} is used to start another lifetime for a macro, pushing its
current definition on a stack. A stack is available for each individual macro.

\texttt{PUSHMACRO} expects three arguments: the name of the macro to push, the
number of its arguments after pushing (which may be different from the number
of arguments interpreted by the pushed macro)  and its new
definition. 

So, \texttt{PUSHMACRO} is used exactly like DEFINEMACRO, but
redefines a current macro (or define a new macro if no macro was defined by
the name specified as its first argument.

Example:
        \begin{verbatim}

    DEFINEMACRO(Hello)(1)(Hello, ARG1, this is a macro definition)
    Hello(Karel)
    PUSHMACRO(Hello)(1)(Hello, ARG1, this is the new definition)
    Hello(Karel)
    POPMACRO(Hello)
    Hello(Karel)
    COMMENT(The third activation of Hello() produces the same output
            as the first activation)
        
\end{verbatim}


\subsection{PUSHSUBST}\label{PUSHSUBST}
    \typeout{Original Yodl file: userguide/builtin/pushsubst}\texttt{PUSHSUBST} can be used to (temporarily) suppress the interpretation of
\texttt{SUBST} definitions (the \texttt{SUBST} built-in command is covered
below, refer to its description for an example). 

\texttt{PUSHSUBST} expects one argument: an integral number which is either 0 or
non-zero (commonly: 1). After calling \texttt{PUSHSUBST}\texttt{(0)} \texttt{SUBST}
definitions are not interpreted anymore; use \texttt{POPSUBST}\texttt{()} to revert to
the previous type of interpretation. Alternatively, \texttt{PUSHSUBST}\texttt{(0)} can
be used to stack another level of \texttt{SUBST} interpretations on top of the
last-used one.

On a 64-bit computer the \texttt{PUSHSUBST} stack can hold slightly more than 60
\texttt{SUBST} interpretation levels. When more levels are pushed, the oldest levels
are silently forgotten. Calling \texttt{POPSUBST} once the \texttt{PUSHSUBST} stack is
empty results in activating the \texttt{SUBST} interpretations (and so a
stack-underflow error will not be encountered).

\subsection{PUSHSYMBOL}\label{PUSHSYMBOL}
    \typeout{Original Yodl file: userguide/builtin/pushsymbol}\texttt{PUSHSYMBOL} is used to start another lifetime for a symbol, pushing its
current value on a stack. A stack is available for each individual symbol.

\texttt{PUSHSYMBOL} expects two arguments: the name of the symbol to push and its
new text after pushing. When the second argument is an empty argument, the new
text will be empty. The new text may be specified as a literal text, or as the
name of an existing symbol. Specify the name of the symbol twice to merely
push its value, without modifying its current value.

Examples:
        \begin{verbatim}

    DEFINESYMBOL(YEAR)(This happened in 1950)
    PUSHSYMBOL(YEAR)(This happened in 1962)
    COMMENT(YEAR now has the value `This happened in 1962' and a 
            pushed value of `This happened in 1950')
        
\end{verbatim}


\subsection{PUSHWSLEVEL}\label{PUSHWSLEVEL}
    \typeout{Original Yodl file: userguide/builtin/pushwslevel}\texttt{PUSHWSLEVEL} is used to start another lifetime of the white-space level
pushing the level's current value on a stack. See also section 
INCWSLEVEL \ref{INCWSLEVEL}

\texttt{PUSHWSLEVEL} expects one argument, the new value of the white-space
level. This value may be specified as a numerical value or as the name of a
counter. The argument may be empty, in which case the new value will be 
zero. 

Example:
        \begin{verbatim}

    COMMENT(Assume WS level is zero)
    
    PUSHWSLEVEL(1)
    COMMENT(WS level now equals 1)

    POPWSLEVEL()
    COMMENT(WS level now equals 0 again)
        
\end{verbatim}


\subsection{RENAMEMACRO}\label{RENAMEMACRO}
    \typeout{Original Yodl file: userguide/builtin/renamemacro}\texttt{RENAMEMACRO} takes two arguments: the name of a built-in macro
(such as \texttt{INCLUDEFILE}) and its new name.

E.g., after
        \begin{verbatim}

    RENAMEMACRO(INCLUDEFILE)(include)
        
\end{verbatim}


a file \emph{must} be included by \texttt{include(file)}.  \texttt{INCLUDEFILE} can no
longer be used for this: following the \texttt{RENAMEMACRO} action, the old name
can no longer be used; it becomes an undefined symbol.

If you want to make an \emph{alias} for a built-in command, do it with 
\texttt{DEFINEMACRO}. E.g., after:
        \begin{verbatim}

    DEFINEMACRO(include)(1)(INCLUDEFILE(ARG1))
        
\end{verbatim}

both \texttt{INCLUDEFILE} and \texttt{include} can be used to include a file.

\subsection{SETCOUNTER}\label{SETCOUNTER}
    \typeout{Original Yodl file: userguide/builtin/setcounter}\texttt{SETCOUNTER} expects two arguments: the name of a counter, and an additive
expression defining the value to assign. The counter must be previously
created with \texttt{DEFINECOUNTER}.

The additive expression may not contain blank spaces and may use + and -
operators, its operands may either be integral numeric values or names of
(defined) counters.  The resulting value can be negative; in that case, a
negative value is assigned to the destination counter.

For example, if \texttt{one} and \texttt{two} are counters, then 
        \begin{verbatim}

    SETTOCOUNTER(one)(-two)\//    assigns -two's value to one
    SETTOCOUNTER(one)(two+two)\// assigns 2 x two's value to one
        
\end{verbatim}


See also section \ref{COUNTERS}.

\subsection{SETSYMBOL}\label{SETSYMBOL}
    \typeout{Original Yodl file: userguide/builtin/setsymbol}\texttt{SETSYMBOL} expects two arguments: the name of a symbol, and
the text to assign to the named symbol. The symbol must previously have been
defined by \texttt{DEFINESYMBOL}.

\subsection{SUBST}\label{SUBST}
    \typeout{Original Yodl file: userguide/builtin/subst}\texttt{SUBST} is a general-purpose substitution mechanism for strings appearing in
the input. \texttt{SUBST} takes two arguments: a search string and a substitution
string.  E.g., after
        \begin{verbatim}

    SUBST(VERSION)(1.00)
        
\end{verbatim}
 
    \texttt{Yodl} transforms all occurrences of \texttt{VERSION} in its input into 
\texttt{1.00}.

\texttt{SUBST} is also useful in situations where multi-character sequences
should be converted to accented characters. E.g., a \LaTeX{} converter might
define:
        \begin{verbatim}

    SUBST('e)(+NOTRANS(\'{e}))
        
\end{verbatim}

    Each \texttt{'e} in the input will subsequently be converted to \texttt{+NOTRANS(\textbackslash{}'\{e\})}. 

\texttt{SUBST} may be used in combination with the command line 
flag \texttt{-P}, as in a invocation
        \begin{verbatim}

    yodl2html -P'SUBST(VERSION)(1.00)' myfile.yo
        
\end{verbatim}


Another useful substitution might be:
        \begin{verbatim}

    SUBST(_OP_)(CHAR(40))
    SUBST(_CP_)(CHAR(41))
        
\end{verbatim}


which defines an opening parenthesis (\texttt{\_OP\_}) and a closing parenthesis
(\texttt{\_CP\_}) as mapped to the \texttt{CHAR} function. The strings \texttt{\_OP\_} and
\texttt{\_CP\_} might then be used to produce unbalanced arguments.

Note that:
    \begin{itemize}
    \item  The first argument of the \texttt{SUBST} command, the search string, is
taken literally. Yodl does not expand it; the string must be literally
matched in the input.
    \item  The second argument, the replacement, is further processed by Yodl. 
Protect this text by \texttt{NOTRANS} or \texttt{NOEXPAND} where appropriate.
    \end{itemize}

Substitutions occur extremely early while \texttt{Yodl} processes its input files. In
order to process its input files, \texttt{Yodl} takes the following steps:
    \begin{enumerate}
    \item  It requests input from its lexical scanner (so-called \emph{tokens})
    \item  Its parser processes the tokens produced by the lexical scanner
    \item  Its parser may send text to an output `object', which 
eventually appears in the output file generated by \texttt{Yodl}.
    \end{enumerate}
    \texttt{Yodl} performs all macro substitutions in step 2, and all character
table conversions in step 3. However, the lexical scanner has access to the
\texttt{SUBST} definitions: as soon as its lexical analyzer detects a series of
characters matching the defining sequence of a \texttt{SUBST} definition, it 
replaces that defining sequence by its definition. That definition is then
again read by the lexical scanner. Of course, this definition may, in turn,
contain defining sequences of other \texttt{SUBST} definitions: these are then 
replaced by their definitions as well. This implies:
    \begin{itemize}
    \item  Circular definitions may cause the lexical scanner to get stuck in a
replacement loop. It is the responsibility of the author defining \texttt{SUBST}
definitions to make sure that this doesn't happen.
    \item  Neither the parser, nor the output object ever sees the \texttt{SUBST}
defining character sequences: they only see their definitions.
    \end{itemize}

In some cases substitutions must be suppressed. Consider double
quoted text strings that are frequently used in programming
languages. E.g., \texttt{"hello world"}. The text inside the string should not be
converted by Yodl, but unless substitutions can be suppressed the string
    \begin{verbatim}
"\"evil code"
    
\end{verbatim}
appears as
    \begin{verbatim}
"+NOTRANS(\"{e})vil code"
    
\end{verbatim}

To suppress the interpretation of \texttt{SUBST} definitions \texttt{PUSHSUBST},
introduced earlier, can be used. The predefined macro \texttt{verb} suppresses the
interpretation of \texttt{SUBST} definitions by starting with \texttt{PUSHSUBST}\texttt{(0)}
and ending with \texttt{POPSUBST}\texttt{()}.

\subsection{SYMBOLVALUE}\label{SYMBOLVALUE}
    \typeout{Original Yodl file: userguide/builtin/symbolvalue}\texttt{SYMBOLVALUE} expands to the value of a symbol. Its single argument
must be the name of a symbol.  The symbol must have been created earlier
using \texttt{DEFINESYMBOL}.
    \ \\    
    Example:
        \begin{verbatim}

    The symbol has value SYMBOLVALUE(MYSYMBOL).
        
\end{verbatim}


\subsection{SYSTEM}\label{SYSTEM}
    \typeout{Original Yodl file: userguide/builtin/system}\texttt{SYSTEM} takes one argument: a command to execute. The command is run via
the standard C function \texttt{system}. 

\texttt{SYSTEM} can be useful in many ways. E.g., you might want to log when
someone processes your document, as in:
        \begin{verbatim}

    SYSTEM(echo Document processed! | mail myself@my.host)
        
\end{verbatim}

    Note that \texttt{SYSTEM} merely performs an system-related task. It's a
process that is separated from the \texttt{Yodl} process itself. One of the
consequences of this is that any output generated by \texttt{SYSTEM} not
normally appears into \texttt{Yodl}'s output file. If the output of a subprocess should
be inserted into \texttt{Yodl}'s output file, either use
PIPETHROUGH \ref{PIPETHROUGH}, or insert a temporary file as shown in the
following example:
        \begin{verbatim}

    SYSTEM(date > datefile)
    The current date is: 
    INCLUDEFILE(datefile)
    SYSTEM(rm datefile)
        
\end{verbatim}


\subsection{TYPEOUT}\label{TYPEOUT}
    \typeout{Original Yodl file: userguide/builtin/typeout}\texttt{TYPEOUT} requires one argument. The text of the list is sent to the
standard error stream, followed by a newline. This feature can be handy to
show, e.g., messages such as version numbers in macro package files.

Example: The following macro includes a file and writes to the screen that
this file is currently processed.
        \begin{verbatim}

    DEFINEMACRO(includefile)(1)(
        TYPEOUT(About to process document: ARG1)
        INCLUDEFILE(ARG1)
    )
        
\end{verbatim}


\subsection{UPPERCASE}\label{UPPERCASE}
    \typeout{Original Yodl file: userguide/builtin/uppercase}\texttt{UPPERCASE} converts a string or a part of it to upper case. It has
two arguments:
    \begin{itemize}
    \item  The string to convert;
    \item  A length, indicating how many characters (starting from the beginning
of the string) should be converted.
    \end{itemize}
    The length indicator can be smaller than one or larger than the length of
the string; in that case, the whole string is convertered.

Example:
        \begin{verbatim}

    UPPERCASE(hello world)(1)
    UPPERCASE(hello world)(5)
    UPPERCASE(hello world)(0)
        
\end{verbatim}

    This code sample expands to:
        \begin{verbatim}

    Hello world
    HELLO world
    HELLO WORLD
        
\end{verbatim}


\subsection{USECHARTABLE}\label{USECHARTABLE}
    \typeout{Original Yodl file: userguide/builtin/usechartable}\texttt{USECHARTABLE} takes one argument: the name of a translation table to
activate. The table must previously have been defined using
\texttt{DEFINECHARTABLE}. See section \ref{CHARTABLES} for a description of
character translation tables.

Alternatively, the name may be empty in which case the default character
mapping is restored.

\subsection{USECOUNTER}\label{USECOUNTER}
    \typeout{Original Yodl file: userguide/builtin/usecounter}\texttt{USECOUNTER} is a combination of \texttt{ADDTOCOUNTER} and \texttt{COUNTERVALUE}. It
expects one argument: the name of an defined counter (see
DEFINECOUNTER \ref{DEFINECOUNTER}).

The counter is first incremented by 1. Then the function expands to 
the counter's value.

See also section \ref{COUNTERS}.

\subsection{VERBOSITY}\label{VERBOSITY}
    \typeout{Original Yodl file: userguide/builtin/verbosity}\texttt{VERBOSITY} expects two arguments, and may be used to change the verbosity
level inside \texttt{Yodl} files. The function may be used profitably for debugging
purposes, to debug the expansion of a macro or the processing of a \texttt{Yodl} input
file. 

The first argument indicates the processing mode of the second argument, and it
may be:
    \begin{itemize}
    \item  Empty, in which case the message-level is set to the value specified
in the second argument;
    \item  \texttt{+}, in which case the value specified in the second argument
augments the current message level;
    \item  \texttt{-}, in which case the value specified in the second argument
augments is removed from the current message level
    \end{itemize}

The second argument specifies one or more, separated by blanks, message
level names or it may be set to a hexadecimal value (starting with \texttt{0x}),
using hexadecimal values to represent message levels. Also, \texttt{NONE} may be
used, to specify no message level, or \texttt{ALL} can be used to specify all
message levels. 

The following message levels are defined:
    \begin{itemize}
    \item  ALERT (0x40). When an alert-error occurs, Yodl
terminates. Here Yodl requests something of the system (like a \texttt{get\_cwd()}),
but the system fails.
    \item  CRITICAL (0x20). When a critical error occurs, Yodl
terminates.  The message itself can be suppressed, but exiting can't. A
critical condition is, e.g., the omission of an open parenthesis at a location
where a parenthesized argument should appear, or a non-existing file in an
\texttt{INCLUDEFILE} specification (as this file should be parsed). A non-existing
file with a \texttt{NOEXPANDINCLUDE} specification is a plain (non-critical) error.
    \item  DEBUG (0x01). Probably too much info, like getting information
about each character that was read by Yodl.
    \item  ERROR (0x10). An error (like doubly defined symbols). Error
messages will not stop the parsing of the input (up to a maximum number of
errors), but no output is generated.
    \item  INFO (0x02). Not as detailed as `debug', but still very much
info, like information about media switches.
    \item  NOTICE (0x04). Information about, e.g., calls to the builtin
function calls.
    \item  WARNING (0x08). Something you should know about, but probably
not affecting Yodl's proper functioning
    \end{itemize}

There also exists a level EMERG (0x80) which cannot be suppressed.

The value \texttt{0x00} represents \texttt{NONE}, the value \texttt{0xff} represents
\texttt{ALL}. 

When specifying multiple message levels using the hexadecimal form, their
hexadecimal values should be binary-or-ed: adding them is ok, as long as you
don't specify \texttt{ALL}:
        \begin{verbatim}

    VERBOSITY()(0x06)
    COMMENT(this specifies `INFO' and `NOTICE')
        
\end{verbatim}

    When specifying message levels by their names, the names may be truncated
at a unique point. However, the message level names are interpreted case
sensitively, so \texttt{INF} for \texttt{INFO} is recognized as such, but \texttt{info} for
\texttt{INFO} isn't. The following examples all specify verbosity levels INFO and
NOTICE: 
        \begin{verbatim}

    VERBOSITY()(I N)
    VERBOSITY()(N I)
    VERBOSITY()(NOT IN)
    VERBOSITY()(INFO NOTICE)
        
\end{verbatim}


\subsection{WARNING}\label{WARNING}
    \typeout{Original Yodl file: userguide/builtin/warning}\texttt{WARNING} takes one argument: text to display as a warning. The 
\texttt{yodl} program makes sure that before showing the text, the current file and 
line number are printed. Other than this, \texttt{WARNING} works just as
\texttt{TYPEOUT} (see section \ref{TYPEOUT}). 

Note that an analogous function \texttt{ERROR} exists, which prints a message and
then terminates the program (see section \ref{ERROR}).

\cleardoublepage\chapter{Macros and Document types}\label{MACROPACKAGE}
The macro package distributed with \texttt{Yodl} is described in
this chapter. The macro package consists of a number of definition files,
which convert a Yodl document that follows a certain syntax to an output
format. The main output formats, currently supported, are:
    \begin{itemize}
    \item  HTML;
    \item  LaTeX (plain LaTeX, no \texttt{latex2e});
    \item  The \texttt{groff} `man' format which is used for man pages;
    \item  The \texttt{groff} `ms' format which is more expressive;
    \item  Basic, plain text 
    \end{itemize}

The following conversion format is in an experimental stage:
    \begin{itemize}
    \item  XML, as used by the University of Groningen's so-called
`webplatform'. 
    \end{itemize}

Currently discontinued conversion formats are:
    \begin{itemize}
    \item  SGML, although the basic macros are available. SGML can probably be
reactivated fairly quickly. Contact the maintainer if support for SGML should
be reinstated
    \item  texinfo, mainly due to the fact that the current maintainer doesn't
know what the required \emph{post-processing} actions are.
    \item  tely, since this conversion format is unknown to the current
maintainer.
    \end{itemize}

Other formats may be available, but maybe in an unstable state. Contact
the the maintainer if you have a new format to add, or want to reanimate
formats that were previously available.

\section{General structure of a Yodl document}
    This section describes the general format of a Yodl document.

First of all, a Yodl document needs a \emph{preamble}. This part
of the document must be at the top, and must define the modifiers and the  
document type. Modifiers, when present, must appear first.

Modifiers are often specific for a particular target document type 
(e.g., \texttt{latexoptions} or \texttt{mailto}), but may also have a general nature
(e.g., \texttt{affiliation} or \texttt{abstract}). All modifiers are used to modify
parameters of document types. Therefore, they must be specified before the
document type is defined.

All modifiers are listed in section \ref{MODIFIERS}. In general, you should use
as many modifiers as appropriate. E.g., you should define a \texttt{mailto} even
when you're not planning to convert your document to HTML. The reason is
twofold: first, you might later decide that a HTML version isn't a bad idea
after all. Second, later versions of the converters might use \texttt{mailto} even
for non-HTML output formats.

Following the modifiers, the \emph{document type} is defined. The document type
is either \texttt{article}, \texttt{report}, \texttt{book}, \texttt{plainhtml} or \texttt{manpage}.
Except for the \texttt{manpage} document type, which is a highly specialized
document type, described in section \ref{MANPAGE}, the following rules apply:

A decision about the document type to use should be based on its
complexity. If the document's organization becomes too complex, it is probably
a good idea to use a document type supporting a more complex
organization. E.g., a complex \emph{article} might be written as an accessible
\emph{report}, combining related sections into chapters. Similarly, the structure
of a report having 30 chapters might improve when it's re-organized as a
\emph{book} having parts. To offer a rule of thumb: a document should have no
more than approximately ten top-level sections, and each top-level sectioning
should have no more than approximately ten subsections, etc..

The document type influences the way Yodl formats the output. An \texttt{article}
(or \texttt{plainhtml}) results in one output file. E.g., one final document when
converting to HTML. If your article is way too long, then the loading of the
HTML document also requires much time. When converting to HTML, Yodl splits
\texttt{report}s and \texttt{books} into files each holding a chapter. These can be
accessed through the table of contents. So, the document length can also be
relevant when you contemplate switching to a \texttt{report} or \texttt{book}.

Documents using special macros, must have defined these macros \emph{before} they
are used. An appropriate location for these macros is immediately beyond the
preamble.  E.g., see the file \texttt{Documentation/manual/manual.yo} distributed
with the Yodl package.  This is the main file of this manual, showing the
preferred organization of Yodl files.

To answer \emph{yes-but-what-if} oriented minds, here are two results of the 
wrong order of text, preamble and modifiers:
    \begin{itemize}
    \item  If you put text before the preamble, i.e., before stating the
document type, chances are that Yodl happily translates the file, but
subsequent states probably fail. E.g., the \texttt{$<$html$>$} tag would come too
late in a HTML conversion, causing the HTML browser to become confused.  Or,
the \texttt{\textbackslash{}documentstyle} definition would be seen too late by the LaTeX
typesetter.
    \item  If you put modifiers, such as \texttt{latexoptions}, \emph{beyond} the
document type, then these modifiers have no effect; though Yodl won't complain
either. The reason for this being that the definitions of such modifiers are
encountered only  \textbf{after} the stage where they were needed....
    \end{itemize}

\subsection{Document types}
        As distributed, Yodl supports four document types: \emph{article, report,
book} and the \emph{manual} page. Note that document types are essentially
unrelated to output formats; a book can be converted to each of the output
formats, and a manual page can be converted to a \texttt{.html} file. Nevertheless,
some formats are particularly useful for some document types. A book
converted to the \texttt{man} output format to be processed later with \texttt{groff}
won't look too good. Its looks would greatly improve when the document would
be converted to ASCII using the \texttt{ms} output format.

Following the preamble and the definition of specialized macros symbols and
counters, documents start by specifying the document type.  The available
macros are:
    \begin{itemize}
    \item  \texttt{article(title)(author)(date)}: The \texttt{article} document type
should be used for short documents. Its arguments specify the document's
title, author and date.

In articles, the title page is numbered and the table of contents is on
the title page. The sectioning commands \texttt{sect}, \texttt{subsect} etc.  are
available.
    \item  \texttt{report(title)(author)(date)}: The \texttt{report} document type differs
from an \texttt{article} in that it has a separate unnumbered title page, a table
of contents on a page of its own, and it supports the sectioning command
\texttt{chapter} in addition to the ones supported by \texttt{article}s. A \texttt{report}
should be used fir larger documents.
    \item  \texttt{book(title)(author)(date)}: The \texttt{book} type is for even larger
documents. In addition to the sectioning commands supported by \texttt{report} it
supports the sectioning command \texttt{part}.
    \item  \texttt{plainhtml(title)}: This document type is typically used in HTML
output. It's implemented for situations where you only need to create a HTML
file, but want to use Yodl to help you by providing useful macros.  This
document type is similar to \texttt{article}, but does not require you to specify
\texttt{author} and \texttt{date} arguments (In fact, you can emulate \texttt{plainhtml} by
using an \texttt{article}, using empty author and date arguments).
    \item  \texttt{manpage(title)(section)(date)(source)(manual)}: The \texttt{manpage}
document type should only be used to write Unix-style manual pages. It uses
its own sectioning commands to reflect the necessary sections in a manual
page. This document format is described separately in \ref{MANPAGE}.
    \end{itemize}
    These macros provide, globally, three functions: First, the macros
generate any commands that need to appear before `real' text is sent to the
output file.  E.g., the LaTeX output needs a \texttt{\textbackslash{}documentstyle}
preamble, HTML output needs \texttt{$<$html$>$} and \texttt{$<$body$>$} tags.

Second, the macros define appropriate document-dependent settings. E.g., the
LaTeX converter defines the title, author and date using \texttt{\textbackslash{}title} etc..

Third, the actual document is started. E.g., for LaTeX this means a
\texttt{\textbackslash{}begin\{}\emph{type}\texttt{\}}, followed by the appropriate commands to generate a
the document title and the table of contents.  The \texttt{title} setting in the
above macros defines the document title which always appears on the front page
of the document. For HTML output, this is also the title of the HTML file (or
files), as appearing in the HTML \texttt{$<$title$>$} tag.

The fact that the macros defining the document type perform many functions
means that once the macro is started, nothing `extra' can be inserted between,
e.g., the generated title and the table of contents. Sometimes this is not
what you'd like; as is the case with an abstract. Yodl therefore uses
\emph{modifiers}, appearing \emph{before} the document type macros, to insert
information between the various elements of a document definition.

\subsection{The manpage document type}\label{MANPAGE}
        The \emph{manpage} document type was implemented to simplify the construction of
Unix-style manual pages. \texttt{Yodl} mapage documents can be converted to \texttt{groff}
documents (using \texttt{yodl2man}), to \texttt{html} documents (using \texttt{yodl2html}), or
to plain ascii text documents (using \texttt{yodl2txt}). 

A \emph{manpage} document \textbf{must} be organized as follows:
    \begin{enumerate}
    \item  The manual page itself is defined, using the macro
        \begin{verbatim}
manpage(short title)
            (section)
            (date)
            (source)
            (manual)
        
\end{verbatim}

    Its arguments are:
    \begin{description}
    \item[Short title:] This should be the program name or something
similar; i.e., whatever the manpage is describing.
    \item[Section:] A number, stating the manpage section. The Linux man (7)
page recognizes the following manpage sections:
        \begin{itemize}
        \item   Section 1 is for commands, like \texttt{ls};
        \item  Section 2 is for system calls, like \texttt{fork()};
        \item  Section 3 is for library calls, like \texttt{strdup()};
        \item  Section 4 is for special files (like \emph{devices});
        \item  Section 5 is for file formats, (like \texttt{syslog.conf});
        \item  Section 6 is for games;
        \item  Section 7 is for macro packages and conventions;
        \item  Section 8 is for system management commands;
        \item  Section 9 is for other types of manpages, such as kernel
            commands.
        \end{itemize}
    \item[Date:] The date of release.
    \item[Source:] The package where the manpage belongs to.
    \item[Manual:] The manual to which the package belongs.
    \end{description}
    The arguments of the \emph{manpage} macro define, e.g., the headers and
footers of the manual page. The \texttt{date}, \texttt{source} and \texttt{manual} arguments
can be empty.
    \item  The subject of the manpage is defined using
        \begin{verbatim}

    manpagename(name)(short description)
        
\end{verbatim}

    The \texttt{name} argument should be a short name (e.g., the program name), and
the \texttt{short description} should state the function. The descriptive argument
is used by, e.g., the \texttt{whatis} database.
    \item  The synopsis starts after:
        \begin{verbatim}

    manpagesynopsis()
        
\end{verbatim}

    Following this, an abbreviated usage information is presented. This
information should show, e.g., the possible program flags and required
arguments; but no more.
    \item  The description is given after:
        \begin{verbatim}

    manpagedescription()
        
\end{verbatim}

    This is followed by some descriptive text. The descriptive text can
e.g. show what the program (function, file, game, etc.) is supposed to do.
    \item  Options are expected after:
        \begin{verbatim}

    manpageoptions()
        
\end{verbatim}

    The options are typically a descriptive list of possible flags and their
meaning. This section lists the information of the synopsis, but also gives an
in-depth description. The \texttt{manpageoptions()} section is optional.
    \item  Necessary files are listed after:
        \begin{verbatim}

    manpagefiles()
        
\end{verbatim}

    \item  The `see also' entry is defined by:
        \begin{verbatim}

    manpageseealso()
        
\end{verbatim}

    This is then followed by a list of related manual pages. Here, use the
format \texttt{bf(topic)(sectionnr)}, e.g., \texttt{Yodl}(1).
    \item  Diagnostics are described after:
        \begin{verbatim}

    manpagediagnostics()
        
\end{verbatim}

    Diagnostics can state, e.g., what error messages are produced by the
program and what the cure is.
    \item  Known bugs should be mentioned after:
        \begin{verbatim}

    manpagebugs()
        
\end{verbatim}

    This section is optional.
    \item  Finally, the author is stated after:
        \begin{verbatim}

    manpageauthor()
        
\end{verbatim}

    \end{enumerate}
    The \texttt{manpage} document type \textbf{requires} you to follow the
above order of commands strictly and to state all the necessary sections (and
optionally, to state the not required sections but in their proper sequence).
Furthermore, sectioning commands that are available in other document types
(\texttt{sect}, \texttt{subsect} etc.) are not allowed in a \texttt{manpage}. You \emph{can}
however insert other sections in the manual page with the macro
\texttt{manpagesection}. This macro takes one argument: the title of the extra
section. It is suggested that you type the section name in upper case, to
conform to the standard.

As an example, the manual page for the \texttt{yodl} program follows (the
actual manual page may differ):
        \begin{verbatim}

    manpage(yodl)
           (1)
           (1996)
           (The Yodl Package)
           (Yet oneOther Document Language)

    manpagename(yodl)(main Yodl converter)
    
    manpagesynopsis()
    YODL [-DNAME] [-IDIR] [-oFILE] [-PCMD] [-pPASS] [-t] [-v] [-w] [-h]
    [-?]  inputfile [inputfile...]

    manpagedescription()
    This manual page describes the YODL program, the main converter of the
    Yodl package. This program is used by the bf(yodl2....) shell scripts,
    e.g., bf(yodl2tex) or bf(yodl2html).

    manpageoptions()
    description(
    dit(-DNAME) Defines symbol em(NAME).
    dit(-IDIR) Overrules the standard include directory (default 
em(/usr/local/lib/yodl)) with em(DIR).
    dit(-oFILE) Specifies em(FILE) as the output file (default is stdout).
    dit(-PCMD) `Preloads' command em(CMD), as if em(CMD) was the first line 
of the input.
    dit(-pPASS) Defines em(PASS) as the maximum number of `passes'; when this 
number is exceeded, YODL aborts.
    dit(-t) Enables tracing mode. Useful for debugging.
    dit(-v) Raises the verbosity mode. Useful for debugging.
    dit(-w) Enables warning. When enabled, YODL warns when it encounters
inconsistencies.
    dit(-h, -?) Shows usage information.
    dit(inputfile) File to process, use em(-) to instruct YODL to read 
from stdin.
    )

    manpagefiles()
    The YODL program requires no files, but `normal' usage of the Yodl package
requires macro files installed (usually in bf(/usr/local/share/yodl)). The
files in this directory are included by the converters bf(yodl2txt) etc..

    manpageseealso()
    bf(yodl2tex), bf(yodl2html), bf(yodl2man), etc..

    manpagediagnostics()
    Warnings and errors of YODL are too many to enumerate, but all errors
are printed to em(stderr) after which YODL exits with a non-zero
status.

    manpagebugs()
    There may be bugs in the YODL program, but that's not very likely.
More likely you'll encounter bugs or omissions in the macro package
itself.

    manpageauthor()
    Karel Kubat
        
\end{verbatim}


\section{Predefined macros}\label{MACROLIST}
    This section describes all macros defined by default. Altering or removing
these macros may produce unexpected results when converting \texttt{Yodl} documents to
other formats. Furthermore, these macros often depend on macros or other
symbols defined for internal use.

Many predefined macros depend on symbols start with \texttt{XX}. Therefore, it is
strongly advised not to start any locally defined symbol with \texttt{XX} as doing
so, or undefining existing symbols starting with \texttt{XX}, may also produce
unexpected results.

Here are the default macros, alphabetically ordered:


    \subsection{abstract(text)}

Defines an abstract for an article or report type of document. Abstracts are
not implemented for books or manpages. Must appear \textbf{before} starting the
document using the \texttt{article} or \texttt{report} macro.


    \subsection{addntosymbol(symbol)(n)(text)}

Adds \texttt{text} \texttt{n} times to \texttt{symbol}. The value \texttt{n} may also be the name
of a defined counter (which is not modified).


    \subsection{affiliation(site)}

Defines an affiliation, to appear in the document titlepage below the author
field. Must appear \textbf{before} starting the document with \texttt{article},
\texttt{report} or \texttt{book}. The affiliation is only printed when the author field
is not empty. When converting to html the way the affiliation is displayed can
be tuned using CSS id selector specifications. The affiliation has
\texttt{id="affiliation"}.


    \subsection{AfourEnlarged()}

Enlarges the usable height of A4 paper by 2 cm.: the top margin is reduced by
2 cm. This macro should be called in the preamble. The macro is available only
for \LaTeX{} conversions.\ \\ 
This macros is somewhat obsolete. Instead, using \texttt{PageEnlarged} is advised


    \subsection{appendix()}

Starts appendices


    \subsection{article(title)(author)(date)}

Starts an article. The top-level sectioning command is \texttt{(n)sect}. In HTML
conversions only one output file is written, while the way the headings are
displayed can be tuned using CSS id selector specifications: the title has
\texttt{id="title"}, the author \texttt{id="author"}, and the date \texttt{id="date"}.
)


    \subsection{attrib(text)}

In html, pushes \texttt{text} as an attribute for the next html tag supporting
\texttt{attrib}.  E.g, to set a blue color and 30 pixel left-hand side margin for a
section use
    \begin{verbatim}

    attrib(style="color:blue;margin-left:30px;")\ 
    sect(Section name)
    
\end{verbatim}
 
    This results in the html markup\ \\ 
    \begin{verbatim}

    <h1 style="color:blue;margin-left:30px;">Section name</h1>
    
\end{verbatim}

    This macro is only effective with html conversions. It is applied in a
stack-wise fashion: when multiple \texttt{attrib} calls are used, then the topmost
attrib-string is added to the first macro calling the 
\texttt{attribinsert} macro, with subsequent macros using subsequent elements on
the attrib-stack. 

Commonly used attributes are \texttt{id="idname"}, expecting a \texttt{\#idname} CSS
label in either internal or external CSS specifications, or \texttt{style="spec"}
(as shown in the example). 

Example: when using
    \begin{verbatim}

    attrib(width = "100" height = "100")
    attrib(id = "#fig")
    figure(imgfile)(Caption)(IMG)
    
\end{verbatim}

    then the \texttt{\#id} attribute is applied to \texttt{$<$figure$>$}, and the \texttt{width}
and \texttt{height} attributes are applied to \texttt{$<$img$>$}, which html markup is
inserted by the \texttt{figure} macro.

The \texttt{attrib} macro is supported by the following predefined macros (between
parentheses the number of attribute strings that are inserted by these macros;
if only 1 attribute string is inserted no number is shown): 

\texttt{bf cell cells center chapter code dashes dit em figure(3) file htmltag
itdesc lchapter link lref lsect lsubsect lsubsubsect nchapter npart nsect
nsubsect nsubsubsect paragraph part quote row sc sect strong subs subsect
subsubsect subsubsubsect sups tableatt tbl tac tc tnac tnc tr tt ttbegin url
verb verborg verbinclude}.


    \subsection{attribclear()}

Removes any existing contents from the attrib-stack. This macro is only
active when converting to html


    \subsection{attribinsert()}

In html, if the attrib-stack is not empty, 
inserts the value on top of the attrib-stack and then pops the topmost value.
If the attrib-stack is empty, nothing happens.


    \subsection{bf(text)}

Sets \texttt{text} in boldface.


    \subsection{bind(text)}

Generate a binding character (non-breaking space) after text.


    \subsection{book(title)(author)(date)}

Starts a book document. The top-level sectioning command is \texttt{(n)chapter},
\texttt{(n)part} being optional. In HTML output files are created for each
chapter, while the way the headings are displayed can be tuned using
CSS id selector specifications: the title has \texttt{id="title"}, the author
\texttt{id="author"}, and the date \texttt{id="date"}.
)


    \subsection{cell(contents)}

Sets a table cell, i.e., one element in a row. With the man/ms converters
multiple blanks between \texttt{cell()} macro calls are merged into a single blank
character.

Instead of using \texttt{cell} in \texttt{table}, consider using \texttt{tc} in \texttt{tbl}.


    \subsection{cells(nColumns)(contents)}

Set a table cell over \texttt{nColumns} columns. With \LaTeX{} and xml the
information in the combined cells is centered. 

With man/ms conversions the \texttt{cells()} macro simply calls the \texttt{cell()}
macro, but here the \texttt{setmanalign()} macro can be used to determine the
alignment of multiple cells.

With html the macro \texttt{attrib} can be used, but when it contains a \texttt{style}
specification the macro's default \texttt{style="text-align: center"} is ignored
(but it can optionally be specified using the \texttt{attrib} macro).

Instead of using \texttt{cells} in \texttt{table}, consider using \texttt{tnc} in \texttt{tbl}.


    \subsection{cellsline(from)(count)}

Sets a horizontal line starting at column number \texttt{from} over \texttt{count}
columns in a row. If \texttt{from} is less then the number of columns already added
to a row then it is ignored. This macro must be embedded in a \texttt{row} macro
defining a table row.  To put a line across the table's full width use
\texttt{rowline}. To set horizontal lines across columns 1
until 2 and columns 4 until 5 table of a table use:
        \begin{verbatim}

    row(cellsline(1)(2)cellsline(4)(2))
        
\end{verbatim}

 Combining \texttt{cellsline} and \texttt{cell} or \texttt{cells} calls in one row produces
undefined results.

Instead of using \texttt{cellsline} in \texttt{table}, consider using \texttt{tline} in
\texttt{tbl}.


    \subsection{center(text)}

Centers \texttt{text}. Use \texttt{nl()} in the text to break lines.  In html the
\texttt{attrib} macro is not supported, but a division (\texttt{div}) with style
definition \texttt{text-align: center} is used. To center a table in html use
the \texttt{tableatt} macro. If a \texttt{table} or \texttt{tableatt} macro is used inside a
\texttt{center} macro then the contents of columns are column-wise centered.

Inside a \texttt{center(...)} context the counter \texttt{XXcenter} is unequal 0.


    \subsection{chapter(title)}

Starts a new chapter in books or reports.


    \subsection{cindex()}

Generate an index entry for LaTex() or texinfo 
c-indices. Its argument is the
index entry.  See also the \texttt{{[}fptv{]}index} macro.


    \subsection{cite(text)}

Sets \texttt{text} as a citation or quotation


    \subsection{clearpage()}

Starts a new page, when the output format permits. Under HTML a horizontal
line is drawn.


    \subsection{code(text)}

Sets \texttt{text} in code font, and prevents it from being expanded.
For unbalanced parameter lists, use \texttt{CHAR(40)} to get
\texttt{(} and \texttt{CHAR(41)} to get \texttt{)}.


    \subsection{columnline(from)(through)}

Sets a horizontal line over some columns in a row. Note that \texttt{columnline}
defines a row by itself, consisting of just a horizontal line spanning some of
its columns, rather than the table's full width, like \texttt{rowline}. The two
arguments represent column numbers. It is the responsibility of the author to
make sure that the \texttt{from} and \texttt{through} values are sensible. I.e., 
        \begin{verbatim}

    1 <= from <= through <= ncolumns
        
\end{verbatim}

To set a horizontal line in just one column select \texttt{through} equal to
\texttt{from}.

\textbf{Note}: this macro cannot be used if multiple lines must be set in one
row. In those cases the macros \texttt{tline, tskip}, and \texttt{tendline} should be
used. 

Instead of using \texttt{columnline} in \texttt{table}, consider using \texttt{tline} in
\texttt{tbl}.


    \subsection{dashes()}

Inserts two dashes in teletype font, and prevents them from being
expanded.  

In html the \texttt{attrib} macro is recognized by the \texttt{$<$code$>$} tag that is used
to embed the two dashes.


    \subsection{def(macroname)(nrofargs)(redefinition)}

Defines \texttt{macroname} as a macro, having \texttt{nrofargs} arguments, and
expanding to \texttt{redefinition}. This macro is a shorthand for
\texttt{DEFINEMACRO}.
 An error occurs when the macro is already defined. Use
\texttt{redef()} to unconditionally define or redefine a macro.


    \subsection{description(list)}

Sets \texttt{list} as a description list. Use \texttt{dit(item)} to
indicate items in the list.


    \subsection{dit(itemname)}

Starts an item named \texttt{itemname} in a description list. The list should be
used in \texttt{description} macros. With \texttt{html} conversions the
contents of a description item is separated from the item itself. The \texttt{dit}
macro only defines the item, and not the description itself. This macro sets
the item in bold-face (`strong' font). The macro \texttt{itdesc}, available since
Yodl 3.05, can be used to defines an item \emph{and} its description, using its
suggested format (i.e., indenting the description relative to the item).


    \subsection{eit()}

Indicates an item in an enumerated list. The \texttt{eit} macro should be used as
an argument in \texttt{enumeration} macros.


    \subsection{ellipsis()}

Sets ellipsis (...).


    \subsection{em(text)}

Sets \texttt{text} as emphasized, usually italics.


    \subsection{email(address)}

In HTML, this macro sets the \texttt{address} in a \texttt{$<$a href="mailto=.."$>$}
locator. In other output formats, the \texttt{address} is sent to the output. The
\texttt{email} macro is a special case of \texttt{url}.


    \subsection{enumeration(list)}

\texttt{enumeration()} starts an enumerated list. Use \texttt{eit()} in the list to 
indicate items in the list.


    \subsection{euro()}

Sets the euro currency symbol in latex, html, (and possibly sgml and xml). In
all other conversions EUR which is the official textual abbreviation
(cf. \texttt{http://ec.europa.eu/euro/entry.html}) is written. Note that \LaTeX{}
may require latexpackage()(eurosym).


    \subsection{evalsymbol(symbol)(expression)}

Symbol \emph{symbol} receives the value resulting from evaluating
\emph{expression}. E.g., if \texttt{sym} is a defined symbol, then
        \begin{verbatim}

    evalsymbol(sym)(SUBSTR(hello world)(3)(2))
        
\end{verbatim}

    assigns the value \texttt{lo} to \texttt{sym}.


    \subsection{fig(label)}

This macro is a shorthand for \texttt{figure ref(label)} and just makes the typing
shorter, as in \texttt{see fig(schematic) for ..} See \texttt{getfigurestring()} and
\texttt{setfigurestring()} for the \texttt{figure} text.


    \subsection{figure(file)(caption)(label)}

Sets the picture in \texttt{file} as a figure in the current document, using the
descriptive text \texttt{caption}. The \texttt{label} is defined as a placeholder for
the figure number and can be used in a corresponding \texttt{ref} statement. Note
that the \texttt{file} must be the filename without extension: By default, Yodl
will supply \texttt{.gif} when in HTML mode, or \texttt{.ps} when in LaTeX mode. Figures
in other modes may not (yet) haven been implemented.

When converting to html, this macro uses three attribute-strings (if
available). The string pushed first using an attrib-call defines the
attributes for its \texttt{$<$figcaption$>$} html-markup; the string pushed next defines
the attributes for its \texttt{$<$img$>$} html-markup; the string pushed last defines
the attributes for its \texttt{$<$figure$>$} html-markup. The \texttt{figure} macro's html
output is organized like this:
    \begin{verbatim}

    <figure -attrib-string pushed last (if any)>
        <img ... -attrib-string pushed last but one>
        <figcaption -attrib-string pushed 2nd to last>
            ...
        </figcaption>
    </figure>
    
\end{verbatim}

Starting with Yodl 3.07.00 no \texttt{alt="Figure \# is shown here..."} attribute is
defined anymore for the \texttt{img} markup: an \texttt{alt}-attribute can easily be
defined at the last attrib-call, using \texttt{getfigurestring()} to obtain
\texttt{Figure} or its language-specific translation, and
\texttt{COUNTERVALUE(XXfigurecounter)} to obtain the order-number of the figure
shown in the next \texttt{figure}-macro call.


    \subsection{file(text)}

Sets \texttt{text} as filename, usually boldface.
 In html \texttt{attrib} macro applies to the \texttt{$<$strong$>$} tag.


    \subsection{findex()}

Generate an index entry for LaTex() or texinfo 
f-indices. Its argument is the
index entry.  See also the \texttt{{[}cptv{]}index} macro.


    \subsection{footnote(text)}

Sets \texttt{text} as a footnote, or between parentheses when the output format
 does not allow footnotes.


    \subsection{gagmacrowarning(name name ...)}

Prevents the \texttt{yodl} program from printing \emph{cannot expand possible user
macro}. E.g., if you have in your document \texttt{the file(s) are ..} then you
might want to put before that: \texttt{gagmacrowarning(file)}. Calls 
\texttt{NOUSERMACRO}.


    \subsection{getaffilstring()}

Expands to the string that defines the name of \emph{Affiliation Information}, by
default \emph{AFFILIATION INFORMATION}. Can be redefined for national language
support by \texttt{setaffilstring()}. Currently, it is relevant only for txt.


    \subsection{getauthorstring()}

Expands to the string that defines the name of \emph{Author Information}, by
default \emph{AUTHOR INFORMATION}. Can be redefined for national language
support by \texttt{setauthorstring()}. Currently, it is relevant only for txt.


    \subsection{getchapterstring()}

Expands to the string that defines a `chapter' entry, by default \emph{Chapter}.
Can be redefined for national language support by \texttt{setchapterstring()}.


    \subsection{getdatestring()}

Expands to the string that defines the name of \emph{Date Information}, by
default \emph{DATE INFORMATION}. Can be redefined for national language
support by \texttt{setdatestring()}. Currently, it is relevant only for txt.


    \subsection{getfigurestring()}

Returns the string that defines a `figure' text, in captions or in the
\texttt{fig()} macro. The string can be redefined using the \texttt{setfiguretext()}
macro.


    \subsection{getpartstring()}

Expands to the string that defines a `part' entry, by default \emph{Part}. Can
be redefined for national language support by \texttt{setpartstring()}.


    \subsection{gettitlestring()}

Expands to the string that defines the name of \emph{Title Information}, by
default \emph{TITLE INFORMATION}. Can be redefined for national language
support by \texttt{settitlestring()}. Currently, it is relevant only for txt.


    \subsection{gettocstring()}

Expands to the string that defines the name of the table of contents, by
default \emph{Table of Contents}. Can be redefined for national language
support by \texttt{settocstring()}.


    \subsection{htmlcommand(cmd)}

Writes \texttt{cmd} to the output when converting to html. The \texttt{cmd} is not
further expanded by Yodl.


    \subsection{htmlheadfile(file)}

Adds the contents of \texttt{file} to the \texttt{head} section of an HTML
document. The contents of file are not interpreted and should contain plain
html text. This option can be useful when large bodies of text, like the
contents of \texttt{$<$script$>$} sections, must be included into the head section of
html documents. This macro is only active in the preamble, should only
specified once, and is only interpreted for html conversions.


    \subsection{htmlheadopt(option)}

Adds the literal text \texttt{option} to the current information in the \texttt{head}
section of an HTML document. \texttt{Option} may (or: should) contain plain html
text. A commonly occurring head option is \texttt{link}, defining, e.g., a style
sheet. Since that option is frequently used, it has received a dedicated
macro: \texttt{htmlstylesheet}. When large bodies of html-text must be added to
html documents the macro \texttt{htmlheadfile} should be used. This macro is only
active in the preamble and is only interpreted for html conversions.


    \subsection{htmlnewfile()}

In HTML output, starts a new file. All other formats are not affected. Note
that you must take your own provisions to access the new file; say via links.
Also, it's safe to start a new file just befoore opening a new section, since
sections are accessible from the clickable table of contents. The HTML
converter normally only starts new files prior to a \texttt{chapter} definition.


    \subsection{htmlstyle(tag)(definition)}

Adds a \texttt{$<$style type="text/css"$>$ ... $<$/style$>$} element to the head section
of an HTML document.\ \\ 
 Use \texttt{htmlstyle} to specify one or more CSS definitions which are eventually
inserted at the ellipsis (\texttt{...}) in the generic \texttt{style} definition shown
above. E.g., (using \texttt{\#rrggbb} to specify a color, where \texttt{rr} are two
hexadecimal digits specifying the color's red component, \texttt{gg} two
hexadecimal digits specifying the color's green component, and \texttt{bb} two
hexadecimal digits specifying the color's blue component)  specifying\begin{verbatim}

    htmlstyle(body)(color: #rrggbb; background-color: #rrggbb)
    htmlstyle(h1)(color: blue; text-align: center)
    htmlstyle(h2)(color: green)
    
\end{verbatim}

    results in the element\begin{verbatim}

    <style type="text/css">
        body {color: #rrggbb; background-color: #rrggbb;}
        h1 {color: blue; text-align: center;} 
        h2 {color: green;}
    </style>
    
\end{verbatim}

 The macros \texttt{htmlheadopt} and \texttt{htmlstylesheet} could also be used to put
information into the head-section of an HTML document, but \texttt{htmlheadopt} is
of a much more general nature, while \texttt{htmlstylesheet} refers to CSS elements
stored in an external file. The macro \texttt{attrib} can be used to define
\emph{inline styles}.

The \texttt{htmlstyle} macro is only active in the preamble and is only
interpreted for html conversions.\ \\ 
 Refer to available CSS specifications (cf.,
\texttt{http://www.w3schools.com/cssref/} for an overview of how CSS
specifications are used, and which CSS specifications are available).

By default the internal style specification\ \\ 
    \texttt{figure \{text-align: center;\} img \{vertical-align: center;\}}\ \\ 
 is used. If this is not appropriate, specify \texttt{nohtmlimgstyle()} in the
preamble. 


    \subsection{htmlstylesheet(url)}

Adds a \texttt{$<$link rel="stylesheet" type="text/css" ...$>$} element to the head
section of an HTML document, using \texttt{url} in its \texttt{href} field. The argument
\texttt{url} is not expanded, and should be plain HTML text, without surrounding
quotes. The macro \texttt{htmlheadopt} can also be used to put information in the
head-section of an HTML document, but \texttt{htmlheadopt} is of a much more
general nature.  This macro is only active in the preamble and is only
interpreted for html conversions.


    \subsection{htmltag(tagname)(start)}

Sets \texttt{tagname} as a HTML tag, enclosed by \texttt{$<$} and \texttt{$>$}. When \texttt{start}
is zero, the \texttt{tagname} is prefixed with \texttt{/}. As not all html tags are
available through predefined Yodl-macros (there are too many of them, some are
used very infrequently, and you can easily define macros for the tags for
which Yodl doesn't offer predefined ones), the \texttt{htmltag} macro can be used
to handle your own set of macros. In html the \texttt{attrib} macro is
supported. E.g.,
    \begin{verbatim}

attrib(title="World Health Organization")\
    htmltag(abbr)()WHO+htmltag(abbr)(0)
    
\end{verbatim}



    \subsection{ifnewparagraph(truelist)(falselist)}

The macro \texttt{ifnewparagraph} should be called from the \texttt{PARAGRAPH} macro,
if defined. It will insert \texttt{truelist} if a new paragraph is inserted,
otherwise \texttt{falselist} is inserted (e.g., following two consecutive calls of
PARAGRAPH). This macro can be used to prevent outputting multiple blank lines.


    \subsection{includefile(file)}

Includes \texttt{file}. The default
extension \texttt{.yo} is supplied if necessary.

Since Yodl version 3.00.0 Yodl's default file inclusion behavior has
changed. The current working directory no longer remains fixed at the
directory in which Yodl is called, but is volatile, changing to the directory
in which a yodl-file is located. This has the advantage that Yodl's file
inclusion behavior now matches the way \textbf{C}'s \texttt{\#include} directive
operates. The originally implemented file inclusion behavior is used when 
Yodl's \texttt{-L} (\texttt{+NOTRANS(-\{\}-\{\})legacy-include}) option is used.


    \subsection{includeverbatim(file)}

Include \texttt{file} into the output.  No processing is done, \texttt{file} should
be in preformatted form, e.g.: \begin{verbatim}
whenhtml(includeverbatim(foo.html))
\end{verbatim}



    \subsection{it()}

Indicates an item in an itemized list. Items in \texttt{it} macros are
arguments of \texttt{itemization} macros.


    \subsection{itdesc(itemname)(contents)}

Starts an item and its description in a description list. Its name is
\texttt{itemname}, the contents of the item is defined by \texttt{contents}. The
\texttt{itemname} is defined by using the \texttt{dit} macro. 

With \texttt{html} conversions the contents are surrounded by \texttt{$<$dd$>$} and
\texttt{$<$/dd$>$} tags, resulting in contents which are indented relative to the
itemname. When the \texttt{attrib} macro is used it is applied to the itemname
(\texttt{dt}-tags). 

With other conversions the \texttt{contents} are quoted (as if using
\texttt{quote(contents)}).


    \subsection{itemization(list)}

Sets \texttt{list} as an itemizationd list. Use \texttt{it()} to indicate items in the
list.


    \subsection{kindex()}

Generate an index entry for LaTex() or texinfo k-indices. Its argument is the
index entry.  See also the \texttt{{[}cfptv{]}vindex} macro.


    \subsection{label(labelname)}

Defines \texttt{labelname} as an anchor for a \texttt{link}
command, or to stand for the last numbering of a section or figure in a
\texttt{ref} command.


    \subsection{langle()}

Character <


    \subsection{languagedutch()}

Defines the Dutch-language specific headers. Active this macro via
setlanguage(dutch).


    \subsection{languageenglish()}

Defines the English-language specific headers. Active this macro via
setlanguage(english).


    \subsection{languageportugese()}

Defines the Portugese-language specific headers. Active this macro via
setlanguage(portugese).


    \subsection{LaTeX()}

The LaTeX symbol.


    \subsection{latexaddlayout(arg)}

This macro is provided to add Yodl-interpreted text to  your own LaTeX layout
commands. The command is terminated with an end-of-line.
See also the macro \texttt{latexlayoutcmds()}


    \subsection{latexcommand(cmd)}

Writes \texttt{cmd} plus a white space to the output when converting to LaTeX. The
\texttt{cmd} is not further expanded by Yodl.


    \subsection{latexdocumentclass(class)}

Forces the LaTeX
\texttt{\textbackslash{}documentclass\{...\}} setting to \texttt{class}. Normally the class is
defined by the macros \texttt{article}, \texttt{report} or \texttt{book}.  This macro
is an escape route in case you need to specify your own document class
for LaTeX. This option is a \emph{modifier} and must
appear \emph{before} the \texttt{article}, \texttt{report} or \texttt{book} macros.


    \subsection{latexlayoutcmds(NOTRANSs)}

This macro is provided in case you want to put your own LaTeX layout commands
into LaTeX output. The \texttt{NOTRANSs} are pasted right after the
\texttt{\textbackslash{}documentclass} stanza. The default is, of course, no local LaTeX
commands. Note that this macro \textbf{does not} overrule my favorite LaTeX
layout. Use \texttt{nosloppyhfuzz()} and \texttt{standardlayout()} to disable my favorite
LaTeX layout.


    \subsection{latexoptions(options)}

Set latex options: \texttt{documentclass{[}options{]}}.  
This command \textbf{must} appear before the document type is
stated by \texttt{article}, \texttt{report}, etc..


    \subsection{latexpackage(options)(name)}

Include latex package(s), a useful package is, e.g.,
\texttt{epsf}. This command \textbf{must} appear before the document type is
stated by \texttt{article}, \texttt{report}, etc..


    \subsection{lchapter(label)(title)}

Starts a new chapter in books or reports, setting a label at the beginning
of the chapter.


    \subsection{letter(language)(date)(subject)(opening)(salutation)(author)}

Starts a letter written in the indicated language. The date of the letter is
set to `date', the subject of the letter will be `subject'. The letter starts
with `opening'. It is based on the `letter.cls' document class definition.
The macro is available for \LaTeX{} only. Preamble command suggestions:
    \begin{itemize}
    \item  \texttt{latexoptions(11pt)}
    \item  \texttt{PageEnlarged(2cm)(4cm)(2cm)(4cm)}
    \item  \texttt{letterreplyto(name)(address)(postalcode/city)}
    \item  \texttt{letterfootitem(phone)(number)}, maybe e-mail too.
    \item  \texttt{letteradmin(yourdate)(yourref)}
    \item  \texttt{letterto(addressitem)}. Use a separate \texttt{letterto()} macro call
            for each new line of the address.
    \end{itemize}


    \subsection{letteraddenda(type)(value)}

Adds an addendum at the end of a letter. `type' should be `bijlagen',
`cc' or `ps'.


    \subsection{letteradmin(yourdate)(yourref)}

Puts `yourletterfrom' and `yourreference' elements in the letter. If left
empty, two dashes are inserted.


    \subsection{letterfootitem(name)(value)}

Puts a footer at the bottom of letter-pages. Up to three will usually fit.
\LaTeX{} only.


    \subsection{letterreplyto(name)(address)(zip city)}

Defines the `reply to' address in \LaTeX{} or txt-letters.


    \subsection{letterto(element)}

Adds `element' as an additional line to the address in \LaTeX{} letters.


    \subsection{link(description)(labelname)}

In HTML output a clickable link with the text \texttt{description} is created
that points to the place where \texttt{labelname} is defined using the \texttt{label}
macro, and \texttt{attrib} macro applies to the \texttt{$<$a$>$} tag.  Using
\texttt{link} is similar to \texttt{url}, except that a hyperlink is set pointing to a
location in the same document. For output formats other than HTML, only the
\texttt{description} appears.


    \subsection{lref(description)(labelname)}

This macro is a combination of the \texttt{ref} and \texttt{link} macros. In HTML
output a clickable link with the text \texttt{description} and the label value is
created that points to the place where \texttt{labelname} is defined using the
\texttt{label} macro, and \texttt{attrib} macro applies to the \texttt{$<$a$>$}
tag. For output formats other than HTML, only the \texttt{description} and the
label value appears.


    \subsection{lsect(label)(title)}

Starts a new section, setting a label at the beginning of the section.
 In html \texttt{attrib} macro applies to the \texttt{$<$h2$>$} tag.


    \subsection{lsubsect(label)(title)}

Starts a new subsection. Other sectioning commands are
\texttt{subsubsect} and \texttt{subsubsubsect}. A label is added just before the
subsection.
 In html \texttt{attrib} macro applies to the \texttt{$<$h3$>$} tag.


    \subsection{lsubsubsect(label)(title)}

Starts a sub-subsection, a label is added just before the section
 In html \texttt{attrib} macro applies to the \texttt{$<$h4$>$} tag.


    \subsection{lsubsubsubsect(label)(title)}

Starts a sub-sub-sub section. This level of sectioning is not numbered, in
contrast to `higher' sectionings. A label is added just before the
subsubsubection.


    \subsection{lurl(locator)}

An url described by its Locator.  For small urls with readable addresses.


    \subsection{mailto(address)}

Defines the default \texttt{mailto} address for HTML output. Must appear
\textbf{before} the document type is stated by \texttt{article}, \texttt{report}, etc..


    \subsection{makeindex()}

Make index for latex.


    \subsection{mancommand(cmd)}

Writes \texttt{cmd} to the output when converting to man. The \texttt{cmd} is not
further expanded by Yodl.


    \subsection{manpage(title)(section)(date)(source)(manual)}

Starts a manual page document. The \texttt{section} argument must be a number,
stating to which section the manpage belongs to. Most often used are commands
(1), file formats (5) and macro packages (7). The sectioning commands in a
manpage are \textbf{not} \texttt{(n)sect} etc., but \texttt{manpage...()}. The first section
\textbf{must} be the \texttt{manpagename}, the last section \textbf{must} be the
\texttt{manpageauthor}. The standard manpage for section 1 contains the following
sections (in the given order): \texttt{manpagename}, \texttt{manpagesynopsis},
\texttt{manpagedescription}, \texttt{manpageoptions}, \texttt{manpagefiles},
\texttt{manpageseealso}, \texttt{manpagediagnostics}, \texttt{manpagebugs},
\texttt{manpageauthor}. Optional extra sections can be added with
\texttt{manpagesection}. Standard manpageframes for several manpagesections
are provided in \texttt{/usr/local/share/yodl/manframes}. \texttt{Yodl} manual pages can be
converted to \texttt{groff, html}, or plain ascii text formats.


    \subsection{manpageauthor()}

Starts the AUTHOR entry in a \texttt{manpage} document. Must be the last section
of a \texttt{manpage}.


    \subsection{manpagebugs()}

Starts the BUGS entry in a \texttt{manpage} document.


    \subsection{manpagedescription()}

Starts the DESCRIPTION entry in a \texttt{manpage} document.


    \subsection{manpagediagnostics()}

Starts the DIAGNOSTICS entry in a \texttt{manpage} document.


    \subsection{manpagefiles()}

Starts the FILES entry in a \texttt{manpage} document.


    \subsection{manpagename(name)(short description)}

Starts the NAME entry in a \texttt{manpage} document. The short description is
used by, e.g., the \texttt{whatis} database.


    \subsection{manpageoptions()}

Starts the OPTIONS entry in a \texttt{manpage} document.


    \subsection{manpagesection(SECTIONNAME)}

Inserts a non-required section named \texttt{SECTIONNAME} in a \texttt{manpage}
document. This macro can be used to augment `standard' manual pages with extra
sections, e.g., EXAMPLES. \textbf{Note that} the name of the extra section should
appear in upper case, which is consistent with the normal typesetting of
manual pages.


    \subsection{manpageseealso()}

Starts the SEE ALSO entry in a \texttt{manpage} document.


    \subsection{manpagesynopsis()}

Starts the SYNOPSIS entry in a \texttt{manpage} document.


    \subsection{manttquoted(onOff)}

With man-conversions arguments of tt macros are displayed as normal text. To
enhance their visibility arguments of tt macros may be quoted, in which case
they are surrounded by backtics and normal quotes. By default arguments of tt
macros are not quoted. Quotation is used after calling \texttt{manttquoted(1)}, and
is suppressed after calling \texttt{manttquoted(0)}. The macro is only active when
converting to man.


    \subsection{mbox()}

Unbreakable box in \LaTeX{}. Other formats may have different opitions on
our unbreakable boxex.


    \subsection{metaC(text)}

Put a line comment in the output.


    \subsection{metaCOMMENT(text)}

Write format-specific comment to the output.


    \subsection{mscommand(cmd)}

Writes \texttt{cmd} to the output when converting to ms. The \texttt{cmd} is not
further expanded by Yodl.


    \subsection{nbsp(count)}

Inserts \texttt{count} `non-breaking space' characters into the generated output;
i.e., the space character is not optimized away. If the argument list is empty
one non-breaking space is inserted.


    \subsection{nchapter(title)}

Starts a chapter (in a \texttt{book} or \texttt{report}) without generating a
number before the title and without placing an entry for the chapter in
the table of contents. 
 In html \texttt{attrib} macro applies to the \texttt{$<$h1$>$} tag.


    \subsection{nemail(name)(address)}

Named email.
A more consistent naming for url, lurl, email and nemail would be
nice.


    \subsection{nl()}

Forces a newline; i.e., breaks the current line in two.


    \subsection{nodeprefix(text)}

Prepend text to node names, e.g. \begin{verbatim}
nodeprefix(LilyPond) sect(Overview)
\end{verbatim}

Currently used in texinfo descriptions only.


    \subsection{nodeprefix(text)}

Prepend text to node names, e.g. \begin{verbatim}
nodeprefix(LilyPond) sect(Overview)
\end{verbatim}

Currently used in texinfo descriptions only.


    \subsection{nodetext(text)}

Use text as description for the next node, e.g. \begin{verbatim}
nodetext(The GNU Music Typesetter)chapter(LilyPond)
\end{verbatim}

Currently used in texinfo descriptions only.


    \subsection{nohtmlfive()}

Starting yodl 3.05 html-conversions by default use html5. This can be
suppressed (in favor of using html4) by calling this macro. This macro merely
suppresses writing the initial \texttt{$<$!DOCTYPE html$>$} to generated html
files; it is only active in the preamble and is only interpreted for
html conversions.


    \subsection{nohtmlimgstyle()}

By default html-pages specify\ \\ 
    \texttt{($<$style type="text/css" img \{vertical-align: bottom;\}$>$$<$/style$>$)}\ \\ 
 This macro suppresses this \texttt{img} CSS style specification. This macro is
only active in the preamble and is only interpreted for html conversions.


    \subsection{nop(text)}

Expand to text, to avoid spaces before macros e.g.: a$^{2}$. Although
a+sups(2) should have the same effect.


    \subsection{nosloppyhfuzz()}

By default, LaTeX output contains commands that cause it to shut up about
hboxes that are less than 4pt overfull. When \texttt{nosloppyhfuzz()} appears
before stating the document type, LaTeX complaints are `vanilla'.


    \subsection{notableofcontents()}

Prevents the generation of a table of contents. This is default in, e.g.,
\texttt{manpage} and \texttt{plainhtml} documents. When present, this option \textbf{must}
appear before stating the document type with \texttt{article}, \texttt{report}
etc..


    \subsection{notitleclearpage()}

Prevents the generation of a \texttt{clearpage()} instruction after the typesetting
of title information. This instruction is default in all non \texttt{article}
documents. When present, must appear \textbf{before} stating the document type with
\texttt{article}, \texttt{book} or \texttt{report}.


    \subsection{notocclearpage()}

With the \LaTeX{} converter, no \texttt{clearpage()} instruction is inserted
immediately beyond the document's table of contents. The \texttt{clearpage()}
instruction is default in all but the \texttt{article} document type. When present,
must appear \textbf{before} stating the document type with \texttt{article}, \texttt{book} or
\texttt{report}. With other converters than the \LaTeX{} converter, it is ignored.


    \subsection{notransinclude(filename)}

Reads filename and inserts it literally in the text
not subject to macro expansion or character translation.
No information is written either before or after the file's contents, not even
a newline.


    \subsection{noxlatin()}

When used in the preamble, the LaTeX converter disables the inclusion of the
file \texttt{xlatin1.tex}. Normally this file gets included in the LateX output
files to ensure the conversion of high ASCII characters (like \'{e}) to
LaTeX-understandable codes. (The file \texttt{xlatin1.tex} comes with the \texttt{Yodl}
distribution.)


    \subsection{nparagraph(title)}

Starts a non-numbered paragraph (duh, corresponds to subparagraph in latex).


    \subsection{npart(title)}

Starts a part in a \texttt{book} document, but without numbering it and without
entering the title of the part in the table of contents.
 In html \texttt{attrib} macro applies to the \texttt{$<$h1$>$} tag.


    \subsection{nsect(title)}

Starts a section, but does not generate a number before the \texttt{title} nor
an entry in the table of contents. Further sectioning commands are
\texttt{nsubsect}, \texttt{nsubsubsect} and \texttt{nsubsubsubsect}.
 In html \texttt{attrib} macro applies to the \texttt{$<$h2$>$} tag.


    \subsection{nsubsect(title)}

Starts a non-numbered subsection.  In html the \texttt{attrib} macro applies to
the \texttt{$<$h3$>$} tag.


    \subsection{nsubsubsect(title)}

Starts a non-numbered sub-sub section. 
  In html \texttt{attrib} macro applies to the \texttt{$<$p$>$} tag.


    \subsection{nsubsubsect(title)}

Starts a non-numbered sub-subsection.


    \subsection{PageEnlarged(up)(height)(left)(width)}

Enlarges the usable width and height of printed pages: the first line printed
on paper is moved up by \texttt{up} units, the usable paper height is enlarged by
\texttt{height} units, the left margin is moved to the left by \texttt{left} units, and
the usable paper width is enlarged by \texttt{width} units.  E.g., A4 pages are by
default using relatively small text blocks. Instead the pages can be used more
efficiently by specifying \texttt{PageEnlarged(2cm)(4cm)(2cm)(4cm)}.\ \\ 
This macro should be called in the preamble. The macro is available only
for \LaTeX{} conversions.


    \subsection{paragraph(title)}

Starts a paragraph. This level of sectioning is not numbered, in
contrast to `higher' sectionings (duh, corresponds to subparagraph in latex).
  In html \texttt{attrib} macro applies to the \texttt{$<$p$>$} tag.


    \subsection{part(title)}

Starts a new part in a \texttt{book} document.
 In html \texttt{attrib} macro applies to the \texttt{$<$h1$>$} tag.


    \subsection{pindex()}

Generate an index entry for LaTex() or texinfo 
p-indices. Its argument is the
index entry.  See also the \texttt{{[}cftv{]}index} macro.


    \subsection{plainhtml(title)}

Starts a document for only a plain HTML conversion. Not available in
other output formats. Similar to \texttt{article}, except that an author- and
date field are not needed.


    \subsection{printindex()}

Make index for texinfo (?).


    \subsection{quote(text)}

Sets the text as a quotation. Usually, the text is indented, depending on
the output format. In html the \texttt{attrib} macro is recognized by the
\texttt{$<$blockquote$>$} tag.


    \subsection{rangle()}

Inserts the right angle character (>).


    \subsection{redef(macro)(nrofargs)(redefinition)}

Defines macro \texttt{macro} to expand to \texttt{redefinition}.
Similar to \texttt{def}, but any pre-existing definition is overruled. Use
\texttt{ARG}\emph{x} in the redefinition part to indicate where the arguments should
be pasted. E.g., \texttt{ARG1} places the first argument, \texttt{ARG2} the second
argument, etc...


    \subsection{redefinemacro(macro)(nrofargs)(redefinition)}

Defines macro \texttt{macro} to expand to \texttt{redefinition}.
Similar to \texttt{def}, but any pre-existing definition is overruled. Use
\texttt{ARG}\emph{x} in the redefinition part to indicate where the arguments should
be pasted. E.g., \texttt{ARG1} places the first argument, \texttt{ARG2} the second
argument, etc... This commands is actually calling redef().


    \subsection{ref(labelname)}

Sets the reference for \texttt{labelname}. Use \texttt{label} to define a label.


    \subsection{report(title)(author)(date)}

Starts a report type document. The top-level sectioning command in a report
is \texttt{chapter}. In html the way the headings are displayed can be tuned using
CSS id selector specifications: the title has \texttt{id="title"}, the author
\texttt{id="author"}, and the date \texttt{id="date"}.


    \subsection{roffcmd(dotcmd)(sameline)(secondline)(thirdline)}

Sets a t/nroff command that starts with a dot, on its own line. The
arguments are: \texttt{dotcmd} - the command itself, e.g., \texttt{.IP}; \texttt{sameline} -
when not empty, \texttt{sameline} is set on the same line, following the
\texttt{dotcmd}; \texttt{secondline} - when not empty, is set on the next line;
\texttt{thirdline} - when not empty, is set on the third line. Note: \texttt{dotcmd} and
\texttt{thirdline} are not further expanded by \texttt{Yodl}, the other arguments are.


    \subsection{row(contents)}

The argument \texttt{contents} may contain a man-page alignment specification
(only one specification can be entered per row), using \texttt{setmanalign()}. If
omitted, the standard alignment is used. Furthermore it contains the contents
of the elements of the row, using \texttt{cell()} or \texttt{cells()} macros. If
\texttt{cells()} is used, \texttt{setmanalign()} should have been used too. In this
macro call only the \texttt{cell()}, \texttt{cells()} and \texttt{setmanalign()} macros
should be called. Any other macro call may produce unexpected results.

The \texttt{row} macro defines a counter \texttt{XXcol} that can be inspected and is
incremented by predefined macros adding columns to a row. The counter is
initially 0. Predefined macros adding columns to a row add the number of
columns they add to the row inserting the contents of those columns.  These
macros rely on the correct value of this counter and any user-defined macros
adding columns to table rows should correctly update \texttt{XXcol}.
 In html \texttt{attrib} macro applies to the \texttt{$<$tr$>$} tag.

Instead of using \texttt{row} in \texttt{table}, consider using \texttt{tr} in \texttt{tbl}.


    \subsection{rowline()}

Sets a horizontal line over the full width of the table. See also
the \texttt{columnline} macro. Use \texttt{rowline} instead of a \texttt{row} macro call to
provide a table with a horizontal line-separator.

Instead of using \texttt{rowline} consider using \texttt{tline} in a \texttt{tbl} argument.


    \subsection{sc(text)}

Set \texttt{text} in the tt (code) font, using small caps.
 In html the \texttt{attrib} macro is not supported, while the code
section is embedded in a \texttt{$<$div style="font-size: 90\%"$>$} section.


    \subsection{sect(title)}

Starts a new section. In html the \texttt{attrib} macro is recognized by the
\texttt{$<$h2$>$} tag.


    \subsection{setaffilstring(name)}

Defines \texttt{name} as the `affiliation information' string, by default
\emph{AFFILIATION INFORMATION}. E.g., after \texttt{setaffilstring(AFILIACION)},
\texttt{Yodl} outputs this Spanish string to describe the affiliation information.
Currently, it is relevant only for txt.


    \subsection{setauthorstring(name)}

Defines \texttt{name} as the `Author information' string, by default
\emph{AUTHOR INFORMATION}. E.g., after \texttt{setauthorstring(AUTOR)},
\texttt{Yodl} outputs this portuguese string to describe the author information.
Currently, it is relevant only for txt.


    \subsection{setchapterstring(name)}

Defines \texttt{name} as the `chapter' string, by default \emph{Chapter}. E.g., after
\texttt{setchapterstring(Hoofdstuk)}, \texttt{Yodl} gains some measure of national language
support for Dutch. Note that LaTeX support has its own NLS, this macro doesn't
affect the way LaTeX output looks.


    \subsection{setdatestring(name)}

Defines \texttt{name} as the `date information' string, by default
\emph{DATE INFORMATION}. E.g., after \texttt{setdatestring(DATA)},
\texttt{Yodl} outputs this portuguese string to describe the date information.
Currently, it is relevant only for txt.


    \subsection{setfigureext(name)}

Defines the \texttt{name} as the `figure' extension. The extension should include
the period, if used. E.g., use setfigureext(.ps) if the extensions
of the figure-images should end in \texttt{.ps}


    \subsection{setfigurestring(name)}

Defines the \texttt{name} as the `figure' text, used e.g. in figure captions. E.g.,
after \texttt{setfigurestring(Figuur)}, Yodl uses Dutch names for figures.


    \subsection{sethtmlfigureext(ext)}

Defines the filename extension for HTML figures, defaults to \texttt{.jpg}. Note
that a leading dot must be included in \texttt{ext}. The new extension takes effect
starting with the following usage of the \texttt{figure} macro.  It is only active
in html, but otherwise acts identically as setfigureext().

See also the \texttt{setlatexfigureext} macro.


    \subsection{htmlmetacharset(meta-charset)}

Adds \texttt{$<$meta charset="meta-charset"$>$} to the head of html documents. By
default \texttt{$<$meta charset="UTF-8"$>$} is used. This macro is only active in the
preamble and is only interpreted for html conversions.


    \subsection{setincludepath(name)}

Sets a new value of the include-path specification used when opening .yo
files. A warning is issued when the path specification does not include a .:
element. Note that the local directory may still be an element of the new
include path, as the local directory may be the only or the last element of
the specification. For these eventualities the new path specification is not
checked.


    \subsection{setlanguage(name)}

Installs the headers specific to a language. The argument must be the name of
a language, whose headers have been set by a corresponding
languageXXX() call. For example: languagedutch(). The
language macros should set the names of the headers of the following elements:
table of contents, affiliation, author, chapter, date, figure, part and title


    \subsection{setlatexalign(alignment)}

This macro defines the table alignment used when setting tables in \LaTeX{}.
Use as many \texttt{l} (for left-alignment), \texttt{r} (for right alignment), and \texttt{c}
(for centered-alignment) characters as there are columns in the table. See
also \texttt{table()}.

Instead of using the \texttt{table} macro consider using the \texttt{tbl} macro.


    \subsection{setlatexfigureext(ext)}

Defines the filename extension for encapsulated PostScript figures in LaTeX,
defaults to \texttt{.ps}. The dot must be included in t new extension \texttt{ext}. The
new extension takes effect starting with a following usage of the \texttt{figure}
macro. It is only active in \LaTeX{}, but otherwise acts identically as
setfigureext().

See also the \texttt{sethtmlfigureext} macro.


    \subsection{setlatexverbchar(char)}

Set the char used to quote \LaTeX{} \texttt{\textbackslash{}verb} sequences


    \subsection{setmanalign(alignment)}

This macro defines the table alignment in the context of the \texttt{table}
macro, and is used when setting tables in man-pages (see \textbf{tbl}(1)).

Use as many \texttt{l} (for left-alignment), \texttt{r} (for right alignment), and \texttt{c}
(for centered-alignment) characters as there are columns in the
table. 

Use \texttt{s} to indicate that the column to its left is combined (spans into) the
current column. Use this specification when cells spanning multiple columns
must be defined. 

Each row in a table which must be convertible to a manpage may be preceded by
its own \texttt{setmanalign} call.  

Note that neither \texttt{rowline} nor \texttt{columnline} requires \texttt{setmanalign}
specifications, as these macros define rows by themselves. It is the
responsibility of the author to ensure that the number of alignment characters
is equal to the number of columns of the table.

Instead of using the \texttt{table} macro consider using the \texttt{tbl} macro.


    \subsection{setpartstring(name)}

Defines \texttt{name} as the `part' string, by default \emph{Part}. E.g., after
\texttt{setpartstring(Teil)}, Yodl identifies parts in the German way. Note that
LaTeX output does its own national language support; this macro doesn't affect
the way LaTeX output looks.


    \subsection{setrofftab(x)}

Sets the character separating items in a line of input data of a \texttt{roff}
(manpage) table. By default it is set to \texttt{\textasciitilde{}}. This separator is used
internally, and needs only be changed (into some unique character) if the
table elements themselves contain \texttt{\textasciitilde{}} characters.

This macro can be used in the context of the \texttt{table} and \texttt{tbl} macros.


    \subsection{setrofftableoptions(optionlist)}

Set options used for man-conversion, as used by the \texttt{tbl} and \texttt{table}
macros. By default no options are used. Multiple options should be separated
by blanks. From the \textbf{tbl}(1) manpage, the following options are available:
    \begin{itemize}
    \item  \texttt{center} Centers the table; default is left-justified. In the
        context of the \texttt{tbl} macro this is implied when the \texttt{tbl} macro is
        specified as argument of the \texttt{center} macro.
    \item  \texttt{expand} Makes the table as wide as the current line length
    \item  \texttt{box} Encloses the table in a box
    \item  \texttt{allbox} Encloses each item of the table in a box
    \end{itemize}

See also \texttt{setrofftab} which is used to set the character separating
    items in a line of input data. 


    \subsection{settitlestring(name)}

Defines \texttt{name} as the `title information' string, by default
\emph{TITLE INFORMATION}. E.g., after \texttt{settitlestring(TITEL)},
\texttt{Yodl} outputs this Dutch string to describe the title information.
Currently, it is relevant only for txt.


    \subsection{settocstring(name)}

Defines \texttt{name} as the `table of contents' string, by default \emph{Table of
Contents}. E.g., after \texttt{settocstring(Inhalt)}, \texttt{Yodl} identifies the table
of contents in the German way. Note that LaTeX output does its own national
language support; this macro doesn't affect the way LaTeX output looks.


    \subsection{sgmlcommand(cmd)}

Writes \texttt{cmd} to the output when converting to sgml. The \texttt{cmd} is not
further expanded by Yodl.


    \subsection{sgmltag(tag)(onoff)}

Similar to \texttt{htmltag}, but used in the SGML converter.


    \subsection{sloppyhfuzz(points)}

By default, LaTeX output contains commands that cause it to shut up about
hboxes that are less than 4pt overfull. When \texttt{sloppyhfuzz()} appears
before stating the document type, LaTeX complaints occur only if hboxes are
overfull by more than \texttt{points}.


    \subsection{standardlayout()}

Enables the default LaTeX layout. When this macro is absent, then the
first lines of paragraphs are not indented and the space between
paragraphs is somewhat larger. The \texttt{standardlayout()} directive must appear
\textbf{before} stating the document type as \texttt{article}, \texttt{report}, etc..


    \subsection{strong(contents)}

In html and xml the \texttt{contents} are set between \texttt{$<$strong$>$} and
\texttt{$<$/strong$>$} tags. 
 In html \texttt{attrib} macro applies to the \texttt{$<$strong$>$} tag.


    \subsection{subs(text)}

Sets text in subscript in supporting formats.  
 In html the \texttt{attrib} macro is recognized by the \texttt{$<$sub$>$} tag.

For \emph{super}scripting, the \texttt{sups} macro can be used.


    \subsection{subsect(title)}

Starts a new subsection. Other sectioning commands are
\texttt{subsubsect} and \texttt{subsubsubsect}.
 In html \texttt{attrib} macro applies to the \texttt{$<$h3$>$} tag.


    \subsection{subsubsect(title)}

Starts a sub-subsection.
 In html \texttt{attrib} macro applies to the \texttt{$<$h4$>$} tag.


    \subsection{subsubsubsect(title)}

Starts a sub-sub-sub-subsection. This level of sectioning is not numbered, in
contrast to `higher' sectionings.


    \subsection{sups(text)}

Sets text in superscript in supporting formats
 In html the \texttt{attrib} macro is recognized by the \texttt{$<$sup$>$} tag.

For \emph{sub}scripting, the \texttt{subs} macro can be used.


    \subsection{table(nColumns)(alignment)(Contents)}

Instead of using the \texttt{table} macro, consider using the \texttt{tbl} macro.

The \texttt{table()}-macro defines a table. Its first argument specifies the number
of columns in the table.

Its second argument specifies the (standard) alignment of the information
within the cells as used by \LaTeX{} or man/ms. Use \texttt{l} for left-alignment,
\texttt{c} for centered-alignment and \texttt{r} for right alignment.

Its third argument defines the contents of the table which are the rows, each
containing column-specifications and optionally man/ms alignment definitions
for this row.

See also the \texttt{tableatt} macro and the specialized \texttt{setmanalign()} macro.


    \subsection{tableatt(nColumns)(alignment)(Contents)}

Instead of using the \texttt{tableatt} macro, consider using the \texttt{tbl} macro.

The \texttt{tableatt()}-macro defines a table. The last \texttt{attrib} call that was
specified before using the \texttt{tableatt()}-macro is used to specify html
attributes for the table. E.g., to center a table in html use
        \begin{verbatim}

    attrib(style="margin-left:auto;margin-right:auto;")
    tableatt(...)
        
\end{verbatim}

    The macro's first argument specifies the number of columns in the table.
Its second argument specifies the (standard) alignment of the information
within the cells as used by \LaTeX{} or man/ms. Use \texttt{l} for left-alignment,
\texttt{c} for centered-alignment and \texttt{r} for right alignment. Its third argument
defines the contents of the table which are the rows, each containing
column-specifications and optionally man/ms alignment definitions for this
row.

See also the \texttt{table} macro and the specialized \texttt{setmanalign()} macro.


    \subsection{tac(alignment)(contents)}

This macro is one of the four macros that can be used to define column
contents of rows of tables defined by the \texttt{tbl} macro. Alternatively, \texttt{tc,
tnc}, and \texttt{tnac} can be used.

The \texttt{tac} macro is used as argument of the \texttt{tr} macro. The cell's
alignment is defined by the \texttt{alignment} specification, containing at most
two alignment specifications: a horizontal alignment (one of c, l, r
(centered, left-aligned, right-aligned)) and a vertical alignment (one of t, b
(vertical top- and bottom-alignment)) (not all conversion types may support
all alignment types, e.g., man-conversion does not support vertical bottom
alignment). Specifications other than c, l, r, b, and t and specifications
beyond the second one are ignored. The result of specifying conflicting
alignment types (e.g., \texttt{lr} or \texttt{tb}) is not defined.

When converting to \texttt{man}, if the table's contents should span multiple rows,
then a \textbf{groff/troff}(1) \emph{text block} must be used. Since most tables do
not use this, a text block is not generated by default. To actually wrap the
contents of column elements in a text block while converting to \texttt{man} prefix
the first text block requiring a text-block wrapping by \texttt{twrap(1)}, and end
the last text block requiring a text-block wrapping by \texttt{wrap(0)}.

The \texttt{tao} macro can be used to overrule the specified alignment for a
specific conversion type.

The macro \texttt{tac} recognizes \texttt{attrib}.


    \subsection{tao(type)(specification)}

This macro is used inside the \texttt{tbl} macro to override the alignment
specification that would otherwise be used for the next table element. It is
only active for the next \texttt{tc, tnc, tac,} or \texttt{tnac} call. Its first
argument defines the conversion type for which the override should be used,
its second argument defines the alignment specification to use.

Here are some examples:
        \begin{verbatim}

tbl(lr)(
    tr(
        tc(left aligned)
        tc(right aligned)
    )
    tr(
        tao(html)(c)
          tc(left aligned, centered with html)
        tao(latex)(l)
        tao(man)(l)
          tac(c)(centered, latex and man: left aligned)
    )
)
        
\end{verbatim}


Further details about the \texttt{tao} macro are provided in the \textbf{yodltables}(7)
man-page.


    \subsection{tbl(align)(contents)}

The \texttt{tbl} macro refines the more basic \texttt{table} macro. It was named after
the \textbf{tbl}(1) table formatting program used with \textbf{troff}(1) documents.

The \texttt{tbl} macro currently is available for \texttt{html, man/ms, latex} and
\texttt{txt} conversions.

Its first argument defines the alignment of the information in the table's
columns, and is used by all conversions except \texttt{txt}. Use \texttt{l} for
left-alignment, \texttt{c} for centered-alignment and \texttt{r} for
right-alignment. Individual cells of the table may override these default
settings using the macros \texttt{tac} and \texttt{tnac}.

Its second argument defines the contents of the table consisting of rows
(using \texttt{tr}), and horizontal lines (using \texttt{tline}), which may extend over
the full table width or may cover one or more individual columns. With \texttt{txt}
conversion rough approximations of horizontal lines are used.

Tables defined by the \texttt{tbl} macro are centered (pseudo centering (8 space
characters) is used for \texttt{txt} conversion) when used as argument of the
\texttt{center} macro.

See also the \texttt{tao} macro for information about how to realize specific
alignments for specific conversion types.

When defining \texttt{tbl} tables it is advised to clearly layout the table
specification. To avoid inadvertently introducing new lines lines should end
in a backslash (or 
The macro \texttt{tbl} recognizes \texttt{attrib}. 


    \subsection{tc(contents)}

This macro is one of the four macros that can be used to define column
contents of rows of tables defined by the \texttt{tbl} macro. Alternatively,
\texttt{tnc, tac}, and \texttt{tnac} can be used.

The \texttt{tc} macro is used as argument of the \texttt{tr} macro. Its order within a
row defines its type attribute, using the alignment specification defined by
the first argument of the \texttt{tbl} call. E.g., if \texttt{tbl(clr)(...)} was used,
then the contents of the first \texttt{tc} call in a \texttt{tr} is centered in the
table's first column; the contents of the second \texttt{tc} call is left-aligned
in the table's second column; and the contents of the third \texttt{tc} call is
right-aligned in the table's third column.

When converting to \texttt{man}, if the table's contents should span multiple rows,
then a \textbf{groff/troff}(1) \emph{text block} must be used. Since most tables do
not use this, a text block is not generated by default. To actually wrap the
contents of column elements in a text block while converting to \texttt{man} prefix
the first text block requiring a text-block wrapping by \texttt{twrap(1)}, and end
the last text block requiring a text-block wrapping by \texttt{wrap(0)}.

The \texttt{tao} macro can be used to overrule the default alignment specification 
for a specific conversion type.

The macro \texttt{tc} recognizes \texttt{attrib}. 


    \subsection{tcell(text)}

Roff helper to set a table text-cell, i.e., a paragraph.  For \LaTeX{}
special table formatting p\{\} should be used.

When using the \texttt{tbl} macro for defining tables the \texttt{twrap} macro can be
used to set table elements in text-blocks (i.e., enclosing text, possibly
containing newlines in \texttt{T\{} and \texttt{T\}} sequences).


    \subsection{telycommand(cmd)}

Writes \texttt{cmd} to the output when converting to tely. The \texttt{cmd} is not
further expanded by Yodl.


    \subsection{TeX()}

The TeX symbol.


    \subsection{texinfocommand(cmd)}

Writes \texttt{cmd} to the output when converting to texinfo. The \texttt{cmd} is not
further expanded by Yodl.


    \subsection{tindex()}

Generate an index entry for LaTex() or texinfo 
t-indices. Its argument is the
index entry.  See also the \texttt{{[}cfpv{]}index} macro.


    \subsection{titleclearpage()}

Forces a new page (using \texttt{clearpage}) following the title of a
document. This is already the default in books and reports, but can be
overruled using \texttt{notitleclearpage}. When present, it must appear in the
\emph{preamble}, i.e., before the document type is stated as article, book or
report.


    \subsection{tline(beginNr)(endNr)}

This macro is used to insert a horizontal line spanning one or more columns
of a table defined by the \texttt{tbl} macro.

If \texttt{endNr} is not specified, and the \texttt{tline} call does not follow a
previous \texttt{line} call in which \texttt{endNr} \emph{was} specified, then a horizontal
line spanning the full width of the table is defined (except when converting
to plain text in which case a line of \texttt{beginNr} - (minus) characters is
written; if \texttt{beginNr} is not specified then a line of 60 - characters is
written).

If \texttt{endNr} is not specified, but the \texttt{tline} call follows previous \texttt{tline}
calls that did specify \texttt{endNr} then the current row is ended. 

If \texttt{endNr} is specified, then a horizontal line is set, starting at column
number \texttt{beginNr} continuing through column number \texttt{endNr}. Note that these
are \emph{numbers}, not \emph{offsets}: \texttt{beginNr} should be at least 1, \texttt{endNr}
must at least be equal to \texttt{beginNr} and should be at most equal to the
number of columns in the table. The \texttt{beginNr} values of subsequent \texttt{tline}
calls refer to the same row as the first \texttt{tline} call, and must exceed
\texttt{endNr} of the previous \texttt{tline} call.

Examples:
        \begin{verbatim}

    tline()()       sets a line spanning the full table width
    tline(1)(1)     sets a line in column 1
    tline(3)(4)     sets another line in column 3 and 4
    tline()()       ends the previous line
    tline()()       sets a line spanning the full table width
        
\end{verbatim}



    \subsection{tnac(nCells)(alignment)(contents)}

This macro is one of the four macros that can be used to define column
contents of rows of tables defined by the \texttt{tbl} macro. Alternatively, \texttt{tc,
tac}, and \texttt{tnc} can be used.

The \texttt{tnac} macro is used as argument of the \texttt{tr} macro. Its first argument
defines the number of columns spanned by the contents (2nd argument) 
of the \texttt{tnc} macro. 

The cell's alignment is defined by the macro's second (\texttt{alignment})
specification, containing at most two alignment specifications: a horizontal
alignment (one of c, l, r (centered, left-aligned, right-aligned)) and a
vertical alignment (one of t, b (vertical top- and bottom-alignment)) (not all
conversion types may support all alignment types). Specifications other than
c, l, r, b, and t and specifications beyond the second one are ignored. The
result of specifying conflicting alignment types (e.g., \texttt{lr} or \texttt{tb}) is
not defined.

When converting to \texttt{man}, if the table's contents should span multiple rows,
then a \textbf{groff/troff}(1) \emph{text block} must be used. Since most tables do
not use this, a text block is not generated by default. To actually wrap the
contents of column elements in a text block while converting to \texttt{man} prefix
the first text block requiring a text-block wrapping by \texttt{twrap(1)}, and end
the last text block requiring a text-block wrapping by \texttt{wrap(0)}.  Multiple
rows in a text block are top-aligned with left and righ neighboring cells.

The \texttt{tao} macro can be used to overrule the default alignment specification 
for a specific conversion type.

The macro \texttt{tnac} recognizes \texttt{attrib}.


    \subsection{tnc(nCells)(contents)}

This macro is one of the four macros that can be used to define the column
contents of rows of tables that are defined by the \texttt{tbl}
macro. Alternatively, \texttt{tc, tac}, and \texttt{tnac} can be used.

The \texttt{tnc} macro is used as argument to the \texttt{tr} macro. Its first argument
defines the number of columns spanned by the contents (2nd argument) 
of the \texttt{tnc} macro. The contents are centered in the \texttt{nCells} columns.

When converting to \texttt{man}, if the table's contents should span multiple rows,
then a \textbf{groff/troff}(1) \emph{text block} must be used. Since most tables do
not use this, a text block is not generated by default. To actually wrap the
contents of column elements in a text block while converting to \texttt{man} prefix
the first text block requiring a text-block wrapping by \texttt{twrap(1)}, and end
the last text block requiring a text-block wrapping by \texttt{wrap(0)}.  Multiple
rows in a text block are top-aligned with left and righ neighboring cells.

The \texttt{tao} macro can be used to overrule the default alignment specification 
for a specific conversion type.

The macro \texttt{tc} recognizes \texttt{attrib}. 


    \subsection{tocclearpage()}

With the \LaTeX{} converter, a \texttt{clearpage()} directive if inserted,
immediately following the document's table of contents. This is already the
default in all but the \texttt{article} document type, but it can be overruled by
\texttt{notocclearpage()}. When present, it must appear in the \emph{preamble}; i.e.,
before the document type is stated with \texttt{article}, \texttt{book} or
\texttt{report}. With other converters than the \LaTeX{} converter, it is ignored.


    \subsection{tr(contents)}

This macro defines the rows of a table that is defined by the \texttt{tbl} macro.

The macro \texttt{tr} expects one argument: the contents of the row, defining the
row's column elements. It is not used for defining a (partial) horizontal
line: to set horizontal lines in a table defined by the \texttt{tbl} macro use the
macro \texttt{tline}.

Normally the contents of the columns in a (\texttt{tr}) row is defined by 
of one or more calls to the macros \texttt{tc, tac, tnc,} and/or \texttt{tnac}.

The macro \texttt{tr} recognizes \texttt{attrib}.


    \subsection{tt(text)}

Sets \texttt{text} in teletype font, and prevents it from being expanded.
When converting to man, \texttt{text} is surrounded by a backtick and a single
quote character.

For unbalanced parameter lists, use \texttt{CHAR(40)} to get
\texttt{(} and \texttt{CHAR(41)} to get \texttt{)}.

The \texttt{tt} macro does interpret character tables as well as any \texttt{SUBST}
definitions. This is usually what is intended. In situations where this is
unwelcome the \texttt{ttbegin} and \texttt{ttend} pair of macros can be used, between
which the builtin commands \texttt{PUSHSUBST, POPSUBST, NOEXPAND} and/or
\texttt{NOTRANS} can be used. E.g., to clearly show two hyphens in \LaTeX{} 
teletype font use 
    \begin{verbatim}

    ttbegin()--ttend()
    
\end{verbatim}

rather than
    \begin{verbatim}

    tt(--)
    
\end{verbatim}

    Likewise, use \texttt{ttbegin} and \texttt{ttend} if the teletype text contains
accented letters like \"{e}. To set this in teletype font use 
\texttt{ttbegin()\textbackslash{}"}\texttt{e+ttend()}.

With html conversions the \texttt{attrib} macro applies to the \texttt{$<$code$>$} tag.

With man conversions the arguments of tt macros can be quoted. See the
\texttt{manttquoted} macro for details.


    \subsection{ttbegin()}

Initiates text set in teletype font. Following the text to set in
teletype font a \texttt{ttend()} macro should be called.

Usually the \texttt{tt} macro can be used instead of the \texttt{ttbegin} -{}-{}
\texttt{ttend} combination. However, \texttt{tt} interprets character tables as well as
\texttt{SUBST} definitions. In situations where this is unwelcome the \texttt{ttbegin}
and \texttt{ttend} pair of macros can be used, between which builtin commands like
\texttt{PUSHSUBST, POPSUBST, NOEXPAND} and/or \texttt{NOTRANS} can be used.

In html the \texttt{attrib} macro applies to the \texttt{$<$code$>$} tag.


    \subsection{ttend()}

Ends text set in teletype font following \texttt{ttbegin}. Refer to the
\texttt{ttbegin} macro's description for details.


    \subsection{twrap(value)}

Used for man/ms conversions only: when called with a non-zero argument
before using the \texttt{tc, tnc, tac}, and \texttt{tnac} macros then their contents are
wrapped in text blocks (\texttt{T\{ ... T\}} blocks). To end the wrapping
\texttt{twrap(0)} must be called. E.g., in the following row-definition the
contents of columns three and four are set in T-blocks when converting to
man/ms:
        \begin{verbatim}

    tr(tc(one)tc(two)twrap(1)tc(one)tc(two)twrap(0))
\end{verbatim}



    \subsection{txtcommand(cmd)}

Writes \texttt{cmd} to the output when converting to txt. The \texttt{cmd} is not
further expanded by Yodl.


    \subsection{url(description)(locator)}

In LaTeX documents the \texttt{description} is sent to the output. For HTML,
a link is created with the descriptive text \texttt{description} and pointing
to \texttt{locator}. The \texttt{locator} should be the full URL, including
service; e.g, \texttt{http://www.icce.rug.nl}, but excluding the double
quotes that are necessary in plain HTML. Use the macro \texttt{link} to create
links within the same document. For other formats, something like
\emph{description {[}locator{]}} will appear.
 In html \texttt{attrib} macro applies to the \texttt{$<$a$>$} tag.


    \subsection{verb(text)}

Sets \texttt{text} in verbatim mode: not subject to macro expansion or character
table expansion, and starting with Yodl version 4.00.00: not using \texttt{SUBST}
definitions. See also \texttt{verborg}, which does not provide the protection
against \texttt{SUBST} definitions.

While converting Yodl-documents to target document types Yodl frequently uses
the (not further documented) builtin function \texttt{XXSUBST}. In the
unlikely event that the text \texttt{XXSUBST(...)} must be written
in a document, the sequence
    \begin{verbatim}

    XXSUBST+CHAR(40)...CHAR(41)
    
\end{verbatim}

    can be used.

The text that is passed as argument to the \texttt{verb}-macro appears literally
on the output, usually in a teletype font (that depends on the output
format). This macro is for larger chunks, e.g., listings. 

When starting the \texttt{verb(} macro on a line by itself and writing the
closing parenthesis on a line by itself then those newlines also appear in the
resulting verbatim text. To omit those lines immediately start the first line
of text after \texttt{verb} and append the closing parenthesis to the last line of
verbatim text. E.g.,
    \begin{verbatim}
verb(    First line of indented literal text
    Last line of indented literal text)
\end{verbatim}


When unbalanced parameter lists are required, use \texttt{CHAR(40)} to get
\texttt{(} and \texttt{CHAR(41)} to get \texttt{)}.


    \subsection{verbinclude(filename)}

Reads filename and inserts it literally in the text, set in verbatim mode.
not subject to macro expansion. The text appears literally on the output,
usually in a teletype font (that depends on the output format). This macro is
an alternative to \texttt{verb(...)}, when the text to set in verbatim mode is
better kept in a separate file.


    \subsection{verbinsert(args)}

Passes \texttt{args} to \textbf{yodlverbinsert}(1), inserting its output into the
converted file. This macro can be used to insert, e.g., a line-numbered
indented file, or a labeled subsection of a file, into the file that's
currently being written by \texttt{yodl}. E.g,
    \begin{verbatim}

verbinsert(-ans4 file)       -- inserts file, showing line
                                numbers, using a 4 blank-space
                                character wide indentation.

verbinsert(-ns4 //SECT file) -- inserts the section of file, 
                                labeled //SECT file, showing 
                                line numbers, using a 4 
                                blank-space character wide 
                                indentation.
    
\end{verbatim}



    \subsection{verborg(text)}

Sets \texttt{text} in verbatim mode: not subject to macro expansion or character
table expansion, and starting with Yodl version 4.00.00: this macro replaces
the previously defined \texttt{verb} macro. The current \texttt{verb} macro surrounds
this macro by \texttt{PUSHSUBST} and \texttt{POPSUBST}.

The text that is passed as argument to the \texttt{verborg}-macro appears
literally on the output, albeit that \texttt{SUBST} definitions are processed,
usually in a teletype font (that depends on the
output format). This macro is for larger chunks, e.g., listings.

When unbalanced parameter lists are required, use \texttt{CHAR(40)} to get
\texttt{(} and \texttt{CHAR(41)} to get \texttt{)}.


    \subsection{verbpipe(command)(text)}

Pipe text through command, but don't expand the output.


    \subsection{vindex()}

Generate an index entry for LaTex() or texinfo v-indices. 
Its argument is the index entry. 
See also the \texttt{{[}cfkpt{]}index} macro.


    \subsection{whenhtml(text)}

Sends \texttt{text} to the output when in HTML conversion mode. The text is
further expanded if necessary.


    \subsection{whenlatex(text)}

Sends \texttt{text} to the output when in LATEX conversion mode. The text is
further expanded if necessary.


    \subsection{whenman(text)}

Sends \texttt{text} to the output when in MAN conversion mode. The text is
further expanded if necessary.


    \subsection{whenms(text)}

Sends \texttt{text} to the output when in MS conversion mode. The text is
further expanded if necessary.


    \subsection{whensgml(text)}

Sends \texttt{text} to the output when in SGML conversion mode. The text is
further expanded if necessary.


    \subsection{whentely(text)}

Sends \texttt{text} to the output when in TELY conversion mode. The text is
further expanded if necessary.


    \subsection{whentexinfo(text)}

Sends \texttt{text} to the output when in TEXINFO conversion mode. The text is
further expanded if necessary.


    \subsection{whentxt(text)}

Sends \texttt{text} to the output when in TXT conversion mode. The text is
further expanded if necessary.


    \subsection{whenxml(text)}

Sends \texttt{text} to the output when in XML conversion mode. The text is
further expanded if necessary.


    \subsection{xit(itemname)}

Starts an xml menu item where the file to
which the menu refers to is the argument of the xit() macro. It
should be used as argument to xmlmenu(), which has a 3rd argument:
the default path prefixed to the xit() elements. 

This macro is only available
within the xml-conversion mode. The argument must be a full filename,
including .xml extension, if applicable.

No .xml extension indicates a subdirectory, containing another sub-menu.


    \subsection{xmlcommand(cmd)}

Writes \texttt{cmd} to the output when converting to xml. The \texttt{cmd} is not
further expanded by Yodl.


    \subsection{xmlmenu(order)(title)(menulist)}

Starts an xmlmenu. Use itemization() to define the items. Only
available in xml conversion. The menutitle appears in the menu as the heading
of the menu.  The menulist is a series of xit() elements, containing
the name of the file to which the menu refers as their argument (including a
final /).  Prefixed to evert every xit()-element is the value of
XXdocumentbase.

Order is the the `order' of the menu. If omitted, no order is defined.


    \subsection{xmlnewfile()}

In XML output, starts a new file. All other formats are not affected. Note
that you must take your own provisions to access the new file; say via links.
Also, it's safe to start a new file just befoore opening a new section, since
sections are accessible from the clickable table of contents. The XML
converter normally only starts new files prior to a \texttt{chapter} definition.


    \subsection{xmlsetdocumentbase(name)}

Defines \texttt{name} as the XML document base. No default.
Only interpreted with xml conversions. It is used with the figure and xmlmenu
macros.


    \subsection{xmltag(tag)(onoff)}

Similar to \texttt{htmltag}, but used in the XML converter.

\section{Conversion-related topics}

\subsection{Conversion-type specific literal commands}\label{FORMATDEFINES}
        According to the format of the output file, the macro package defines a given 
symbol: 
    \begin{itemize}
    \item  \texttt{latex} when the output format is LaTeX,
    \item  \texttt{html} when the output format is HTML,
    \item  \texttt{man} when the output format is groff in conjunction with the
man macro package,
    \item  \texttt{ms} when the output format is groff with the ms package,
    \item  \texttt{sgml} when the output format is SGML,
    \item  \texttt{txt} when the output format is plain ASCII.
    \item  \texttt{xml} when the output format is XML.
    \end{itemize}
    The defined symbol can be tested in a document to determine the conversion
type.

Furthermore, the package defines the following macros to send literal text 
(commands in the output format) to the output file:
    \begin{itemize}
    \item  \texttt{latexcommand(cmd)}: sends the LaTeX command \texttt{cmd} when in LaTeX
conversion mode. The \texttt{cmd} is not further expanded.
    \item  \texttt{htmlcommand(cmd)}: sends the HTML command \texttt{cmd} when in HTML 
conversion mode.  The \texttt{cmd} is not further expanded.
    \item  \texttt{htmltag(tag)(onoff)}: sends \texttt{$<$tag$>$} to the output when \texttt{onoff}
is nonzero, or sends \texttt{$<$/tag$>$} when \texttt{onoff} is zero. Only active in
HTML conversions.
    \item  \texttt{mancommand(cmd)}: sends \texttt{cmd} to the output when in man 
conversion mode.  The \texttt{cmd} is not further expanded.
    \item  \texttt{mscommand(cmd)}: sends \texttt{cmd} to the output when in ms
conversion mode. The \texttt{cmd} is not further expanded.
    \item  \texttt{roffcmd(dotcmd)(trailer)(secondline)(thirdline)}: sends a command
to the output when in \texttt{man} or \texttt{ms} conversion mode. The \texttt{dotcmd} is the
typical \texttt{groff} command that starts with a dot. All other arguments may be
empty, but when given are interpreted as follows. The \texttt{trailer} follows the
\texttt{dotcmd} on the same line. The \texttt{secondline} is sent on a separate line
following the \texttt{dotcmd} and \texttt{trailer}. The \texttt{thirdline} is sent after
that. Of the four arguments, \texttt{dotcmd} and \texttt{thirdline} are \textbf{not} subject
to further expansion. All other arguments are further expanded if necessary.

The \texttt{roffcmd} macro illustrates the complexity of dot-commands for the 
divers \texttt{groff} macro packages. E.g., a section title for the \texttt{man} 
package should look as
        \begin{verbatim}

    .SH "Section Title"
        
\end{verbatim}

    while the same command for the \texttt{ms} macro package must be sent as
        \begin{verbatim}

    .SH
    Section Title
    .PP
        
\end{verbatim}

    The \texttt{roffcmd} macro can be used to send these commands to the output 
    file as follows:
        \begin{verbatim}

    COMMENT(For the man output format:)
    roffcmd(.SH)("Section Title")()()

    COMMENT(For the ms output format:)
    roffcmd(.SH)()(Section Title)(.PP)()
        
\end{verbatim}

    \item  \texttt{sgmlcommand(cmd)}: sends the SGML command \texttt{cmd} when in SGML 
conversion mode. The \texttt{cmd} is not further expanded.
    \item  \texttt{sgmltag(tag)(onoff)}: sends \texttt{$<$tag$>$} when \texttt{onoff} is nonzero,
or sends \texttt{$<$/tag$>$} when \texttt{onoff} is zero. Only active in SGML conversions.
    \item  \texttt{txtcommand(cmd)}: implemented for compatibility reasons, though a
`command' in plain ASCII output doesn't make much sense. The usefulness of
this macro is rather in the fact that it only produces output when in ASCII
conversion mode.
    \end{itemize}
    The above commands can be used to quickly implement a macro. E.g., the
macro package implements the \texttt{it} macro (which starts an item in a list) as:
        \begin{verbatim}

    DEFINEMACRO(it)(0)(
        latexcommand(\item )
        htmlcommand(<li> )
        ....
    )
        
\end{verbatim}

    Depending on the output format, \texttt{it()}  applies one of the above 
expansions.

The above described \emph{format}\texttt{command()} macros are implemented to send not 
further expanded strings (i.e., commands) to the output. The macro package 
also implements \texttt{when}\emph{format}\texttt{()} macros to send any text, which is 
then subject to further expansion. These \texttt{when...()} macros are:
    \begin{itemize}
    \item  \texttt{whenlatex(text)}: sends \texttt{text} when in LaTeX conversion mode,
    \item  \texttt{whenhtml(text)}: sends \texttt{text} when in HTML conversion mode,
    \item  \texttt{whenman(text)}: sends \texttt{text} when in man conversion mode,
    \item  \texttt{whenms(text)}: sends \texttt{text} when in ms conversion mode,
    \item  \texttt{whentxt(text)}: sends \texttt{text} when in ASCII conversion mode,
    \item  \texttt{whensgml(text)}: sends \texttt{text} when in SGML conversion mode.
    \end{itemize}
    Once again, \textbf{note} that the difference between the
\texttt{when}\emph{format}\texttt{()} macros and the \emph{format}\texttt{command()} macros is,
that the former expands their argument while the latter does not. As an
example, consider the following code fragment:
        \begin{verbatim}

    You are now reading
        whenlatex(a LaTeX-generated 
                  footnote(LaTeX is a great 
                   document language!)
                  document)
        whenhtml(a HTML document via your
                 favorite browser)
        
\end{verbatim}

    The \texttt{when}\emph{format}\texttt{()} macros are used here to make sure that the 
arguments to the macros are further expanded; this makes sure that the 
\texttt{footnote} macro in the \texttt{whenlatex} block gets treated as a footnote.

\subsection{Figures}
        Figures in format-independent documents are a problem. You \emph{cannot} avoid
contact with the final format (HTML, LaTeX or whatever) if you want to include
figures in a text.

Yodl approaches figures as follows:
    \begin{itemize}
    \item  Figures can only be included in LaTeX, HTML and XML documents.
    \item  For LaTeX, you must prepare a picture in an external file that is
included in the document as en \emph{encapsulated PostScript} file.
Incidentally, that means that \texttt{epsf} must be stated as one of the LaTeX
styles using the \texttt{latexoptions} macro.  The default, however, can be
modified using the \texttt{setlatexfigureext()} macro.
    \ \\ 
    The file in question is stated in Yodl without an extension. Yodl provides
a default extension, \texttt{.ps}.
    \item  For HTML and XML, you must prepare a picture in an external file that
is placed in the document using the \texttt{$<$img src=...$>$} tag. The file must
have the default extension (\texttt{.jpg}) or the extension specified with the
\texttt{sethtmlfigureext()} macro.
    \item  All other output formats do not include pictures in the document, but
    typeset something like \emph{insert figure .. here}.
    \end{itemize}
    The macro to include a figure is called, appropriately, \texttt{figure}. It
takes three arguments:
    \begin{itemize}
    \item  The first argument is the filename. This name may include directories,
but may not include the filename extension. The reason for this is, that
Yodl supplies the correct extension once the output format is known.
    \item  The second argument is the figure title, or the caption. Yodl prefixes
this caption with the text \emph{Figure xx:}, where \emph{xx} is a number.
    \item  The last argument is a label, which Yodl defines as a placeholder for
the figure number.
    \end{itemize}
    For example, you might draw a picture or scan a photo and put it in a
\texttt{.jpg} file, for usage with HTML documents. The conversion to PostScript
could be automated, e.g., using a Yodl macro:
        \begin{verbatim}

    SYSTEM(xpmtoppm picture.xpm | pnmtops > picture.ps)
        
\end{verbatim}

    See section \ref{SYSTEM} for details about using the \texttt{SYSTEM} macro.

After this, you would be reasonably safe that the picture is available for
both HTML and LaTeX output. The picture would be typeset in a figure using:
        \begin{verbatim}

    figure(picture)
    (A photo of me.)
    (photo)
        
\end{verbatim}

    Note how the first argument, the filename, does not contain an
extension. The third argument, which is a label, can be used in, e.g.,
        \begin{verbatim}

    See figure ref(photo) for a photograph showing me.
        
\end{verbatim}

    Yodl has a several auxiliary macros, which are:
    \begin{itemize}
    \item  \texttt{fig(label)}: This macro is a shorthand for \texttt{getfigurestring()
ref(label)}. It just makes typing shorter, and is used as e.g.: \texttt{See
fig(photo) for a photograph.} Note that the string \texttt{figure} that is
generated by this macro can be (re)defined, see below.
    \item  \texttt{setfigurestring(name)}: This macro is similar to
\texttt{setchapterstring} etc.. It defines the string that is used to identify a
figure, and is (appropriately) \texttt{figure} by default. The macro
\texttt{getfigurestring()} expands to the string in question. See also section
\ref{NATIONAL} for a discussion of national language support.
    \item  \texttt{sethtmlfigureext(.new)}: This macro redefines the filename
extension for HTML conversions from \texttt{.gif} to \texttt{.new}. Note that you must
include a leading dot in the redefinition.
    \ \\ 
    The new extension is used in the first following \texttt{figure} statement.
    \item  \texttt{sethtmlfigurealign(align)}: This redefines the alignment of
figures in HTML, which is default \texttt{bottom}. Check your HTML handbook for
possible options; \texttt{top} and \texttt{center} should be fairly standard.
    \item  \texttt{setlatexfigureext(.new)}: Redefines the extension from \texttt{.ps} to
\texttt{.new}.
    \end{itemize}

\subsection{Fonts and sizes}
        Yodl's standard macro package supports the following macros to change fonts:
    \begin{itemize}
    \item  \texttt{bf(text)}: sets \texttt{text} in boldface.
    \item  \texttt{em(text)}: sets \texttt{text} emphasized, usually in italics.
    \item  \texttt{tt(text)}: sets \texttt{text} in teletype. 
    \end{itemize}
    Furthermore, the \texttt{tt()} macro does \emph{not} expand macros occurring
inside its argument. That means that you can safely write:
        \begin{verbatim}

    In Yodl, you can use tt(includefile(somefile)) to include a file
    in your document.
        
\end{verbatim}

    The \texttt{tt()} macro should not be used for long listings of verbatim text;
use \texttt{verb()} to set code samples etc..

Yodl's standard macro package has no commands to change font sizes, as the
size is changed internally when appropriate (e.g., in section titles), nor is
there a default macro to define other font-families.

\subsection{Labels, links, references and URLs}\label{LABELS}
        
    References such as \emph{see ... for more information} are very common in
documents. Yodl supports three mechanisms to accomplish such references:
    \begin{description}
    \item[Labels and references:] Labels can be defined in a document as a
placeholder for the last number used in a sectioning command. At other points
in the document, references to those labels are used. The reference expands to
the number, as in \emph{see section 1.3}.

This mechanism is available in all output formats. Furthermore, the
numeric reference (1.3 in the example of the previous paragraph) is in HTML a
clickable reference that leads to the mentioned section.
    \item[Labels and links:] This mechanism can be used to set links in a
document without using the number of a sectioning command, as in \emph{see the
introduction for more information}, with the \emph{introduction} being a
clickable link to some label. 

This mechanism of course only leads to a clickable link in HTML: in other
formats the text \emph{see the} etc. is just typeset as is.
    \item[URLs:] Universal Resource Locators (URLs) are used to create links to
other HTML documents or services, like HTML's \texttt{$<$a href=..$>$} method.  The
URLs of course only result in clickable links in HTML output; in other output
formats only some descriptive text appears.
    \end{description}
    The above mechanism is implemented by the following macros:
    \begin{itemize}
    \item  The macro \texttt{label(name)} defines a label named \texttt{name}. The
name of the label can be used in a \texttt{ref} or \texttt{link} macro.
        \item  The macro \texttt{ref(name)} sets a reference to the label named
\texttt{name}.  The text of the reference is the number of the last sectioning
command that was active during the creation of the label. When using
references it is therefore important to define the corresponding labels right
after a sectioning command, as in
        \begin{verbatim}

    section(How to install my program) label(howtoinstall)
    This section describes...
    ...
    See section ref(howtoinstall) for installation instructions.
        
\end{verbatim}

    The macro \texttt{ref(howtoinstall)} expands to the number of the 
section named \emph{How to install my program}.
    \item  The macro \texttt{link(description)(name)} always expands to the
\texttt{description}. In HTML output, a clickable link is created pointing to a
label called \texttt{name}. For example:
        \begin{verbatim}

    label(megahard)
    COMMENT(sigh...)
    The Jodel package isn't shareware, it isn't
    beggarware, it isn't freeware, it's
    bf(megahard-ware).
    ...
    Who wants a link(picosoft)(megahard)?
        
\end{verbatim}

    This code fragment would always set the text \emph{picosoft}, but under HTML
a clickable link would appear pointing to \texttt{link(the text)(megahard)}.
    \item  The macro \texttt{url(description)(location)} always expands to the
\texttt{description}, but creates a hyperlink pointing to \texttt{location} in HTML.
For example,
        \begin{verbatim}

    Take a look at my 
    url(homepage)(http://www.somewhere.nl/karel/karel.html).
        
\end{verbatim}

    The text \texttt{homepage}\footnote{http://www.somewhere.nl/karel/karel.html} always
appears, but only in HTML it is a link. (Note that the double quotes, which
are necessary in HTML around the location, are not required by Yodl.) To use a
different font in the \texttt{description} part, surrond it \emph{inside the url
parameter list}, as in:
        \begin{verbatim}

    The Yodl package can be obtained at the site tt(ftp.rug.nl) in the
    directory url(tt(/contrib/frank/software/yodl))
                 (ftp://ftp.rug.nl/contrib/frank/software/yodl).
        
\end{verbatim}

    \item  The macro \texttt{email(address)} is a special case of \texttt{url}: under
HTML, the \texttt{address} appears as a clickable link in slanted font to mail
\texttt{address}. For example:
        \begin{verbatim}

    I can be reached at
    email(f.b.brokken@rug.nl).
        
\end{verbatim}

    I can be reached at \mbox{f.b.brokken@rug.nl}\texttt{$<$f.b.brokken@rug.nl$>$}.

Always keep in mind that the name of a label must be exactly identical in
both the \texttt{label} macro and in the \texttt{ref} or \texttt{link} macro. Other than
that, the name is irrelevant.

Furthermore, note that \texttt{lincludefile} is yet another macro defining a
label: it includes a file and automatically creates a label just before the
included file's text. That means that a Yodl file like:
        \begin{verbatim}

    chapter(Introduction)
    sect(Welcome)
    lincludefile(WELCOME)(welcome)

    chapter(Technical information)
    lincludefile(TECHINFO)(techinfo)
        
\end{verbatim}

    creates two labels: \texttt{WELCOME} and \texttt{TECHINFO}.
    \end{itemize}
    Here are  some final thoughts about using labels and references:
    \begin{itemize}
    \item  Don't put `weird' characters in label names. Generally, don't use
spaces and tabs.
    \item  The name of the label is always only an internal symbol; it does
not appear in the output. Therefore, constructions such as the following are
not correct:
        \begin{verbatim}

    ref(em(labelname))
        
\end{verbatim}

    The reason for the incorrectness is, what internal name should
\texttt{em(labelname)} generate? Here probably an attempt is made to set a
reference in italics. The right construction is of course to set \emph{whatever
\texttt{ref()} returns} in italics, as in:
        \begin{verbatim}

    em(ref(labelname))
        
\end{verbatim}

    \item  The \texttt{label} macro should not appear nested inside another
macro.  There is no strict reason for this as far as Yodl is concerned;
however, the processors of Yodl's output might go haywire. E.g., beware of the
construction
        \begin{verbatim}

    section(Introduction label(intro))
        
\end{verbatim}

    The right form being
        \begin{verbatim}

    section(Introduction)label(intro)
        
\end{verbatim}

    (linking to \texttt{intro} usually does \emph{not} show \texttt{Introduction}), or:
        \begin{verbatim}

    label(intro)section(Introduction) 
        
\end{verbatim}

    (linking to \texttt{intro} usually \emph{does} show \texttt{Introduction}).
    \end{itemize}

\subsection{Lists and environments}
            Yodl's default macros support the following lists and environments:

By default, the following lists are available:
    \begin{description}
    \item[Description lists:] A description list consists of a list of elements,
where each element starts with a short (usually bold faced) description. The
description list is generated by the \texttt{description()} macro. The
elements of the list start with \texttt{dit()}. The \texttt{dit()} 
macro expects a short description of the item.

Example:
        \begin{verbatim}

    A description list:
    description(
    dit(First this:) One item.
    dit(Then this:) Another item.
    )
        
\end{verbatim}

    \item[Enumeraton lists:] An enumeration list consist of sequentially
numbered elements.  The list is generated by the \texttt{enumeration()}
macro. Its elements start with the \texttt{eit()} macro.

Example:
    \begin{verbatim}

    An enumerated list:    
    enumeration(    
    eit() One item.    
    eit() Another item.    
    )    
        
\end{verbatim}

    \item[Itemized lists:] An itemized lists consists of indented items, usually
    preceded by a bullet. 

An itemized list is produced by the \texttt{itemization()} macro, which has one
argument: the items themselves. These items must start with \texttt{it()}.

Example:
        \begin{verbatim}

    An itemized list:
    itemization(
    it() One item.
    it() Another item.
    )
        
\end{verbatim}
    
    \end{description}
    Specialized environments are:
    \begin{description}
    \item[Centered text:] Centering text may not be available in all output 
    formats. When unavailable, the text is typeset left-flushed.

Centered text is generated by the \texttt{center()} macro. Line brakes within
centered text may be obtained using the \texttt{nl()} macro.

Example:
        \begin{verbatim}

    center(
    Centered text. nl()    
    Another line of centered text.
    )    
        
\end{verbatim}

    \item[Verbatim text:] \emph{Verbatim} text appears on the output exactly in the
    same layout as it is in the input file. Typesetting text in verbatim mode
    is useful for, e.g., source files. Depending on the output format, the
    font of the verbatim text is changed to a teletype font.

The text must either be inside the \texttt{verb()} macro. For example:
        \begin{verbatim}

    verb(
        This is totally verbatim text.
        It is not further processed by Yodl.
    )
        
\end{verbatim}

    The verbatim text is of course not subject to macro expansion by Yodl.
Note, however, that \texttt{SUBST} transformations \emph{will} take place, as these
substitutions take place during the lexical scanning phase of \texttt{Yodl}'s input,
and are not part of the macro-expansion process. See also section \ref{SUBST}.

Furthermore, if a character translation table has been defined, the
argument of the \texttt{verb()} macro will also be subject to character
table transformations. By temporarily suppressing the active character table
(see section PUSHCHARTABLE \ref{PUSHCHARTABLE}) this can be prevented.
    \item[Quotations:] Quotations are usually indented with respect to their
surrounding text. It is for the author to decided whether the quoted text
should be typeset normally, or that it should be bold-faced or emphasized. To
insert a quotation use the \texttt{quote()} macro:
        \begin{verbatim}

    Shakespeare once wrote:
    quote(
        ``To be or not to be, that's the question''
    )
        
\end{verbatim}

    \end{description}

\subsubsection{National language support}\label{NATIONAL}
        Yodl includes rudimentary national language support (NLS), in the sense that
it allows you to redefine the strings identifying chapters or parts, or the
strings identifying figures. E.g., a command \texttt{chapter(Introduction)} 
by default results in the text \emph{Chapter 1: Introduction}.

Using the \texttt{setchapterstring(text)} macro, the \emph{Chapter} text can be
redefined.  E.g., in a Dutch text you might put
        \begin{verbatim}

    setchapterstring(Hoofdstuk)
        
\end{verbatim}

    somewhere near the beginning of your document. Similar to
\texttt{setchapterstring}, a macro \texttt{getchapterstring} exists returning the
text identifying chapters.  (Internally, \texttt{getchapterstring} is of course
used to actually set the text).  To redefine the text to identify a part, use
\texttt{setpartstring(text)}; to redefine the text to identify a figure, use
\texttt{setfigurestring(text)}.

The \texttt{set....string} macros only influence how Yodl names chapters or
parts in HTML, \texttt{man}, \texttt{ms} or \texttt{txt} output. LaTeX output is not
affected, since LaTeX does its own NLS. Usually, NLS is present for LaTeX as a
`style file' named, e.g., \texttt{dutch.sty}. Therefore, if you want a Dutch
document, you need to:
    \begin{itemize}
    \item  put \texttt{latexpackage(dutch)(babel)}in the preamble of
the document. This ensures that LaTeX uses Dutch abbreviation rules.
    \item  redefine the chapter and part names for non-LaTeX output, using:
        \begin{verbatim}

    setlanguage(dutch)
        
\end{verbatim}

    \item  Finally, you should probably type your text in Dutch.
    \end{itemize}
    The \texttt{setlanguage()} macro expects one argument: the name of the language
that is used. See section \ref{MACROLIST} for details about this macro. The
\texttt{setlanguage()} macro redefines the language-dependent section (and other)
headers, and depends on the availability of the corresponding
\texttt{language$<$name$>$()} macro, where \texttt{$<$name$>$} is the name of the language (by
convention \texttt{$<$name$>$} states the english name of the language). 
Currently, \texttt{languagedutch()}, \texttt{languageenglish()} (the default), 
and \texttt{languageportugese()} are available. It's easy to expand this little set
with macros for other languages. The \texttt{setlanguage()} macro merely requires
the specification of the language. For example:
        \begin{verbatim}

    setlanguage(english)
        
\end{verbatim}

    This macro installs the following defaults (corresponding translations
should be defined for other languages):
        \begin{verbatim}

    settocstring(Table of Contents)
    setaffilstring(Affiliation)
    setauthorstring(Author)
    setchapterstring(Chapter)
    setdatestring(Date)
    setfigurestring(Figure)
    setpartstring(Part)
    settitlestring(Title)
        
\end{verbatim}


\subsubsection{Pagebreaks after the title and table of contents}
            Yodl inserts  page-breaks in a limited number of cases:
    \begin{itemize}
    \item  A pagebreak is generated after the title information in \texttt{book} and
\texttt{report} documents.
    \item  A pagebreak is generated after a table of contents in all documents.
    \end{itemize}
    So, when a document has both title information and a table of contents
then whatever follows next normally starts on a separate page.  Furthermore,
if the document is a \texttt{book} or a \texttt{report}, the title and table of contents
will also be separated by pagebreaks.

This behavior can be modified using the \texttt{(no)titleclearpage()} and
\texttt{(no)tocclearpage()} directives, further described in section
\ref{MODIFIERS}.

\subsection{Sectioning}
        This section describes the sectioning commands for \texttt{article}s, \texttt{report}s,
\texttt{book}s and for \texttt{plainhtml}. The document type \texttt{manpage} defines its own
sectioning commands (cf. section \ref{MANPAGE}:
    \begin{itemize}
    \item  \texttt{part(title)}: Starts a new part. Only available in \texttt{book} 
documents. 
    \item  \texttt{chapter(title)}: Starts a new chapter. Only available in \texttt{book} 
or \texttt{report} documents.
    \item  \texttt{sect(title)}: Starts a section. 
    \item  \texttt{subsect(title)}: A subsection.
    \item  \texttt{subsubsect(title)}: A sub-subsection.
    \item  \texttt{subsubsubsect(title)}: An even smaller sectioning command.
    \end{itemize}
    These macros generate entries in the table of contents and use numbering,
which means that each section is prefixed with a number (1, 1.1, 1.2, and so
on).  The macros are also available with an \texttt{n} prefix (\texttt{npart},
\texttt{nchapter}, \texttt{nsect} etc.) which generate neither entries in the table of
contents nor numbers. The \texttt{n}-versions can be used in, e.g., an article
where the sectioning commands should show their captions, but not any numbers
generated by default.

Sectioning should always start at the top level sections of the available
document: \texttt{chapter} for reports, \texttt{sect} for articles, etc.. If you start a
document with a lower sectioning command (e.g., when you start an article with
a \texttt{subsect}), the numbering of sections may go haywire. The only exception
to this rule is the \texttt{part} of a \texttt{book} document: parts are optional, in
books, \texttt{chapter}s may be the top sectioning commands.  Summarizing, books or
reports should start with \texttt{chapter}.  Articles should start with
\texttt{sections}.

The sectioning commands have a further function: when \texttt{label} statements 
appear after the sectioning command, then a label name is used as a 
placeholder for the last generated number. This is further described in 
section \ref{LABELS}.

\subsection{Typesetting modifiers}\label{MODIFIERS}
        This section lists various macros that can be used to modify the looks of your
document. When used, these macros must appear \emph{before} stating the document
type with \texttt{article}, \texttt{report}, \texttt{book}, \texttt{manpage} or \texttt{plainhtml}.
    \begin{itemize}
    \item  \texttt{abstract(text)}: This macro is relevant for all output formats.
The \texttt{text} is added to the document after the title, author and date
information, but before the table of contents. The abstract is usually set as
a quote, in italics font (though this depends on the output format).
Abstracts are supported in \texttt{article}s and \texttt{report}s, but not in other
document types. I.e., if you need introductory text in a \texttt{book}, you should
start with a non-numbered chapter that holds this text.
    \item  \texttt{affiliation(site)}: This macro is relevant for \texttt{article},
\texttt{report} and \texttt{book} documents. It defines the affiliation of the
author. The \texttt{site} information appears in the title, below the author's
name.
    \item  \texttt{htmlbodyopt(option)(value)}: This macro adds \texttt{option="value"} to
the \texttt{$<$body$>$} tag that is generated for HTML output. The HTML converter
generates \texttt{$<$body$>$} tags each time that a new file is started; i.e., at the
top of the document and at each chapter-file. Different HTML browsers support
different \texttt{$<$body$>$} tag options, but useful ones may be e.g.:
        \begin{verbatim}

    htmlbodyopt(fgcolor)(#000000)
    htmlbodyopt(bgcolor)(#FFFFFF)
        
\end{verbatim}

    This defines the foreground color as pure white (red/green/blue all 0) and
the background color as black (red/green/blue all hexadecimal FF, or 255).
Another useful option may be \texttt{htmlbodyopt(background) (some.gif)}, defining
\texttt{some.gif} as the page background.

See the documentation on HTML for more information.

Note that \texttt{value} is automatically surrounded by double quotes when 
this macro is used. They should not be used by authors using this macro.
    \item  \texttt{latexdocumentclass(class)}: This macro forces the
    \texttt{\textbackslash{}documentclass\{...\}} setting in LaTeX output to \texttt{class}.
    \item  \texttt{latexlayoutcmds(commands)}: This macro can be used to specify your
own LaTeX layout commands. When present, the \texttt{commands} are placed in LaTeX
output following the \texttt{\textbackslash{}documentclass} definition.
    \item  \texttt{latexoptions(options)}: This macro is only relevant for LaTeX
output formats, it is not expanded in other formats. The \texttt{options} are used
in LaTeX's \texttt{\textbackslash{}documentclass} definition; e.g., a useful option might be
\texttt{dina4}. Multiple options should be separate by commas, according to the
LaTeX convention.
    \item  \texttt{latexpackage(options)(name)}: This macro is only relevant for
LaTeX output formats, it is not expanded in other formats. Each \emph{package}
should have its own \texttt{latexpackage()} statement. If there are no options, the
\texttt{options} argument should remain empty. Here is an example using this macro:
        \begin{verbatim}

    latexpackage(dutch)(babel)
        
\end{verbatim}

    \item  \texttt{mailto(email)}: The \texttt{mailto} macro is only expanded in HTML
documents, it is ignored in other formats. It defines where mail about the
document should be sent to.
    \item  \texttt{nosloppyhfuzz()}: By default, the LaTeX output contains the text
        \begin{verbatim}

    \hfuzz=4pt
        
\end{verbatim}

    which is placed there by the macro package. This suppresses \emph{overfull
hbox} warnings of LaTeX when the overfull-ness is less than 4pt.  Use
\texttt{nosloppyhfuzz()} to get the standard LaTeX warnings about overfull hboxes.
    \item  \texttt{notableofcontents()}: As the name suggests, this macro suppresses
the generation of the table of contents. For HTML that means that no
clickable index of sections appears after the document title.

The table of contents is by default suppressed in \texttt{plainhtml} and
\texttt{manpage} documents.
    \item  \texttt{notitleclearpage()}: Normally, Yodl inserts a \texttt{clearpage()}
directive after typesetting title information in \texttt{book} or \texttt{report}
documents, but not in \texttt{article} documents. Use \texttt{notitleclearpage} to
suppress this directive.
    \item  \texttt{notocclearpage()} (no table-of-contents clear-page): In all
document types, Yodl inserts a \texttt{clearpage()} directive following the table
of contents. Use \texttt{notocclearpage()} to suppress that.
    \item  \texttt{noxlatin()}: The LaTeX output contains by default the command to
include the file \texttt{xlatin1.tex}, distributed with Yodl. This file maps
Latin-1 characters to LaTeX-understandable codes and makes sure that you can
type characters such as \texttt{ü}, and still make them processable by LaTeX. If
you don't want this, put \texttt{noxlatin()} in the preamble.
    \item  \texttt{standardlayout()}: This is another LaTeX option.  Use
\texttt{standardlayout()} to get `vanilla' LaTeX layout, possibly indenting
paragraphs and using fairly limited vertical spacing between paragraphs.
This macro is ignored for other conversion types.
    \item  \texttt{titleclearpage()}: Forces the insertion of a \texttt{clearpage()}
directive after the title information has been typeset. This behavior is the
default in \texttt{book} and \texttt{report} documents. See also \texttt{notitleclearpage()}.
    \item  \texttt{tocclearpage()}: Forces the insertion of a \texttt{clearpage()}
directive following the table of contents. This behavior is default in all
document types; the macro is provided for consistency reasons with
\texttt{(no)titleclearpage()}.
    \end{itemize}
    \emph{Note again}: these modifiers must appear \emph{before} the document type
definition.

\subsection{Miscellaneous commands}
            The following is a list of commands that don't fall in one of the above
categories. 
    \begin{itemize}
    \item  \texttt{clearpage()}: This macro starts a new page in LaTeX. For HTML, a
horizontal rule is shown. (Note that the macro package sometimes inserts new
pages by itself; e.g., following a table of contents. See also section
\ref{MODIFIERS} for a discussion of \texttt{(no)titleclearpage()} and
\texttt{(no)tocclearpage()}.)
    \item  \texttt{def(macro)(nrofarguments)(definition)}: This defines a new macro
\texttt{macro} having \texttt{nrofarguments} arguments, and expanding to
\texttt{definition}. The markers \texttt{ARG}\emph{x}, where \emph{x} is 1, 2, etc., can be
used in the \texttt{definition} part to indicate where arguments should be pasted
in. This macro is a shorthand for \texttt{DEFINEMACRO}, see section
\ref{DEFINEMACRO}.
    \item  \texttt{footnote(text)}: This macro sets \texttt{text} as a footnote when the
output format allows it. When not, the text is set in parentheses.
    \item  \texttt{gagmacrowarning(name name ...)}: This macro suppresses \texttt{yodl}'s
warnings \emph{cannot expand possible user macro name}, where \texttt{name} is a
candidate macro name. \texttt{gagmacrowarning} is a synonym for \texttt{NOUSERMACRO},
described in section \ref{NOUSERMACRO}.
    \ \\ 
    E.g., if your document contains \texttt{"as for manpages, see sed(1), tr(1) and
awk(1)"}, and if you get tired of warnings about possible user macros sed, tr
and awk, try the following:
        \begin{verbatim}

    gagmacrowarning(sed tr awk)
    ...
    As for manpages, see sed(1), tr(1) and awk(1).
        
\end{verbatim}

    \item  \texttt{htmlnewfile()}: Starts a new subfile in HTML output. This stanza
is also automatically generated when the HTML converter encounters a
\texttt{chapter} directive. Using \texttt{htmlnewfile}, the output can be split at
any point. However make sure that the subfile is still reachable; e.g., by
creating a clickable link with \texttt{label} and \texttt{ref}, or \texttt{label} and
\texttt{link}.
    \item  \texttt{includefile(file)}: Includes \texttt{file} and defines a label (see the
\texttt{label} macro) with the same name. Furthermore, a message about the
inclusion is shown on the screen. The \texttt{file} is searched for relative to the
directory of the file in which the \texttt{includefile} macro was used (or relative
to the directory where the \texttt{yodl} run was started when the
\texttt{+NOTRANS(-\{\}-\{\})legacy-include} or \texttt{-L} option was provided) and also in the
system-wide include directory. The default extension \texttt{.yo} is supplied if
necessary.
    \ \\ 
    The \texttt{lincludefile} macro is handy in the following situation:
        \begin{verbatim}

    chapter(Introduction)
    lincludefile(INTRO)(intro)
        
\end{verbatim}

    This fragment starts a chapter and includes a file. Here the label name
(\texttt{INTRO}) can also be used to refer to the chapter as the \texttt{lincludefile}
stanza appears \emph{immediately} following the corresponding
sectioning command.
    \item  \texttt{nl()}: Forces a new line. Some output formats may produce an error
upon the usage of \texttt{nl()} in `unexpected' places; e.g., LaTeX won't allow new
lines in the footnote text (as defined in the \texttt{footnote} macro). Using
\texttt{nl()} in running text should however be ok. Example:
        \begin{verbatim}

    This line is nl()
    broken in two.
        
\end{verbatim}

    \item  \texttt{redefinemacro(macro)(nrofargs)(redef)}: This command (re)defines a
macro, expecting \texttt{nrofargs} arguments, to \texttt{redef}. If a previous
definition of the macro existed, it is overruled. Example:
        \begin{verbatim}

    redefinemacro(clearpage)(0)(\ 
    em(---New page starts here---))
        
\end{verbatim}

    Use \texttt{ARG}\emph{x} in the \texttt{redef} part to indicate where all arguments 
should occur, as in the following imaginary macro to typeset a literature
reference:
        \begin{verbatim}

    redefinemacro(litref)(3)(
        Title: bf(ARG1) nl()
        Author(s): em(ARG2) nl()
        Published by: ARG3
    )
    ...
    litref(Java in a Nutshell)
      (David Flanagan)
      (O'Reilly & Associates, Inc.)
        
\end{verbatim}

    The \texttt{redefinemacro} statement also has a shorthand called \texttt{redef}.
    \end{itemize}

\section{Locations of the macros}    
    The files defining the macros are by default installed to the directory
\texttt{/usr/local/share/yodl} during Yodl's installation process (Note that this
diverts from an earlier default: \texttt{/usr/local/lib/yodl}; furthermore, 
some systems or some distributions may use other locations).

The files in this directory are organized as follows:
    \begin{itemize}
    \item  The files that should be read for a particular conversion are named
after their conversion, e.g., \texttt{latex.yo} and \texttt{html.yo}. These files must
be processed by Yodl before your document can be converted accordingly. The
provided \texttt{yodl2...} scripts take care of that automatically.
    \item  All support counters, symbols and macros are defined in files named
\texttt{std.$<$conversion$>$.yo}, e.g., \texttt{std.html.yo, std.latex.yo}. These files may
be modified without notice, and are an essential part of the Yodl macros. They
should not be modified by hand, as they are created by the macro generating
process. 
    \item  The predefined character tables are found in files names
\texttt{chartables/$<$conversion$>$.yo}.
    \end{itemize}
    The (binary) Yodl package contains the following programs and support
files:
    \begin{itemize}
    \item  The \texttt{yodl} program itself, which generates converted document(s);
    \item  The \texttt{yodlpost} postprocessor, which performs fixups for conversion
formats. Using \texttt{yodlpost} is required for formats whose documents 
cannot be created in one pass by \texttt{yodl} itself;
    \item  Auxiliary scripts such as \texttt{yodl2tex}, \texttt{yodl2html};
    \item  The macros and character tables for the various conversion types;
    \item  The raw macros and the macro-generating scripts;
    \item  The documentation (html and manual pages)
    \end{itemize}
    The source Yodl package contains all the sources files, installation
guides, change-logs etc., that are required to compile the binary
programs. Those who want to compile Yodl themselves, must have a \texttt{C}
compiler (preferably the \texttt{Gnu} \textbf{C} compiler) available, and preferably the
\texttt{icmake} program maintenance utility. Basic support for \texttt{make} is provided
as well.

\cleardoublepage\chapter{Conversions and converters}
Each macro package handling a conversion from Yodl to a given output format
has its peculiarities. Although the various macro packages are very similar,
they do show some differences, due to the unique characteristics of the output
formats. Normally, these differences should not cause difficulties in
performing the conversion(s). In this chapter the conversion of a Yodl
document is covered. The currently supported document types are discussed. 
Furthermore, in this chapter the new \emph{post processor} \texttt{yodlpost} is
described as well as a little support program: \texttt{yodlverbinsert}.

\section{Conversion script invocations}
    Yodl is distributed with scripts  named \texttt{yodl2latex}, \texttt{yodl2html} and 
other \texttt{yodl2...} drivers. Invocations like
        \begin{verbatim}

    yodl2latex file
        
\end{verbatim}

    causes \texttt{Yodl} to process \texttt{file.yo} and to write output to
\texttt{file.latex}. The extension of the input file, \texttt{.yo}, is the default \texttt{Yodl}
extension; the extension of the output file, \texttt{.latex}, is given by the name
of the shell script. Analogously, \texttt{yodl2html} writes to a file having the
extension \texttt{.html}.

The conversion scripts auto-load the macro file appropriate for the
conversion: \texttt{latex.yo} for LaTeX conversions, \texttt{html.yo} for HTML
conversions, etc.. The macro files are in \texttt{Yodl}'s standard include directory
(which is mentioned in \texttt{Yodl}'s usage information when \texttt{Yodl} is started without
arguments). If the include directory is altered in such a way that it doesn't
contain a path to the default directory anymore, then \texttt{Yodl} won't be able to
auto-load the conversion specific macro files, producing unexpected
results. This can be prevented by specifying the literal text \texttt{\$STD\_INCLUDE}
in a user-defined path setting.

When the conversion scripts themselves are started without arguments, usage
information is shown about the conversion scripts.

Depending on the conversion type, the following output is produced:
    \begin{itemize}
    \item  For LaTeX conversions, one output file with the extension \texttt{.latex}
is written. 
    \item  For HTML conversions, several files may be written; one file per
chapter of the original document. When the document is not sectioned by
chapters, only one output file is produced.

The `main' output file always has the name of the input file but with
extension \texttt{.html}. This file holds the document title and the table of
contents. When more than one output files are created, then they are named
\texttt{name01.html}, \texttt{name02.html} etc., where \texttt{name} is the original name of
the input file. E.g., a document \texttt{prog.yo} might lead to \texttt{prog.html},
\texttt{prog01.html} etc..
    
    \item  For man conversions, one output file with the extension \texttt{.man} is
written. 
    \item  For text conversions, the converter is named \texttt{yodl2txt} and one 
output file with the extension \texttt{.txt} is created.
    \item  For XML conversions, the converter is named \texttt{yodl2xml} and output
files are produced comparably to the way they are produced with the \texttt{html}
conversion: one file per chapter if chapters are used, otherwise one single
output file, having the extension(s) \texttt{.xml}.
\end{itemize}
    The `second-phase' scripts, distributed with earlier versions of \texttt{Yodl}, are
no longer part of \texttt{Yodl}'s distribution, as they do not relate directly to
\texttt{Yodl}'s actions. They may remain useful, though, as leftovers from earlier
distributions.
    

\section{The HTML converter}    
    HTML doesn't support automatic section numbering or resolving of
label/reference pairs. The converter takes care of this. Other target
languages (e.g., XML, text) suffer from the same problems.

\subsubsection{Direct commands to HTML}
        Similar to the \LaTeX{} converter, you can use either \texttt{NOTRANS} or
\texttt{htmlcommand} to send HTML commands to the output. Or, since the only 
`difficult' characters are probably only \texttt{$<$} and \texttt{$>$}, you can also resort 
to \texttt{CHAR} for these two characters.

Furthermore, the HTML converter defines the macro \texttt{htmltag}, expecting two 
arguments: the tag to set, and an `on/off' switch. E.g., \texttt{htmltag(b)(1)} 
sets \texttt{$<$b$>$} while \texttt{htmltag(b)(0)} sets \texttt{$<$/b$>$}.

E.g., the following code sends a HTML command \texttt{$<$hr$>$} to the output file when 
in HTML mode:
        \begin{verbatim}
COMMENT(-- alternative 1, using htmlcommand --)
    htmlcommand(<hr>)
    
    COMMENT(-- alternative 2, using NOTRANS --)
    IFDEF(html)(
        NOTRANS(<hr>)
    )()
    
    COMMENT(-- alternative 3, using CHAR --)
    IFDEF(html)(
        CHAR(<)hrCHAR(>)
    )()
        
    COMMENT(-- alternative 4, using htmltag --)
    htmltag(hr)(1)
        
\end{verbatim}


\subsubsection{Section numbering}
        The HTML converter numbers its own sections. This is handled internally.
However, the current converter only can number sections as starting at 1, and
outputs the numbers in arabic numerals (you can't number with A, B, etc..).

\section{The LaTeX converter}    
    The \LaTeX{} converter is, from \texttt{Yodl}'s viewpoint, an easy one: since
\LaTeX{} supports wide functionality, a Yodl document is basically just
re-mapped to \LaTeX{} commands. No post-processing by \texttt{yodlpost} is
required.

\subsubsection{Direct commands to LaTeX}    
        To send \LaTeX{} commands directly to the output, use the \texttt{latexcommand()}
macro (see section \ref{FORMATDEFINES}), or use \texttt{NOTRANS} (see section
\ref{NOTRANS}). The advantage of the \texttt{latexcommand} macro is that it only
outputs its argument when in \LaTeX{} mode.

The following two code fragments both output \texttt{\textbackslash{}pagestyle\{plain\}} when in 
\LaTeX{} mode: 
        \begin{verbatim}

    COMMENT(-- First alternative: --)
    latexcommand(\pagestyle{plain})
    
    COMMENT(-- Second alternative: --)
    IFDEF(latex)(
        NOTRANS(\pagestyle{plain})
    )()
        
\end{verbatim}
 

\subsubsection{Verbatim text}    
        The Yodl macro package defines two macros that generate verbatim text (e.g.,
source code listings). These macros are \texttt{verb()} and \texttt{tt()}.
    \begin{description}
    \item[verb] The \texttt{verb()} macro and is meant for longer listings (whole
files); as in:
        \begin{verbatim}

        verb(
    #include <stdio.h>
    
    int main (int argc, char **argv)
    {
        printf ("Hello World!\n");
        return 0;
    }
        )
        
\end{verbatim}

    The \texttt{verb()} macro generates \texttt{\textbackslash{}begin\{verbatim\}} and
\texttt{\textbackslash{}end\{verbatim\}} when used in \LaTeX{} conversion mode.
That means that (in that situation) the \texttt{verb} macro has only one caveat:
you cannot put \texttt{\textbackslash{}end\{verbatim\}} into it.
    \item[tt] The \texttt{tt()} macro also inserts verbatim text. It is used for
short in-line strings (e.g, \texttt{$*$$*$argv}). The \LaTeX{} converter doesn't
actually use a verbatim mode, but sets the characters in teletype font.
    \end{description}

\section{The man converter}    
    Manual pages can be constructed using the special \texttt{yodl2man} converter.
This converter assumes that the manual page has been designed using the
\texttt{manpage()} macro. Yodl (and thus the \texttt{yodl2man} converter, when converting
man-pages, skips all leading white space on lines. Paragraphs are supported,
though. An empty line separates paragraphs.

\subsubsection{Direct commands to man}
        Either \texttt{NOTRANS} or \texttt{mancommand} can be used to send man commands to the
output. 

E.g., the following code sends a MAN command \texttt{$<$hr$>$} to the output file when 
in MAN mode:
        \begin{verbatim}
COMMENT(-- alternative 1, using mancommand --)
    mancommand(<hr>)
    
    COMMENT(-- alternative 2, using NOTRANS --)
    IFDEF(man)(
        NOTRANS(<hr>)
    )()
        
\end{verbatim}


\section{The txt converter}    
    Plain text documents can be constructed using the \texttt{yodl2txt} converter.
This converter resolves all references into the document itself, so
postprocessing is required. 

\subsubsection{Direct commands to txt}
        Either \texttt{NOTRANS} or \texttt{txtcommand} can be used to send txt commands to the
output. 

E.g., the following code sends a TXT command \texttt{$<$hr$>$} to the output file when 
in TXT mode:
        \begin{verbatim}
COMMENT(-- alternative 1, using txtcommand --)
    txtcommand(<hr>)
    
    COMMENT(-- alternative 2, using NOTRANS --)
    IFDEF(txt)(
        NOTRANS(<hr>)
    )()
        
\end{verbatim}


\section{The experimental XML converter}    
    The XML converter is experimental. It was added to \texttt{Yodl} to allow me to write
documents for the horrible `webplatform' of the university of Groningen. The
XML support files (located in the \texttt{xml} directory in the standard macro's
directory) clearly reflect this target. Although experimental, they were kept
because the XML macros support interesting constructions allowing \texttt{Yodl} to
handle closing tags somewhat more strict than required for HTML.

\section{The Yodl Post-processor `yodlpost'}
    Following the conversion of a \texttt{Yodl} text, most target-languages require an
additional operation, called `post-processing'. Post-processing is required
for various reasons: to split the output in separate files (HTML, XML); to
fixup the locations of labels, that are referred to earlier than the labels
are defined (virtually all target language except LaTeX); tables of contents
are available only after the conversion, but have to be inserted at the
beginning of the document; etc. etc..

Starting with \texttt{Yodl} V. 2.00 there is only one post-processor, handling all
the conversions for all target languages. Program maintenance of just one
program is certainly easier than maintenance of as many programs as there are
target-languages, at the expense of only a slightly larger program: after all,
the one post-processor contains the conversion procedures for all target
languages. It turns out that this is a very minimal drawback. See section
\ref{POSTPROCESSOR} for the technical details of post-processor program
maintenance. 

The post-processor that is distributed since \texttt{Yodl} V. 2.00 does \emph{not} use the
\texttt{.tt(Yodl)TAGSTART.} and \texttt{.tt(Yodl)TAGEND.} tags anymore. Instead, the conversion
process produces a \emph{index file} in which comparable information is
written. The advantage of using an index file is that the postprocessor
doesn't have to parse the output file generated by \texttt{Yodl} twice (once to
determine the tags, once to process the tags), which by itself accelerates the
conversion process; and (albeit of a somewhat limited practical importance)
that the tags are no longer \emph{reserved words}: authors may put
\texttt{.tt(Yodl)TAGSTART.} and \texttt{.tt(Yodl)TAGEND.} into their texts as often as they
want. 

Authors should be aware of some caveats with respect to some target languages:
    \begin{description}
    \item[man- and ms- conversions] all dots are converted by the active
character conversion table to \texttt{\textbackslash{}\&.}. Commands in these languages always
start with a dot as the first character on a line. In order to insert these
commands the \texttt{roffcmd()} (see section \texttt{MACROLIST}) should be used.
    \item[plain text conversions] As stated before, the ASCII converter
basically only strips macronames from its input. This converter is so basic,
that it should only be used as a last
resort, when no other target language is available for the job.
        \ \\ 
    With the plain text converer, the layout of the input file is very
important, as the output is basically the same as the input. The only
exception to this rule are multiple empty lines, which normally are consumed
by the post-processor, to be replaced by one single empty line.
    \item[sgml conversions] the SGML converter was implemented for historic
reasons. It is by no means complete, and can at best be considered an `initial
starting point'. Currently, the SGML converter only supports the \texttt{article}
document type, having \texttt{sect} as its top-level sectioning command.
    \item[xml conversions] The XML converter was implemented to allow me
(Frank) to produce XML text as defined by the so-called `webplatform' of the
University of Groningen. A completely pathological implementation of XML,
crippling its users to the level of the `double click brigade'. Well, so be
it. The net result of this is that \texttt{Yodl} now offers some basic form  of XML
conversion. After adding XML conversion, however, there was never any real
situation where it could profitably be used. Therefore, further development of
the XML conversion has, for the time being, been suspended.
    \end{description}

\section{The support program `yodlverbinsert'}
        The program \texttt{yodlverbinsert} is a simple \textbf{C} support program that
can be used to generate \texttt{verb()}-sections in \texttt{Yodl} files
from sections of existing files. The files from which sections are included
are usually \textbf{C} or \textbf{Cpp} source files, accepting either \texttt{//} or
\texttt{/$*$}-style comment. 

\texttt{Yodlverbinsert} offers the possibility to indent both the initial
\texttt{verb}-statement and the inserted file contents. Furthermore, an additional
empty line may be inserted before the first line that is actually inserted.
The program is invoked according to the following synopsis:

\begin{center}\textbf{yodlverbinsert} {[}OPTIONS{]} \texttt{marker file}\end{center}

The arguments have the following meanings;
    \begin{itemize}
    \item  \texttt{marker}\ \\ 
    The argument \texttt{marker} must start in \texttt{file}'s first column en must
either start as a standard \textbf{C} or \textbf{C++} comment: \texttt{//} or \texttt{/$*$} must be
used. Following that, the remainder of the argument is used as a label, e.g.,
\texttt{//label}, \texttt{/$*$LABEL$*$/}. The label may contain non-alpha characters as
well. Except for the first two characters and their locations no special
restrictions imposed upon the label texts. A labeled section ends at the next
\texttt{//=} (when the label started with \texttt{//}) or at the next \texttt{/$*$$*$/} (when the
label started with \texttt{/$*$}). Like the labels, the end-markers must also start
in the file's first column.
    \item  \texttt{file}\ \\ 
    The argument \texttt{file} must be an existing file. \texttt{Yodlverbinsert} was
designed with \textbf{C} or \textbf{C++} sources in minde, from which labeled sections
must be inserted into a \texttt{Yodl} document, but \texttt{file} could also refer to
another type of (text) file.
    \end{itemize}

The default values of options are listed below, with each of the options
between square brackets. The defaults were chosen so that \texttt{yodlverbinsert}
performs the behavior of an earlier version of this program, which was
not distributed with \texttt{Yodl}.
    \begin{itemize}
    \item  \textbf{-N}\ \\ 
    Do not write a newline immediately following \texttt{verb}-statement's
open-parenthesis. By default it is written, causing an additional line to be
inserted before the first line that's actually inserted from a file.
    \item  \textbf{-s} \texttt{spaces} {[}0{]}\ \\ 
        start each line that is written into the \texttt{verb}-section with
\texttt{spaces} additional blanks.
    \item  \textbf{-S} \texttt{spaces} {[}8{]}\ \\ 
        prefix the \texttt{verb} of the \texttt{verb}-section by 
\texttt{spaces} additional blanks.
    \item  \textbf{-t} \texttt{tabs} {[}0{]}\ \\ 
        start each line that is written into the \texttt{verb}-section with
\texttt{tabs} additional tab characters. If both \texttt{-s} and \texttt{-t} are specified,
the tabs are inserted first.
    \item  \textbf{-T} \texttt{tabs} {[}0{]}\ \\ 
        prefix the \texttt{verb} of the \texttt{verb}-section by \texttt{tabs} additional tab
characters. If both \texttt{-S} and \texttt{-T} are specified, the tabs are inserted
first.
    \end{itemize}

\texttt{Yodlverbinsert} writes its selected section to its standard output
stream.

\subsection{Example}

Assume the file \texttt{demo} contains the following text:
        \begin{verbatim}

preceding text

//one
one 1

//=

/*two*/

    two

/**/

trailing text
    
\end{verbatim}


Then the following commands write the shown output to the program's
standard output:
    \begin{itemize}
    \item  \texttt{verbinclude //one demo}\ \\ 
        \begin{verbatim}
        verb(
one 1

)

\end{verbatim}

    \item  \texttt{verbinclude -N //one demo}\ \\ 
        \begin{verbatim}
        verb(one 1

)

\end{verbatim}

    \item  \texttt{verbinclude -s4 '/$*$two$*$/' demo}\ \\ 
        \begin{verbatim}
        verb(
    
        two
    
)

\end{verbatim}

    \end{itemize}        

To call \texttt{yodlverbinsert} from a \texttt{Yodl} document, use
\textbf{PIPETHROUGH}. E.g., 
        \begin{verbatim}

    PIPETHROUGH(yodlverbinsert //one demo)
        
\end{verbatim}


Alternatively, define a simple macro like the macro \texttt{verbinsert}:
    
    \begin{verbatim}

DEFINEMACRO(verbinsert)(2)(PIPETHROUGH(yodlverbinsert //ARG1 ARG2)()\ 
)
    
\end{verbatim}

    which may be a useful macro if all or most of your labeled sections start
with \texttt{//}, and if \texttt{yodlverbinsert}'s arguments don't vary much. Variants
to this macro can easily be conceived of.

\cleardoublepage\chapter{Technical information}
This chapter consists of various sections. The first section describes \texttt{Yodl}
from the point of view of the systems administrator. Issues such as the
installation of the package are addressed here. The second section describes
\texttt{Yodl}'s technical implementation in some detail. Apart from the documentation
about \texttt{Yodl} given here, much can be found in the individual source
files. However, section \ref{ORGANIZATION} describes `the broad
picture'. Having read section \ref{ORGANIZATION}, it should be relatively easy
to determine what happens where inside the \texttt{Yodl} program and the \texttt{yodl-post}
post processor.

\section{Obtaining Yodl}
    \texttt{Yodl} and the distributed macro package can be obtained from
\texttt{https://fbb-git.gitlab.io/yodl/}. The associated git-repository page is 
located at \texttt{https://gitlab.com/fbb-git/yodl}.

Yodl can also be retrieved as a binary Debian package: to find it at 
\texttt{http://www.debian.org/distrib/packages} by entering \texttt{yodl} (in any
distribution) in the form-fields you'll find on that page.

\subsection{Installing Yodl}
            The binary package, distributed in \texttt{yodl-X.Y.Z\_a.b.c.deb} can be
installed using \texttt{dpkg -install yodl-X.Y.Z}. It installs:
    \begin{itemize}
    \item  \texttt{Yodl}'s binaries in \texttt{/usr/bin};
    \item  \texttt{Yodl}'s macros in \texttt{/usr/share/yodl}
    \item  \texttt{Yodl}'s documentation in \texttt{/usr/share/doc/yodl};
    \item  \texttt{Yodl}'s manpages in \texttt{/usr/share/man/man\{1,7\}};
    \end{itemize}
    Local installations, not using the Debian installation process, can be
obtained using the provided \texttt{icmake} build-script see below. An alternative
(cf. \texttt{contrib/build.pl}) is to use the contributed \texttt{build.pl} script. Note
that \texttt{build.pl} is not maintained by me. If you bump against problems when
using it, I'll probably not be able to help you out.

If a local installation is preferred or required, 
unpack the file \texttt{yodl-X.Y.Z.tar.gz}. Next, chdir to the directory 
\texttt{yodl-X.Y.Z}, and optionally tweak the file
\texttt{config} to your needs. Next, issue the command:
        \begin{verbatim}

    build programs    (or use `build programs strip' to strip the binaries)
    build macros
    build man
    build manual
        
\end{verbatim}

    followed by 
        \begin{verbatim}

   install programs WHERE        (install the programs under WHERE,
                                  e.g. install programs /usr/bin)

   install macros WHERE          (install the macros under WHERE
                                  e.g., install macros /usr/share/yodl)

   install man WHERE             (install the man-pages under WHERE
                                  e.g., install man /usr/share/man)
                                
   install manual WHERE          (install the manual under WHERE
                                  e.g., install manual /usr/share/doc/yodl)

   install docs WHERE            (install additional docs under WHERE
                                  e.g., install docs /usr/share/doc/yodl)
        
\end{verbatim}


The installation process installs the binaries, manual pages, other
documentation and macro files under the indicated directories. 

However, by far the easiest way to install a binary distribution is to use
the Debian \texttt{dpkg +NOTRANS(-\{\}-\{\})install yodl$*$.deb} command. \texttt{Dpkg} installs the
various parts according to Debian's conventions under \texttt{usr/}. 

Installation from source requires you to have the following programs
installed on your system: 
    \begin{itemize}
    \item  A recent \textbf{C} compiler and run-time environment. A POSIX-compliant
compiler, libraries and set of header files should work without problems. 
    \item  A recent installation of \texttt{Icmake}: \texttt{Icmake} is part of the
standard Debian distribution, and can also be obtained from 
\texttt{https://fbb-git.gitlab.io/icmake/}
    \item  Standard tools, like \texttt{sed}, \texttt{grep}, \texttt{perl}, etc..
    \item  \texttt{/bin/sh}: a POSIX-compliant shell interpreter. The GNU shell
interpreter \texttt{bash} can be used instead.
    \end{itemize}

\section{Organization of the software}\label{ORGANIZATION}
    This section describes the organization of the source files. Its contents are
not necessarily relevant for the binary distribution. The section is probably
most useful to those readers who want to be able to extend or who want to do
maintenance on \texttt{Yodl}'s sources, or who want simply to understand what's
happening inside the \texttt{Yodl} program. 

Much of the documentation is provided in the individual source files
themselves. This section, however, should offer the `broad picture', allowing
you to understand the logic behind \texttt{Yodl} relatively fast.

\subsection{Subdirectories and their meanings}
        After unpacking \texttt{Yodl}'s source archive, the following directories are available:
    \begin{itemize}
    \item  \texttt{yodl}: the root-directory of the \texttt{Yodl} tree. All sources and
program maintenance scripts are found in or below this directory.
    \item  \texttt{yodl/macros}: This directory contains all the macro
definitions of the standard macro package. It contains the following
subdirectories: 
        \begin{itemize}
        \item  \texttt{yodl/macros/in}: This directory contains 
generic macro files. These macro files contain the word \texttt{@STD\_INCLUDE@},
which is replaced by the standard include directory used in a particular
distribution.
        \item  \texttt{yodl/macros/rawmacros}: This directory contains the raw
macro definition files themselves. One file per raw macro. A raw macro
contains the implementations of that macro for \emph{all} supported conversion
types, and has the extension \texttt{.raw}. Furthermore, this directory contains
some support scripts: \texttt{create, separator.pl, startdoc.pl}.
        \item  \texttt{yodl/macros/yodl}: this is the directory to contain \texttt{Yodl}'s
standard macros. The (recursive) contents of this directory is eventually
copied by the installation procedure to the \texttt{.../share/yodl} directory,
which then becomes \texttt{Yodl}'s standard include directory.
        \item  \texttt{yodl/macros/yodl/chartables}: This directory contains 
character-translation tables for various target languages.
        \item  \texttt{yodl/macros/yodl/xml}: This directory contains the XML frame
files, used to convert \texttt{Yodl} documents to XML, as implemented by the
`webplatform' of the University of Groningen. All these frame files have the
extensions \texttt{.xml}.
        \end{itemize}
    \item  \texttt{yodl/man}: The raw source files of all man-pages:
manpages of the \texttt{Yodl} program itself, of the yodl post-processor, of the
conversion scripts, of the builtin-functions, of the standard macros and of
\texttt{Yodl}'s \texttt{manpage} and \texttt{letter} document types. These raw source files have
the extensions \texttt{.in}, indicating that they may contain \texttt{@STD\_INCLUDE@}
words, which is replaced by the eventually used standard include path.
        \begin{itemize}
        \item  \texttt{yodl/man/1}: The destination for \texttt{Yodl}'s manual pages in
section 1 (programs).
        \item  \texttt{yodl/man/7}: The destination for \texttt{Yodl}'s manual pages in
section 7 (macro packages and conventions).
        \end{itemize}
    \item  \texttt{yodl/manual}: The source files of the complete
\texttt{Yodl} manual, as well as the directories for the various converted formats.
    The script \texttt{build}, found in this directory, constructs the manual in
the subdirectories:
        \begin{itemize}
        \item  \texttt{yodl/manual/html}: the HTML-converted manual;
        \item  \texttt{yodl/manual/latex}: the \LaTeX{}-version of the manual;
        \item  \texttt{yodl/manual/pdf}: the pdf-version of the manual;
        \item  \texttt{yodl/manual/ps}: the PostScript-version of the manual;
        \item  \texttt{yodl/manual/txt}: the plain text-version of the manual;
        \end{itemize}
    \item  \texttt{yodl/manual/}: The source files of the complete
    The \texttt{Yodl} document files themselves are located in subdirectories of this
directory. They are:
        \begin{itemize}
        \item  \texttt{yodl/manual/converters}
        \item  \texttt{yodl/manual/intro}
        \item  \texttt{yodl/manual/macros}
        \item  \texttt{yodl/manual/technical}
        \item  \texttt{yodl/manual/userguide} (and various subdirectories)
        \end{itemize}
    \item  \texttt{yodl/scripts}: support scripts used by the building process:
\texttt{configreplacements} replaces \texttt{@XXX@} words by their actual values as
found in \texttt{yodl/src/config.h}; \texttt{yodl2whatever.in} is the generic
yodl-converter, calling macros specific for a particular conversion type. This
generic converter is installed in \texttt{.../bin/}, together with specific
converters, installed as soft-links to this generic converter.
    \item  \texttt{Yodl}'s base directory contains sub-directories holding the source
files of the \textbf{C} programs \texttt{Yodl} and \texttt{yodl-post}, as well as all auxiliary
directories containing sources of the (logical) components of these
programs. Most of these components are like \textbf{C++} classes in that they
define a building block of the \texttt{Yodl} and/or \texttt{yodl-post} program. Their
organization, interaction and relationship is described below. They are:
        \begin{itemize}
        \item  \texttt{yodl/args}: the component handling the command-line
arguments; 
        \item  \texttt{yodl/builtin}: the component handling \texttt{Yodl}'s builtin
functions;
        \item  \texttt{yodl/chartab}: the component handling \texttt{Yodl}'s
character table type;
        \item  \texttt{yodl/counter}: the component handling \texttt{Yodl}'s
counter type;
        \item  \texttt{yodl/file}:  the component handling all file
operations (locating, opening, etc.);
        \item  \texttt{yodl/hashitem}: key/value combinations stored in
\texttt{Yodl}'s hashtable;
        \item  \texttt{yodl/hashmap}: \texttt{Yodl}'s hashtable;
        \item  \texttt{yodl/lexer}: \texttt{Yodl}'s lexical scanner: this component
consumes the \texttt{.yo} file, and produces a continuous stream of tokens to be
handled by another component: the parser.
        \item  \texttt{yodl/lines}: the component storing lines of text,
used by \texttt{yodl-post}. 
        \item  \texttt{yodl/macro}: the component handling \texttt{Yodl}'s
macro type;
        \item  \texttt{yodl/message}: the component handling all messages
(warnings, errors, verbosity settings, etc.).
        \item  \texttt{yodl/new}: the component handling all memory
allocations (except for duplicating \emph{strings}, which is handled by the
root-component). 
        \item  \texttt{yodl/ostream}: the component handling all \texttt{Yodl}'s
output to its output-file (\texttt{Yodl} may also output to strings, which is not
handled by the ostream component). 
        \item  \texttt{yodl/parser}: the component handling the tokens
produced by the lexer-component. This component governs all actions to be
taken during a conversion. Its actions all derive from its function
\texttt{parser\_process()}. 
        \item  \texttt{yodl/postqueue}: the component handling the
postprocessing required by most conversions.
        \item  \texttt{yodl/process}: the component handling the execution
of child- or system-processes.
        \item  \texttt{yodl/queue}: the component allowing the lexical
scanner to queue its input, awaiting further processing. 
        \item  \texttt{yodl/root}: the component defining some basic
typedefs and enumerations, as well as the \texttt{new\_str()} function duplicating a
string, and the \texttt{out\_of\_memory()} function handling memory allocation
failures. 
        \item  \texttt{yodl/stack}: the component implementing a stack
data structure.
        \item  \texttt{yodl/string}:  the component implementing a
text-storage data structure and its functionality.
        \item  \texttt{yodl/strvector}:  the component implementing a table of
\texttt{SUBST} key-value pairs.
        \item  \texttt{yodl/subst}:  the component handling \texttt{Yodl}'s
SUBST definitions;
        \item  \texttt{yodl/symbol}:  the component handling \texttt{Yodl}'s
symbol type;
        \item  \texttt{yodl/yodl}: the sources of the \texttt{Yodl} program
itself. This directory also contains the implementations of all builtin
functions, whose filenames all start with \texttt{gram\_} (E.g.,
\texttt{gramaddtocounter.c}). 
        \item  \texttt{yodl/yodlpost}: the sources of the \texttt{yodl-post}
program. 
        \end{itemize}
    The script \texttt{build}, found in this directory, compiles  the programs
and macros, storing them in:
        \begin{itemize}
        \item  \texttt{tmp/install/usr/bin} (the binary programs)
        \item  \texttt{tmp/install/usr/share/yodl} (the macros)
        \item  \texttt{tmp/install/usr/share/man} (the man-pages)
        \item  \texttt{tmp/install/usr/share/doc} (the manual and additional
                documentation) 
        \end{itemize}
    \end{itemize}

\section{Yodl's component interrelations and component setup}
        \texttt{Yodl}'s components show a strict hierarchical ordering. This allows the testing
and development of components placed nearer to the component's tree without
considering anything that's placed farther away.

The following piece of `ascii-art' shows the relationships for the \texttt{Yodl}
program. The root of the tree starts at the top, at the \texttt{root} component. 
The tree can be read from the top to the bottom, where each horizontal line
starts a level of components mentioned immediately below it, and each vertical
route through the figure a series of components whose functioning depend on at
least the components mentioned earlier. 

However, a more natural way to look at it is to start somewhere in the
tree, and see what's envountered going up. Doing so, all components that
are required are visited. Once the figure shows a 
        \begin{verbatim}

        |
    --- | ---
        |
        
\end{verbatim}

    construction. This means that the horizontal line is not related to the
vertical dependency crossing (but not touching) it.

\begin{verbatim}

                                root
                                |                        
                                message
                                |
                                new
                                |                             
                    +-------+---+-------+
                    |       |           |                    
                    string  queue       stack                
                    |       |           |                    
    +--+--+---------+       |           hashitem               
    |  |  |         |       |           |                    
    |  |  strvector |       |           |                    
    |  |  |         |       |           |                    
    |  |  +---------+       |           |                    
    |  |            |       |           |                    
    |  args         subst   |           hashmap              
    |  |            |       |           |                    
    |  |            +-------+       +---+-------+
    |  |                    |       |           |
    |  |                    |       symbol  +---+----+-------+-------+
    |  |                    |       |       |        |       |       |
    |  +------------+------ | ------+       chartab  counter macro   builtin
    |               |       |               |        |       |       |     
    |               file    |               +---+----+-------+-------+
    |               |       |                   |
    |               +---+---+                   |                         
    |                   |                       |
    |               +---+---+                   |
    |               |       |                   |
    process         lexer   ostream             |
    |               |       |                   |
    |               +-------+-------+-----------+
    |                               |
    |                               parser 
    |                               |
    +-------------------------------+
                                    |
                                    (yodl)   
    
\end{verbatim}


A similar, albeit much simpler, tree can be drawn for \texttt{yodl-post}. Here
is the organization of the components for the \texttt{yodl-post} program:
        \begin{verbatim}

                                root
                                |                        
                                message
                                |
                                new
                                |                             
                      +-----+---+---+
                      |     |       |
                      |     |       |
                      lines string  hashitem
                      |     |       |
                      |     args    hashmap
                      |     |       |
                      |     +-------+
                      |     |
                      |     file
                      |     |
                      +-----+
                            |
                            postqueue
                            |
                            yodl2html-post
        
\end{verbatim}


The source files of each component are organized as follows:
    \begin{itemize}
    \item  All the files of a component are stored in a directory, named after
the component. For example, the \texttt{counter} component is found in the
directory
        \begin{verbatim}

    yodl/counter
        
\end{verbatim}

    containing all the (source) files that define that component.
    \item  Each function is stored in a file of its own inside its 
component-directory. For example, the function \texttt{counter\_value()} is defined
in the source file \texttt{countervalue.c}.
    \item  The file names are identical to the names of the functions, except for
the fact that only lower case letters are used for the file names, and that
the file names never use underscore characters. 
    \item  The \texttt{.h} header files declare the functions that can be used by
other components. These functions are comparable to \textbf{C++}'s \emph{public}
members. Furthermore, these \texttt{.h} files define all structs and typedefs that
are required for other components to use a particular component. For example,
the \texttt{component.h} header file may contain
        \begin{verbatim}

#ifndef _INCLUDED_COUNTER_H_
#define _INCLUDED_COUNTER_H_

#include "../root/root.h"
#include "../hashmap/hashmap.h"

void        counter_add(HashItem *item, int add);   /* err  if no counter   */
bool        counter_has_value(int *valuePtr, HashItem *item);
Result      counter_insert(HashMap *symtab, char const *key, int value);
void        counter_set(HashItem *item, int value); /* err  if no counter   */
char const *counter_text(HashItem *item);       /* returns static buffer    */
int         counter_value(HashItem *item);      /* err  if no stack/item    */

#endif
        
\end{verbatim}

    \item  All functions declared in \texttt{.h} file start with the name of the
component, and often contain an initial pointer to some \texttt{struct} containing
the essential fields that are associated with that particular component. For
example, most \texttt{counter\_} functions have a \texttt{HashItem $*$} as their first
argument, as a \texttt{HashItem} is normally used to store the details about a
counter. 
    \item  The modifier \texttt{const} is used with pointers to indicate that the
information pointed to by the pointer is `owned' by the provider of that
information. With parameters it indicates that the caller owns the
information, and the function will not modify the provided info; with return
types it indicates that the function `owns' the returned information, which
therefore may not be modified (or freed) by the caller of that function (e.g.,
\texttt{char const $*$counter\_text}). The absence of \texttt{const} in combination with
pointers indicates that the information pointed to by the pointer could, in
principle, be modified by the code receiving the pointer value.
    \item  Most components also show a \texttt{.ih} file, a so-called \emph{internal
header} file. The internal header declares `internal support functions', not
to be used by other parts of the software, and defines internal
typedefs. Since they are an essential ingredient of the component, all these
internal headers start to include the component's \texttt{.h} file, followed by the
declarations of the `private' functions. All these private functions start
with abbreviated component names, like \texttt{co\_} in the case of counters. Here
is a possible implementation of the \texttt{counter.ih} internal header file:
        \begin{verbatim}

#include "counter.h"

#include <stdio.h>

#include "../stack/stack.h"
#include "../message/message.h"
#include "../new/new.h"

Stack  *co_construct(int value);
Stack  *co_sp(HashItem *item, bool errOnFailure);
        
\end{verbatim}

    \item  The combination of \texttt{.h} and \texttt{.ih} files define the dependencies
of the component in the component hierarchy. As can be seen, \texttt{counter}
depends on \texttt{stack, message, new, hashmap} and \texttt{root}. The actual
dependency listing may be a bit more complex, as some \texttt{.h} files themselves
depend on other \texttt{.h} files. This is clearly visible in the \texttt{counter.h}
file. The class hierarchy given earlier shows the final component
dependencies.
    \item  A \texttt{.h} file of a component \texttt{X} \emph{never} includes a \texttt{.ih}
file of component \texttt{Y}, but only the \texttt{.h} files of other components. 
    \end{itemize}

\section{The token-producer `lexer\_lex()'}
        Tokens are produced by the lexical scanner. The function \texttt{lexer\_lex()}
produces the next token, which is always an element of the following set:
        \begin{verbatim}

    TOKEN_UNKNOWN,          /* should never be returned */

    TOKEN_SYMBOL,     
    TOKEN_TEXT,         
    TOKEN_PLAINCHAR,        /* formerly: anychar */
    TOKEN_OPENPAR,
    TOKEN_CLOSEPAR,
    TOKEN_PLUS,             /* it's semantics what we do with a +, not      */
                            /* something for the lexer to worry about       */

    TOKEN_SPACE,            /* Blanks should be at the end                  */
    TOKEN_NEWLINE,

    TOKEN_EOR,              /* end of record: ends pushed strings           */
    TOKEN_EOF,              /* at the end of nested evaluations/eof         */
        
\end{verbatim}


In particular note the existence of a \texttt{TOKEN\_EOR} token: this token
indicates the end of a piece of text, a string, inserted into the input stream
by the \emph{parser}'s actions, when it calls \texttt{lexer\_push\_str()}. Such a
situation occurs in particular when a macro is evaluated: having read a macro,
and replacing its parameters \texttt{ARG1, ARG2, ... ARGn} by their respective
argumentes, the resulting string is pushed back into the input stream by
\texttt{lexer\_push\_str()}. This happens, e.g., inside the function
\texttt{p\_expand\_macro()}. An excerpt from this function shows this call:
        \begin{verbatim}

    void p_expand_macro(register Parser *pp, register HashItem *item)
    {
        ...
            if (argc)                           /* macro with arguments     */
                p_macro_args(pp, &expansion, argc);
            ...
            lexer_push_str(&pp->d_lexer, string_str(&expansion));
        ...
    }
        
\end{verbatim}


The parser repeatedly calls the lexer's function \texttt{lexer\_lex()}. This happens
most dramatically inside the function \texttt{p\_parse()}, defined by a mere single
statement:
        \begin{verbatim}

    void p_parse(register Parser *pp)
    {
        while ((*pp->d_handler[lexer_lex(&pp->d_lexer)])(pp))
            ;
    }
        
\end{verbatim}

    Here, in a loop continuing until the handler indicates that the loop
should terminate, \texttt{lexer\_lex()} is called to produce the next token. The
finite state automaton (FSA) implemented here is described in more detail in
section \ref{PARSERFSA}.

Apart from here, \texttt{lexer\_lex()} is called from four other locations
inside the \texttt{parser} component:
    \begin{itemize}
    \item  \texttt{parser\_parlist()} repeatedly calls \texttt{lexer\_lex()} to obtain all
the tokens associated with a parameter list;
    \item  \texttt{p\_handle\_default\_newline()} repeatedly calls \texttt{lexer\_lex()} to
obtain all the tokens until all consecutive spaces and newlines are read. This
is one of the handlers of the parser FSA \ref{PARSERFSA};
    \item  \texttt{p\_no\_user\_macro()} calls \texttt{lexer\_lex()} to determine whether a
`no user macro' has been detected;
    \item  \texttt{p\_plus\_series()} calls \texttt{lexer\_lex()} to determine whether a
\texttt{+symbol} has been encountered.
    \end{itemize}

So, \texttt{lexer\_lex()} is the parser's `window to the outside world'. The
\texttt{lexer\_lex()} function, however, is a fairly complex animal:
    \begin{itemize}
    \item  \texttt{lexer\_lex()}: returns next token.  It calls \texttt{l\_lex()} to
retrieve the next character from the info waiting to be read;
    \item  \texttt{l\_lex()}: calls \texttt{l\_nextchar()} to obtain the next token, and
appends all char-tokens to the lexer's matched text buffer. Potential compound
symbols (words, numbers) are combined by \texttt{l\_compound()} and are then
returned as \texttt{TOKEN\_PLAINCHAR} or as a compound token like \texttt{TOKEN\_IDENT};
    \item  \texttt{l\_nextchar()}: calls \texttt{l\_get()} to get the next character, and
handles escape chars, including \textbackslash{} at eoln;
    \item  \texttt{l\_get()}: if there are no media left, \texttt{EOF} is returned.  If
there are media left, then \texttt{l\_subst\_get()} retrieves the next character,
handling possible \texttt{SUBST} definitions. At the end of the current input
buffer (memory buffer or file) \texttt{l\_pop()} attempts to reactivate the previous
buffer. If this succeeds, \texttt{EOR} is returned, otherwise \texttt{EOF} is returned.
So, the lexer is not able to switch between truly nested media, as in
\texttt{EVAL()} calls, but is able to switch between nested buffers resulting from
replacing macro calls by their definitions;
    \item  \texttt{l\_subst\_get()}: calls \texttt{l\_media\_get()} to get the next char from
the media. The next char is passed to subst\_find() which is a FSA trying to
match the longest \texttt{SUBST}. This may be done repeatedly, and eventually
\texttt{subst\_text()} either returns a substitution text, or the next plain
character. A substitution text is pushed onto the lexer's media buffer. The
next character returned is then the next one to appear at the lexer's media
buffer;
    \item  \texttt{l\_media\_get()}: If the current active source of information is a
file, it returns the next character from that file or \texttt{EOF} if no such char
is available anymore.  If the current active source is a memory buffer then
the next char from the buffer is returned. If the buffer is empty \texttt{EOF} is
returned. The media buffer is a circular, self-expanding Queue.
    \end{itemize}

\section{The Parser's Finite State Automaton}\label{PARSERFSA}
        The  input files are parsed by  the function
\texttt{parser\_process()}, which is called by \texttt{Yodl}'s \texttt{main()} function.

This processor pushes all files that were specified on the input in reverse
order on the input stack, and then calls the support function \texttt{p\_parse()} to
process each of them in turn.

\texttt{p\_parse()} is an very short function: it contains one \texttt{while} statement,
repeatedly calling a \emph{handler} appropriate  with the next token returned
by the lexical scanner. Therefore, the parser can be considered as a table
driven finite state automaton (FSA). 

The table itself is initialized in \texttt{parser/psetuphandlerset.c}, by the
function \texttt{p\_setup\_handlerSet()}. It fills the two dimensional array
\texttt{ps\_handlerSet} with the address of the function that must be called for
each combination of parser-state (as defined in the \texttt{HANDLER\_SET\_ELEMENTS}
enum) in \texttt{parser/parser.h} and token that may be produced by the lexical
scanner (as defined in the \texttt{LEXER\_TOKEN} enum in \texttt{lexer/lexer.h}).
Depending on the situation the parser encounters, it may point its pointer
\texttt{d\_handler} to a particular \emph{row} in this table. Since the rows represent
the parser's states, states can be switched easily by reassigning this
pointer. This happens all the time. For example, when in
\texttt{parsernameparlist.c} a name must be retrieved from a parameter list, it
calls \texttt{ parser\_parlist(pp, COLLECT\_SET)}, which function temporarily
switches the parser's state to \texttt{COLLECT\_SET}, returning the parameter list's
contents. to its caller.

The functions whose addresses are stored in the various column-elements of the
array \texttt{ps\_handlerSet} are called \emph{handler}. Most handlers are named
\texttt{p\_handle\_$<$state$>$\_$<$lextoken$>$()}, where \texttt{$<$state$>$} is the name of the
associated parser state, and \texttt{$<$lextoken$>$} is the name of the appropriate
lexical scanner token. For example, \texttt{p\_handle\_default\_symbol()} is the
handler that was designed for the situation where the parser is in its
initial, or default, state, and the lexical scanner returns a \texttt{TOKEN\_SYMBOL}
token. Some handlers have more generic names, like \texttt{p\_handle\_unknown()},
which is some sort of emergengy exit, called when the parser doesn't know what
to do with the received lexical scanner token (a situation which should, of
course, not happen).

In version 2.00, the following handler functions are available:
    \begin{itemize}
    \item  \texttt{p\_handle\_insert(Parser $*$pp)}: insert matched text
    \item  \texttt{p\_handle\_default\_eof(Parser $*$pp)}: return false
    \item  \texttt{p\_handle\_default\_newline(Parser $*$pp)}: series of \textbackslash{}n's
    \item  \texttt{p\_handle\_default\_plus(Parser $*$pp)}: handle + series
    \item  \texttt{p\_handle\_default\_symbol(Parser $*$pp)}: handle all symbols
    \item  \texttt{p\_handle\_ignore(Parser $*$pp)}: ignores token
    \item  \texttt{p\_handle\_ignore\_closepar(Parser $*$pp)}: handle openpar
    \item  \texttt{p\_handle\_ignore\_openpar(Parser $*$pp)}: handle openpar
    \item  \texttt{p\_handle\_noexpand\_plus(Parser $*$pp)}: handle + series
    \item  \texttt{p\_handle\_noexpand\_symbol(Parser $*$pp)}: handle executed symbols in
        NOEXPAND
    \item  \texttt{p\_handle\_parlist\_closepar(Parser $*$pp)}: handle closepar
    \item  \texttt{p\_handle\_parlist\_openpar(Parser $*$pp)}: handle openpar
    \item  \texttt{p\_handle\_skipws\_unget(Parser $*$pp)}: unget received text 
    \item  \texttt{p\_handle\_unexpected\_eof(Parser $*$pp)}: EMERG exit
    \item  \texttt{p\_handle\_unknown(Parser $*$pp)}: emergency exit
    \end{itemize}

The parser has the following states: 
    \begin{description}
    \item[COLLECT\_SET] \ \\ 
       retrieves parameter lists as they are encountered on the input. The
        parameter list is not processed in any way, and omits the surrounding
        parentheses. So, when entering this state (e.g., in the function
        \texttt{parser\_parlist()}), a parameter list is completely consumed, but
        only its contents (and not its surrounding parentheses) become
        available. In fact, when entering a state, \texttt{p\_parse()} can be called
        again to process the information in this state. Eventually a state
        will encounter some stopping signal (e.g., a non-nested close
        parenthesis in the collect-state results in
        \texttt{p\_handle\_parlist\_closepar()} to return \texttt{false}, thus terminating
        \texttt{p\_parse()}), terminating that particular state. The function
        \texttt{parser\_parlist()} shows this process in further detail.
    \item[DEFAULT\_SET] \ \\ 
       In this state macros, builtins etc. are processed.  For most of the
        tokens that can be returned by the lexical scanner
        \texttt{p\_handle\_insert()} is called.  \begin{itemize} \item  When receiving EOF
        it tries to switch to the next file on the stack (or stop), \item  When
        receiving a symbol, it either handles them as plain symbols or as
        macros, \item  When receiving newlines they are handled (maybe merging
        them by calling a paragraph handler (if defined)), \item  Series of +
        characters are handled \item  All other tokens are inserted into the
        current output medium (which may be a file, but it may also be a
        memory buffer).  \end{itemize}
    \item[IGNORE\_SET] \ \\  
       In this state a parameter list is completely skipped. This state is
        used, for example, when processing \texttt{COMMENT()}.
    \item[NOEXPAND\_SET] \ \\ 
       The contents of a parameter list is not expanded, but \texttt{CHAR} builtins
        \emph{are} processed. In \texttt{Yodl} version 2.00 there is only one situation
        where this state (and its companion state NOTRANS\_SET) is actively
        used: \texttt{Yodl}'s function \texttt{gram\_NOEXPAND()} uses these states to
        retrieve the contents of a no-expanded or no-transed parameter list.
    \item[NOTRANS\_SET] \ \\ 
       When the parser is in this state, a parameter list is inserted using
        the currently active insertion function (inserting to file or memory)
        It is identical to the NOEXPAND\_SET state, but the character
        translation table is not used in the NOTRANS\_STATE, whereas it is used
        in the NOEXPAND\_STATE.
    \item[SKIPWS\_SET]\ \\ 
       In this state all white-space characters are consumed. The lexical
        scanner merely returns the next non-whitespace character. This state
        is used, e.g., to skip the white space between multiple parameter
        lists when they are defined for macros.
    \end{description}

\section{Adding a new macro}
    With the advent of \texttt{Yodl} V 2.00, \emph{raw macros files} are introduced. A raw
macro file defines one macro, and \emph{all} of its conversions. The raw macro
files must be organized as follows:
        \begin{verbatim}

    <STARTDOC>
    macro(name(arg1)(arg2)(etc))
    ( 

        Description of the macro `name', having arguments `arg1', `arg2',
        `etc', each argument is given its own parameter list. The names of the
        arguments in this description should be chosen in such a way that they
        suggest their function or purpose. All macro descriptions starting
        with tt(<STARTDOC>) are included in both the `man yodlmacros'
        manpage and the description of the macro in the user guide. If this is
        not considered appropriate (e.g., tt(XX...()) macros are not described
        in these documents) then use tt(<COMMENT>) rather than
        tt(<STARTDOC>). 
    )
    <>
    DEFINEMACRO(name)(#)(
        statements of macro `name' expecting `#' arguments used by all
        conversions. This section is optional
    <html>
        statements that should be executed by the HTML converter
    <man ms>
        statements that should be executed by two converters. In this case,
        the `man' and `ms' converters
    <else>
        statements that should be executed by all converters not explicitly
        mentioned above
    <>
        statements of macro `name' expecting `#' arguments used by all
        conversions, having processed their specific statements. 
        This section is also optional
    )
        
\end{verbatim}

    When setting up these macro definitions, the \texttt{$<$$>$} tags must appear with
the initial documentation section. It must also appear when at least one
specific converter tag is used. For a macro which is converter independent,
the macro definition doesn't contain these pointed-arrow tags. 

When writing standard \texttt{Yodl} macros, each macro should be stored in a file
\texttt{`name'.raw}, where \texttt{`name'} is the lower-case name of the macro. This
file should then be kept in the \texttt{macros/rawmacros} directory. The
\texttt{macros/build std} call then adds the macro (filtering only the required
statements per conversion) to each of the standard conversion formats.

If the macro requires a counter or symbol, consider defining the counter
or symbol in, respectively, \texttt{@counters} and \texttt{@symbols}. Furthermore,
consider \emph{pushing} and \emph{popping} these `variables', rather than plain
assigning them, to allow other macros to use the variables as well. A case in
point is the counter \texttt{XXone} which was added to the set of counters
representing a \emph{local counter}. Macros may \emph{always} push \texttt{XXone} and pop
\texttt{Xxone}, but should never reassign \texttt{XXone} before its value has been
pushed. For \texttt{Yodl} version 2.00 only \texttt{XXone} was required, but other local
counters might be considered useful in the future. In that case, \texttt{XXtwo},
\texttt{XXthree} etc. are used. For local symbold \texttt{XXs} prefixes are used:
\texttt{XXsone}, \texttt{XXstwo}, etc.

\section{The Yodl post-processor}\label{POSTPROCESSOR}
    With \texttt{Yodl} version 2.00 the old-style post-processor has ceased to exist. Also,
the \texttt{.tt(Yodl)TAGSTART.} and \texttt{.tt(Yodl)TAGEND.} symbols no longer appear in
\texttt{yodl}'s output. 

Instead, a system using an \emph{index} file was adopted. When converting
information, \texttt{yodl} produces an output file and an associated \emph{index}
file. The index file defines \emph{offsets} in the output file up to where
certain actions are to be performed. Each line in the index file contains the
required information of one \emph{directive} for \texttt{yodlpost}. For example:
        \begin{verbatim}

    0 set extension man
    53 ignorews
    2112 verb on
    2166 verb off
    80007 ignorews
    80065 copy
    80065 mandone
        
\end{verbatim}

    Entries can be written into the index file using the \texttt{INTERNALINDEX}
builtin function. This function has one argument: the information following
the offset where it is called. So, there will be a \texttt{INTERNALINDEX(set
extension man)} in the macro definitions for this particular conversion
(obviously it is a \texttt{man} conversion. The particular \texttt{INTERNALINDEX} call
is found in the standard \texttt{man.yo} macro definition file). 

When \texttt{yodlmacros} is called, it processes the directives on the \texttt{idx}
file in two steps:
    \begin{itemize}
    \item  First, it reads all directives, and constructs a queue of actions to
perform. During this phase it solves all references to, e.g., labels
defined in the \texttt{s} processed by \texttt{yodl}. This queue is constructed by a
\texttt{PostQueue} object, during its construction phase. 

Postprocessing is realized by a template-method design pattern-like
construction in C.

The algorithm proceeds as follows:

Each element of the index file is read, and its keyword (the word
following the offset) is determined. Then the 'construct' function associated
with that keyword is called. The `construct' functions return pointers to
HashItem elements, which areprocessed by storing them either into the the
symbol table or into the work-queue. The construct functions can use all
\texttt{PostQueue, New, Message String Args} and \texttt{File} functions. Which function
is actually called is determined in the file \texttt{yodlpost/data.c}, where the
array \texttt{Task task{[}{]}} is initialized. \texttt{Task} structs have three elements:
        \begin{itemize}
        \item  \texttt{char const $*$d\_key} points to the name of the keyword that 
triggers the corresponding \texttt{Task} struct;
        \item  \texttt{HashItem $*$($*$d\_constructor)(char const $*$key, char $*$rest)}
points to the function that is called when the task struct is created.
        \item  \texttt{ void ($*$d\_handler)(long offset, HashItem $*$item)} points to the
function that is called when the queue is processed.
        \end{itemize}

\item  Then, when all commands are available, the queued commands are
processed. For this, the appropriate 'handle' functions are called. 
    \end{itemize}

For example, when the \texttt{INTERNALINDEX(htmllabel ...)} is specified, the
function \texttt{construct\_label()} is called. This function receives a line line
        \begin{verbatim}

    432 label Overview
        
\end{verbatim}

    meaning that this label has been defined in offset 432 in the file
generated by \texttt{yodl}. The \texttt{construct\_label()} function now:
    \begin{itemize}
    \item  Stores the current section number, the filecount and the
sectionnumber in a HashItem.
    \item  Stores the hashitem inside its hash-table.
    \end{itemize}

Then, when the queue is processed, a reference to this label may be
encountered. This is signalled by an \texttt{INTERNALINDEX(ref Overview)} call. In
this case the \texttt{construct\_ref()} function doesn't have to do much. Here it is
the handler that's doing all the work: 
    \begin{itemize}
    \item  First it looks up the label in the symbol table. The label should be
there, as a result of the earlier construction of the symbol table during the
\texttt{postqueue\_construct()} call. 
    \item  Then it copies the file written by \texttt{yodl} up to the offset
mentioned in the the \texttt{ref} command.
    \item  Then (since we're talking about an html-specific reference) the
appropriate \texttt{$<$a href=...} command is inserted into the current output file.
    \end{itemize}

When references are solved in text-files, the \texttt{INTERNALINDEX(txtref
...)} command is used. Here, \texttt{construct\_ref()} can still be used, but a
specific \texttt{handle\_txt\_ref()} function is required. 

New postprocessing labels can be constructed easily:
    \begin{itemize}
    \item  Add an element to the array \texttt{Task task{[}{]}} in
\texttt{src/yodlpost/data.c}. For example, add a line like:
        \begin{verbatim}

    {"verb",            construct_verb,         handle_verb},
        
\end{verbatim}

    \item  Declare the functions in \texttt{yodlpost.h}:
        \begin{verbatim}

    HashItem *construct_verb(char const *key, char *rest);
    void handle_verb(long offset, HashItem *item);
        
\end{verbatim}

    \item  The \texttt{construct\_verb()} function receives the key (e.g., \texttt{verb})
and any information that may be available beyond the key as a trimmed line
(not beginning or ending in white space). The construct function should return
a pointer to a hashitem, which can be constructed by
\texttt{hashitem\_construct()}. This function should be called with the following
arguments:
        \begin{itemize}
        \item  \texttt{VOIDPTR};
        \item  a pointer to some text to be stored as the hashitem's key (use an
empty string if nothing needs to be stored in a hashtable);
        \item  A pointer to the information associated with the key (use 0 if no
information is used; use \texttt{(void $*$)intValue} to store an \texttt{int} value. Note
that this is \emph{not} \texttt{(void $*$)\&intValue}: it is the value of the variable
that is interpreted as a pointer here).
        \item  The function that handles the destruction of the
value-information. Use \texttt{free} if some information was actually allocated and
must be freed. E.g.,\end{itemize}
        \begin{verbatim}

    hashitem_construct(VOIDPTR, "", new_str(rest), free);
        
\end{verbatim}

    Use \texttt{root\_nop} if no allocation took place. E.g.,
        \begin{verbatim}

    hashitem_construct(VOIDPTR, "", (void *)s_lastLabelNr, root_nop);
        
\end{verbatim}

    Often the constructor doesn't have to do anything at all. In that case,
initialize the \texttt{Task} element with the existing \texttt{construct\_nop}
function. E.g., 
        \begin{verbatim}

    {"drainws",         construct_nop,          handle_drain_ws},
        
\end{verbatim}

    \item  The \texttt{handle\_verb()} function is called when the file produced by
\texttt{yodl} is processed by \texttt{postqueue\_process()}. This happens immediately
after \texttt{postqueue\_construct()}. The handler is called with two arguments: 
        \begin{itemize}
        \item  Its first argument is the offset where the \texttt{INTERNALINDEX} call
was generated. The handler should make sure that \texttt{yodl}'s output file is
processed up to this offset. Not any further. If a simple copy is required the
function \texttt{file\_copy2offset()} is available. E.g.,
        \begin{verbatim}

    file_copy2offset(global.d_out, postqueue_istream(), offset);
        
\end{verbatim}

    Note its arguments: the output and input file pointers are available
through, respectively, \texttt{global.d\_out} and \texttt{postqueue\_istream()}. 
        \item  Its second argument is a pointer to the hashitem struct
originally created by the matching \texttt{construct...()} function. The handler
should \emph{not} free the information it receives. The function
\texttt{postqueue\_process()} takes care of that. 
       \end{itemize}
    Examples of actual \texttt{construct...()} and \texttt{handle...()} functions can be
found in \texttt{src/yodlpost}. 
    \end{itemize}

\end{document}
