
TITLE INFORMATION: YODL Installation Guide (excerpt from the main YODL guide) 
AUTHOR INFORMATION: Karel Kubat (karel@icce.rug.nl) 
DATE INFORMATION: 1996 

Contents 

1: Obtaining and installing YODL 
1.1: Configuring the yodl program 
1.2: Installing the yodl program 

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. 

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.22.tar.gz,
which is a gzipped archive containing all sources,
documentation and macro files. The version string (1.22 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:

rm /usr/local/bin/dom /usr/local/bin/dom2*
rm /var/man/cat3/yodl.3.gz
rm -r /usr/local/lib/dom

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

rm /usr/local/bin/yodl2less

1.1: Configuring the yodl program

Once you unpack the archive, edit the 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.

1.2: Installing the yodl program

Once configured, type 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

cd doc
yodl2msless yodl > /tmp/yodl.txt

(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 gzipped 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?).

1.2.1: Prerequisites for the installation

To successfully build and install the YODL package, the following tools must be 
present. 

    o  First, you'll of course need a C compiler and run-time 
    environment. A POSIX-compliant compiler, libraries and set of header files 
    should work without problems. The gcc compiler 2.6 and above should 
    work without a flaw.

    o  Second, the Makefiles in the YODL source tree use typical building 
    programs, such as, install. Most Unixes will have these.

    o  Third, the installation and also scripts in the YODL package require a 
    POSIX-compliant shell interpreter /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.

    o  Fourth, a number of `standard' tools should be present: 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.

    o  Finally, you'll need a command that converts groff input into
    viewable format. The default setting for this command in the top level 
    Makefile is groff -Tascii -man and groff -Tascii -gms.

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.
