8000 minix/commands/cawf at v3.2.0 · devinblood/minix · GitHub
[go: up one dir, main page]

Skip to content
  • Latest commit

     

    History

    History

    cawf

    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) 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 distribution contains complete source, make files for Unix and
    MS-DOS, documentation (raw and formatted) and MS-DOS executables for cawf
    and a companion output filters, bsfilt.
    
    This is the fourth distribution of cawf.  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 .ds request argument.
    
    	*  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.
    
    Changes to cawf to run under Minix:
    
    	*  The DOS binaries and make files have been removed.
     
    	*  Tabs stops changed from per 5 to per 8.
    
    	*  Bold and underline as it should be in device.cf.
    
    	*  Added .SB and .TA to man.mac.
    
    	*  Numerous prototypes added.
    
    
    CONTENTS
    --------
    
    This Minix distribution of cawf includes:
    
    	README		    this file
    	*.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
    	cawf.1		    nroff source for the cawf manual page
    	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
    	man.mac		    man(7) macros for CAWFLIB library
    	me.mac		    me(7) macros for CAWFLIB library
    	ms.mac		    ms(7) macros for CAWFLIB library
    	diffs		    Minix patches
    #ifdef PUTTING_IT_ON_THE_NET
    	cawf
    	bsfilt		    binaries compiled under Minix-PC 1.5 using the ACK
    			    ANSI C compiler using software floating point
    #endif
    
    
    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 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 addition 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
    -------
    
    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.
    
    	MALLOCH		is a string that should be defined when a UNIX
    			environment has a <malloc.h>, unless it also has a
    			<stdlib.h> with protoypes 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 MS-DOS Quick 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 MS-DOS Quick-C; do define
    			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.
    
    
    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.
    
    
    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, Bob Hardy and Ted Campbell for their contributions
    	to font filtering;
    
    	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.
    
    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@cc.purdue.edu>
    24 November 1992
    
    
    MINIX SPECIFIC TINKERING
    ------------------------
    
    Kees J. Bot <kjb@cs.vu.nl>
    26 November 1992
    
    0