Provided by: yodl_2.15.1-1_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.

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