| [9] | 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
|
|---|
