From: kjb@cs.vu.nl (Kees J. Bot)
Newsgroups: comp.os.minix
Subject: [Source] Cawf, an nroff clone (part 0/4)
Date: 5 Nov 92 13:42:49 GMT
Organization: Fac. Wiskunde & Informatica, VU, Amsterdam

You may have noticed that the current Minix nroff can't format it's way
out of a wet paper bag.  (Especially paper bags made out of the manual
pages that I like to write.)

I managed to find 'cawf' an nroff-like text formatter.  It is small
enough to be compilable under PC-Minix, and it is able to format all the
manual pages that I cared to try.  (30 or so, from free software
packages and X11 programs (e.g. xterm.1))

One problem with the source is that it uses floating point, so I added
binaries compiled under PC-Minix 1.5 with software floating point.  If
you can do the same for the ST or the 386 then please post the binaries.
[We should not make a habit out of this.]

Unpacking.
Cat the four parts together into one file and edit out the headers, then
uudecode, uncompress and untar in a fresh directory.

Fill /usr/local/lib/cawf with the files mentioned in the README and put
the binaries wherever you want them to be.  Linking 'cawf' to 'nroff'
might be the next step after you've seen it work.

[I wanted to make unpacking simpler by putting the files in four
different tar files.  After moving files around for 20 minutes I decided
to make a program to do that, but that never came to be.  It being a
shame to have good software lying around I decided to post it as is.
Anyone into writing the program I mentioned?  Don't make it perfect,
that's NP-complete.  Arguments: The size of one part and the filenames.
One line of space separated filenames for each part as output.  It must
know subdirectories and treat them as one unit however.]
--
	                        Kees J. Bot  (kjb@cs.vu.nl)
	              Systems Programmer, Vrije Universiteit Amsterdam
_._. .._ _   ._ ._.. ___ _. __.   _ .... .   _.. ___ _ _ . _..   ._.. .. _. .

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.


Changes to cawf to run under Minix:

	o  A 1000+ line function in pass2.c has been split in two.  The
	   ACK ANSI C compiler for the PC didn't quite like it.

	o  Setting a flag -DDUMB in the Makefile makes the code in cawf.c
	   always use the "dumb" terminal description file.  This way cawf
	   will only put backspaces in its output for overstrike and
	   underlining.  This is the Right Thing for manual pages, they may
	   not be terminal dependent.  More(1) knows how to display it nicely.

	o  Several unneeded files have been removed, many archives carry
	   the original package.

	o  A few macros have been added to man.mac.  Cawf can now format
	   any man page I (kjb) cared to try.


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
	cawf.1		Nroff source for the 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)
	makefile	Unix-style make file
	man.mac		man(7) macros for CAWFLIB library
	ms.mac		ms(7) macros for CAWFLIB library
	cawf
	bsfilt
	font		Binaries compiled under Minix-PC 1.5 using the ACK
			ANSI C compiler using software floating point


LIBRARY
-------

To use cawf, you must select a location for the CAWFLIB library files.  The
distributed cawf binary expects to find them in /usr/local/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 "<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.)  Note that you will have
to remove the -DDUMB flag from the Makefile to use different .dev files.

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
-------

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 <stddef.h>.

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

	DUMB		Convenience hack to only use the dumb terminal
			definition.

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.


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 <abe@mace.cc.purdue.edu>
4 June 1991


MINIX SPECIFIC TINKERING
------------------------

Kees J. Bot <kjb@cs.vu.nl>
25 June 1992
Newsgroups: comp.os.minix,comp.sys.ibm.pc