The tt(yodl) program is reads one or more input files, interprets the commands
therein, and writes one output file. The program is started as:

center(
    tt(yodl) em(flags) em(inputfile) em([inputfile...])
)

In this specification, the flags are optional and may be:

startit()
    
    it() tt(-D) em(name): Defines em(name) as a symbol. This flag is similar
    to the tt(DEFINESYMBOL) statement which may appear in the text. The
    purpose of defining symbols is described later.
    
    it() tt(-I) em(directory): This defines the system-wide include directory
    where tt(yodl) searches for its input files when they cannot be located by
    their bare name. E.g. a statement to include a given file:
    
    verb(INCLUDEFILE(latex))
    
    will search for the file tt(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 tt(yodl) program.
    
    The name of the included file (tt(latex) in the above example) is the bare
    name, the tt(yodl) program will supply a default extension if necessary. 
    
    The tt(-I) flag overrules Yodl's built-in name for the system-wide include
    directory. The built-in name is defined when compiling Yodl, and is usually
    tt(/usr/local/lib/yodl). 

    it() tt(-l) em(number): This flag controls the em(live data) policy;
    em(number) is default 0. This means that macros that can access your
    operating system (these are the macros tt(SYSTEM) and tt(PIPETHROUGH)) are
    disabled. The em(number) valuse can be:

    itemize(

        it() 0: (the default): No potentially harmful macros are allowed.

        it() 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.

        it() 2: The macros are executed, but also shown during the Yodl run.

        it() 3: The macros are executed, and not shown during the run. Use
        tt(-l3) only when a document has proven `unharmful'.

    )

    These macros are further discussed in the sections ref(system) (the
    tt(SYSTEM) macro) and ref(pipethrough) (the PIPETHROUGH macro).

    it() tt(-o) em(file): This option causes Yodl to write its output to em(
    file). By default, the output goes to the standard output stream. E.g.,
    you can use the tt(yodl) program to read a file tt(input) and to write to
    tt(output) with the following two commands:
    
verb(\
yodl input > output
yodl -ooutput input)

    it() tt(-P) em(cmd): This flag `pre-loads' the string tt(cmd) to the 
    tt(yodl) processor. It is as if the tt(cmd) were before any actual input.
    
    More than one tt(-P) em(cmd) flags may be present on the command line. 
    Each of the commands is sent to the processor before any input is read. 
    
    it() tt(-p) em(maxpass): This flag causes Yodl to abort when the number of
    parsing cycles exceeds em(maxpass), which is usually 20. Exceeding this
    number usually means a circular definition somewhere in the document. This
    is the case when, e.g., a macro tt(a) expands to tt(b), and tt(b) expands
    again to tt(a). Alternatively, the em(maxpass) cycle can be exceeded when 
    a file tt(a.yo) includes tt(b.yo), while tt(b.yo) includes tt(a.yo) etc..
    
    it() tt(-t): This flag enables tracing: while parsing, Yodl writes its
    output to the standard error stream. As is the case with the tt(-k) flag,
    this option is for debugging purposes.
    
    it() tt(-v): This flag increases Yodl's `verbosity level' and may occur
    more than once. The presence of one tt(-v) causes Yodl to show which files
    are parsed; four tt(-v)'s show the inner workings of Yodl's lexical
    analyzer. 
    
    it() tt(-w): The presence of this flag caused Yodl to warn when, e.g., 
    symbols are redefined.

endit()

The em(inputfile) elements on the command line specify which files Yodl should
process. All names are supplied with an extension+footnote(this extension is
defined in the installation of Yodl and is usually tt(.yo)). The files are then
searched for `as-is', or in the system-wide include directory.

Note that all filenames on the command line are input files. To define an
output file, either use the tt(-o) flag or redirect the output. 

