Provided by: yodl_3.06.00-1_amd64 
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),