Provided by: yodl_4.02.00-2_amd64 bug

NAME

       yodlbuiltins - Builtins for the Yodl converters

SYNOPSIS

       This manual page lists the standard builtins of the Yodl package.

DESCRIPTION

       The  following list shows the builtins defined by the Yodl converters define and which can
       be used in Yodl documents. Refer to  the  Yodl  user  guide,  distributed  with  the  Yodl
       package, for a full description.

       The following list shows all builtins of the package in alphabetical order.

       `Yodl’s builtin commands’
              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.

              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 `[MACROPACKAGE]’ that describes a
              macro package for YODL.

              Most built-in functions and macros expand the information they receive the way they
              receive the information. I.e., the information itself is only evaluated by the time
              it is eventually inserted into an output medium (usually  a  file).  However,  some
              builtin  functions  evaluate their argument(s) once the argument is processed. They
              are:

       o      The `ERROR’ built-in function (see section `[ERROR]’);

       o      The `EVAL’ built-in function (see section `[EVAL]’);

       o      The `FPUTS’ built-in function (see section `[FPUTS]’);

       o      The `INTERNALINDEX’ built-in function (see section `[INTERNALINDEX]’);

       o      The `PUSHSUBST’ built-in function (see section `[PUSHSUBST]’);

       o      The `TYPEOUT’ built-in function (see section `[TYPEOUT]’);

       o      The `UPPERCASE’ built-in function (see section `[UPPERCASE]’);

       o      The `WARNING’ built-in function (see section `[WARNING]’);

       o      The `XXSUBST’ internal use only built-in function;  All  other  built-in  functions
              will not evaluate their arguments.  See the mentioned functions for details, and in
              particular `EVAL()’ for a description of this evaluation process.

       `ADDTOCOUNTER’
              The `ADDTOCOUNTER’ function adds a  given  value  to  a  counter.  It  expects  two
              arguments:  the counter name, and an additive expression defining the value to add.
              The counter must be previously created with `DEFINECOUNTER’.

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

              For example, if `one’ and `two’ are counters, then

                  ADDTOCOUNTER(one)(-two)\//    subtracts two’s value from one
                  ADDTOCOUNTER(one)(two+two)\// adds 2 x two’s value to one

              See further section `[COUNTERS]’.

       `ADDTOSYMBOL’
              Since  Yodl  version  2.00  symbols  can be manipulated. To add text to an existing
              symbol the builtin `ADDTOSYMBOL’ is available. It expects two parameter lists:  the
              symbol’s  name,  and  the  text  to  add  to the symbol.  The symbol must have been
              created earlier using DEFINECOUNTER (see section  `[DEFINECOUNTER]’).  The  macro’s
              second argument is not evaluated while `ADDTOSYMBOL’ is processed. Therefore, it is
              easy to add the text of another symbol or the expansion of  a  macro  to  a  symbol
              value. E.g.,

                  ADDTOSYMBOL(one)(SYMBOLVALUE(two)XXnl())

              This  adds  the  text  of  symbol `two’, followed by a new line, to the contents of
              symbol `one’ only when  symbol  `one’  is  evaluated,  not  when  `ADDTOSYMBOL’  is
              evaluated.

              Example:

                  ADDTOSYMBOL(LOCATION)(this is appended to LOCATION)

       `ATEXIT’
              `ATEXIT’  expects  one  argument. The argument is appended to the output file. Note
              that this text is subject to character table translations etc..

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

                  ATEXIT(NOEXPAND(\end{document}))

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

                  COMMENT(Start the LaTeX document.)
                  NOEXPAND(\begin{document})

                  COMMENT(Ensure its proper ending.)
                  ATEXIT(NOEXPAND(\end{document}))

       `CHAR’ The command `CHAR’ takes one argument, a number or a  character,  and  outputs  its
              corresponding  ASCII character to the final output file.  This command is built for
              `emergency situations’, where you need to typeset a character despite the fact that
              it  may  be redefined in the current character table (for a discussion of character
              tables, see `[CHARTABLES]’). Also, the `CHAR’ function can be  used  to  circumvent
              Yodl’s requirement that open- and close-parentheses must match.

              The following arguments may be specified with `CHAR’ (attempted in this order):

       o      A  decimal  number  indicating  the number of the character in the ascii-table (for
              example `CHAR’`(41)’);

       o      A plain, single character  (for example `CHAR’`(#)’).

              So, when you’re sure that you want to send a printable  character  that  is  not  a
              closing parenthesis to the output file, you can use the form `CHAR’`(c)’, `c’ being
              the character (as in, `CHAR’`(;)’).  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 `CHAR’ command.

              Example: The following two statements send an `A’ to the output file.

                  CHAR(65)
                  CHAR(A)

              The following statement sends a closing parenthesis:

                  CHAR(41)

              Another way to send a string to the output  file  without  expansion  by  character
              tables  or by macro interpretation, is by using the function `NOTRANS’ (see section
              `[NOTRANS]’).  If  you  want  to  send  a  string  to  the  output  without   macro
              interpretation,  but  with character table translation, use `NOEXPAND’ (see section
              `[NOEXPAND]’).

       `CHDIR’
              The command `CHDIR’ takes one argument, a directory to change to. This  command  is
              implemented  to  simplify  the  working  with  `includefile’  (see `includefile’ in
              `yodlmacros(7)’).  As a demonstration, consider the following fragment:

                  includefile(subdir/onefile)
                  includefile(subdir/anotherfile)
                  includefile(subdir/yetanotherfile)

              This fragment can be changed to:

                  CHDIR(subdir)
                  includefile(onefile)
                  includefile(anotherfile)
                  includefile(yetanotherfile)
                  CHDIR(..)

              The current directory, as given to `CHDIR’, only affects how `includefile’ searches
              for its files.

              Note  that  this  example assumes that the current working directory is a member of
              Yodl’s include-path specification (cf., Yodl’s `--include’ option).

       `COMMENT’
              The `COMMENT’ function defines one parameter list.  The  text  that  is  passed  as
              argument  is treated as comment. I.e., it is ignored; it is not copied to the final
              output file.

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

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

              Example:

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

       `COUNTERVALUE’
              `COUNTERVALUE’s’ argument expands to the value of a counter.  Its  single  argument
              must  contain  the  name  of a counter.  The counter must have been created earlier
              using the builtin `DEFINECOUNTER’.
              Example:

                  The counter has value COUNTERVALUE(MYCOUNTER).

              See also section `[COUNTERS]’.

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

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

              Example:

                  INCWSLEVEL()
                  DEFINESYMBOL(....)
                  DEFINEMACRO(...)(...)(...)
                  DECWSLEVEL()

              Without  the  `INCWSLEVEL’  and  `DECWSLEVEL’,  calls,  the  above definition would
              generate four empty lines to the output stream.

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

       `DEFINECHARTABLE’
              `DEFINECHARTABLE’ is used to define a character translation  table.   The  function
              expects  two  parameterlists,  containing  the  name  of  the  character  table and
              character table translations on separate lines. These character table  translations
              are of the form

                  character = quoted-string

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

              Example:

                  DEFINECHARTABLE(demotable)(
                      ’&’     = "&"
                      ’\\’    = "\\backslash"
                      ’\045’  = "oct(45)"
                      ’0xa4’  = "hex(a4)"
                  )

              The builtin function `DEFINECHARTABLE’ does not activate the table.  The  table  is
              merely  defined.  To  activate the character translation table, use `USECHARTABLE’.
              The discussion of character tables is postponed to section `[CHARTABLES]’.

       `DEFINECOUNTER’
              `DEFINECOUNTER’ creates a new counter. This builtin function expects two arguments:
              the  name  of  the  counter  and  an  additive  expression  whose  value is used to
              initialize the counter.

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

              Examples:

                  DEFINECOUNTER(year)(1950)
                  DEFINECOUNTER(nTimes)(year+12)\// initializes nTimes to 1962

              See  also  section  `[COUNTERS]’  and  the  `USECOUNTER’ and `ADDTOCOUNTER’ builtin
              functions.

       `DEFINEMACRO’
              `DEFINEMACRO’ is used to define new macros. This function expects three arguments:

       o      An identifier, being the name of the macro to  define.  This  identifier  may  only
              consist of uppercase or lowercase characters. Note that it can not contain numbers,
              nor underscore characters.

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

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

                  DEFINEMACRO(bookref)(3)(
                      Author(s):           ARG1
                      Book title:          ARG2
                      Published by:        ARG3
                  )

              Such a macro could be used as follows:

                  bookref(Sobotta/Becher)
                         (Atlas der Anatomie des Menschen)
                         (Urban und Schwarzenberg, Berlin, 1972)

              When called, it would produce the following output:

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

              While  applying a macro, the values of the three arguments are pasted to the places
              where `ARG1’, `ARG2’ etc. occur in the definition.

              Note the following when defining new macros:

       o      The argument containing the name  of  the  new  macro,  `(bookref)’  in  the  above
              example,  must  occur  right after `DEFINEMACRO’. No spaces are allowed in between.
              Space characters and newlines may however occur following this first argument.

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

                  I like me (but so do you)

              still  is  simple  text;  the  macro  `me’  only  is  activated  when a parenthesis
              immediately follows it.

       o      Be careful when placing newlines or spaces in the definition of a new macro.  E.g.,
              the definition, as given:

                  DEFINEMACRO(bookref)(3)(
                      Author(s):           ARG1
                      Book title:          ARG2
                      Published by:        ARG3
                  )

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

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

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

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

       o      Macro  arguments  may evaluate to text. When a \ is appended to the macro-argument,
              or in the default input handling within a non-zero white-space level  (see  section
              `[INCWSLEVEL]’) this may invalidate a subsequent macro call. E.g., the macro

                  DEFINEMACRO(oops)(1)(
                      ARG1
                      XXnl()
                  )

              when called as `oops(hello world)’, produces the output:

                  hello worldXXnl()

              To  prevent  this  gluing to arguments to subsequent macros, a single `+’ should be
              prepended to the macro call:

                  DEFINEMACRO(oops)(1)(
                      ARG1
                      +XXnl()
                  )

              See also section `[PLUSIDENT]’ obout the `+identifier’-sequence.

       o      Note the preferred layout of macro definitions and  macro  calls.  Adhere  to  this
              form, to prevent drowning in too many parentheses. In particular:

       o      Put   all   elements   of  the  macro  definition  on  one  line,  except  for  the
              macro-expansion itself. Each expansion element should be on a line by itself.

       o      When calling macros put  the  macro’s  arguments  underneath  each  other.  If  the
              macrolists  themselves  contain  macro-calls,  put each call again on a line of its
              own, indenting one tab-position beyond the location of the opening  parenthesis  of
              the argument.

       o      No continnuation backslashes are required between arguments.

       o      With  complex  calls,  indent  just the arguments, and put the parentheses in their
              required of logical locations.  Example of a complex call:

                      complex(
                          first(
                              ARG1
                          )(
                              ARG2
                              +XXnl()
                          )
                          ARG3
                          +nop()
                          ARG4
                          +XXnl()
                      )

       o      Macro expansion proceeds as follows:

       o      The arguments are read from the input

       o      The contents of the arguments then replace their `ARGx’ references in  the  macro’s
              definition  (in  some exceptional cases, clearly indicated as such when applicable,
              the arguments themselves are evaluated first, and then  these  evaluated  arguments
              are used as replacements for their corresponding `ARGx’ references).

       o      The  now  modified  macro is read by Yodl’s lexical scanner. This may result in yet
              another macro expansion, which will then be evaluated recursively.

       o      Eventually, all expansion is completed (well, should complete, since  Yodl  doesn’t
              test for eternal recursion) and scanning of the input continues beyond the original
              macro call.  For example, assume we have the following two macros:

                  DEFINEMACRO(First)(1)(
                      Hello ARG1
                      +XXnl()
                  )
                  DEFINEMACRO(Second)(1)(
                      First(ARG1)
                      First(ARG1)
                  )

              and the following call is issued:

                  Second(Yodl)

              then the following happens:

       o      `Second(Yodl)’ is read as encountered.

       o      `ARG1’ in `Second’ is replaced by YODL, and the resulting macro body is sent to the
              lexical scanner for evaluation: It will see:

                  First(Yodl)First(Yodl)

       o      The  first call to `First()’ is now evaluated. This puts (after replacing `ARG1’ by
              YODL) the following on the scanner’s input:

                  Hello Yodl+XXnl()First(Yodl)

       o      `Hello Yodl’ contains no macro call,  so  it  is  written  to  the  output  stream.
              Remains:

                  +XXnl()First(Yodl)

       o      Assume `XXnl()’ merely contains a newline (represented by `\n’, here), so `+XXnl()’
              is now replaced by `\n’. This results  in  the  following  input  for  the  lexical
              scanner:

                  \nFirst(Yodl)

       o      The `\n’ is now written to the output stream, and the scanner sees:

                  First(Yodl)

       o      The  second  call  to  `First()’  is  now evaluated. This puts the following on the
              scanner’s input:

                  Hello Yodl+XXnl()

       o      `Hello Yodl’ is written to the output stream. Remains:

                  +XXnl()

       o      `+XXnl()’ is now replaced by `\n’. The lexical scanner sees:

                  \n

       o      The newline is printed and we’re done.

       `DEFINESYMBOL’
              `DEFINESYMBOL’ expects two arguments. An identifier,  which  is  the  name  of  the
              symbol  to  define,  and the textual value of the symbol. If the second argument is
              empty, the symbol is defined, but has an empty value.

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

              Example:

                  DEFINESYMBOL(Yodl)(Your own document language)
                  DEFINESYMBOL(Options)()

       `DELETECHARTABLE’
              `DELETECHARTABLE’  removes  a  definition  of a character table that was defined by
              `DEFINECHARTABLE’. This function expects one argument: the name  of  the  character
              table remove.

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

              Example:

                  DELETECHARTABLE(mytable)

       `DELETECOUNTER’
              `DELETECOUNTER’  removes  a  definition  of  a  counter   that   was   defined   by
              `DEFINECOUNTER’.  This  function  expects  one argument: the name of the counter to
              remove.

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

              Example:

                  DELETECOUNTER(mycounter)

       `DELETEMACRO’
              `DELETEMACRO’  removes  a  definition of a macro that was defined by `DEFINEMACRO’.
              This function takes one argument: the macro name to remove.

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

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

              Example:
              DELETEMACRO(mymacro)

       `DELETENOUSERMACRO’
              `DELETENOUSERMACRO’ removes a `nousermacro’ definition. The  function  expects  one
              argument:  the  name  of  the  `nousermacro’  identifier  to  be  removed  from the
              nousermacro-set.

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

              Example:
              DELETENOUSERMACRO(mymacro)

       `DELETESYMBOL’
              `DELETESYMBOL’  removes  the  definition  of  a  symbol  variable.  It  expects one
              argument, holding the name of the variable to deleted.

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

              Example:

                  DELETESYMBOL(Options)

       `ERROR’
              The  `ERROR’  function  takes  one  argument: text to display to the standard error
              stream. The current input file and line number are also displayed. After displaying
              the text, the `yodl’ program aborts with an exit status of 1.

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

              The  `ERROR’  function  is  an  example  of  a function that evaluates its argument
              itself.

              This command can be used, e.g., in a macro  package  when  an  incorrect  macro  is
              expanded.  In  my macro package (see chapter `[MACROPACKAGE]’) the `ERROR’ function
              is used when the sectioning command `chapter()’ is used in  an  `article’  document
              (in the package, `chapter’’s are only available in `book’s or `report’s).

              An  analogous  builtin  function is `WARNING’, which also prints a message but does
              not exit (see section `[WARNING]’).

              Example: In the following call, `COUNTERVALUE(NTRIES)’ is replaced  by  its  actual
              value:

                  ERROR(Stopping after COUNTERVALUE(NTRIES) attempts)

       `EVAL’ The  `EVAL’  function  takes  one argument: the text to be evaluated. This function
              allows you to perform an indirect evaluation of Yodl commands. Assume that there is
              a  symbol  `varnam’  containing  the name of a counter variable, then the following
              displays the counter’s value, after having incremented it:

                  EVAL(NOTRANS(USECOUNTER)(SYMBOLVALUE(varnam)))

              Here, `EVAL’ performs the following steps:

       o      First, `NOTRANS(USECOUNTER)’ is evaluated, producing `USECOUNTER’.

       o      Next, the open parenthesis is processed, producing the open parenthesis itself

       o      Then, `SYMBOLVALUE(varnam)’ is evaluated, producing the name  of  a  counter,  e.g.
              ``counter’’.

       o      The closing parentheis is processed, producing the closing parenthesis itself.

       o      All this results in the text

                  USECOUNTER(counter)

       o      This  text  is  presented  to Yodl’s lexical scanner, resulting in incrementing the
              counter, and displaying its incremented value.

              b(Caveat): macro arguments themselves are usually not evaluated. So, a construction
              like

                  USECOUNTER(EVAL(SYMBOLVALUE(varnam)))

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

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

              Summarizing: `EVAL’ acts as follows:

       o      Its argument is presented to Yodl’s lexical scanner

       o      The  output  produced  by  the processing of the argument is then inserted into the
              input stream in lieu of the original `EVAL’ call.

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

              Postponing evaluations allows you to write:

                  DEFINESYMBOL(later)(SYMBOLVALUE(earlier))

              Eventually, and not when `later’ is defined, a statement like

                  SYMBOLVALUE(later)

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

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

              The example also shows yet another way to suppress macro  calls,  using  the  macro
              `nop()’ which is defined in the all standard conversion types:

                  DEFINESYMBOL(one)(One’s first value)
                  DEFINESYMBOL(two)(SYMBOLVALUE(one))
                  EVAL(DEFINESYMBOL+nop()(three)(SYMBOLVALUE(one)))
                  SETSYMBOL(one)(One’s second value)
                  "SYMBOLVALUE(two)"      COMMENT(displays "One’s second value")
                  "SYMBOLVALUE(three)"    COMMENT(displays "One’s first value")

       `FILENAME’
              The function `FILENAME()’ produces an absolute path to the currently processed Yodl
              file. This is not necessarily the canonical path name, as it may  contain  current-
              and parent-path directories.

       `FPUTS’
              The function `FPUTS’ expects two arguments: the first argument is information to be
              appended to a file, whose name is given as the second argument. The first  argument
              is  processed  by  Yodl  before it is appended to the requested filename, so it may
              contain macro calls.

              For example, the following statement appends a countervalue to the mentioned file:

                  FPUTS(There have been COUNTERVALUE(attempts) attempts)(/tmp/logfile)

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

       `IFBUILTIN’
              The `IFBUILTIN’ function tests whether its first argument is the name of a  builtin
              function.  If  so,  the  second  argument is evaluated, else, the third argument is
              evaluated. All three arguments (the variable, the  true-list  and  the  false-list)
              must be present; though the true-list and/or the false-list may be empty.

              Example:

                  IFBUILTIN(IFBUILTIN)(\
                      `BUILTIN’ is a builtin - function
                  )(\
                      `BUILTIN’ is NOT a builtin - function
                  )

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

       `IFCHARTABLE’
              The `IFCHARTABLE’ function tests whether its  first  argument  is  the  name  of  a
              character  table. The character table needs not be active.  If the name is the name
              of a character table, the second argument is evaluated, else, the third argument is
              evaluated. All three arguments (the name, the true list and the false list) must be
              present; though the true list and/or the false list may be empty.

              Example:

                  IFCHARTABLE(standard)(\
                      `standard’ is a character tablebuiltin - function
                  )(\
                      `standard’ is NOT a character tablebuiltin - function
                  )

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

       `IFDEF’
              The  `IFDEF’  function tests for the definition status of the argument in its first
              argument. If it is a defined entity, the second argument is  evaluated,  else,  the
              third argument is evaluated. All three arguments (the entity, the true list and the
              false list) must be present; though the true list and/or  the  false  list  may  be
              empty.

              The true list is evaluated if the first argument is the name of:

       o      a built-in function, or

       o      a character table, or

       o      a counter, or

       o      a no-user-macro symbol, or

       o      a symbol, or

       o      a user-defined macro, or Example:

                  IFDEF(someName)(\
                      `someName’ is a defined entity
                  )(\
                      `someName is not defined.
                  )

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

       `IFEMPTY’
              `IFEMPTY’ expects  three  arguments:  a  symbol,  a  true-list  and  a  false-list.
              `IFEMPTY’  evaluates  to the true-list if the symbol is an empty string; otherwise,
              it evaluates to the false-list.

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

              Example:

                  IFEMPTY(something)(\
                      `something’ is empty...
                  )(\
                      `something’ is not an empty string
                  )

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

              Using the macro, as in:
              \
                  bookref(Helmut Leonhardt)
                         (Histologie, Zytologie und Microanatomie des Menschen)
                         ()

              would now result in the text `Unknown’ behind the `Published by:’ line.

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

       `IFEQUAL’
              `IFEQUAL’ expects four argument lists. It tests whether its first argument is equal
              to  its  second  argument. If so, the third argument is evaluated, else, the fourth
              argument is evaluated. All four argument lists must be present, though all  can  be
              empty.

              The first two arguments of `IFEQUAL’ should be integral numeric arguments. In order
              to  determine  whether  the  first  two  arguments  are  equal,  their  values  are
              determined:

       o      If the argument starts with an integral numerical value, that value is the value of
              the argument.

       o      If the argument is the name of a counter, the counter’s value is the value  of  the
              argument

       o      If  the  values  of  the  first  two arguments van be determined accordingly, their
              equality determines whether the true list (when the values are equal) or the  false
              list (when the values are unequal) will be evaluated.

       o      Otherwise, `IFEQUAL’ evaluates the false list.

              Example:

                  IFEQUAL(0)()(\
                      0 and an empty string are equal
                  )(\
                      0 and an empty string are not equal
                  )

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

       `IFGREATER’
              `IFGREATER’ expects four argument lists. It tests whether  its  first  argument  is
              greater  than  its  second  argument. If so, the third parameter list is evaluated,
              otherwise its fourth argument  is  evaluated.  All  four  argument  lists  must  be
              present, though all can be empty.

              The  first  two  arguments  of `IFGREATER’ should be integral numeric arguments. In
              order to determine whether the first two arguments  are  equal,  their  values  are
              determined:

       o      If the argument starts with an integral numerical value, that value is the value of
              the argument.

       o      If the argument is the name of a counter, the counter’s value is the value  of  the
              argument

       o      If the values of the first two arguments van be determined accordingly, their order
              relation determines whether the true list (when the first value is greater than the
              second  value) or the false list (when the first value is smaller or equal than the
              second value) is evaluated.

       o      Otherwise, `IFGREATER’ evaluates the false list.

              Example:

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

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

       `IFMACRO’
              The  `IFMACRO’ function tests whether its first argument is the name of a macro. If
              the name is the name of a macro, the second argument is evaluated, else, the  third
              argument  is  evaluated. All three arguments (the name, the true list and the false
              list) must be present; though the true list and/or the false list may be empty.

              Example:

                  IFMACRO(nested)(\
                      `nested’ is the name of a macro
                  )(\
                      There is no macro named `nested’
                  )

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

       `IFSMALLER’
              `IFSMALLER’  expects  four  argument  lists. It tests whether its first argument is
              smaller than its second argument. If so, the third  parameter  list  is  evaluated,
              otherwise  its  fourth  argument  is  evaluated.  All  four  argument lists must be
              present, though all can be empty.

              The first two arguments of `IFSMALLER’ should be  integral  numeric  arguments.  In
              order  to  determine  whether  the  first two arguments are equal, their values are
              determined:

       o      If the argument starts with an integral numerical value, that value is the value of
              the argument.

       o      If  the  argument is the name of a counter, the counter’s value is the value of the
              argument

       o      If the values of the first two arguments van be determined accordingly, their order
              relation determines whether the true list (when the first value is smaller than the
              second value) or the false list (when the first value is greater than or  equal  to
              the second value) is evaluated.

       o      Otherwise, `IFSMALLER’ evaluates the false list.

              Example:

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

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

       `IFSTREQUAL’
              `IFSTREQUAL’ tests for the equality of two strings. It expects four arguments:  two
              strings  to  match,  a  true list and a false list. The true list is only evaluated
              when the contents of the two string arguments exactly match.

              The first two arguments of `IFSTREQUAL’ are partially evaluated:

       o      If the argument is the name of a symbol, the symbol’s value is  the  value  of  the
              argument

       o      Otherwise, the argument itself is used.

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

              Example:

                  IFSTREQUAL(MYSYMBOL)(Hello world)(
                      The symbol `MYSYMBOL’ holds the value `Hello world’
                  )(
                      The symbol `MYSYMBOL’ doesn’t hold the value `Hello world’
                  )

       `IFSTRSUB’
              `IFSTRSUB’  tests  whether  a  string  is  a  sub-string of another string. It acts
              similar to IFSTREQUAL, but it tests whether the second string is part of the  first
              one.

              The first two arguments of `IFSTREQULA’ are partially evaluated:

       o      If  the  argument  is  the name of a symbol, the symbol’s value is the value of the
              argument

       o      Otherwise, the argument itself is used.

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

              Example:

                      IFSTRSUB(haystack)(needle)(
                          `needle’ was found in `haystack’
                      )(
                          `needle’ was not found in `haystack’
                      )

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

       `IFSYMBOL’
              The `IFSYMBOL’ function tests whether its first argument is the name of  a  symbol.
              If  it  is  the  name  of a symbol, the second argument is evaluated, otherwise the
              third argument is evaluated. All three arguments (the name, the true list  and  the
              false  list)  must  be  present;  though the true list and/or the false list may be
              empty.

              Example:

                  IFSYMBOL(nested)(\
                      `nested’ is the name of a symbol
                  )(\
                      There is no symbol named `nested’
                  )

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

              C(  FBB consider additive expressions   )

       `IFZERO’
              `IFZERO’  expects  three  arguments. If the first argument is zero (0) the function
              expands to the true list (the second argument). Otherwise it expands to  the  false
              list (the third argument).

              The  first  argument  of `IFZERO’ should be an integral numeric value. Its value is
              determined as follows:

       o      If the argument starts with an integral numerical value, that value is the value of
              the argument.

       o      If  the  argument is the name of a counter, the counter’s value is the value of the
              argument

       o      Otherwise, the first arguments evaluates as 0, and the false list is used.

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

              Example:

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

              Such a macro may be used as follows:

                  environment(center)(1)
                      Now comes centered text.
                  environment(center)(0)

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

       `INCLUDEFILE’
              `INCLUDEFILE’  takes  one argument, a filename. The file is processed by Yodl. If a
              file should be inserted without processing  the  builtin  function  NOEXPANDINCLUDE
              `[NOEXPANDINCLUDE]’ or NOEXPANDPATHINCLUDE `[NOEXPANDPATHINCLUDE]’ should be used.

              The  `yodl’  program  supplies,  when necessary, an extension to the filename.  The
              supplied extension is `.yo’, unless defined otherwise during the compilation of the
              program.

              Furthermore, Yodl tries to locate the file in the Yodl’s include path (which may be
              set using the `--include’ option). The actual value of the include path is shown in
              the usage information, displayed when Yodl is started without arguments.

              Example:

                  INCLUDEFILE(latex)

              Here,  Yodl  attempts  to  include  the file `latex’ or `latex.yo’ from the current
              include path. When the file is not found, Yodl aborts.

       `INCWSLEVEL’
              `INCWSLEVEL’ requires one (empty) argument.

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

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

              Example:

                  INCWSLEVEL()
                  DEFINESYMBOL(....)
                  DEFINEMACRO(...)(...)(...)
                  DECWSLEVEL()

              Without the `INCWSLEVEL’  and  `DECWSLEVEL’,  calls,  the  above  definition  would
              generate four empty lines to the output stream.

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

       `INTERNALINDEX’
              `INTERNALINDEX’  expects  one  argument  list.  The  argument list is evaluated and
              written to the index file.

              The index file  is  defined  since  Yodl  version  2.00,  and  contains  the  fixup
              information  which  was  previously written to Yodl’s output as the `.YODLTAGSTART.
              ... .YODLTAGEND.’ sequence.

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

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

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

                  3004 ref MACROPACKAGE

              indicating that at offset 3004 in the produced output file a reference to the label
              `MACROPACKAGE’   is  requested.  Assuming  a  html  conversion,  The  postprocessor
              thereupon writes something like

                  <a href="outfile04.html#MACROPACKAGE">4.3.2.</a>

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

              Consequently, producing Yodl-output normally consists of two steps:

       o      First,  Yodl  itself  is  started,  producing, e.g., `out.idx’ (the index file) and
              `out.yodl’ (Yodl’s raw output).

       o      Then, Yodl’s post-processor processes `out.idx’ and `out.yodl’,  producing  one  or
              more final output files, in which the elements of the index file have been properly
              handled. This may result in multiple output file, like `report.html, report01.html,
              report02.html’ etc.

       `NOEXPAND’
              `NOEXPAND’  is used to send text to the final output file without being expanded by
              Yodl (the other methods are  the  `CHAR’  macro,  see  section  `[CHAR]’,  and  the
              `NOTRANS’ macro, see section `[NOTRANS]’).  `NOEXPAND’ takes one argument, the text
              in question. Whatever occurs in the argument is not subject to parsing or expansion
              by  Yodl,  but  is  simply  copied  to  the  output  file  (except  for  `CHAR’ and
              (iinternally used) `XXSUBST’ functions in the  argument,  which  are  expanded.  If
              `CHAR’-expansion is not required either NOTRANS `[NOTRANS]’ can be used).

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

              So, the following situations are recognized:

              ──────────────────────────────────────────────
                                    support chartables
                                         and CHAR
                              ──────────────────────────────
              Macro expansion   yes          no
              ──────────────────────────────────────────────
              Yes               (standard)   Push chartable
                                             (standard)
                                             Pop chartable
              No                NOEXPAND     NOTRANS
              ──────────────────────────────────────────────

              E.g., let’s assume that you need to write in your document the following text:

                  INCLUDEFILE(something or the other)
                  IFDEF(onething)(
                      ...
                  )(
                      ....
                  )
                  NOEXPAND(whatever)

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

              For this function, keep the following caveats in mind:

       o      There  is only one thing that a `NOEXPAND’ cannot protect from expansion: an `ARG’x
              in a macro definition. The argument specifier is always processed. E.g., after

                  DEFINEMACRO(thatsit)(1)(
                      That is --> NOEXPAND(ARG1) <-- it!
                  )
                  thatsit(after all)

              the `ARG1’ inside the `NOEXPAND’ statement is replaced with `after all’.

       o      The `NOEXPAND’ function must, as all functions, be  followed  by  a  argument.  The
              parentheses  of  the  list must therefore be `balanced’.  For unbalanced lists, use
              `CHAR(40)’ to  set  an  open  parenthesis,  or  `CHAR(41)’  to  typeset  a  closing
              parenthesis.

       `NOEXPANDINCLUDE’
              `NOEXPANDINCLUDE’ takes one argument, a filename. The file is included.

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

              The argument to `NOEXPANDINCLUDE’ is partially evaluated:

       o      If the argument is the name of a symbol, the symbol’s value is  the  value  of  the
              argument

       o      Otherwise, the argument itself is used.  The thus obtained file name is not further
              evaluated: in particular, it is not affected by available character translations.

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

              The purpose of NOEXPANDINCLUDE is to include source code literally in the document,
              as in:

                  NOEXPANDINCLUDE(literal.c)

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

       `NOEXPANDPATHINCLUDE’
              `NOEXPANDPATHINCLUDE’  takes  one  argument,  a filename. The file is included. The
              file is searched for in the directories specified in Yodl’s includepath.

              The argument to `NOEXPANDPATHINCLUDE’ is partially evaluated:

       o      If the argument is the name of a symbol, the symbol’s value is  the  value  of  the
              argument

       o      Otherwise, the argument itself is used.  The thus obtained file name is not further
              evaluated: in particular, it is not affected by available character translations.

              Like the  `NOEXPANDINCLUDE’  function,  the  contents  of  the  file  are  included
              literally,  not  subject  to macro expansion. Character translations are performed,
              though.   If   character   translations   are   not   appropriate,    PUSHCHARTABLE
              `[PUSHCHARTABLE]’ can be used to suppress character table translations temporarily.

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

                  NOEXPANDPATHINCLUDE(rug-menubegin.xml)

       `NOTRANS’
              `NOTRANS’ copies its one argument literally to the output file,  without  expanding
              macros  in  it  and without translating the characters with the current translation
              table. The `NOTRANS’ function is typically used to send  commands  for  the  output
              format to the output file.

              For example, consider the following code fragment:

                  COMMENT(--- Define character translations for \, { and } in LaTeX. ---)
                  DEFINECHARTABLE(standard)(
                      ’\\’    =    "$\\backslash$"
                      ’{’     =    "\\verb+{+"
                      ’}’     =    "\\verb+}+"
                  )

                  COMMENT(--- Activate the translation table. ---)
                  USECHARTABLE(standard)

                  COMMENT(--- Now two tests: ---)

                  NOEXPAND(\input{epsf.tex})
                  NOTRANS(\input{epsf.tex})

              `NOEXPAND’ sends

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

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

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

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

                  XXSUBST+CHAR(40)...CHAR(41)

              can be used.

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

       `NOUSERMACRO’
              `NOUSERMACRO’ controls `yodl’’s warnings in the following way: When Yodl is started
              with the `-w’ flag on the command line, warnings are generated when Yodl encounters
              a  possible  macro name, i.e., a name that is followed by a parenthesized argument,
              while no macro by that name has been defined.   Yodl  then  prints  something  like
              `cannot expand possible user macro’.

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

              When  a  corresponding `NOUSERMACRO’ statement appears before `yodl’ encounters the
              candidate macros, no warning is generated. A fragment might therefore be:

                  NOUSERMACRO(file sed)
                  The necessary file(s) are in ...
                  See the manual page for sed(1).

              The `NOUSERMACRO’ accepts one or more names in its  argument,  separated  by  white
              space, commas, colons, or semi-colons.

       `OUTBASE’
              `OUTBASE’ inserts the current basename of the output file into the output file. The
              basename is the name of the file of which the directory  components  and  extension
              were stripped.

              If the output file is the standard output file, `-’ is inserted.

       `OUTDIR’
              `OUTDIR’ inserts the current path name of the output file into the output file. The
              path name is a, not necessarily absolute, designator of the directory in which  the
              output  file  is  located. If the output file is indicated as, e.g., `-o out’, then
              `OUTDIR’ simply inserts a dot.

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

       `OUTFILENAME’
              `OUTFILENAME’ inserts the current filename of the output file into the output file.
              The  filename  is  the  name  of  the  file of which the directory components  were
              stripped.

              If the output file is the standard output file, `-’ is inserted.

       `PARAGRAPH’
              `PARAGRAPH’ isn’t really a builtin function, but as Yodl handles  paragraphs  in  a
              special  way it is probably useful to describe paragraph handling here nonetheless.
              Starting with Yodl 2.00  `PARAGRAPH’ operates as follows:

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

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

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

              Note that, in order to inspect `XXparagraph’ it must have been defined first.  Yodl
              itself does not define this symbol itself.

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

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

                  DEFINEMACRO(PARAGRAPH)(0)(
                      XXnl()
                      NOTRANS(<p>)
                  )

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

                  DEFINEMACRO(PARAGRAPH)(0)(
                      XXnl()
                      IFZERO(XXp)(
                      )(
                          NOTRANS(</p>)
                      )
                      NOTRANS(<p>)
                      SETCOUNTER(XXp)(1)
                  )

              Note  that  the  above  fragment  exemplifies  an  approach,  not  necessarily  the
              implementation of the `PARAGRAPH’ macro for an xml-converter.

       `PIPETHROUGH’
              The  builtin  function `PIPETHROUGH’ is, besides `SYSTEM’, the second function with
              which a Yodl document can affect its environment. `PIPETHROUGH’ can be very useful.
              It  uses  an  external  program to accomplish special features. The idea is that an
              external command is started, to which a block of text from within a  Yodl  document
              is  `piped’. The output of that child program is piped back into the Yodl document;
              hence, a block of text  is  `piped  through’  an  external  program.   Whatever  is
              received again in the Yodl run, is further processed.

              The `PIPETHROUGH’ function takes two arguments:

       o      the command to run, and

       o      the text to send to that command.

              Functionally, the occurrence of the `PIPETHROUGH’ function and of its two arguments
              is replaced by whatever the child program produces on its standard output.

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

              The current date is:
              PIPETHROUGH(date)()

              In this example the command is `date’ and the text  to  send  to  that  program  is
              empty.

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

       `POPCHARTABLE’
              Character  tables which are pushed onto the table stack using `PUSHCHARTABLE()’ are
              restored (popped) using `POPCHARTABLE()’.  For  a  description  of  this  mechanism
              please refer to section `[PUSHINGTABLES]’.

       `POPCOUNTER’
              `POPCOUNTER’  is  used  to  remove the topmost counter from the counter stack.  The
              values of counters may be pushed on a stack using PUSHCOUNTER  `[PUSHCOUNTER]’.  To
              remove  the  topmost  element  of  a  counter’s  stack  `POPCOUNTER’  is available.
              `POPCOUNTER’ expects one argument: the name of the counter to pop.  The  previously
              pushed  value  then  becomes the new value of the counter. A counter’s value may be
              popped after defining it, whereafter the stack is empty, but the counter will still
              be defined. In that case, using the counter’s value is considered an error.

              Examples:

                  DEFINECOUNTER(YEAR)(1950)
                  POPCOUNTER(YEAR)
                  COMMENT(YEAR now has an undefined value)

              See also section `[COUNTERS]’.

       `POPMACRO’
              `POPMACRO’  is  used  to remove the actual macro definition, restoring a previously
              pushed definition.  The values of macros may be pushed on a stack using PUSHMACRO.

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

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

              Example:

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

       `POPSUBST’
              `POPSUBST’ is used to revert to a  previous  level  of  interpretation  of  `SUBST’
              definitions.  Refer  to  the  descriptions  of  the `PUSHSUBST’ and `SUBST’ builtin
              commands below for details.

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

       `POPSYMBOL’
              `POPSYMBOL’ is used to remove the topmost symbol from the symbol stack.  The values
              of  symbols may be pushed on a stack using PUSHSYMBOL `[PUSHSYMBOL]’. To remove the
              topmost element of a symbol’s stack `POPSYMBOL’ is available.

              `POPSYMBOL’ expects one argument: the name of the symbol  to  pop.  The  previously
              pushed value then becomes the new value of the symbol.

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

              Example:

                  DEFINESYMBOL(YEAR)(This happened in 1950)
                  POPSYMBOL(YEAR)
                  COMMENT(YEAR now has an undefined value)

       `POPWSLEVEL’
              `POPWSLEVEL’  is  used  to  remove the topmost wslevel from the wslevel stack.  The
              values of wslevels may be pushed on a stack using PUSHWSLEVEL `[PUSHWSLEVEL]’.  See
              also section DECWSLEVEL `[DECWSLEVEL]’

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

              Example:

                  COMMENT(Assume WS level is zero)

                  PUSHWSLEVEL(1)
                  COMMENT(WS level now equals 1)

                  POPWSLEVEL()
                  COMMENT(WS level now equals 0 again)

       `PUSHCHARTABLE’
              Once  a  character  table  has  been  defined,  it can be pushed onto a stack using
              `PUSHCHARTABLE’. The pushed chartable  may  be  popped  later.  `PUSHCHARTABLE’  is
              described in more detail in section `[PUSHINGTABLES]’.

       `PUSHCOUNTER’
              `PUSHCOUNTER’  is used to start another lifetime for a counter, pushing its current
              value on a stack. A stack is available for each individual counter.

              `PUSHCOUNTER’ expects two arguments: the  name  of  the  counter  to  push  and  an
              additive  expression whose value becomes the counter’s new value (after pushing the
              current value)

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

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

              Examples:

                  DEFINECOUNTER(YEAR)(1950)
                  PUSHCOUNTER(YEAR)(1962)
                  COMMENT(YEAR now has the value 1962, and a pushed value of 1950)

              See also section `[COUNTERS]’.

       `PUSHMACRO’
              `PUSHMACRO’  is  used  to  start  another lifetime for a macro, pushing its current
              definition on a stack. A stack is available for each individual macro.

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

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

              Example:

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

       `PUSHSUBST’
              `PUSHSUBST’ can be used to (temporarily) suppress  the  interpretation  of  `SUBST’
              definitions   (the  `SUBST’  built-in  command  is  covered  below,  refer  to  its
              description for an example).

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

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

       `PUSHSYMBOL’
              `PUSHSYMBOL’ is used to start another lifetime for a symbol,  pushing  its  current
              value on a stack. A stack is available for each individual symbol.

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

              Examples:

                  DEFINESYMBOL(YEAR)(This happened in 1950)
                  PUSHSYMBOL(YEAR)(This happended in 1962)
                  COMMENT(YEAR now has the value `This happended in 1962’ and a
                          pushed value of `This happened in 1950’)

       `PUSHWSLEVEL’
              `PUSHWSLEVEL’  is  used  to start another lifetime of the white-space level pushing
              the level’s current value on a stack. See also section INCWSLEVEL `[INCWSLEVEL]’

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

              Example:

                  COMMENT(Assume WS level is zero)

                  PUSHWSLEVEL(1)
                  COMMENT(WS level now equals 1)

                  POPWSLEVEL()
                  COMMENT(WS level now equals 0 again)

       `RENAMEMACRO’
              `RENAMEMACRO’  takes  two  arguments:  the  name  of  a  built-in  macro  (such  as
              `INCLUDEFILE’) and its new name.

              E.g., after

                  RENAMEMACRO(INCLUDEFILE)(include)

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

              If  you  want  to  make  an alias for a built-in command, do it with `DEFINEMACRO’.
              E.g., after:

                  DEFINEMACRO(include)(1)(INCLUDEFILE(ARG1))

              both `INCLUDEFILE’ and `include’ can be used to include a file.

       `SETCOUNTER’
              `SETCOUNTER’ expects two  arguments:  the  name  of  a  counter,  and  an  additive
              expression  defining  the  value  to assign. The counter must be previously created
              with `DEFINECOUNTER’.

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

              For example, if `one’ and `two’ are counters, then

                  SETTOCOUNTER(one)(-two)\//    assigns -two’s value to one
                  SETTOCOUNTER(one)(two+two)\// assigns 2 x two’s value to one

              See also section `[COUNTERS]’.

       `SETSYMBOL’
              `SETSYMBOL’  expects two arguments: the name of a symbol, and the text to assign to
              the named symbol. The symbol must previously have been defined by `DEFINESYMBOL’.

       `SUBST’
              `SUBST’ is a general-purpose substitution mechanism for strings  appearing  in  the
              input.  `SUBST’  takes  two  arguments:  a search string and a substitution string.
              E.g., after

                  SUBST(VERSION)(1.00)

              YODL transforms all occurrences of `VERSION’ in its input into `1.00’.

              `SUBST’ is also useful in situations  where  multi-character  sequences  should  be
              converted to accented characters. E.g., a LaTeX converter might define:

                  SUBST(’e)(+NOTRANS(\’{e}))

              Each `’e’ in the input will subsequently be converted to `e’.

              `SUBST’  may  be  useed  in  combination  with  the command line flag `-P’, as in a
              invocation

                  yodl2html -P’SUBST(VERSION)(1.00)’ myfile.yo

              Another useful substitution might be:

                  SUBST(_OP_)(CHAR(40))
                  SUBST(_CP_)(CHAR(41))

              which defines an opening parenthesis (`_OP_’) and a closing parenthesis (`_CP_’) as
              mapped  to the `CHAR’ function. The strings `_OP_’ and `_CP_’ might then be used to
              produce unbalanced arguments.

              Note that:

       o      The first argument of the `SUBST’ command, the search string, is  taken  literally.
              Yodl does not expand it; the string must be literally matched in the input.

       o      The  second  argument, the replacement, is further processed by Yodl.  Protect this
              text by `NOTRANS’ or `NOEXPAND’ where appropriate.

              Substitutions occur extremely early while YODL processes its input files. In  order
              to process its input files, YODL takes the following steps:

       1.     It requests input from its lexical scanner (so-called tokens)

       2.     Its parser processes the tokens produced by the lexical scanner

       3.     Its  parser  may  send  text to an output `object’, which eventually appears in the
              output file generated by YODL.  YODL performs all macro substitutions  in  step  2,
              and  all  character  table  conversions in step 3. However, the lexical scanner has
              access to the `SUBST’ definitions: as soon as its lexical analyzer detects a series
              of  characters  matching the defining sequence of a `SUBST’ definition, it replaces
              that defining sequence by its definition. That definition is then again read by the
              lexical  scanner.  Of  course,  this  definition  may,  in  turn,  contain defining
              sequences  of  other  `SUBST’  definitions:  these  are  then  replaced  by   their
              definitions as well. This implies:

       o      Circular  definitions  may  cause the lexical scanner to get stuck in a replacement
              loop. It is the responsibility of the author defining `SUBST’ definitions  to  make
              sure that this doesn’t happen.

       o      Neither  the parser, nor the output object ever sees the `SUBST’ defining character
              sequences: they only see their definitions.

              In some cases substitutions must be suppressed. Consider double quoted text strings
              that  are frequently used in programming languages. E.g., `"hello world"’. The text
              inside the string should not be converted by Yodl, but unless substitutions can  be
              suppressed the string
              "\"evil code"

              appears as
              "evil code"

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

       `SYMBOLVALUE’
              `SYMBOLVALUE’ expands to the value of a symbol. Its single  argument  must  be  the
              name of a symbol.  The symbol must have been created earlier using `DEFINESYMBOL’.
              Example:

                  The symbol has value SYMBOLVALUE(MYSYMBOL).

       `SYSTEM’
              `SYSTEM’  takes  one  argument:  a  command  to execute. The command is run via the
              standard C function `system’.

              `SYSTEM’ can be useful in many ways. E.g., you  might  want  to  log  when  someone
              processes your document, as in:

                  SYSTEM(echo Document processed! | mail myself@my.host)

              Note  that  `SYSTEM’ merely performs an system-related task. It’s a process that is
              separated from the YODL process itself. One of the consequences of this is that any
              output  generated  by `SYSTEM’ not normally appears into YODL’s output file. If the
              output of a subprocess should be inserted  into  YODL’s  output  file,  either  use
              PIPETHROUGH  `[PIPETHROUGH]’,  or insert a temporary file as shown in the following
              example:

                  SYSTEM(date > datefile)
                  The current date is:
                  INCLUDEFILE(datefile)
                  SYSTEM(rm datefile)

       `TYPEOUT’
              `TYPEOUT’ requires one argument. The text of the list is sent to the standard error
              stream,  followed  by  a newline. This feature can be handy to show, e.g., messages
              such as version numbers in macro package files.

              Example: The following macro includes a file and writes to  the  screen  that  this
              file is currently processed.

                  DEFINEMACRO(includefile)(1)(
                      TYPEOUT(About to process document: ARG1)
                      INCLUDEFILE(ARG1)
                  )

       `UPPERCASE’
              `UPPERCASE’ converts a string or a part of it to upper case. It has two arguments:

       o      The string to convert;

       o      A  length,  indicating  how  many  characters  (starting  from the beginning of the
              string) should be converted.  The length indicator  can  be  smaller  than  one  or
              larger  than  the  length  of  the  string;  in  that  case,  the  whole  string is
              convertered.

              Example:

                  UPPERCASE(hello world)(1)
                  UPPERCASE(hello world)(5)
                  UPPERCASE(hello world)(0)

              This code sample expands to:

                  Hello world
                  HELLO world
                  HELLO WORLD

       `USECHARTABLE’
              `USECHARTABLE’ takes one argument: the name of a translation table to activate. The
              table  must  previously  have  been  defined  using  `DEFINECHARTABLE’. See section
              `[CHARTABLES]’ for a description of character translation tables.

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

       `USECOUNTER’
              `USECOUNTER’  is a combination of `ADDTOCOUNTER’ and `COUNTERVALUE’. It expects one
              argument: the name of an defined counter (see DEFINECOUNTER `[DEFINECOUNTER]’).

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

              See also section `[COUNTERS]’.

       `VERBOSITY’
              `VERBOSITY’  expects  two  arguments, and may be used to change the verbosity level
              inside YODL files. The function may be used profitably for debugging  purposes,  to
              debug the expansion of a macro or the processing of a YODL input file.

              The  first argument indicates the procesing mode of the second argument, and it may
              be:

       o      Empty, in which case the message-level is set to the value specified in the  second
              argument;

       o      `+’,  in which case the value specified in the second argument augments the current
              message level;

       o      `-’, in which case the value specified in the second argument augments  is  removed
              from the current message level

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

              The following message levels are defined:

       o      ALERT (0x40). When an alert-error  occurs,  Yodl  terminates.  Here  Yodl  requests
              something of the system (like a `get_cwd()’), but the system fails.

       o      CRITICAL (0x20). When a critical error occurs, Yodl terminates.  The message itself
              can be suppressed, but exiting can’t. A critical condition is, e.g.,  the  omission
              of  an open parenthesis at a location where a parenthesized argument should appear,
              or a non-existing file in an `INCLUDEFILE’ specification (as this  file  should  be
              parsed).  A  non-existing  file  with  a `NOEXPANDINCLUDE’ specification is a plain
              (non-critical) error.

       o      DEBUG (0x01). Probably too much info, like getting information about each character
              that was read by Yodl.

       o      ERROR  (0x10). An error (like doubly defined symbols). Error messages will not stop
              the parsing of the input (up to a maximum number  of  errors),  but  no  output  is
              generated.

       o      INFO (0x02). Not as detailed as `debug’, but still very much info, like information
              about media switches.

       o      NOTICE (0x04). Information about, e.g., calls to the builtin function calls.

       o      WARNING (0x08). Something you should know about, but probably not affecting  Yodl’s
              proper functioning

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

              The value `0x00’ represents `NONE’, the value `0xff’ represents `ALL’.

              When   specifying  multiple  message  levels  using  the  hexadecimal  form,  their
              hexadecimal values should be binary-or-ed: adding them is ok, as long as you  don’t
              specify `ALL’:

                  VERBOSITY()(0x06)
                  COMMENT(this specifies `INFO’ and `NOTICE’)

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

                  VERBOSITY()(I N)
                  VERBOSITY()(N I)
                  VERBOSITY()(NOT IN)
                  VERBOSITY()(INFO NOTICE)

       `WARNING’
              `WARNING’ takes one argument: text to display as  a  warning.  The  `yodl’  program
              makes  sure  that  before  showing  the  text, the current file and line number are
              printed.  Other  than  this,  `WARNING’  works  just  as  `TYPEOUT’  (see   section
              `[TYPEOUT]’).

              Note  that  an  analogous  function `ERROR’ exists, which prints a message and then
              terminates the program (see section `[ERROR]’).

FILES

       The files in tmp/wip/macros define the converter’s macro packages. The  scripts  yodl2tex,
       yodl2html, yodl2man etc. perform the conversions.

SEE ALSO

       yodl(1),  yodlconverters(1),  yodlletter(7),  yodlmacros(7),  yodlmanpage(7), yodlpost(1),
       yodlstriproff(1), yodltables(7), yodlverbinsert(1).

BUGS

       --

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl),