Cawf - nroff-like text formatter

Cawf is a C version of awf, Henry Spencer's Amazingly Workable (text)
Formatter.  (Awf is written in awk and appears in comp.sources.unix,
Volume 23, Issue 27.)  Cawf and awf provide a usable subset of raw nroff
capabilities and the styles of the man(7) and ms(7) macro sets.  One of
cawf's virtues is that it will run on PC clones under MS-DOS.  It is
also, like awf, totally independent of any licensed Unix source code.


CONTENTS
--------

This distribution of cawf includes:

	*.c and *.h	source files to build cawf and bsfilt (bsfilt
			removes Backspaces from cawf output)
	bsfilt.1	nroff source for the bsfilt manual page
	bsfilt.exe	bsfilt executable for MS-DOS
	bsfilt.man	the formatted (with cawf) and filtered (with bsfilt)
			bsfilt manual page
	cawf.1		nroff source for the cawf manual page
	cawf.exe	cawf executable for MS-DOS
	cawf.mak	MS-DOS, Quick-C make file
	cawf.man	the formatted (with cawf) and filtered (with bsfilt)
			cawf manual page
	common		initialization file for CAWFLIB library
	dumb.dev	device description file for CAWFLIB library
	makefile	Unix-style make file
	man.mac		man(7) macros for CAWFLIB library
	ms.mac		ms(7) macros for CAWFLIB library


LIBRARY
-------

To use cawf, you must select a location for the CAWFLIB library files.  The
distributed cawf.exe expects to find them in c:\sys\lib\cawf, but you can
alter that with the CAWFLIB environment variable, or you can change the
CAWFLIB #define in cawf.h and rebuild cawf from the sources.

CAWFLIB contains a minimum of four files:

	common		common raw nroff commands to get cawf started
	dumb.dev	a basic set of definitions for a plain, "dumb"
			output device - e. g., the console display or
			a generic line printer
	man.mac		the man(7) macros
	ms.mac		the ms(7) macros

You may want to add your own macro files to the library.  Just name them
"m[your-name].mac", following the usual nroff naming convention for macro
files.

If you have fancy output devices, you may want to generate new *.dev files
for them.  Follow the format of dumb.dev.  To define support for a new
device, select a name prefix for it and create a file in CAWFLIB with the
name "<prefix>.dev".  To use the new device file, set the TERM environment
variable to <prefix> - e. g., when I test cawf on Unix, I need a vt100.dev,
because my TERM environment variable value is usually vt100.  (All I need
do is make vt100.dev a symbolic link to dumb.dev.)


SOURCES
-------

A generic Unix make file and a cawf.mak file for Microsoft MS-DOS Quick-C
are included.  The Unix make file has two definitions that help tune it
to the local Unix environment:

	UNIX		switches the build environment to Unix

	STDLIB		indicates that standard library function prototype
			definitions may be found in <stddef.h>

			If STDLIB is not defined, the cawf sources try to
			define their own library function return values.

Cawf has been successfully built and tested in the UNIX context under 4.3BSD
Tahoe, Ultrix 2.2, SunOS 4.0, Dynix 3.0.12, ETAV (a SYSV 3.2 derivative) and
NeXTOS 1.0.  If you try to build under a BSD derivative Unix that doesn't
have the SYSV string functions, strchr() and strrchr(), simply redefine them
to the index() and rindex() functions.


MS-DOS CONSIDERATIONS
---------------------

The MS-DOS version of cawf was created to run under the KornShell of the
Mortis Kern Systems Toolkit.  One ramification of using MKS' ksh is that it
supports the separate standard error and standard output streams.  Hence,
cawf blithely distributes its error messages to the standard error file, and
assumes the user's shell is capable of separating them from standard output.

If you don't use the MKS KornShell, but do want to separate the output
streams, you'll have to modify the cawf source code.  As a rudimentary aid,
cawf uses a separate stream pointer, Efs, for writing error output, but sets
it to stderr.  You can change that process to open a separate error file and
set Efs to point to it.


COPYRIGHTS AND CREDITS
----------------------

The sources are copyrighted, but freely distributable under usual terms -
retention of credit, etc.

Please acknowledge the credits to Henry Spencer for awf and his regular
expression package.

Henry says about awf, "I can't believe I really wrote this."  Those are
my sentiments exactly about cawf, but I also understand that necessity
sometimes forces us to do what we would prefer to avoid.


BUGS AND ENHANCEMENTS
---------------------

I'll be glad to hear about bugs and needs for enhancements, but make no
promises about delivering fixes or upgrades in response.

Vic Abell <abe@mace.cc.purdue.edu>
20 February 1991
