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), me(7) (only cawf supports
me(7)), and ms(7) macro sets.

One of cawf's virtues is that it will run on PC clones under MS-DOS or
OS/2.  It will also run on the Apple Macintosh as a Macintosh Programmer's
Workshop (MPW) tool.

Like awf, cawf is completely independent of any licensed Unix source
code.  In comparison to awf, cawf supports more nroff functions and one
more macro set, me(7).

This distribution contains: complete source; make files for Unix,
Macintosh, MS-DOS, and OS/2; documentation; and executables (MS-DOS
and Macintosh) for cawf and a companion output filter, bsfilt.

This is the version 4.10 distribution of cawf.  Changes since version
4.09 include:

	*  The ms macro MO string is now supported, including its
	   modification by the .DA macro.

	*  The general string register IF now contains the name of
	   the current input file.  It contains STDIN if the current
	   input source is the standard input file.

Version 4.08 changes include:

	*  Some rudimentary output device support has been added,
	   via a device configuration file.

	*  The code has been converted to use unsigned characters.

	*  An attempt has been made to make the code ANSI C compliant.

	*  The following bugs have been fixed:

		A bug in the locating of the device file has been
		corrected, so that the code performs as documented.

		Null macro arguments are ignored.

		Some unused arguments to local functions have been
		more carefully type cast to avoid portability
		problems.

	*  The .fl and .rn requests are now supported.

	*  Limited support has been added for the non-break request
	   control character, the acute accent (').

	*  Argument count conditionals -- operating on \n(.$ --
	   may now use the >= and <= operators in addition to [<=>].

	*  Macros may be terminated with "..", ".", "''" or "'".

	*  String interpolation is performed if it is specified at
	   the start of the defined value -- i.e., the string value
	   may be a request for interpolation of another string.

	*  In .ds string values "\\b" is converted to '\b' and
	   "\\\\"" is converted to '\\'.  No other sequence,
	   beginning with '\\', is modified.

	*  The .tr request has been enhanced to handle named
	   characters and string interpolation.

	*  The SS macro is now included in man.mac.

	*  The cawf version number is now displayed in the help
	   output.

	*  A limited -me macro set is included in me.mac.

	*  Some forms of the hyphen -- e.g., one of two `-' characters
	   at the start of a word or ME(7)'s \*- -- will now be
	   output in bold or italic face, if they're in effect.
	   See cawf(1) for a complete description of the rules of
	   hyphenation and the output of hyphen characters.

	   A bug was corrected in the handling of the \*(em hyphen.

	*  Three part titles -- the .tl and .lt commands -- are
	   now supported.

	*  4.02 handles TABs better.

	*  4.03 handles NULL characters in font and device definitions
	   properly.

	*  4.04 changes include:

	   o  The -n<starting_page_number> and -o<page_number_range>
	      options are supported.

	   o  The current date is preset in the ME td string or
	      the MS DY string.

	   o  The MS CH string is preset to "- % -" and the CH
	      string is preset to \*(DY.

	   o  Some minor bug fixes were made.

	      .  The binary search in the Nreq() function in nreq.c
		 is now constrained to the proper length.

	      .  Null strings -- e.g., defined with ".ds xx" --
		 are now handled correctly.

	*  4.05 changes include:

	   o  MS-DOS now uses the Borland C++ 3.1 compiler.
	      Accordingly:

	      .  The bsfilt.mak and cawf.mak make files for MS
		 Quick C have been replaced by makefile.bcc.

	      .  Some additional ANSI C purifications have been
		 performed.  (The _ANSI definition is now required
		 for Borland C++ 3.1.)

	   o  Two new initialization directives are supported:

	      .  .^b lf n 

		 This directive sets the page footer section line
		 count to n-1.

	      .  .^b lh n 

		 This directive sets the page header section line
		 count to n.

	       See cawf(1) for a more complete description of them.

	*  4.06 changes include:

	   o  Header and footer strings may now contain some in-text
	      codes, including:

	      .  Font specifications via \f;

	      .  Number register interpolations via \n;

	      .  String interpolations via \*;

	      .  Escaping of other characters with \.

	      See cawf(1) for a more complete description of the
	      header and footer controls.

	   o  Some Borland C++ 3.1 source code dependencies are
	      now controlled under the _BCC #define.

	   o  Hard spaces -- "\ " -- are handled better.

	*  4.07 changes include:

	   o  Support was added for OS/2, using the Microsoft or
	      EMX GNU C compilers.  The __EMX__ definition selects
	      some code conditionally defined for the EMX GNU C
	      compiler.

	      The OS/2 support was provided by Darrel Hankerson
	      <hankedr@mail.auburn.edu>.  Executables may be obtained
	      via anonymous ftp from ftp-os2.cdrom.com (192.153.46.2)
	      in pub/os2/all/unix/cawf4*.zip.  Please direct
	      questions about compiling and using cawf under OS/2
	      to Darrel.

	*  4.08 changes include:

	   o  Handling of .ce was changed to flush any pending
	      output before centering takes place.   Mike Soyka
	      <mgs@ssd.ray.com> pointed out the need for this.


	*  4.09 changes include:

	   o  Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch> has
	     ported cawf 4.09 to the Macintosh, where it runs under
	     the Macintosh Programmer's Workshop (MPW) tool.
	     Information on his port may be found in the 00readme
	     file and in the mac_cawf sub-directory of the
	     distribution.  Please direct questions about Macintosh
	     cawf to Matthias.


CONTENTS
--------

This Unix distribution of cawf includes:

	00readme	this file
	00diffs         description of differences between cawf
			and [nt]roff
	*.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.def      linker definition file for OS/2 16 bit
			versions
	bsfilt.exe	bsfilt executable for MS-DOS
	bsfilt32.def    linker definition file for OS/2 32 bit
			versions
	cawf.1		nroff source for the cawf manual page
	cawf.def        linker definition file for OS/2 16 bit
			versions
	cawf.exe	cawf executable for MS-DOS
	cawf32.def      linker definition file for OS/2 32 bit
			versions
	common		initialization file for CAWFLIB library
	device.cf       output device configuration file for CAWFLIB
			library
	dumb.dev	device description file for CAWFLIB library
	Makefile	Unix-style make file
	mac_cawf        a subdirectory of Macintosh-related files
			for cawf, including:
			  Makefile.mk	 MPW make file
			  bsfilt.bin	 bsfilt fat binary
			  cawf.bin	 cawf fat binary
			  cawf.r	 textual resources for cawf
			  cawf.rsrc.bin	 cursors for cawf
			  macish.c	 Toolbox initialization
	makefile.bcc	Borland C++ 3.1 command-line make file
	makefile.os2    makefile for Microsoft C and EMX GNU C
			(mostly for OS/2, but will produce DOS
			executables, too)
	man.mac		man(7) macros for CAWFLIB library
	me.mac		me(7) macros for CAWFLIB library
	ms.mac		ms(7) macros for CAWFLIB library
	strcasecmp.c    the strcasecmp() function from BSD4.3 (See
			the discussion under STRCASECMP for
			information on when you might need to use
			this.)


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 cawflib.h and rebuild cawf
from the sources.

CAWFLIB contains a minimum of six files:

	common          common raw nroff commands to get cawf
			started

	dumb.dev        a set of character definitions for a plain,
			"dumb" ASCII device - e. g., the console
			display, a CRT or a basic line printer

	device.cf	the output device configuration file
	man.mac		the man(7) macros
	me.mac		the me(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 with special character specifications,
you may want to generate new *.dev files for them.  Follow the
format of dumb.dev in making new character specifications.

To define characters 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 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 do is make
vt100.dev a symbolic link to dumb.dev.  Even that isn't even
necessary, because cawf will use dumb.dev if it can't find TERM.dev.

In addition to the character specifications possible through the
*.dev files, cawf provides one-time font selection and bold or
italic face support for output devices via its -d and -f options.
Cawf can be directed to issue specific device codes for bold and
italic characters, and one font can be specified for the entire
document.  Cawf has some built-in output device support, and
additional support is contained in the device configuration file,
device.cf.  Additional devices may be defined in device.cf.

It is not necessary to generate a new *.dev file for each output
device definition.  Only when you need special character definitions
do you need to create a *.dev file.  The dumb.dev file is adequate
for most devices you define in device.cf.


SOURCES
-------

A Unix make file and a make file for Borland's C++ 3.1 compiler
are included.  The Unix make file has some definitions that help
tune it to the local Unix environment:

	_ANSI           must be defined for Borland C++ 3.1 to
			effect proper function prototype declarations.

	_BCC            must be defined to use Borland C++ #pragma
			statements.

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

	__EMX__         must be defined when using the EMX GNU C
			compiler (usually under OS/2).  You must
			also use the special make file, makefile.os2.
			See the OS/2 INFORMATION section.

	macintosh	must be defined when build cawf under the
			Macintosh Programmer's Workshop (MPW) on
			the Apple Macintosh.  The UNIX and USG
			definitions are also required.

	MALLOCH         is a string that should be defined when a
			UNIX environment has a <malloc.h>, unless
			it also has a <stdlib.h> with prototypes
			for malloc() and its relatives.  In the
			latter case, you should define STDLIB, but
			you don't need to define MALLOCH.

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

			STDLIB must be defined for Borland C++

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

	__STR__         The definition of this string must be
			deleted when using the xlc 1.2 compiler on
			the RISC/System 6000 under AIX 3.2.  Put

				-U__STR__

			in the Makefile DEFS string.  This must be
			done because the xlc 1.2 compiler does not
			correctly inline string functions when
			compiling pass3.c.

	UNIX            switches the build environment to Unix.
			You may also have to decide about MALLOCH,
			STDLIB, __STR__ and USG when you define
			UNIX.

			Do not define UNIX for Borland C++ 3.1; do
			define _ANSI and STDLIB.

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

			You may also need to define USG to select
			the proper header file for string function
			prototypes.  If UNIX and USG are defined,
			"proto.h" selects <string.h>; if only UNIX,
			<strings.h>.  Cawf needs the more complete
			set of definitions, including strchr() and
			strrchr().  If <string.h> #includes
			<strings.h>, as is sometimes the case,
			define only UNIX.

I have built and tested cawf in the UNIX context under AIX 3.2 (see
the note above on __STR__), BSD4.3-Tahoe, Sequent DYNIX, ETAV (SYSV
3.0), NeXTStep 3.0, SunOS 4.1.1 and Ultrix 2.2.  If you build under
another Unix variant, you may have to adjust the source code, header
files and Makefile to fit.  Check the Makefile first for hints.


STRCASECMP
----------

Some platforms don't provide the strcasecmp() or strcmpi() functions
for case-insensitive string comparisons.  Strcasecmp() is used
several times in the Defdev() function of the device.c module.
Strcasecmp() is redefined in device.c to be stricmp() for the EMX
GNU C compiler for OS/2, and strcmpi() for other non-UNIX compilers,
including Borland C++ 3.1.

If you don't have either function in your run-time library, consider
using the strcasecmp() function in the enclosed strcasecmp.c file.
It is freely distributable, subject to the restrictions noted in
its comments.  You may have to modify the code slightly -- Chet
Creider reports that the Xenix C compiler in the 2.3.0 Development
System (based on Microsoft C 5.0) doesn't accept the "const" keyword,
while the 2.3.1 compiler (based on Microsoft C 5.1) does.  If you
have a 2.3.0 system, remove the "const" keywords from strcasecmp.c
before compiling it.


ANSI C COMPLIANCE
-----------------

Some effort has been devoted to making the cawf sources ANSI C
compliant.  The header file proto.h contains function prototypes
that enable ANSI C argument checking.  The state of definition of
the __STDC__ symbol is used to select options that depend on strict
adherence to the ANSI C standard -- e.g., the need for the isascii()
test before islower() or isupper().  If your ANSI compiler doesn't
define this variable when it's acting in strict ANSI C mode, you
may have to define it in the Makefile.

The Borland C++ 3.1 compiler must have the _ANSI symbol defined
for proper function prototype handling.


OS/2 INFORMATION
----------------

Cawf has been ported to OS/2.  The lastest round of porting was
done by Darrel Hankerson <hankedr@mail.auburn.edu>.  I do not
include OS/2 executables and cannot give OS/2 assistance, because
I do not have an OS/2 test platform.  Executables may be obtained
via anonymous ftp from ftp-os2.cdrom.com (192.153.46.2) in
pub/os2/all/unix/cawf4*.zip.  Please direct questions about compiling
and using cawf under OS/2 to Darrel.

Here's a note from Darrel:

    The "emxbnd" target will produce an executable which runs under
    both OS/2 2.x and DOS (32-bit), but requires run-time support
    from the emx distribution (available from ftp-os2.cdrom.com).
    It is possible to include the runtime support in the executable,
    in order to simplify the installation (at the price of larger
    executables).  The 16-bit "mscbnd" exe will run under all
    versions of OS/2 and DOS.


MS-DOS AND OS/2 SHELL 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, or
obtain a shell that does.  As a rudimentary aid to the modification
process, 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.

There are several freely distributed shells that will separate
standard error and standard output streams.  Look for versions of
ksh, bash and Stewartson's sh for OS/2 1.x, OS/2 2.x, and MS-DOS
on ftp-os2.cdrom.com (192.153.46.2).


MACINTOSH CONSIDERATIONS
------------------------

Cawf was ported to the Macintosh by Matthias Ulrich Neeracher
<neeri@iis.ee.ethz.ch>.  If you have specific questions about the
port, please direct them to Matthias.

The Macintosh version of cawf was created to run under MPW, the
Macintosh Programmer's Workshop.  The tools are fat binaries, and
thus on a PowerMac, at least version 3.4 beta is required.

To compile cawf on a Mac, you need the Metrowerks CodeWarrior 7
MPW compilers, CWGUSI, and dmake. CWGUSI and dmake are available
from:

	ftp://ftp.switch.ch/software/mac/src/mw_c/CWGUSI_164.sit.bin
	ftp://ftp.switch.ch/software/mac/src/mpw_c/dmake-401.sit.bin


MACINTOSH INSTALLATION
----------------------

To install cawf:

	*  Depending on how you unpack the distribution, some of
	   the files might still be in MacBinary format.  Convert
	   them with StuffIt Expander or some other tool.

	*  Place the files cawf and bsfilt in the Tools folder in
	   your MPW folder.  You may find these files in the mac_cawf
	   subdirectory of your distribution with a .bin suffix on
	   them.  Remove the suffix when you place them in the
	   Tools folder of your MPW folder.

	*  Create a folder named cawf in the Interfaces folder of
	   your MPW Folder and copy the following files into it:

	   o  common
	   o  dumb.dev
	   o  device.cf
	   o  man.mac
	   o  me.mac
	   o  ms.mac


SPECIAL CONSIDERATIONS FOR MACINTOSH SOURCES
--------------------------------------------

Macintosh specific passages are bracketed with the pre-processor
directives:

	#if	defined(macintosh)
	#else	/* !defined(macintosh) */
	#endif	/* defined(macintosh) */

Makefile.mk in the mac_cawf subdirectory of the distribution defines
the macintosh symbol.  It also defines the UNIX and USG symbols.

Don't forget to move cawf.r, Makefile.mk, and macish.c from the
mac_cawf subdirectory to its parent directory (where the rest of
the cawf sources reside) before building cawf.


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, Bob Hardy and Ted Campbell for their
	contributions to font filtering;

	Darrel Hankerson for the OS/2 port.  (Kai Uwe Rommel
	<rommel@ars.muc.de> did the original port of cawf to OS/2.)

	Matthias Ulrich Neeracher for the Macintosh port.

	Henry Spencer for awf and his regular expression package;

	Andy Tanenbaum for his help in ANSI C compliance, including
	his ansi.h header file from Minix;

	Ed Tankus for suggesting useful feature additions;

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@purdue.edu>
February 22, 1997
