Installation guide for troffcvt distribution

--------------------------------------------------------------------------

1) Consider whether or not you really want to try to build the troffcvt
distribution.  The process is non-trivial unless you already have all
the other prerequisite pieces.  If you want to find out whether or not
troffcvt produces output that is good enough for your purposes, you can
use the troffcvt-server mail server to convert some sample documents by
mail.  Check the following location for instructions:

	http://www.primate.wisc.edu/software/troffcvt/

Should you decide to go ahead, the troffcvt distribution is available
from the same location as a gzip'ed tar file.  Unzip and extract the
distribution:

	% gunzip < troffcvt-X.YY.tar.gz | tar xf -

where X.YY is the current release number.

2) You'll need some prerequisite software to build the distribution.
See one of the Prereq.{html,ps,txt} files for information about the
prerequisites upon which the troffcvt distribution depends.

3) Familiarize yourself with the distribution layout.  The primary
directories are:

	config		Project-specific imake configuration files
	doc		General documentation
	h		Header files
	lib		General library files
	libmac		Macintosh-specific library files (unusable)
	libunix		UNIX-specific library files
	man		manual pages
	misc		Odds and ends
	post		Postprocessor source
	tblcvt		tblcvt source
	troffcvt	troffcvt source

4) Build the troffcvt distribution.

First take a look in the config directory and see if there's anything
in the configuration files that you want to modify.  Then in the
distribution top-level directory, build the software with this command:

	% make World

If that doesn't work, try these commands:

	% imboot -C WRPRC2
	% make Makefiles
	% make clean
	% make depend
	% make all

When the build process is done, you should have these programs:

	troffcvt
	tblcvt
	tc2html
	tc2html-toc
	tc2rtf
	tc2text
	tc2null
	troff2html
	troff2rtf
	unroff
	troff2null

5) Test troffcvt:

	% cd troffcvt/tests
	% runtest

This should run a bunch of test files through troffcvt and compare
the output with the expected output, printing "OK" or "*** NOT OK
***" for each.  You want to see "OK" for each.  If a test doesn't
produce that result, try:

	% runtest -d testname

which will run the test and show you a "diff" output for the expected
and actual result.  If the difference is simply that the pathname of
a macro or action file being processed is different on my machine and
yours, the test result is okay.  Otherwise there may be a real problem.

6) In the post (postprocessor) directory, you may want to modify
tcr-fonts, html-fonts, and rtf-fonts to reflect typefaces locally
available at your site.  You may want to modify html-specials,
text-specials, and rtf-spec-* to reflect special characters available
in versions of troff at your site.  You can edit these files to modify
the output that you get from the postprocessors for particular fonts
and special characters, without making any changes to the postprocessors
themselves.

7) Install the distribution:

	% make install

--------------------------------------------------------------------------

Questions and comments to: dubois@primate.wisc.edu

If you find bugs, please report them.
