Provided by: yodl_3.00.0-6ubuntu1_i386 bug

NAME

       yodl - main Yodl converter

SYNOPSIS

       yodl [OPTION]... [FILE]...

DESCRIPTION

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

       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 the -L (--legacy-include)  option  is  used  (see
       below).

OPTIONS

       o      -D, --define=NAME[=VALUE]: Defines name as a symbol. This option
              is acts like DEFINESYMBOL(NAME)(). If =VALUE is added,  NAME  is
              initialized to VALUE (identically to DEFINESYMBOL(NAME)(VALUE)).

       o      -d,   --definemacro=NAME=EXPANSION:   Defines   NAME   as  macro
              expanding to EXPANSION

       o      -h, --help: usage information is written to the  standard  error
              stream, describing all of Yodl's options.

       o      -i,  --index[=file]:  `file'  is  the name of the index file. By
              default <outputbase>.idx is used.  No  default  when  output  is
              written  to  stdout.  The  index  file  is  processed  by Yodl's
              post-processor, yodlpost.

       o      -I,  --include=DIR:  This  defines   the   system-wide   include
              directory  where  YODL  searches  for  its  input  files. E.g. a
              statement to include a given file, like:
              INCLUDEFILE(latex)
              will cause Yodl to search for the  file  latex  in  the  current
              directory,  and  when  that  fails,  in  the system-wide include
              directory. The system-wide include directory  is  typically  the
              place  where  the  maintainer of a system stores macro-files for
              Yodl. This searching process applies to files that are  included
              inside  a  document but also applies to filenames on the command
              line when invoking the YODL program.

              The name of the included file (latex in the  above  example)  is
              the  bare name, the YODL program will supply a default extension
              (.yo), if necessary.

              The -I option overrules Yodl's built-in name for the system-wide
              include  directory.  The built-in name is defined when compiling
              Yodl, and is, e.g., /usr/share/yodl. Furthermore, the definition
              may  contain  $HOME,  which  will be replaced by the user's home
              directory if  the  `home'  or  `HOME'  environment  variable  is
              defined.  It  may  also  contain  $STD_INCLUDE,  which  will  be
              replaced by the compilation defined standard include  path.  The
              standard  includepath may be overruled by either (in that order)
              the command line switch -I or the YODL_INCLUDE_PATH  environment
              variable.  By  default,  the  current  directory is added to the
              standard include path. Hewver, when -I or  YODL_INCLUDE_PATH  is
              used,  the  current directory must be mentioned explicitly.  The
              individual directories need not be terminated by a  /-character.
              In  distributed .deb archives, the standard directory is defined
              as /usr/share/yodl (prefixed by the current working directory).

       o      -k, --keep-ws: Since YODL version 2.00 blanks at the  begin  and
              end  of  lines  are ignored, even without a trailing \, when the
              `white space level' is non-zero.  Earlier  versions  kept  these
              blanks.  The  legacy handling of white space at end of lines can
              by obtained using the -k flag. Note that white space are  always
              kept when using verbatim copying, and when the white-space level
              is zero.

       o      -l,  --live-data=HOW:  This  option  controls  the  policy   for
              executing  SYSTEM or PIPETHROUGH commands; HOW being none (0) by
              default. The HOW argument can have the following values:

       o      none or 0: (the default): No macros calling system programs  are
              allowed.

       o      confirm  or  1:  The macros can be executed, but only after user
              confirmation is obtained. The macros in question are shown while
              the  Yodl document is processed, and the user must either accept
              or reject the call.

       o      report or 2: The macros are executed,  but  what  is  called  is
              shown  during  the  Yodl  run  (if  the WARNING message level is
              active).

       o      ok or 3: The macros are executed, and not shown during the  run.
              Be  careful  when  using  --live-data ok. It should be used only
              when a document is clearly `unharmful'.

       o      -m, --messages=SET: Set  the  so-called  `message  level'  to  a
              combination of the SET acdeinw. The letters of this set have the
              following meanings:

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

       o      c: critical. When a critical error occurs, Yodl terminates.  The
              message  itself can be suppressed, but exiting can't. A critical
              condition is, e.g., the omission of an  open  parenthesis  at  a
              location where a 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      d: debug. Probably too much info, like getting information about
              each character that was read by Yodl.

       o      e: error. 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      i:  info.  Not as detailed as `debug', but still very much info,
              like information about media switches.

       o      n:  notice.  Information  about,  e.g.,  calls  to  the  builtin
              function calls.

       o      w:  warning.  Something  you should know about, but probably not
              affecting Yodl's  proper  functioning  Non-configurable  is  the
              handling  of  an  emergency  message.  These  messages  can't be
              suppressed, but shouldn't happen, as they point to some internal
              error.  It  would  be  appreciated  to receive information about
              these messages if they ever occur.

       o      -n, --max-nested-files=NR: This option causes Yodl to abort when
              the  number  of  nested  input  files exceeds NR, which is 20 by
              default.  Exceeding  this  number  usually  means   a   circular
              definition  somewhere  in the document. This is the case when, a
              file a.yo includes b.yo, while b.yo includes a.yo etc.. It  does
              not prevent recursive macro- or subst-replacements. For that the
              -r (--max-replacements) option is available.

       o      -o, --output=FILE: This option causes Yodl to write  its  output
              to  FILE.  By  default,  the  output goes to the standard output
              stream. E.g., you can use YODL to read a file input and to write
              to output with the following two commands:

                      yodl input > output
                      yodl -ooutput input

              The  difference  being  that in the latter case an index file is
              generated, but not in the former case. Notice  that  writing  an
              index file can be forced when the --index option is specified.

       o      -p,  --preload=CMD:  This  option `pre-loads' the string cmd. It
              acts as though cmd was the first command in the first input file
              that is processed by YODL.

              More  than  one  --preload=CMD  options  may  be  present on the
              command line.  Each of the commands is then processed  in  turn,
              before reading any file.

       o      -r, --max-replacements=NR: This option causes Yodl to abort when
              the number of macro calls or  subst-replacements  exceeds  NR  *
              10,000.   By  default, NR equals 1. Setting --max-replacements=0
              implies  that  no  macro-  or   subst-replacement   checks   are
              performed.

       o      -t,  --trace:  This  option enables tracing: while parsing, Yodl
              writes its output to the standard error stream. As is  the  case
              with  the  -k  option,  this  option  is  defined  for debugging
              purposes only.

       o      -V, --version. This option will show YODL's actual version.

       o      -v, --verbose: This option increases  Yodl's  `verbosity  level'
              and  may  occur  more  than  once.  By  default  yodl  will show
              alerting, critical, emergency and error messages. Each --verbose
              option will add a next message level. In order, warning, notice,
              info and debug messages will be added to this set.  It  is  also
              possible to suppress messages. The VERBOSITY builtin can be used
              for that.

       o      -W, --warranty. This option will show a warranty disclaimer  and
              a copyright notice.

       o      -w,  --warn:  The  presence  of  this option caused Yodl to warn
              when, e.g., symbols are redefined.

FILES

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

SEE ALSO

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

BUGS

       -

AUTHOR

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