commands/cawf/README

   1 Cawf - nroff-like text formatter
   2
   3 Cawf is a C version of awf, Henry Spencer's Amazingly Workable (text)
   4 Formatter.  (Awf is written in awk and appears in comp.sources.unix,
   5 Volume 23, Issue 27.)  Cawf and awf provide a usable subset of raw nroff
   6 capabilities and the styles of the man(7), me(7) and ms(7) macro sets.
   7 One of cawf's virtues is that it will run on PC clones under MS-DOS.  It
   8 is also, like awf, totally independent of any licensed Unix source code.
   9
  10 This distribution contains complete source, make files for Unix and
  11 MS-DOS, documentation (raw and formatted) and MS-DOS executables for cawf
  12 and a companion output filters, bsfilt.
  13
  14 This is the fourth distribution of cawf.  Changes include:
  15
  16         *  Some rudimentary output device support has been added, via a device
  17            configuration file.
  18
  19         *  The code has been converted to use unsigned characters.
  20
  21         *  An attempt has been made to make the code ANSI C compliant.
  22
  23         *  The following bugs have been fixed:
  24
  25                 A bug in the locating of the device file has been corrected,
  26                 so that the code performs as documented.
  27
  28                 Null macro arguments are ignored.
  29
  30                 Some unused arguments to local functions have been more
  31                 carefully type cast to avoid portability problems.
  32
  33         *  The .fl and .rn requests are now supported.
  34
  35         *  Limited support has been added for the non-break request control
  36            character, the acute accent (').
  37
  38         *  Argument count conditionals -- operating on \n(.$ -- may now use
  39            the >= and <= operators in addition to [<=>].
  40
  41         *  Macros may be terminated with "..", ".", "''" or "'".
  42
  43         *  String interpolation is performed if it is specified at the start
  44            of the .ds request argument.
  45
  46         *  The .tr request has been enhanced to handle named characters and
  47            string interpolation.
  48
  49         *  The SS macro is now included in man.mac.
  50
  51         *  The cawf version number is now displayed in the help output.
  52
  53         *  A limited -me macro set is included in me.mac.
  54
  55 Changes to cawf to run under Minix:
  56
  57         *  The DOS binaries and make files have been removed.
  58
  59         *  Tabs stops changed from per 5 to per 8.
  60
  61         *  Bold and underline as it should be in device.cf.
  62
  63         *  Added .SB and .TA to man.mac.
  64
  65         *  Numerous prototypes added.
  66
  67
  68 CONTENTS
  69 --------
  70
  71 This Minix distribution of cawf includes:
  72
  73         README              this file
  74         *.c and *.h         source files to build cawf and bsfilt (bsfilt
  75                             removes Backspaces from cawf output)
  76         bsfilt.1            nroff source for the bsfilt manual page
  77         cawf.1              nroff source for the cawf manual page
  78         common              initialization file for CAWFLIB library
  79         device.cf           output device configuration file for CAWFLIB
  80                             library
  81         dumb.dev            device description file for CAWFLIB library
  82         Makefile            Unix-style make file
  83         man.mac             man(7) macros for CAWFLIB library
  84         me.mac              me(7) macros for CAWFLIB library
  85         ms.mac              ms(7) macros for CAWFLIB library
  86         diffs               Minix patches
  87 #ifdef PUTTING_IT_ON_THE_NET
  88         cawf
  89         bsfilt              binaries compiled under Minix-PC 1.5 using the ACK
  90                             ANSI C compiler using software floating point
  91 #endif
  92
  93
  94 LIBRARY
  95 -------
  96
  97 To use cawf, you must select a location for the CAWFLIB library files.  The
  98 distributed cawf binary expects to find them in /usr/local/lib/cawf but you
  99 can alter that with the CAWFLIB environment variable, or you can change the
 100 CAWFLIB #define in cawf.h and rebuild cawf from the sources.
 101
 102 CAWFLIB contains a minimum of six files:
 103
 104         common          common raw nroff commands to get cawf started
 105         dumb.dev        a set of character definitions for a plain, "dumb"
 106                         ASCII device - e. g., the console display, a CRT or
 107                         a basic line printer
 108         device.cf       the output device configuration file
 109         man.mac         the man(7) macros
 110         me.mac          the me(7) macros
 111         ms.mac          the ms(7) macros
 112
 113 You may want to add your own macro files to the library.  Just name them
 114 "m[your-name].mac", following the usual nroff naming convention for macro
 115 files.
 116
 117 If you have fancy output devices with special character specifications, you
 118 may want to generate new *.dev files for them.  Follow the format of dumb.dev
 119 in making new character specifications.  To define characters for a new
 120 device, select a name prefix for it and create a file in CAWFLIB with the
 121 name "<prefix>.dev".  To use the new file, set the TERM environment variable
 122 to <prefix> - e. g., when I test cawf on Unix, I need a vt100.dev, because
 123 my TERM environment variable value is usually vt100.  All I do is make
 124 vt100.dev a symbolic link to dumb.dev.  Even that isn't even necessary,
 125 because cawf will use dumb.dev if it can't find TERM.dev.
 126
 127 In addition to the character specifications possible through the *.dev files,
 128 cawf provides one-time font selection and bold or italic face support for
 129 output devices via its -d and -f options.  Cawf can be directed to issue
 130 specific device codes for bold and italic characters, and one font can be
 131 specified for the entire document.  Cawf has some built-in output device
 132 support, and addition support is contained in the device configuration file,
 133 device.cf.  Additional devices may be defined in device.cf.
 134
 135 It is not necessary to generate a new *.dev file for each output device
 136 definition.  Only when you need special character definitions do you need to
 137 create a *.dev file.  The dumb.dev file is adequate for most devices you
 138 define in device.cf.
 139
 140
 141 SOURCES
 142 -------
 143
 144 The Unix make file has some definitions that help tune it to the local
 145 Unix environment:
 146
 147         CAWFLIB         is a string that can be used in lieu of changes
 148                         to cawf.h's CWFLIB #define.
 149
 150         MALLOCH         is a string that should be defined when a UNIX
 151                         environment has a <malloc.h>, unless it also has a
 152                         <stdlib.h> with protoypes for malloc() and its
 153                         relatives.  In the latter case, you should define
 154                         STDLIB, but you don't need to define MALLOCH.
 155
 156         STDLIB          indicates that standard library function prototype
 157                         definitions may be found in <stdlib.h>.
 158
 159                         STDLIB must be defined for MS-DOS Quick C.
 160
 161                         If STDLIB is not defined, the cawf sources try to
 162                         define their own library function return values.
 163
 164         __STR__         The definition of this string must be deleted when
 165                         using the xlc 1.2 compiler on the RISC/System 6000
 166                         under AIX 3.2.  Put
 167
 168                                 -U__STR__
 169
 170                         in the Makefile DEFS string.  This must be done
 171                         because the xlc 1.2 compiler does not correctly inline
 172                         string functions when compiling pass3.c.
 173
 174         UNIX            switches the build environment to Unix.  You may also
 175                         have to decide about MALLOCH, STDLIB, __STR__ and USG
 176                         when you define UNIX.
 177
 178                         Do not define UNIX for MS-DOS Quick-C; do define
 179                         STDLIB.
 180
 181         USG             adjusts for System V.  (UNIX must also be defined.)
 182
 183                         You may also need to define USG to select the proper
 184                         header file for string function prototypes.  If UNIX
 185                         and USG are defined, "proto.h" selects <string.h>;
 186                         if only UNIX, <strings.h>.  Cawf needs the more
 187                         complete set of definitions, including strchr() and
 188                         strrchr().  If <string.h> #includes <strings.h>, as
 189                         is sometimes the case, define only UNIX.
 190
 191 I have built and tested cawf in the UNIX context under AIX 3.2 (see the
 192 note above on __STR__), BSD4.3-Tahoe, Sequent DYNIX, ETAV (SYSV 3.0),
 193 NeXTStep 3.0, SunOS 4.1.1 and Ultrix 2.2.  If you build under another Unix
 194 variant, you may have to adjust the source code, header files and Makefile
 195 to fit.  Check the Makefile first for hints.
 196
 197
 198 ANSI C COMPLIANCE
 199 -----------------
 200
 201 Some effort has been devoted to making the cawf sources ANSI C compliant.
 202 The header file proto.h contains function prototypes that enable ANSI C
 203 argument checking.  The state of definition of the __STDC__ symbol is used
 204 to select options that depend on strict adherence to the ANSI C standard --
 205 e.g., the need for the isascii() test before islower() or isupper().  If
 206 your ANSI compiler doesn't define this variable when it's acting in strict
 207 ANSI C mode, you may have to define it in the Makefile.
 208
 209
 210 MS-DOS CONSIDERATIONS
 211 ---------------------
 212
 213 The MS-DOS version of cawf was created to run under the KornShell of the
 214 Mortis Kern Systems Toolkit.  One ramification of using MKS' ksh is that it
 215 supports the separate standard error and standard output streams.  Hence,
 216 cawf blithely distributes its error messages to the standard error file, and
 217 assumes the user's shell is capable of separating them from standard output.
 218
 219 If you don't use the MKS KornShell, but do want to separate the output
 220 streams, you'll have to modify the cawf source code.  As a rudimentary aid,
 221 cawf uses a separate stream pointer, Efs, for writing error output, but sets
 222 it to stderr.  You can change that process to open a separate error file and
 223 set Efs to point to it.
 224
 225
 226 COPYRIGHTS AND CREDITS
 227 ----------------------
 228
 229 The sources are copyrighted, but freely distributable under usual terms -
 230 retention of credit, etc.
 231
 232 Please acknowledge:
 233
 234         AT&T for their public-domain release of getopt(3) at the 1985
 235         UNIFORUM conference;
 236
 237         Chet Creider, Bob Hardy and Ted Campbell for their contributions
 238         to font filtering;
 239
 240         Henry Spencer for awf and his regular expression package;
 241
 242         Andy Tanenbaum for his help in ANSI C compliance, including his
 243         ansi.h header file from Minix.
 244
 245 Henry says about awf, "I can't believe I really wrote this."  Those are
 246 my sentiments exactly about cawf, but I also understand that necessity
 247 sometimes forces us to do what we would prefer to avoid.
 248
 249
 250 BUGS AND ENHANCEMENTS
 251 ---------------------
 252
 253 I'll be glad to hear about bugs and needs for enhancements, but make no
 254 promises about delivering fixes or upgrades in response.
 255
 256 Vic Abell <abe@cc.purdue.edu>
 257 24 November 1992
 258
 259
 260 MINIX SPECIFIC TINKERING
 261 ------------------------
 262
 263 Kees J. Bot <kjb@cs.vu.nl>
 264 26 November 1992