Provided by: yodl_3.03.0-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.

       NOTE:  Starting  with  Yodl  version  3.00.0  Yodl’s  default  file inclusion behavior has
       changed. The current working directory no longer remains fixed at the directory  in  which
       Yodl  is  called,  but  is  volatile,  changing  to  the directory in which a yodl-file is
       located. This has the advantage that Yodl’s file inclusion behavior now  matches  the  way
       C’s  #include  directive  operates; it has the disadvantage that it may break some current
       documents. Conversion, however is simple but  can  be  avoided  altogether  if  Yodl’s  -L
       (--legacy-include)   option   is  used.  The  builtins  INCLUDEFILE,  NOEXPANDINCLUDE  and
       NOEXPANDPATHINCLUDE are affected by this new behavior.

       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 will 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 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]);  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 parameter
              lists: the counter name, and the value to  add.  The  counter  must  be  previously
              created with DEFINECOUNTER.

              The  value  to  add  can be negative; in that case, a value is of course subtracted
              from the counter.

              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 will add 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  takes  one  parameter  list  as argument. The text of the parameter list is
              appended to the output file. Note that this text  is  subject  to  character  table
              translations etc..

              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
              way of matching parentheses in a parameter list.

              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 will search
              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 takes one parameter list. The text in the list is treated as
              comment. I.e., it is ignored. The text is not copied to the final output file.

       COUNTERVALUE
              COUNTERVALUE expands to the value of a counter.  Its  single  parameter  list  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) parameter list.  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 will be 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  will  effectively be 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 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,  to  be  subsequently  used  by,  e.g, the
              USECOUNTER function. DEFINECOUNTER expects two parameter  list:  the  name  of  the
              counter  to  create  and  an optional initial value. By default the counter will be
              initialized to zero.

              Examples:

                  DEFINECOUNTER(YEAR)(1950)
                  DEFINECOUNTER(NTIMES)()

              See also section [COUNTERS].

       DEFINEMACRO
              DEFINEMACRO is used to define new macros. This function  requires  three  parameter
              lists:

       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 used.
              The number must be in the range 0 to 61.

       o      The text that the macro will expand to,  once  used.  This  text  may  contain  the
              strings  ARGx,  x being 1, 2, etc.. At these places the arguments to the macro will
              be pasted in. The numbers that identify the arguments are 1 to 9, then A to  Z  and
              finally  a to z. This gives a range of 61 expandable arguments, 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 three parameter lists are pasted to  the  places  where
              ARG1, ARG2 etc. occur in the definition.

              Note the following when defining new macros:

       o      The  parameter  list  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 parameter
              list.

              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 will be
              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
              parameter list 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()
                  )

              will, when called as oops(hello world), produce 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 parameter lists 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 parameter lists. So, do not use
              them there to prevent unnecessary clutter.

       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 parameter lists are read from the input

       o      The  contents  of  the parameters then replace their ARGx references in the macro’s
              definition (in some exceptional cases, clearly indicated as such  when  applicable,
              the  arguments  will  themselves  be  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 will happen:

       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 will put (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 will put  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
              NOTE:  this  function  has  changed at the release of Yodl 2.00. It now expects two
              parameter lists, rather than one

              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  parameter
              list, 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)

       DUMMY  This function is obsolete. It does nothing, and may be removed in  future  versions
              of Yodl.

       ENDDEF ENDDEF  is  obsolete,  and  should be replaced by DECWSLEVEL.  It may be removed in
              future versions of Yodl.

       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  parameter  list
              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 books or reports).

              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  will
              display the value of the counter, incrementing it first:

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

              The actions of the EVAL function can be described as follows:

       o      First, the NOTRANS(USECOUNTER) is evaluated, producing USECOUNTER.

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

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

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

       o      All this results in the text

                  USECOUNTER(counter)

       o      This text is now presented to Yodl’s lexical scanner, resulting in incrementing the
              counter, and displaying its incremented value.  It should be  realized  that  macro
              arguments themselves are usually not evaluated. So, a construction like

                  USECOUNTER(EVAL(SYMBOLVALUE(varnam)))

              will  fail,  since EVAL(SYMBOLVALUE(varnam)) is not a legal name for a counter: the
              EVAL() call is used here as an argument, which is not expanded. The distinction  is
              subtle,  and  is  caused  by  the  fact  that builtin functions receive unprocessed
              arguments, and may impose certain requirements on them (like  USECOUNTER  requiring
              the name of a counter).

              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.

              Mosy built-in functions will not evaluate their arguments.  In  fact,  only  ERROR,
              EVAL,  FPUTS,  INTERNALINDEX,  TYPEOUT, UPPERCASE and WARNING() will 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)

              will produce 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  keep
              original  values  in  some situation?’ In those situations EVAL() must be used. The
              following example shows the definition of three symbols: one  receives  an  initial
              value,  two  will  return  one’s  actual value when two’s value is displayed, three
              will, using EVAL(), store one’s initial value. The example also shows  yet  another
              way  to  suppress macro  calls. It uses the macro nop() which is defined in the all
              standard conversion types.

                  DEFINESYMBOL(one)(This is one, before)
                  DEFINESYMBOL(two)(SYMBOLVALUE(one))
                  EVAL(DEFINESYMBOL+nop()(three)(SYMBOLVALUE(one)))
                  SETSYMBOL(one)(this is one, after)
                  SYMBOLVALUE(two)
                  SYMBOLVALUE(three)

       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 argment 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 will append 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 parameter list is evaluated, else, the third parameter
              list is evaluated. All three parameter lists (the variable, the true-list  and  the
              false-list)  must  be  present;  though  the true-list and/or the false-list may be
              empty parameter lists.

              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  parameter list is evaluated, else, the third
              parameter list is evaluated. All three parameter lists (the name, the true list and
              the  false list) must be present; though the true list and/or the false list may be
              empty parameter lists.

              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
              parameter list. If it is a defined entity, the second parameter list is  evaluated,
              else, the third parameter list is evaluated. All three parameter lists (the entity,
              the true list and the false list) must be present; though the true list and/or  the
              false list may be empty parameter lists.

              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 parameter list is evaluated, else, the
              fourth parameter list is evaluated. All four argument lists must be present, though
              all can be empty lists.

              The first two arguments of IFEQUAL should be integral numerical 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 will determine whether the true list (when the values are  equal)  or  the
              false list (when the values are unequal) will be evaluated.

       o      Otherwise, IFEQUAL will evaluate 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 to its second argument. If so, the third parameter list is evaluated, else,
              the fourth parameter list is evaluated. All four argument lists  must  be  present,
              though all can be empty lists.

              The  first  two  arguments  of IFGREATER should be integral numerical 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 will determine 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) will be evaluated.

       o      Otherwise, IFGREATER will evaluate 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 parameter list is evaluated, else,  the
              third  parameter  list  is evaluated. All three parameter lists (the name, the true
              list and the false list) must be present; though the true  list  and/or  the  false
              list may be empty parameter lists.

              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 to its second argument. If so, the third parameter list is evaluated, else,
              the fourth parameter list is evaluated. All four argument lists  must  be  present,
              though all can be empty lists.

              The  first  two  arguments  of IFSMALLER should be integral numerical 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 will determine 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) will be evaluated.

       o      Otherwise, IFSMALLER will evaluate 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 parameter list is evaluated, else, the third
              parameter list is evaluated. All three parameter lists (the name, the true list and
              the  false list) must be present; though the true list and/or the false list may be
              empty parameter lists.

              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.

       IFZERO IFZERO  expects three parameter lists. The first argument defines whether the whole
              function expands to the true list or to the false list.

              The first argument of IFZERO should be an integral numerical 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, IFZERO will evaluate the false list.

              Note  that, starting with Yodl version 2.00 the first argument is not evaluated any
              further. So, COUNTERVALUE(somecounter) will always be evaluated 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.

              NOTE:  Starting with Yodl version 3.00.0 Yodl’s default file inclusion behavior has
              changed. The current working directory no longer remains fixed at the directory  in
              which  Yodl  is  called,  but  is  volatile,  changing  to the directory in which a
              yodl-file is located. This has the advantage that Yodl’s  file  inclusion  behavior
              now  matches  the way C’s #include directive operates; it has the disadvantage that
              it may break some current documents. Conversion,  however  is  simple  and  can  be
              avoided altogether if Yodl’s -L (--legacy-include) option is used.

              Example:

                  INCLUDEFILE(latex)

              will try to include the file latex or latex.yo from the current include parth. When
              the file is not found, Yodl aborts.

       INCLUDELIT, INCLUDELITERAL
              INCLUDELIT and INCLUDELITERAL are obsolete.  NOEXPANDINCLUDE  [NOEXPANDINCLUDE]  or
              NOEXPANDPATHINCLUDE [NOEXPANDPATHINCLUDE] should be used instead.

       INCWSLEVEL
              INCWSLEVEL   requires  one  (empty)  parameter  list.   It  increases  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 will be 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 will effectively be 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 greated processing speed, at the expense of an additional
              file.  The  associated  yodlpost  postprocessing  program will read and process the
              index file, and will fixup 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 will alter
              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 will
              thereupon write 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.

       NEWCOUNTER
              NEWCOUNTER is obsolete. DEFINECOUNTER [DEFINECOUNTER] should be used instead.

       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 parameter list, the text in
              question. Whatever occurs in the argument is not subject to parsing or expansion by
              Yodl,  but  is  simply  copied to the output file (except for CHAR functions in the
              argument, which are expanded. If CHAR-expansion  is  not  required  either  NOTRANS
              [NOTRANS] can be used).

              Furthermore, the contents of the parameter list 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 sence 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 ARGx 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 parameter list.  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.

              NOTE:  Starting with Yodl version 3.00.0 Yodl’s default file inclusion behavior has
              changed. The current working directory no longer remains fixed at the directory  in
              which  Yodl  is  called,  but  is  volatile,  changing  to the directory in which a
              yodl-file is located. This has the advantage that Yodl’s  file  inclusion  behavior
              now  matches  the way C’s #include directive operates; it has the disadvantage that
              it may break some current documents. Conversion,  however  is  simple  and  can  be
              avoided altogether if Yodl’s -L (--legacy-include) option is used.

              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 will not be subject to 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.

              NOTE:  Starting with Yodl version 3.00.0 Yodl’s default file inclusion behavior has
              changed. The current working directory no longer remains fixed at the directory  in
              which  Yodl  is  called,  but  is  volatile,  changing  to the directory in which a
              yodl-file is located. This has the advantage that Yodl’s  file  inclusion  behavior
              now  matches  the way C’s #include directive operates; it has the disadvantage that
              it may break some current documents. Conversion,  however  is  simple  and  can  be
              avoided altogether if Yodl’s -L (--legacy-include) option is used.

              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 will not be subject to 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 will send

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

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

              The  parameter  list  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 ).

              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,  then warnings are generated when Yodl
              encounters a possible macro name, followed by a parameter list, without  finding  a
              macro  by  that  name.  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 parameter list.

              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 it is handled especially by Yodl,
              it is described 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 will call it whenever a new paragraph
              (defined as a series of at least two blank lines) was 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 will contain 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 will 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 will 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  sytem  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-convertor.

       PIPETHROUGH
              The builtin function PIPETHROUGH is, besides SYSTEM, the second function with which
              a Yodl document can affect its environment. Therefore, the danger  of  `live  data’
              exists  which is also described in the section about SYSTEM (see section [SYSTEM]).
              Nevertheless, PIPETHROUGH can be very  useful.  It  is  intended  to  use  external
              programs  to  accomplish  special features. The idea is that an external command is
              started, to which a block of text from within  a  Yodl  document  is  `piped’.  The
              output  of  that child program is piped back into the Yodl document; hence, a block
              of text is `piped through’ an external program.  Whatever is received again in  the
              Yodl run, is further processed.

              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  will be 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,  whereafter  the  stack  will  be
              empty,  but  the  macro  will  still  be  defined. In that case, using the macro 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)

       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, whereafter the stack will be empty, but the  symbol  will
              still be defined. In that case, using the symbol’s value 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, whereafter the stack will be empty, 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  its  new
              value  after  pushing. When the second argument is an empty parameter list, the new
              value will be zero. The new value may be specified as a numerical value, or as  the
              name  of  an existing counter. 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 will redefine 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)

       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  value
              after  pushing.  When the second argument is an empty parameter list, the new value
              will be zero. The new value may be specified as a numerical value, 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 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 parameter lists: the name of a counter, and a numeric value
              or the name of another counter.

              The corresponding counter (which must be previously created with NEWCOUNTER) is set
              to, respectively, the numeric value or the value of the other counter.

              See also section [COUNTERS].

       SETSYMBOL
              SETSYMBOL expects two parameter lists: the name of a symbol, and the text to assign
              to the named symbol.

       STARTDEF
              STARTDEF is obsolete. Instead, INCWSLEVEL [INCWSLEVEL] should be used.

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

                  SUBST(VERSION)(1.00)

              YODL will transorm all occurrences of VERSION in its input into 1.00.

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

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

              Each ’e in the input will then 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 parameter lists.

              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 processs its input files, YODL takes the following basic 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 will eventually appear in the
              output file generated by YODL.  YODL will perform 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 will replace
              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  will  then  be  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 will only see their definitions.

       SYMBOLVALUE
              SYMBOLVALUE expands to the value of  a  symbol.  Its  single  parameter  list  must
              contain  the name of a symbol.  The symbol must have been created earlier using the
              builtin 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.  The  presence of this function in the Yodl language
              introduces the danger  of  live  data.  Imagine  someone  sending  you  a  document
              containing

                  SYSTEM(rm *)

              To  avoid such malevolent side effects, YODL has a flag -l to define the `live data
              policy’. By default, -l0 is implied which suppresses the SYSTEM  function  and  the
              related PIPETHROUGH function. See also section [USING].

              Despite  the  potential  danger, 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 will not normally appear 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 parameter list. The text of the list is sent to the standard
              error stream, followed by a newline. This feature  can  be  handy  to  show,  e.g.,
              messages such as version numbers in macro package files.

              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)
                  )

       UNDEFINEMACRO
              UNDEFINEMACRO is deprecated. Use DELETEMACRO [DELETEMACRO] instead.

       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 parameter list: 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
              parameter list: 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 parameter list  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]).

       WRITEOUT
              WRITEOUT is deprecated, use FPUTS [FPUTS] instead.

FILES

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

SEE ALSO

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

BUGS

       --

AUTHOR

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