The following information describes the YODL package from the point of the
system administrator. Issues such as the installation of the package are
addressed here.
4.1: Obtaining and installing YODL
The YODL program and the distributed macro package can be obtained at the ftp
site ftp.icce.rug.nl
in the directory
/pub/unix
. Look for the file
yodl-1.14.tar.gz
,
which is a gzipped archive containing all sources,
documentation and macro files. The version string (1.14 in this
example) may have been upgraded by the time you read this; so always get the
archive with the highest version number.
If you have an older yodl
source tree, remove it first. Then uncompress
and untar it in a `sources' directory, e.g., in /usr/local/src
. This
creates a subdirectory yodl-X.YY/
under which all necessary files are
located.
Please note: YODL has evolved from a previous program dom
, which is
no longer supported or maintained. If you have a version of the predecessor
program dom
, then issue the following commands:
Also note: Pre-1.03 versions of YOLD had a command yodl2less
, which is
now obsolete. This command has been replaced with yodl2manless
and
yodl2msless
. If you have a pre-1.03 installation, run the command
Makefile
in the yodl-X.YY/
subdirectory. At the top you will find a number of macros that may need
adaptation (e.g., BINDIR
is where make install
puts the program).
You can also set compiler options in this file.
Next, edit the file config.h
. A number of relevant macros for the inner
workings of yodl
can be defined here. If you're unsure about the macros,
leave them to their defaults.
make install
to build and install the program. The
executable, which is built as src/yodl
is created and copied to a
system-wide program directory. The macro package from lib/yodl
and divers
post-processors are also placed in a public directory, which is
/usr/local/lib/yodl
by default (you can change this directory name in
the Makefile
too). Furthermore, a number of shell scripts (drivers
of the yodl
program) are copied to your programs directory.
The make install
command only installs necessary executables and
macrofiles. Use make installman
to create and install manpages which go
under /usr/man/man*
, or use make installcat
to create and install
formatted manpages which go under /var/man/cat*
. Available manual pages
include descriptions of the executables, an abbreviated list of macros, and a
description of the manpage
document type. Optionally, you can install the
whole YODL manual under /usr/man/man5/yodl.5
with make installmanual
, or
you can install the manual in preformatted form under
/usr/man/cat5/yodl.5.gz
using make installcatual
. Note that all
make
commands that install documentation, also implicitely make
install
. This is not a bug! A working YODL set is required to create and
install the documentation.
If you want yodl
to create full documentation about itself, type make
latexdoc
(for LaTeX-style documentation) or make
htmldoc
(for
HTML-style documentation). The documentation is written to doc/yodl.tex
or
doc/yodl.html
respectively. You can also make flat ASCII documentation via
the ms
converter with
(Note that yodl.html
already comes with the distribution, just start your
favorite HTML browser on doc/yodl.html
. Similarly, ASCII docs are provided
in gzip
ped format as doc/yodl.txt.gz
.)
If you can neither process LaTeX nor HTML nor ms
documentation, try
make txtdoc
to produce a flat ASCII file yodl/yodl.txt
(but then, if
you can only view plain ASCII, why get YODL in the first place?).
4.1.2.1: Prerequisites for the installation
To successfully build and install the YODL package, the following tools must be
present.
If you have problems building YODL on your particular system, please mail me
the problem description (and, if you have it, the solution) -- I will adapt
YODL for a wider variety of Unix blands.
This is best illustrated with an example. Given the code,
is pushed back.
The most complex part of the program is therefore the tokenizer (lexical
analyzer): that part is responsible for matching tokens such as identifiers in
the input, and for pushing back text. The pushing back is implemented as a
relocatable buffer, which is expanded as text is pushed into it and which
shrinks as the lexical analyzer processes input. I already achieved about 100%
speed gain by optimizing the tokenizer, but this implementation can still be
somewhat of a CPU hog. (But hey, premature optimzation is the root of
all evil, says D.E. Knuth. So why optimize, as long as you don't know whether
you're being premature about it?)
The lexical analyzer is furthermore responsible for the line continuation
feature (see section 2.2.2) and for the The place to start looking is the file The macro expands to a set of commands that are active per output format,
using The file
gcc
compiler 2.6 and above should
work without a flaw.
Makefile
s in the YODL source tree use typical building
programs, such as, install
. Most Unixes will have these.
/bin/sh
. The GNU shell interpreter
bash
works without problems. You can define the path to your bash
shell in the top-level Makefile
. I've been told that ksh
works just
as well.
awk
,
sed
, grep
, etc.. These tools must furthermore include the code
generators bison
and flex
(yacc- and lex lookalikes) to
genererate the grammar parsers. The GNU implementations of these
tools work like a charm.
groff
input into
viewable format. The default setting for this command in the top level
Makefile
is groff -Tascii -man
and groff -Tascii -gms
.
4.2: Internal workings of the YODL package
This section describes the internal workings of the yodl
package, for
those who are interested (and of course, for the maintainer).
4.2.1: A single-pass interpreter
The yodl
program is a single-pass interpreter of its input files. The
program does not build an internal data representation of the text and
commands that it encounters; therefore, all actions must be completed in one
pass. The basic way by which yodl
does this, is by reading input, taking
actions and possibly `pushing back' information on the input.
yodl
will take the following actions:
DEFINESYMBOL
command updates an internal table of symbols, no
other action is necessary here.
IFDEF
command is parsed, yodl
eats up all of the
necessary parts from the input: the keyword itself, and three parameter
lists. The IFDEF
test obviously yields `true', and therefore yodl
`pushes back' the true-list
yodl
sees normal text (Symbol
sym
is
etc.). This
is sent to the output file.
DEFINEMACRO
statement is seen, which defines
testmac()
as a placeholder for one
thing
.
testmac()
is seen. The parser recognizes a user-defined
macro having no arguments, which conforms to the definition. The text
yodl
reads this last string from its input and sends it
to the output.
SUBST
mechanism (see
section 2.3.30). These mechanisms are also implemented with the push-back
method.
4.2.2: Macros of the converters
The macro files for all converters are (by default) installed to a directory
/usr/local/lib/yodl
. This is a good place to look if you want to
see how a converter works, or if you want to write a new converter.
shared.yo
, which is used by all
converters. This file defines most commands that are `global' in the sense
that all converters implement them: e.g., bf
, em
and so on. The
implementation is per macro as follows, illustrated for e.g., bf
(the
actual implementation may be slightly different):
latexcommand
, htmlcommand
etc..
shared.yo
is included in its turn by tex.yo
, html.yo
and
so on. These separate files are very short; their function is to:
latex
for
latex conversions, html
for HTML, and so on),
shared.dm
,