Provided by: yodl_4.02.00-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.

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)
              Yodl  now  searches  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, YODL
              supplies 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 is replaced
              by  the  user’s  home  directory  if  the  `home’ or `HOME’ environment variable is
              defined. It may also contain $STD_INCLUDE, which is  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      `-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 parenthesized argument should appear,
              or a non-existing file in an `INCLUDEFILE’ specification (as this  file  should  be
              parsed).  A  non-existing  file  with  a `NOEXPANDINCLUDE’ specification is a plain
              (non-critical) error.

       o      `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).  Once  an error has been
              encountered the remainder of the input is still parsed (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 shows YODL’s actual version.

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

       o      `-W, --warranty’. This option shows 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

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

BUGS

       -

AUTHOR

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