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