1Cawf - nroff-like text formatter 2 3Cawf is a C version of awf, Henry Spencer's Amazingly Workable (text) 4Formatter. (Awf is written in awk and appears in comp.sources.unix, 5Volume 23, Issue 27.) Cawf and awf provide a usable subset of raw nroff 6capabilities and the styles of the man(7), me(7) and ms(7) macro sets. 7One of cawf's virtues is that it will run on PC clones under MS-DOS. It 8is also, like awf, totally independent of any licensed Unix source code. 9 10This distribution contains complete source, make files for Unix and 11MS-DOS, documentation (raw and formatted) and MS-DOS executables for cawf 12and a companion output filters, bsfilt. 13 14This 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 55Changes 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 68CONTENTS 69-------- 70 71This 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 94LIBRARY 95------- 96 97To use cawf, you must select a location for the CAWFLIB library files. The 98distributed cawf binary expects to find them in /usr/local/lib/cawf but you 99can alter that with the CAWFLIB environment variable, or you can change the 100CAWFLIB #define in cawf.h and rebuild cawf from the sources. 101 102CAWFLIB 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 113You 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 115files. 116 117If you have fancy output devices with special character specifications, you 118may want to generate new *.dev files for them. Follow the format of dumb.dev 119in making new character specifications. To define characters for a new 120device, select a name prefix for it and create a file in CAWFLIB with the 121name "<prefix>.dev". To use the new file, set the TERM environment variable 122to <prefix> - e. g., when I test cawf on Unix, I need a vt100.dev, because 123my TERM environment variable value is usually vt100. All I do is make 124vt100.dev a symbolic link to dumb.dev. Even that isn't even necessary, 125because cawf will use dumb.dev if it can't find TERM.dev. 126 127In addition to the character specifications possible through the *.dev files, 128cawf provides one-time font selection and bold or italic face support for 129output devices via its -d and -f options. Cawf can be directed to issue 130specific device codes for bold and italic characters, and one font can be 131specified for the entire document. Cawf has some built-in output device 132support, and addition support is contained in the device configuration file, 133device.cf. Additional devices may be defined in device.cf. 134 135It is not necessary to generate a new *.dev file for each output device 136definition. Only when you need special character definitions do you need to 137create a *.dev file. The dumb.dev file is adequate for most devices you 138define in device.cf. 139 140 141SOURCES 142------- 143 144The Unix make file has some definitions that help tune it to the local 145Unix 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 191I have built and tested cawf in the UNIX context under AIX 3.2 (see the 192note above on __STR__), BSD4.3-Tahoe, Sequent DYNIX, ETAV (SYSV 3.0), 193NeXTStep 3.0, SunOS 4.1.1 and Ultrix 2.2. If you build under another Unix 194variant, you may have to adjust the source code, header files and Makefile 195to fit. Check the Makefile first for hints. 196 197 198ANSI C COMPLIANCE 199----------------- 200 201Some effort has been devoted to making the cawf sources ANSI C compliant. 202The header file proto.h contains function prototypes that enable ANSI C 203argument checking. The state of definition of the __STDC__ symbol is used 204to select options that depend on strict adherence to the ANSI C standard -- 205e.g., the need for the isascii() test before islower() or isupper(). If 206your ANSI compiler doesn't define this variable when it's acting in strict 207ANSI C mode, you may have to define it in the Makefile. 208 209 210MS-DOS CONSIDERATIONS 211--------------------- 212 213The MS-DOS version of cawf was created to run under the KornShell of the 214Mortis Kern Systems Toolkit. One ramification of using MKS' ksh is that it 215supports the separate standard error and standard output streams. Hence, 216cawf blithely distributes its error messages to the standard error file, and 217assumes the user's shell is capable of separating them from standard output. 218 219If you don't use the MKS KornShell, but do want to separate the output 220streams, you'll have to modify the cawf source code. As a rudimentary aid, 221cawf uses a separate stream pointer, Efs, for writing error output, but sets 222it to stderr. You can change that process to open a separate error file and 223set Efs to point to it. 224 225 226COPYRIGHTS AND CREDITS 227---------------------- 228 229The sources are copyrighted, but freely distributable under usual terms - 230retention of credit, etc. 231 232Please 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 245Henry says about awf, "I can't believe I really wrote this." Those are 246my sentiments exactly about cawf, but I also understand that necessity 247sometimes forces us to do what we would prefer to avoid. 248 249 250BUGS AND ENHANCEMENTS 251--------------------- 252 253I'll be glad to hear about bugs and needs for enhancements, but make no 254promises about delivering fixes or upgrades in response. 255 256Vic Abell <abe@cc.purdue.edu> 25724 November 1992 258 259 260MINIX SPECIFIC TINKERING 261------------------------ 262 263Kees J. Bot <kjb@cs.vu.nl> 26426 November 1992 265