Category : Word Processors
Archive   : CAWF.ZIP
Filename : 00README

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.

This is the second distribution of cawf. Changes include:

o Support has been added for a few more nroff commands -- .di, .tr,
and \k.

o Known bugs have been corrected, including bugs in the man.mac
and ms.mac files:

Error in skipping to predicate of argument string comparison
.if;

Improved .ti handling, including the undocumented, oft-used
absolute form;

Error in output of .NH numbers;

Handle expressions that aren't separated from the command by
white space -- e. g., ".ti0";

Compensate for printers that can't print a blank line,
followed by a FF without printing a blank page.

o A limited printer formatting capability has been added via a small
change to cawf (the -fe option) and the addition of a post-filter,
fontfilt(1).

o Documentation has been added to describe the additions.


CONTENTS
--------

This distribution of cawf includes:

*.c and *.h source files to build cawf, bsfilt (bsfilt
removes Backspaces from cawf output) and
fontfilt (fontfilt provides more elaborate
font and type style filtering)
bsfilt.1 nroff source for the bsfilt manual page
bsfilt.exe bsfilt executable for MS-DOS
bsfilt.man the formatted (with cawf -fn) 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 for cawf
cawf.man the formatted (with cawf -fn) cawf manual page
common initialization file for CAWFLIB library
dumb.dev device description file for CAWFLIB library
fontfilt.1 nroff source for the fontfilt manual page
fontfilt.cf device and font configuration file for fontfilt(1)
fontfilt.exe fontfilt executable for MS-DOS
fontfilt.mak MS-DOS Quick-C make file for fontfilt
fontfilt.man the formatted (with cawf -fn) fontfilt manual page
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 five 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
fontfilt.cf the device and font configuration file for
fontfilt(1)
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 ".dev". To use the new device file, set the TERM environment
variable to - 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.)

Through its -fe option and the fontfilt(1) post-filter cawf provides
limited support for printer devices. Cawf and fontfilt can be directed
to issue specific printer codes for bold and italic characters, and one
font can be selected for the entire document. A device and font
configuration file is used for these selections, and the file can be
easily changed for individual printers.


SOURCES
-------

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

CAWFLIB is a string that can be used in lieu of changes
to cawf.h's CWFLIB #define.

UNIX switches the build environment to Unix.

USG adjusts for System V. (UNIX must also be defined.)

STDLIB indicates that standard library function prototype
definitions may be found in .

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
NeXTStep 1.0a/2.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:

AT&T for their public-domain release of getopt(3) at the 1985
UNIFORUM conference

Chet Creider and Ted Campbell for their contributions to font
filtering

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
4 June 1991