Ubuntu Manpage: yodl - main Yodl converter

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..

BUGS

AUTHOR

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