Provided by: yodl_3.03.0-2_amd64 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 tmp/wip/macros. 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),