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