<! 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>Stew Benedict <<a href=\"mailto:(address unknown)\">(address unknown)</a>>, Sat Jan 18 18:43:45 2003 EST.</address><p></font></BODY> </html>