<! banner_id ><html>
<head>
<title>Yodl 1.31.18 </title>
</head>
<body text="#27408B" bgcolor="#FFFAF0" >
<hr>
<ul>
<li> <a href="refman03.html">Next chapter</a>
<li> <a href="refman01.html">Previous chapter</a>
<li> <a href="refman.html">Table of contents</a>
</ul>
<hr>
<a name="l4"></a>
<h1>Chapter 2: Yodl User Guide</h1>
<a name="userguide"></a>This section describes the <code>yodl</code> 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 <a href="refman03.html#macropackage">3</a>).
<p>The <code>yodl</code> program the main converter of the Yodl package. The basic usage
of the <code>yodl</code> program, <code>yodl</code>'s built-in macros, and the syntax of the
Yodl language is described here.
<p><a name="l5"></a>
<h2>2.1: Using the yodl program</h2>
<a name="using"></a>The <code>yodl</code> program is reads one or more input files, interprets the commands
therein, and writes one output file. The program is started as:
<p><center>
<code>yodl</code> <em>flags</em> <em>inputfile</em> <em>[inputfile...]</em>
</center>
<p>In this specification, the flags are optional and may be:
<p><dl>
<p><li > <code>-D</code> <em>name</em>: Defines <em>name</em> as a symbol. This flag is similar
to the <code>DEFINESYMBOL</code> statement which may appear in the text. The
purpose of defining symbols is described later.
<p><li > <code>-I</code> <em>directory</em>: This defines the system-wide include directory
where <code>yodl</code> searches for its input files when they cannot be located by
their bare name. E.g. a statement to include a given file:
<p><pre>
INCLUDEFILE(latex)
</pre>
<p>will search for the file <code>latex</code> 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 <code>yodl</code> program.
<p>The name of the included file (<code>latex</code> in the above example) is the bare
name, the <code>yodl</code> program will supply a default extension if necessary.
<p>The <code>-I</code> flag overrules Yodl's built-in name for the system-wide include
directory. The built-in name is defined when compiling Yodl, and is usually
<code>/usr/local/lib/yodl</code>.
<p><li > <code>-l</code> <em>number</em>: This flag controls the <em>live data</em> policy;
<em>number</em> is default 0. This means that macros that can access your
operating system (these are the macros <code>SYSTEM</code> and <code>PIPETHROUGH</code>) are
disabled. The <em>number</em> valuse can be:
<p><dl>
<p><li > 0: (the default): No potentially harmful macros are allowed.
<p><li > 1: The macros can be executed, but only after user confirmation is
obtained. The macros in question are shown while the Yodl document is
processed.
<p><li > 2: The macros are executed, but also shown during the Yodl run.
<p><li > 3: The macros are executed, and not shown during the run. Use
<code>-l3</code> only when a document has proven `unharmful'.
<p></dl>
<p>These macros are further discussed in the sections <a href="refman02.html#system">2.3.32</a> (the
<code>SYSTEM</code> macro) and <a href="refman02.html#pipethrough">2.3.25</a> (the PIPETHROUGH macro).
<p><li > <code>-o</code> <em>file</em>: This option causes Yodl to write its output to <em>
file</em>. By default, the output goes to the standard output stream. E.g.,
you can use the <code>yodl</code> program to read a file <code>input</code> and to write to
<code>output</code> with the following two commands:
<p><pre>
yodl input > output
yodl -ooutput input
</pre>
<p><li > <code>-P</code> <em>cmd</em>: This flag `pre-loads' the string <code>cmd</code> to the
<code>yodl</code> processor. It is as if the <code>cmd</code> were before any actual input.
<p>More than one <code>-P</code> <em>cmd</em> flags may be present on the command line.
Each of the commands is sent to the processor before any input is read.
<p><li > <code>-p</code> <em>maxpass</em>: This flag causes Yodl to abort when the number of
parsing cycles exceeds <em>maxpass</em>, which is usually 20. Exceeding this
number usually means a circular definition somewhere in the document. This
is the case when, e.g., a macro <code>a</code> expands to <code>b</code>, and <code>b</code> expands
again to <code>a</code>. Alternatively, the <em>maxpass</em> cycle can be exceeded when
a file <code>a.yo</code> includes <code>b.yo</code>, while <code>b.yo</code> includes <code>a.yo</code> etc..
<p><li > <code>-t</code>: This flag enables tracing: while parsing, Yodl writes its
output to the standard error stream. As is the case with the <code>-k</code> flag,
this option is for debugging purposes.
<p><li > <code>-v</code>: This flag increases Yodl's `verbosity level' and may occur
more than once. The presence of one <code>-v</code> causes Yodl to show which files
are parsed; four <code>-v</code>'s show the inner workings of Yodl's lexical
analyzer.
<p><li > <code>-w</code>: The presence of this flag caused Yodl to warn when, e.g.,
symbols are redefined.
<p></dl>
<p>The <em>inputfile</em> elements on the command line specify which files Yodl should
process. All names are supplied with an extension (this extension is
defined in the installation of Yodl and is usually <code>.yo</code>). The files are then
searched for `as-is', or in the system-wide include directory.
<p>Note that all filenames on the command line are input files. To define an
output file, either use the <code>-o</code> flag or redirect the output.
<p>
<p><a name="l6"></a>
<h2>2.2: The Yodl grammar</h2>
<a name="grammar"></a>The grammar which is used by the Yodl system mixes `real' text that should
appear on the output with commands for Yodl. The commands must follow a certain
grammar, which is described in this section.
<p>
<p><a name="l7"></a>
<h3>2.2.1: Language elements</h3>
<a name="elements"></a>The basic elements of the Yodl grammar are identifiers, names, numbers and
parameter lists.
<p><dl>
<p><p></p><dt><strong>Identifiers</strong><dd> are names that can have a special meaning in the Yodl
language. E.g., the sequence <code>INCLUDEFILE</code> is such an identifier: when
followed by a filename in parentheses, Yodl will take some special action
(in this case, read the file).
<p>Identifiers may consist of uppercase or lowercase characters. No other
characters may appear in them.
<p><p></p><dt><strong>A name</strong><dd> is a `one-word' sequence, i.e., a series of characters where
no spaces, tabs or newlines appear. E.g., the Yodl language requires a name
to follow the <code>INCLUDEFILE</code> identifier, enclosed in parentheses.
<p><p></p><dt><strong>Numbers</strong><dd> consist of digits. Yodl seldom uses numbers, but they are
required.
<p><p></p><dt><strong>Parameter lists</strong><dd> are the arguments that names or numbers that are
arguments to a Yodl command. A parameter list must be enclosed by
parentheses.
<p></dl>
<p>Basically, Yodl only does `something special' when it encounters a recognized
identifier, followed by a parameter list. Sometimes an identifier may be
followed by more than one parameter list, in that case, the action requires
more than one argument. The grammar of Yodl requires that the identifier and
its first parameter list follow right after each other, without intervening
spaces. That means that
<p><pre>
somemacro (argument)
</pre>
<p>will not start any Yodl action (supposing that <code>somemacro</code> is the name of a
defined macro), since the parameter list and the identifier are separated by a
space. The Yodl grammar is very strict in this sence; this rule however
simplifies the parsing process of the input.
<p>To make life easier for those who write documentation using Yodl, there <strong>may</strong>
be spaces or newlines between the parameter lists (i.e., between the first and
second parameter list, between the second and third, and so on). Therefore,
assuming that <code>somemacro</code> now is defined as a macro having three arguments,
the following will work:
<p><pre>
somemacro(argument one)
(and another argument, number two)
(and the last one)
</pre>
<p>Summarized, an identified macro is only expanded by Yodl when it is followed by
a parameter list without spaces in between. Further parameter lists may follow
separated by spaces, tabs or newline characters. All required parameter lists
must however be in the same input file.
<p>
<p><a name="l8"></a>
<strong>2.2.1.1: Unbalanced parameter lists</strong><p>
<a name="unbalanced"></a>Yodl recognizes the arguments to a macro as parameter lists, i.e., delimited by
<code>(</code> and <code>)</code>. As long as the number of opening and closing
parentheses matches, Yodl will correctly recognize the list. E.g., given a
hypothetical macro <code>somemacro</code>, the following code sample shows the macro
followed by one parameter list:
<p><pre>
somemacro(Here is a chunk of text.)
somemacro(Here is a some (more) text.)
</pre>
<p>A problem arises when the number of parentheses is unbalanced: i.e., when the
parameter list consists of more opening than closing parentheses or v.v.. To
handle such situations, Yodl offers a `literal-character' mechanism (see the
<code>CHAR</code> macro in <a href="refman02.html#char">2.3.3</a>) and a `global substitution' mechanism (see the
<code>SUBST</code> macro in <a href="refman02.html#subst">2.3.30</a>). For example, to send the text
<p><pre>
here's a ")" closing parenthesis
</pre>
<p>as an argument to our hypothetical macro <code>somemacro</code>, the following can be
used:
<p><pre>
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)
</pre>
<p>Both methods have disadvantages: the <code>CHAR</code> method requires you to remember
that an ASCII 41 is a closing parenthesis. The <code>SUBST</code> method defines a
string <code>closepar</code> that is <strong>always</strong> expanded to a closing parenthesis,
wherever in the text it occurs. Nevertheless, unbalanced parameter lists can
be handled by Yodl. (If the here described method proves to be too much of a
pain, I'll think of something. As for myself, I've <strong>never yet</strong> have felt the
need to use an unbalanced parameter list -- except in this document..) Also,
remember that unbalanced parenthesis pairs are only relevant in argument
lists. Yodl handles parentheses in normal text as ordinary characters.
<p>
<p><a name="l9"></a>
<h3>2.2.2: Line continuation</h3>
<a name="continuation"></a>
To make the typing of input easier, Yodl allows you to end a line with a
backslash character \ and to continue it on the next line. That way you can
split long lines to fit your screen. When processing its input, Yodl will treat
these lines as one long line, and will of course ignore the \ character. This
feature only works when the \ character is the last one on the line (no spaces
may follow).
<p>When the line <strong>following</strong> the one with the \ 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 <code>yodl</code> program.
<p>A trivial example is the following:
<p><pre>
Grampa and\
grandma are sitting on the sofa.
</pre>
<p>Due to the occurrence of the \ character in the sequence <code>and\</code>, Yodl will
combine the lines into
<p><pre>
Grampa andgrandma are sitting on the sofa.
</pre>
<p>Note that the spaces before <code>grandma</code> are ignored, since this is the second
line following a \ character.
<p>If you <strong>do</strong> want one or more spaces while joining lines with \, put the
spaces <strong>before</strong> the \ character.
<p>Summarized:
<p><dl>
<p><li > A Line that ends in a backslash character is merged with the
following line.
<p><li > This only occurs if the \ character is the <strong>last</strong> character of the
line, no spaces may occur after the character.
<p><li > When merging lines, Yodl ignores leading spaces of the second line.
<p></dl>
<p>The question is of course, how do you accomplish that a line really ends with
a \, when you do <strong>not</strong> want Yodl to merge it with the following line? In such
a case, type a space character following your \: Yodl won't combine the lines.
Or set the \ character as <code>CHAR(\)</code> or <code>CHAR(92)</code> (see section
<a href="refman02.html#char">2.3.3</a> for the <code>CHAR</code> macro). In my opinion, the ease of line
continuation in Yodl files outweighs the extra necessary actions to typeset a
real \ character at the end of a line.
<p><a name="l10"></a>
<h3>2.2.3: The +identifier sequence</h3>
<a name="plusident"></a>
One more feature of the Yodl language remains to be described. 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 <code>footnote</code> for you (someone did, in fact, see the next
chapter), to typeset footnotes. If you'd type in a document:
<p><pre>
The C Programming Languagefootnote(as defined by
Kernighan and Ritchie) ...
</pre>
<p>then of course Yodl would fail to see the start of a macro in the sequence
<code>Languagefootnote</code>. You could say
<p><pre>
The C Programming Language footnote(as defined by
Kernighan and Ritchie) ...
</pre>
<p>but that would introduce a space between <code>Language</code> 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.
<p>For these special situations, Yodl recognizes the <code>+identifier</code> sequence as
the start of a macro, while the <code>+</code> sign is effectively ignored. In the
above example you could therefore use
<p><pre>
The C Programming Language+footnote(as defined by
Kernighan and Ritchie) ...
</pre>
<p>The <code>+identifier</code> recognition only works when the identifier following the
<code>+</code> sign is a macro. In all other situations, a <code>+</code> is just a plus-sign.
<p>(The <code>+identifier</code> sequence furthermore plays an important role in macro
packages. If you're interested, see the file <code>shared.yo</code> which is by default
installed to <code>/usr/local/lib/yodl</code>.)
<p><a name="l11"></a>
<h2>2.3: Yodl's builtin commands</h2>
<a name="builtin"></a>As mentioned previously. Yodl's input consists of text and of commands. Yodl
supports a number of built-in commands which may either be used in a Yodl
document, or which can be used to create a macro package.
<p>Don't despair if you find that the description of this section is too
technical. Exactly for this reason, Yodl supports the macro packages to make
the life of a documentation writer easier. E.g., see chapter <a href="refman03.html#macropackage">3</a>
that describes a macro package for Yodl.
<p><a name="l12"></a>
<h3>2.3.1: ADDTOCOUNTER</h3>
<a name="addtocounter"></a>
The <code>ADDTOCOUNTER</code> macro adds a given value to a counter. It expects two
parameter lists: the counter name, and the value to add. The counter must be
previously created with <code>NEWCOUNTER</code>.
<p>The value to add can be negative; in that case, a value is of course
subtracted from the counter.
<p>See further section <a href="refman02.html#counters">2.6</a>.
<p><a name="l13"></a>
<h3>2.3.2: ATEXIT</h3>
<a name="atexit"></a>
The macro <code>ATEXIT</code> takes one parameter list as argument. The text of the
parameter list is appended to the output file. Note that this text is subject
to character table translations etc..
<p>A good example of the usage of this macro is the following. A document in the
LaTeX typesetting language requires <code>\end{document}</code> to occur at the end of
the document. To automatically append this string to the output file, the
following specification can be used:
<p><pre>
ATEXIT(NOEXPAND(\end{document}))
</pre>
<p>Several <code>ATEXIT</code> lists can be defined. They are appended to the output file
in the <strong>reverse</strong> order of specification; i.e., the first <code>ATEXIT</code> list is
appended to the output file last. That means that in general the <code>ATEXIT</code>
text should be specified when a `matching' starting command is sent to the
output file; as in:
<p><pre>
COMMENT(Start the LaTeX document.)
NOEXPAND(\begin{document})
COMMENT(Make sure that the ending is
on time.)
ATEXIT(NOEXPAND(\end{document}))
</pre>
<p><a name="l14"></a>
<h3>2.3.3: CHAR</h3>
<a name="char"></a>The command <code>CHAR</code> 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 <a href="refman02.html#chartables">2.4</a>). Also, the <code>CHAR</code>
macro can be used to circumvent Yodl's way of matching parentheses in a
parameter list.
<p>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
<code>CHAR(c)</code>, <code>c</code> being the character (as in, <code>CHAR(")</code>). 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 <code>CHAR</code> command.
<p>Example: The following two statements send an <code>A</code> to the output file.
<p><pre>
CHAR(65)
CHAR(A)
</pre>
<p>The following statement sends a closing parenthesis:
<p><pre>
CHAR(41)
</pre>
<p>Another way to send a string to the output file without expansion by character
tables or by macro interpretation, is by using the macro <code>NOTRANS</code> (see
section <a href="refman02.html#notrans">2.3.22</a>). If you want to send a string to the output <strong>without</strong>
macro interpretation, but <strong>with</strong> character table translation, use
<code>NOEXPAND</code> (see section <a href="refman02.html#noexpand">2.3.21</a>).
<p>
<p><a name="l15"></a>
<h3>2.3.4: CHDIR</h3>
<a name="chdir"></a>The command <code>CHDIR</code> takes one argument, a directory to change to. This
command is implemented to simplify the working with <code>includefile</code> (see
<code>includefile</code> in <code>yodlmacros(7)</code>).
As a demonstration by example, consider the
following fragment:
<p><pre>
includefile(subdir/onefile)
includefile(subdir/anotherfile)
includefile(subdir/yetanotherfile)
</pre>
<p>This fragment can be changed to:
<p><pre>
CHDIR(subdir)
includefile(onefile)
includefile(anotherfile)
includefile(yetanotherfile)
CHDIR(..)
</pre>
<p>The current directory, as given to <code>CHDIR</code>, only affects how <code>includefile</code>
will search for its files.
<p><a name="l16"></a>
<h3>2.3.5: COMMENT</h3>
<a name="comment"></a>The <code>COMMENT</code> macro takes one parameter list. The text in the list is
treated as comment; i.e., nothing is done with it. The text is not copied to
the final output file; this command is meant as comment for Yodl files only.
<p>
<p><a name="l17"></a>
<h3>2.3.6: COUNTERVALUE</h3>
<a name="countervalue"></a>
The macro <code>COUNTERVALUE</code> expands to the value of a counter. Its only
parameter list is a counter name. The counter must be previously created by
<code>NEWCOUNTER</code>.
<p>See further section <a href="refman02.html#counters">2.6</a>.
<p><a name="l18"></a>
<h3>2.3.7: DEFINECHARTABLE</h3>
<a name="definechartable"></a>
The macro <code>DEFINECHARTABLE</code> is used to define a character translation table.
Its complement, <code>USECHARTABLE</code>, activates the table. The discussion of
character tables is postponed to section <a href="refman02.html#chartables">2.4</a>.
<p>
<p><a name="l19"></a>
<h3>2.3.8: DEFINEMACRO</h3>
<a name="definemacro"></a>The macro <code>DEFINEMACRO</code> lets you define new macros. This macro requires
three parameter lists:
<p><dl>
<p><li > An identifier, being the name of the macro to define. This identifier
must only consist of uppercase or lowercase characters.
<p><li > A number, stating the number of arguments that the macro will require
once used. The number must be in the range 0 to 61.
<p><li > The text that the macro will expand to, once used. This text may
contain the strings <code>ARG</code><em>x</em>, <em>x</em> being 1, 2, etc.. At these places
the arguments to the macro will be 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, that should be enough for most
applications.
<p></dl>
<p>For example, the following fragment defines a macro <code>bookref</code>, 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:
<p><pre>
DEFINEMACRO(bookref)(3)
(Author(s): ARG1
Book title: ARG2
Published by: ARG3)
</pre>
<p>Such a macro could be used as:
<p><pre>
bookref(Sobotta/Becher)
(Atlas der Anatomie des Menschen)
(Urban und Schwarzenberg, Berlin, 1972)
</pre>
<p>It would of course lead to:
<p><pre>
Author(s): Sobotta/Becher
Book title: Atlas der Anatomie des Menschen
Published by: Urban und Schwarzenberg, Berlin, 1972
</pre>
<p>While applying a macro, the three parameter lists are pasted to the places
where <code>ARG1</code>, <code>ARG2</code> etc. occur in the definition.
<p>A few caveats when defining new macros are:
<p><dl>
<p><li > The parameter list containing the name of the new macro,
<code>(bookref)</code> in the above example, must occur right after
<code>DEFINEMACRO</code>. No spaces are allowed in between. Space characters and
newlines may however occur following this first parameter list.
<p>This behavior of the <code>yodl</code> program is similar to the usage of the
defined macro: the author information must, enclosed in parentheses,
follow right after the <code>bookref</code> identifier. I implemented this feature
to improve the distinguishing between macros and real text. E.g., a macro
<code>me</code> might be defined, but the text
<p><pre>
I like me (but so do you)
</pre>
<p>still is simple text; the macro <code>me</code> only is activated when a
parenthesis immediately follows it.
<p><li > Be careful when placing newlines or spaces in the definition of a new
macro. E.g., the definition
<p><pre>
DEFINEMACRO(bookref)(3)(
Author(s): ARG1
Book title: ARG2
Published by: ARG3)
</pre>
<p>introduces an extra newline, that will be copied to the output each time
that the macro is used. The extra newline occurs, of course, right before
the sequence <code>Author(s):</code>. A simple backslash character at the end of
the <code>DEFINEMACRO</code> line would prevent the insertion of an extra newline
character.
<p><li > Note that when a macro is used which requires no arguments at all,
one empty parameter list still must be specified. E.g., my macro package
(see chapter <a href="refman03.html#macropackage">3</a>) defines a macro <code>it</code> that starts a
bullet item in a list. The macro takes no arguments, but still must be
typed as <code>it()</code>.
<p>This behavior is consistent: it helps distinguish which identifiers are
macros and which are simple text.
<p></dl>
<p><a name="l20"></a>
<h3>2.3.9: DEFINESYMBOL</h3>
<a name="definesymbol"></a>The macro <code>DEFINESYMBOL</code> takes one argument, an identifier, which is treated
as a symbol that is set to the logic value `true'. The true-ness or false-ness
of this symbol may subsequently be tested with <code>IFDEF</code> (see section
<a href="refman02.html#ifdef">2.3.13</a>).
<p>The corresponding macro <code>UNDEFINESYMBOL</code> removes the definition of a symbol.
<p>Example:
<p><pre>
Definining "somesymbol"...
DEFINESYMBOL(somesymbol)
IFDEF(somesymbol)
(Symbol "somesymbol" is true.)
(Symbol "somesymbol" is false.)
Removing definition of "somesymbol"...
UNDEFINESYMBOL(somesymbol)
IFDEF(somesymbol)
(Symbol "somesymbol" is true.)
(Symbol "somesymbol" is false.)
</pre>
<p>This produces output similar to:
<p><pre>
Definining "somesymbol"...
Symbol "somesymbol" is true.
Removing definition of "somesymbol"...
Symbol "somesymbol" is false.
</pre>
<p><a name="l21"></a>
<h3>2.3.10: DUMMY</h3>
<a name="dummy"></a>This macro takes one argument, which is not interpreted. The macro is a real
dummy, it does nothing.
<p>(I implemented the macro in order to provide a simple debugging hook. After
inserting <code>DUMMY()</code> somewhere in the macro file, I can start the <code>yodl</code>
program under a debugger and set a breakpoint in the dummy-routine; then watch
what happens from there.)
<p><a name="l22"></a>
<h3>2.3.11: ENDDEF</h3>
<a name="enddef"></a>
The macro <code>ENDDEF</code> takes one (empty) parameter list. It signals the ending
of a Yodl definition section. See the description of <code>STARTDEF</code>,
<a href="refman02.html#startdef">2.3.31</a>.
<p><a name="l23"></a>
<h3>2.3.12: ERROR</h3>
<a name="error"></a>The <code>ERROR</code> macro 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 <code>yodl</code> program aborts with an exit status of 1.
<p>This command can be used, e.g., in a macro package when an incorrect macro is
expanded. In my macro package (see chapter <a href="refman03.html#macropackage">3</a>) the <code>ERROR</code>
macro is used when the sectioning command <code>chapter()</code> is used in an
<code>article</code> document (in the package, <code>chapter</code>'s are only available in
<code>book</code>s or <code>report</code>s).
<p>An analogous builtin macro is <code>WARNING</code>, which also prints a message but
does not exit (see section <a href="refman02.html#warning">2.3.39</a>).
<p><a name="l24"></a>
<h3>2.3.13: IFDEF</h3>
<a name="ifdef"></a>The <code>IFDEF</code> macro tests for the logical true value of the argument in its
first parameter list. If `true', the second parameter list is evaluated, else,
the third parameter list is evaluated. All three parameter lists (the
variable, the true-list and the false-list) must be present; though the
true-list and/or the false-list may be empty parameter lists.
<p>The variable in the first parameter list evaluates the macro to `true' when
the first argument is:
<p><dl>
<p><li > a built-in macro,
<p><li > a user-defined macro (see <code>DEFINEMACRO</code>, section <a href="refman02.html#definemacro">2.3.8</a>),
<p><li > a logical symbol (see <code>DEFINESYMBOL</code>, section <a href="refman02.html#definesymbol">2.3.9</a>),
<p><li > a counter (see <code>NEWCOUNTER</code>, section <a href="refman02.html#newcounter">2.3.20</a>).
<p></dl>
<p>For an example, see the description of <code>DEFINESYMBOL</code>, section
<a href="refman02.html#definesymbol">2.3.9</a>.
<p><a name="l25"></a>
<h3>2.3.14: IFEMPTY</h3>
<a name="ifempty"></a>
The macro <code>IFEMPTY</code> expects three arguments: a symbol, a true-list and a
false-list. The macro evaluates to the true-list if the symbol is an empty
string; otherwise, it evaluates to the false-list.
<p>A trivial example is the following:
<p><pre>
IFEMPTY(something) \
("something" is supposedly nothing ?!?")
("something" is not an empty string)
</pre>
<p>In the same way, <code>IFEMPTY</code> can be used to test whether a macro expands to a
non-empty string. A more elaborate example follows below. Say you want to
define a <code>bookref</code> macro to typeset information about an author, a book
title and about the publisher. The publisher information may be absent, the
macro then typesets <code>unknown</code>:
<p><pre>
DEFINEMACRO(bookref)(3)(\
Author(s): ARG1
Title: ARG2
Published by: IFEMPTY(ARG3)(Unknown)(ARG3))
</pre>
<p>Using the macro, as in:
<p><pre>
bookref(Helmut Leonhardt)
(Histologie, Zytologie und Microanatomie des Menschen)
()
</pre>
<p>would of course supply <code>Unknown</code> in the <code>Published by:</code> line.
<p><a name="l26"></a>
<h3>2.3.15: IFSTREQUAL</h3>
<a name="ifstrequal"></a>
The macro <code>IFSTREQUAL</code> 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 two string arguments match exactly.
<p><a name="l27"></a>
<h3>2.3.16: IFSTRSUB</h3>
<a name="ifstrsub"></a>The <code>IFSTRSUB</code> macro tests whether a string is a sub-string of another
string. It is similar to <code>IFSTREQUAL</code> (see section <a href="refman02.html#ifstrequal">2.3.15</a>), except
that the test is whether the second string is part of the first one. Hence:
<p><pre>
IFSTRSUB(some piece of text)(ce o)
(truelist)
(falselist)
</pre>
<p>evaluates to <code>truelist</code>.
<p><a name="l28"></a>
<h3>2.3.17: IFZERO</h3>
<a name="ifzero"></a>The <code>IFZERO</code> macro expects three parameter lists, just as the other
<code>IF...</code> macros: a symbol, a true-list and a false-list.
<p>The first argument defines whether the whole macro expands to the true-list or
to the false-list. The first argument may be:
<p><dl>
<p><li > Nothing (empty): the macro expands to the true-list.
<p><li > A number: when zero, the macro expands to the true-list.
<p><li > The name of a counter: when the value of the counter is zero, the
macro expands to the true-list.
<p><li > Anything else: the macro expands to the false-list.
<p></dl>
<p>You can use <code>COUNTERVALUE(somecounter)</code> as the argument to <code>IFZERO</code>, it is
treated in the same manner as the corresponding counter name.
<p>Example: The <code>IFZERO</code> macro offers a very simple way to pass a flag-argument
(an on/off switch) to a macro. E.g., in LaTeX you start environments with
<code>\begin{environment}</code> and end them with <code>\end{environment}</code>;
<code>environment</code> being e.g., <code>center</code>, <code>flushright</code>, <code>flushleft</code>. A
possible meta-macro for the environments might be:
<p><pre>
DEFINEMACRO(environment)(2)(\
IFZERO(ARG2)\
NOEXPAND(\end{ARG1})\
NOEXPAND(\begin{ARG1}))
</pre>
<p>Such a macro may be used as:
<p><pre>
environment(center)(1)
Now comes centered text.
environment(center)(0)
</pre>
<p>which would of course lead to <code>\begin</code> and <code>\end{center}</code>. The numeric
second argument is used here as a on/off switch.
<p><a name="l29"></a>
<h3>2.3.18: INCLUDEFILE</h3>
<a name="includefile"></a>The command <code>INCLUDEFILE</code> takes one argument, a filename. The file is
included.
<p>The <code>yodl</code> program supplies, when necessary, an extension to the filename.
The supplied extension is <code>.yo</code>, unless defined otherwise in the compilation
of the program. Furthermore, <code>yodl</code> prefixes the file with the system-wide
include directory if necessary. This directory is normally
<code>/usr/local/lib/yodl</code>, unless overruled by the command line flag <code>-I</code> or
defined otherwise in the compilation.
<p>E.g., if you install a macro package in a file <code>latex.yo</code> in the directory
<code>/usr/local/lib/yodl</code>, then the command
<p><pre>
INCLUDEFILE(latex)
</pre>
<p>will include it.
<p><a name="l30"></a>
<h3>2.3.19: INCLUDELITERAL</h3>
<a name="includeliteral"></a>The command <code>INCLUDELITERAL</code> takes one argument, a filename. The file is
included.
<p>The filename is not changed in any way.
<p>Furthermore the contents of the file is included literally, not subject to
macro expansion. Character translations are allowed.
<p>The purpose of INCLUDELITERAL is to include source code literally in the
document, as in:
<p><pre>
INCLUDELITERAL(literal.c)
</pre>
<p>This example shows how to put the contents of C file literal.c into the
document.
<p><a name="l31"></a>
<h3>2.3.20: NEWCOUNTER</h3>
<a name="newcounter"></a>
The macro <code>NEWCOUNTER</code> creates a new counter, to be subsequently used by,
e.g, the <code>USECOUNTER</code> macro. <code>NEWCOUNTER</code> expects one parameter list: the
name of the counter to create. See further section <a href="refman02.html#counters">2.6</a>.
<p><a name="l32"></a>
<h3>2.3.21: NOEXPAND</h3>
<a name="noexpand"></a>The macro <code>NOEXPAND</code> is one of the ways in which text can be sent to the
final output file without being expanded by Yodl (the other methods are the
<code>CHAR</code> macro, see section <a href="refman02.html#char">2.3.3</a>, and the <code>NOTRANS</code> macro, see section
<a href="refman02.html#notrans">2.3.22</a>). The macro <code>NOEXPAND</code> takes one parameter list, 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 <code>CHAR</code>
macros in the argument, which are expanded). The contents of the parameter
list <strong>are</strong> subject to character table translations, using the currently
active table (see section <a href="refman02.html#chartables">2.4</a>).
<p>E.g., let's assume that you need to write in your document the following text:
<p><pre>
INCLUDEFILE(something or the other)
IFDEF(onething) (..) (....)
NOEXPAND(whatever)
</pre>
<p>The way to accomplish this is by prefixing the text by <code>NOEXPAND</code> 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 sence of the Yodl
language).
<p>For this macro, keep the following caveats in mind:
<p><dl>
<p><li > There is only one thing that a <code>NOEXPAND</code> cannot protect from
expansion: an <code>ARG</code><em>x</em> in a macro definition. The argument specifier
is always expanded. E.g., after
<p><pre>
DEFINEMACRO(thatsit)(1)(That is --> NOEXPAND(ARG1) <-- it!)
thatsit(after all)
</pre>
<p>the <code>ARG1</code> inside the <code>NOEXPAND</code> statement is replaced with <code>after</code>
<code>all</code>.
<p><li > The <code>NOEXPAND</code> macro must, as all macros, be followed by a
parameter list. The parentheses of the list must therefore be `balanced'.
For unbalanced lists, use <code>CHAR(40)</code> to set an open parenthesis,
or <code>CHAR(41)</code> to typeset a closing parenthesis.
<p></dl>
<p><a name="l33"></a>
<h3>2.3.22: NOTRANS</h3>
<a name="notrans"></a>The macro <code>NOTRANS</code> copies its one argument literally to the output file,
without expanding macros in it (except for <code>CHAR</code>, which is expanded) and
without translating the characters with the current translation table. The
<code>NOTRANS</code> macro is typically used to send commands for the output format to
the output file.
<p>For example, consider the following code fragment:
<p><pre>
COMMENT(--- Define character translations for \{} 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})
</pre>
<p>The <code>NOEXPAND</code> macro in this example will send
<p><pre>
$\backslash$input\verb+{+epsf.tex\verb+}+
</pre>
<p>since the characters in its argument are translated with the <code>standard</code>
translation table. In contrast, the <code>NOTRANS</code> macro, will send literally
<code>\input{epsf.tex}</code>.
<p>The parameter list of the <code>NOTRANS</code> macro must be balanced in respect to its
parentheses. When using an unbalanced number of parentheses, use
<code>CHAR(40)</code> to send a literal (, or <code>CHAR(41)</code> to send
a <code>)</code>.
<p>
<p><a name="l34"></a>
<h3>2.3.23: NOUSERMACRO</h3>
<a name="nousermacro"></a>The macro <code>NOUSERMACRO</code> controls <code>yodl</code>'s warnings in the following
respect. When <code>yodl</code> is started with the <code>-w</code> flag on the command line,
then warnings are generated when <code>yodl</code> encounters a possible macro
name, followed by a parameter list, but fails to lookup the macro. The
<code>yodl</code> program then prints something like <code>cannot expand possible user
macro</code>.
<p>Examples of such sequences are, <code>The necessary file(s) are in
/usr/local/lib/yodl</code>, or <code>see the manual page for sed(1)</code>. The candidate
macros are hee <code>file</code> and <code>sed</code>; these names could just as well be `valid'
user macros followed by their parameter list.
<p>When a corresponding <code>NOUSERMACRO</code> statement appears <strong>before</strong> <code>yodl</code>
encounters the candidate macros, no warning is generated. A fragment might
therefore be:
<p><pre>
NOUSERMACRO(file sed)
The necessary file(s) are in ...
See the manual page for sed(1).
</pre>
<p>The <code>NOUSERMACRO</code> accepts one or more names in its argument, separated by
spaces, commas, colons, or semi-colons.
<p><a name="l35"></a>
<h3>2.3.24: PARAGRAPH</h3>
<a name="paragraph"></a>The <code>PARAGRAPH</code> macro is defined by the Yodl program, but is had normally no
actions. The macro works as follows.
<p>If you define the macro, then Yodl's parser will trigger it whenever a new
paragraph is started. The macro must be defined as one with zero arguments,
but leading to some (necessary) action. New paragraphs are -by definition-
indicated in the source file as two or more consecutive newline characters,
optionally separated by spaces. I.e., in the text
<p><pre>
Here is a line of text.
And here's another one.
</pre>
<p>one new paragraph occurs: the first line is terminated by a newline, then one
newline follows right behind. Given such input, the <code>PARAGRAPH</code> macro is
triggered right before the parsing process of the line starting with <code>And</code>.
<p>Some macro packages do not need paragraph starts; e.g., LaTeX does its own
paragraph handling. Other macro packages do need it: typically, <code>PARAGRAPH</code>
is then defined in a macro file to trigger some special action. E.g., a HTML
converter might define a paragraph as:
<p><pre>
DEFINEMACRO(PARAGRAPH)(0)(<p>)
</pre>
<p><strong>Note that</strong> the definition of the action of the <code>PARAGRAPH</code> macro is again
parsed and expanded by Yodl. Therefore, if you put two consecutive newlines in
the definition itself, the definition will again trigger the <code>PARAGRAPH</code>
macro, etcetera, ad infinitum. If you want the <code>PARAGRAPH</code> redefinition to
insert a blank line, protect the line in a <code>NOEXPAND</code>, as in:
<p><pre>
DEFINEMACRO(PARAGRAPH)(0)(NOEXPAND(
)<p>)
</pre>
<p><a name="l36"></a>
<h3>2.3.25: PIPETHROUGH</h3>
<a name="pipethrough"></a>The builtin macro <code>PIPETHROUGH</code> is, besides <code>SYSTEM</code>, the second macro with
which a Yodl document can affect its environment. Therefore, the danger of `live
data' exists which is also described in the section about <code>SYSTEM</code> (see
section <a href="refman02.html#system">2.3.32</a>). Nevertheless, <code>PIPETHROUGH</code> can be very useful. It is
intended to use external programs 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.
<p>The <code>PIPETHROUGH</code> macro takes two arguments:
<p><dl>
<p><li > the command to run, and
<p><li > the text to send to that command.
<p></dl>
<p>Functionally, the occurrence of the <code>PIPETHROUGH</code> macro and of its two
arguments is replaced by whatever the child program produces on its standard
output.
<p>An example might be the inclusion of the current date, as in:
<p><pre>
The current date is:
PIPETHROUGH(date)()
</pre>
<p>In this example the command is <code>date</code> and the text to send to that program is
empty.
<p>The main purpose of this macro 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.
<p><a name="l37"></a>
<h3>2.3.26: POPCHARTABLE</h3>
<a name="popchartable"></a>Character tables which are pushed onto the table stack using
<code>PUSHCHARTABLE()</code> are restored (popped) using <code>POPCHARTABLE()</code>. For a
description of this mechanism please refer to section <a href="refman02.html#pushingtables">2.4.3</a>.
<p><a name="l38"></a>
<h3>2.3.27: PUSHCHARTABLE</h3>
<a name="pushchartable"></a>After a character table has been defined, it can be "pushed" onto a stack; to
be "popped" later. This discussion is postponed to section <a href="refman02.html#pushingtables">2.4.3</a>.
<p><a name="l39"></a>
<h3>2.3.28: RENAMEMACRO</h3>
<a name="renamemacro"></a>The command <code>RENAMEMACRO</code> takes two arguments: the name of a built-in macro
(such as <code>INCLUDEFILE</code>) and its new name.
<p>E.g., after
<p><pre>
RENAMEMACRO(INCLUDEFILE)(include)
</pre>
<p>a file must be included by <code>include(file)</code>, and no longer using
<code>INCLUDEFILE</code>.
<p>Note that following the <code>RENAMEMACRO</code> action, the old name can no longer
be used; it is then an unknown symbol.
<p>If you want to make an <em>alias</em> for a built-in command, do it with
<code>DEFINEMACRO</code>. E.g., after:
<p><pre>
DEFINEMACRO(include)(1)(INCLUDEFILE(ARG1))
</pre>
<p>both <code>INCLUDEFILE</code> and <code>include</code> can be used to read in a file.
<p><a name="l40"></a>
<h3>2.3.29: SETCOUNTER</h3>
<a name="setcounter"></a>
The <code>SETCOUNTER</code> macro expects two parameter lists: one counter name, and
one numeric value. The corresponding counter (which must be previously created
with <code>NEWCOUNTER</code>) is set to the numeric value.
<p>See also section <a href="refman02.html#counters">2.6</a>.
<p><a name="l41"></a>
<h3>2.3.30: SUBST</h3>
<a name="subst"></a>The <code>SUBST</code> macro is a general-purpose substitution mechanism for strings in
the input. It takes two arguments: a search string and a substitution string.
E.g., after
<p><pre>
SUBST(VERSION)(1.00)
</pre>
<p>the <code>yodl</code> program will output <code>1.00</code> for each occurence of <code>VERSION</code> in
its input.
<p>The <code>SUBST</code> macro is also useful in situations where multi-character
sequeces should be converted to accent characters. E.g., a LaTeX converter
might define:
<p><pre>
SUBST('e)(NOTRANS(\'{e}))
</pre>
<p>Each <code>'</code><code>e</code> in the input would then be converted to é.
<p>The <code>SUBST</code> macro may also be useful in combination with the command line
flag <code>-P</code>, as in a invocation
<p><pre>
yodl2html -P'SUBST(VERSION)(1.00)' myfile.yo
</pre>
<p>A further useful substitution may be the following:
<p><pre>
SUBST(_OP_)(CHAR(40))
SUBST(_CP_)(CHAR(41))
</pre>
<p>which defines an opening parenthesis (<code>_OP_</code>) and a closing parenthesis
(<code>_CP_</code>) as mapped to the <code>CHAR</code> macro. The strings <code>_OP_</code> and <code>_CP_</code>
might then be used in unbalanced parameter lists.
<p>Note that:
<p><dl>
<p><li > The first argument of the <code>SUBST</code> command, the search string, is
taken literally. Yodl does not expand it; the string must be literally
matched in the input.
<p><li > The second argument, the replacement, is further processed by Yodl.
Protect this text by <code>NOTRANS</code> or <code>NOEXPAND</code> where appropriate.
<p></dl>
<p><a name="l42"></a>
<h3>2.3.31: STARTDEF</h3>
<a name="startdef"></a>
The <code>STARTDEF</code> macro typically occurs in files that define a macro package
for Yodl. The macro signals the <code>yodl</code> program that the following input holds
only the definitions of macros, symbols etc..
<p>When <code>yodl</code> is inside a definition, the generation of empty lines on the
output is suppressed, and <code>yodl</code> warns when non-whitespace output is
generated. Using <code>STARTDEF</code> is never obligatory, but it is useful in a macro
file. Macro files tend to define a lot of symbols or commands, leading to
unnecessary spaces and newlines.
<p>The definition section is ended with the <code>ENDDEF</code> macro.
<p>Example:
<p><pre>
STARTDEF()
DEFINESYMBOL(....)
DEFINEMACRO(...)(...)(...)
ENDDEF()
</pre>
<p>Without the <code>STARTDEF</code> and <code>ENDDEF</code>, the above definition would generate
four empty lines in the output.
<p><a name="l43"></a>
<h3>2.3.32: SYSTEM</h3>
<a name="system"></a>The <code>SYSTEM</code> macro takes one argument: a command to execute. The command is
run via the standard C function <code>system</code>. The presence of this macro in the
Yodl language introduces the danger of <em>live data</em>; imagine someone sending
you a document with
<p><pre>
SYSTEM(rm *)
</pre>
<p>in it. To avoid such malevolent side effects, the <code>yodl</code> program has a flag
<code>-l</code> to define the `live data policy'. By default, <code>-l0</code> is implied which
suppresses the <code>SYSTEM</code> macro and the related <code>PIPETHROUGH</code> macro. See also
section <a href="refman02.html#using">2.1</a>.
<p>Despite the potential danger, <code>SYSTEM</code> can be useful in many ways. E.g., you
might want to log when someone processes your document, as in:
<p><pre>
SYSTEM(echo Document processed! | mail myself@my.host)
</pre>
<p>
<p><a name="l44"></a>
<h3>2.3.33: TYPEOUT</h3>
<a name="typeout"></a>
The macro <code>TYPEOUT</code> requires one parameter list. 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.
<p>Example: The following macro includes a file and writes to the screen that
this file is currently processed.
<p><pre>
DEFINEMACRO(includefile)(1)(\
TYPEOUT(About to process document: ARG1)\
INCLUDEFILE(ARG1))
</pre>
<p>
<p><a name="l45"></a>
<h3>2.3.34: UNDEFINEMACRO</h3>
<a name="undefinemacro"></a>
The macro <code>UNDEFINEMACRO</code> removes a definition of a macro that was defined
by <code>DEFINEMACRO</code>. This macro takes one argument: the macro name to remove.
<p>There is no error condition (except for syntax errors): when no macro with a
matching name was previously defined, no action is taken.
<p>For example, the safe way to define a macro is by first undefining it. This
ensures that possible previous definitions are removed first:
<p><pre>
UNDEFINEMACRO(mymacro)
DEFINEMACRO(mymacro)(1)(This is my macro with argument ARG1.)
</pre>
<p><a name="l46"></a>
<h3>2.3.35: UNDEFINESYMBOL</h3>
<a name="undefinesymbol"></a>The macro <code>UNDEFINESYMBOL</code> removes the definition of a logical symbol. It
expects one parameter list, holding the variable to undefined.
<p>This macro has no error condition (except for syntax errors): the symbol in
question may be previously defined, but that is not necessary.
<p><a name="l47"></a>
<h3>2.3.36: UPPERCASE</h3>
<a name="uppercase"></a>The <code>UPPERCASE</code> macro converts a string or a part of it to upper case. It has
two arguments:
<p><dl>
<p><li > The string to convert;
<p><li > A length, indicating how many characters (starting from the beginning
of the string) should be converted.
<p></dl>
<p>The length indicator can be smaller than one or larger than the length of the
string; in that case, the whole string is convertered.
<p>Example:
<p><pre>
UPPERCASE(hello world)(1)
UPPERCASE(hello world)(5)
UPPERCASE(hello world)(0)
</pre>
<p>This code sample expands to:
<p><pre>
Hello world
HELLO world
HELLO WORLD
</pre>
<p><a name="l48"></a>
<h3>2.3.37: USECHARTABLE</h3>
<a name="usechartable"></a>
The macro <code>USECHARTABLE</code> takes one parameter list: the name of a translation
table to activate. The table must be previously defined using
<code>DEFINECHARTABLE</code>. See section <a href="refman02.html#chartables">2.4</a> for a description of
character translation tables.
<p>Alternatively, the name may be empty in which case the default character
mapping is restored.
<p><a name="l49"></a>
<h3>2.3.38: USECOUNTER</h3>
<a name="usecounter"></a>
The macro <code>USECOUNTER</code> is a combination of <code>ADDTOCOUNTER</code> and
<code>COUNTERVALUE</code>. It expects one parameter list: a counter name, that must be
previously created with <code>NEWCOUNTER</code>.
<p>The counter is first increased by 1. Then the macro expands to the number of
the counter.
<p>See also section <a href="refman02.html#counters">2.6</a>.
<p><a name="l50"></a>
<h3>2.3.39: WARNING</h3>
<a name="warning"></a>The <code>WARNING</code> macro takes one argument: text to display as a warning. The
<code>yodl</code> program makes sure that before showing the text, the current file and
line number are printed. Other than this, <code>WARNING</code> works just as
<code>TYPEOUT</code> (see section <a href="refman02.html#typeout">2.3.33</a>).
<p>Note that an analogous macro <code>ERROR</code> exists, which prints a message and then
terminates the program (see section <a href="refman02.html#error">2.3.12</a>).
<p><a name="l51"></a>
<h2>2.4: Character tables</h2>
<a name="chartables"></a>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.
<p>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 <code>$*$</code> or <code>\verb/*/</code> (these are sequences from the
LaTeX document language). Hence, a mechanism that expands a * in the input to
to <code>\verb/*/</code> on the output, saves the users a lot of typing.
<p>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 <code>\verb/*/</code> 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?
<p>The solution is of course to define the translation for an input character
like * given the output format.
<p>
<p><a name="l52"></a>
<h3>2.4.1: Defining a translation table</h3>
<a name="definingtable"></a>
The built-in macro <code>DEFINECHARTABLE</code> defines a character translation table.
It takes two parameter lists: the name of the table and the character
translations. Hence, each table is defined by its own name.
<p>As an example of a table, consider the following fragment. It defines a table
that translates the upper case characters <code>A</code> to <code>E</code> to their lower case
equivalents:
<p><pre>
DEFINECHARTABLE(tolower)(
'A' = "a"
'B' = "b"
'C' = "c"
'D' = "d"
'E' = "e"
)
</pre>
<p>Each <code>DEFINECHARTABLE</code> statement <strong>must</strong> have a non-empty second
parameter. "Empty" character tables cannot be defined, though one
non-translation table is built-in.
<p>The syntaxis of the second parameter list is as follows:
<p><dl>
<p><li > On separate lines, input characters are mapped to a sequence to
appear on the output.
<p><li > Per line, the input character is specified as <code>'c'</code>, <code>c</code> being
any character. Escape-sequences from the <strong>C</strong> programming language can be
used in this specification; Yodl supports the sequences <code>\a</code> (alert),
<code>\b</code> (beep), <code>\f</code> (formfeed), <code>\n</code> (newline), <code>\r</code> (carriage
return), <code>\t</code> (tab), and <code>\v</code> (vertical tab). Any other character
following a \ defines itself: <code>\\</code> defines one backslash character.
<p><li > Following the character specification, a <code>=</code> must appear.
<p><li > 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:
<p><pre>
'\n' = "End of line\n"
</pre>
<p>Such a mapping adds the text <code>End of line</code> to each line, since each
newline character in the input is replaced by the text <code>End of line</code>,
followed by the newline itself.
<p></dl>
<p>Translations which are <strong>not</strong> specified in the table are left to the default,
which is to output the character as-is.
<p>Note that the character table translation is something that the <code>yodl</code>
program does as one of its last actions, just before sending text to the
output file. The expansion text is not further processed by <code>yodl</code>, except
for the conversion of <strong>C</strong>-type escape sequences to ordinary characters. The
expansion text should therefore not be protected by, e.g., <code>NOTRANS</code>
(unless of course you want some character to generate the text <code>NOTRANS</code>
on the output).
<p><a name="l53"></a>
<h3>2.4.2: Using a translation table</h3>
<a name="usingtable"></a>
A defined translation table is activated by the macro <code>USECHARTABLE</code>. This
macro takes one parameter list, which may be:
<p><dl>
<p><li > empty, in which case the default mapping is restored,
<p><li > a name of a previously defined character table.
<p></dl>
<p>The default mapping, selected when an empty parameter list is given, means
that Yodl enters its `zero translation state', meaning no character translation
at all.
<p><a name="l54"></a>
<h3>2.4.3: Pushing and popping character tables</h3>
<a name="pushingtables"></a>Besides the previously described macro <code>USECHARTABLE()</code>, 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
<code>PUSHCHARTABLE()</code> and <code>POPCHARTABLE()</code>.
<p><dl>
<p><li > <code>PUSHCHARTABLE(name)</code> <em>pushes</em> the currently active translation
table onto a stack, and activates the table identified by <code>name</code>. The
argument may be emtpy; in that case, the zero-translation table is
activated (analogously to <code>USECHARTABLE()</code>).
<p><li > <code>POPCHARTABLE()</code> activates the translation table that was last
pushed. There is no argument to this macro.
<p></dl>
<p>Using the push/pop mechanism is handy when a table must be temporarily
activated, but when it is not known which table exacty is active prior to the
temporary activation. E.g., imagine that you need to use a character table
called <code>listing</code> to typeset a listing, but that you do not know the current
table. The pushing and popping mechanism is then used as follows:
<p><pre>
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()
</pre>
<p><a name="l55"></a>
<h2>2.5: Sending literal text to the output</h2>
<a name="sending"></a>The Yodl program has three built-in macros to send literal text to the output
file. The macros are listed in the above section <a href="refman02.html#builtin">2.3</a> and are
furthermore described here.
<p><dl>
<p><li > The <code>CHAR</code> macro 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.
<p><li > The <code>NOTRANS</code> macro 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.
<p>The <code>NOTRANS</code> macro is conceptually like a series of <code>CHAR</code> macros.
<p><li > The <code>NOEXPAND</code> macro takes one argument: the text in question. The
text is not parsed, but it <strong>is</strong> translated with the current character
translation table.
<p></dl>
<p>To illustrate the need for the distinction between <code>NOTRANS</code> and
<code>NOEXPAND</code>, consider the following. The <code>HTML</code> converter (described in
chapter <a href="refman03.html#macropackage">3</a>) 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 <code>&</code>,
<code><</code> and <code>></code> characters can cause difficulties. Two possible macros for a
HTML converter are:
<p><pre>
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))
</pre>
<p>In this example it is assumed that a character translation table <code>standard</code>
exists, defining the `normal' translations. This table is re-activated in the
<code>verb</code> macro.
<p><a name="l56"></a>
<h2>2.6: Counters</h2>
<a name="counters"></a>
Some document languages (notably LaTeX) automatically prefix numbers when
typesetting sections, subsections, tables, figures etc.. Other document
languages (e.g. HTML) unfortunately don't.
<p>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.
<p>This section describes the counters in Yodl: how to create a new counter, how
to use it, etc..
<p><a name="l57"></a>
<h3>2.6.1: Creating a counter</h3>
<a name="creating"></a>
Before a counter can be used, it must be created with the macro
<code>NEWCOUNTER</code>. This macro expects one parameter list: the name of the
counter. The initial value of the counter is set to zero.
<p>As for an example, let's say that our macro package should provide two
sectioning commands: <code>section</code> and <code>subsection</code>. The sections should be
numbered 1, 2, etc., and the subsections 1.1, 1.2, 1.3 etc.. Hence we'd need
two counters:
<p><pre>
NEWCOUNTER(sectcounter)
NEWCOUNTER(subsectcounter)
</pre>
<p><a name="l58"></a>
<h3>2.6.2: Using counters</h3>
<a name="usingcounters"></a>
Yodl has four macros to modify and/or to set the values of counters. The macros
are:
<p><dl>
<p><li > <code>COUNTERVALUE(somecounter)</code>: This macro expands to the value of
<em>somecounter</em>. E.g., if the current value is 2, then the macro writes 2
on the output file.
<p><li > <code>SETCOUNTER(somecounter)(number)</code>: This macro sets the value of
<em>somecounter</em> to the value of <em>number</em>. The second parameter list must
be an integer number (i.e., consisting of the characters <code>0</code> to <code>9</code>,
optionally prefixed by a <code>-</code> sign). The macro does not expand to
anything; i.e., it does not write to the output file.
<p><li > <code>ADDTOCOUNTER(somecounter)(number)</code>: This macro adds the value of
<em>number</em> to <em>somecounter</em>. The number may be negative.
<p><li > <code>USECOUNTER(somecounter)</code>: This macro first increases the value of
<em>somecounter</em> by 1, and then writes the value of the counter to the
output file.
<p>This command is particularly useful in combination with <code>NEWCOUNTER</code>:
since <code>NEWCOUNTER</code> initializes a counter to zero, <code>USECOUNTER</code> can be
used to increase the value and to output it. The first time that
<code>USECOUNTER</code> is used on a new counter, the number 1 appears on the
output file. The next time, number 2 appears on the output file etc..
<p></dl>
<p>Given the numbering requirements of the hypothetical commands <code>section</code> and
<code>subsection</code> (see the previous section), we can now complete the
definitions:
<p><pre>
NEWCOUNTER(sectcounter)
NEWCOUNTER(subsectcounter)
DEFINEMACRO(section)(1)(\
SETCOUNTER(subsectcounter)(0)\
USECOUNTER(sectcounter) ARG1)
DEFINEMACRO(subsection)(1)(\
COUNTERVALUE(sectcounter).USECOUNTER(subsectcounter) ARG1)
</pre>
<p>
<hr>
<ul>
<li> <a href="refman03.html">Next chapter</a>
<li> <a href="refman01.html">Previous chapter</a>
<li> <a href="refman.html">Table of contents</a>
</ul>
<hr>
<!--
if this file ./Documentation/footer.html.in is present, it is included
automatically by add-html-footer, and replaces the simple standard
footer substitutions:
* index,
* package name
* package name
* ENV:WEBMASTER,
* ENV:WEBMASTER
-->
<hr>
Go <a href=>back</a> to index of Yodl.
<p>
Please send Yodl questions and comments to
<a href="mailto:yodl@icce.rug.nl">
<em>yodl@icce.rug.nl</em></a>.
<p>
<!-- package Yodl Yodl -->
Please send comments on these web pages to
<a href="mailto:(address unknown)"><em>(address unknown)</em></a>
<p>
Copyright (c) 1997, 1998, 1999 Karel Kubat and Jan Nieuwenhuizen.
<p>
Verbatim copying and distribution of this entire article is
permitted in any medium, provided this notice is preserved.<p>
<hr><font size=-1>
This page was built from Yodl-1.31.18 by
<address><br> <<a href=\"mailto:(address unknown)\">(address unknown)</a>>, Wed Mar 5 04:36:20 2008 EST.</address><p></font></BODY>
</html>
distrib
>
Mandriva
>
2008.1
>
x86_64
>
media
>
main-release
>
by-pkgid
>
00b22311ee5115bec2c62951147eb789
>
files
>
160
