This directory contains complete code and user documentation for the preproff
program, which transforms nroff/troff files in preparation for running off.
The program was developed at Hitachi Computer Products (America), Inc., in its
Open Systems Division, which is responsible for porting and adapting OSF
offerings.  Hitachi Computer Products has given the program to OSF so it can
use and distribute it as part of its documentation build tools.  In addition,
OSF licensees can adapt the program to the needs of their sites, and this file
offers guidelines for doing so.  The program is offered as is, with no
warranty attached, and so forth and so on.

The files in this directory are:

	howto		User documentation

	Maintenance	Guidelines for adapting to new sites, plus currently
			known problems with the program

	*test		Unit tests for various features

	test_output	Canned output, to which you can compare your test output.

	makefile	build and installation procedures for source code

	Source code:

	define_stack.c	Support routines called by the lexical
			analyzer in filter.l and by main() in filter_driver.c.

	filter.h	C preprocessor directives, structure definitions, and
			enum specifiers.  This file is included by all .c
			files.  In turn, it includes site_specific.h.

	filter.l	The main engine of the program: an enormous lex file
			that parses input, deciding what to pass through and
			what to change.

	filter_driver.c	The main() module, which parses the user's input line
			(a complicated job in itself) and passes each input
			file for processing.

	global_var.c	To make tracing through the functions of the program
			easier, all global variables are stored in this file,
			except for the main table of user options.  Each site
			will probably change the user options, so these are
			isolated in site_specific.c.

	site_specific.c	The table of user options, controlling the activities
			both of main() and of the lexical analyzer in
			filter.l.  Most sites will probably want to change
			this table, following the instructions in the
			maintenance file.

	site_specific.h Definitions that other sites will need to change have
			been isolated in this file, which is included by
			filter.h.

The tests can basically be run in any order (sotest can run by itself, but
it's there mainly to be invoked within sotopleveltest).  Here's a quick Bourne
shell script that does a lot of verification:

	preproff -stan -rmb -rmp -DYES -DYES_TOO \
		ifexpressiontest ifnesttest multitest sotopleveltest \
		> /tmp/output$$
	if
		diff /tmp/output$$ test_output
	then
		echo "Basic features of program still working as before.
	else
		echo "Better check program -- the output has changed."
	fi

Of course, the tests are rudimentary.  For instance, they do not include any
incorrect input, so they do not test the ability of the program to recognize
error messages and issue useful messages.  However, extensive testing has also
been performed at Hitachi, through both informal checking and daily use on OSF
documentation.

Report bugs or suggestions to:

		Hitachi Computer Products, Inc.
		Open Systems Software Development
		Technical Publications Group
		Reservoir Place
		1601 Trapelo Road
		Waltham, Mass.	02154

		e-mail:
		   uunet!hicomb!nancy
                   hicomb!nancy@uunet.uu.net
