yodl - main Yodl converter
yodl [OPTION]... [FILE]...
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.
- 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.
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..
Frank B. Brokken (f.b.brokken@rug.nl),