| blob | 3d3ad3451ece0069fe136307ebc2efbf27090d47 |
1 .\" manual page for cawf(1)
2 .\"
3 .\"
4 .\" Copyright (c) 1991 Purdue University Research Foundation,
5 .\" West Lafayette, Indiana 47907. All rights reserved.
6 .\"
7 .\" Written by Victor A. Abell <abe@cc.purdue.edu>, Purdue
8 .\" University Computing Center. Not derived from licensed software;
9 .\" derived from awf(1) by Henry Spencer of the University of Toronto.
10 .\"
11 .\" Permission is granted to anyone to use this software for any
12 .\" purpose on any computer system, and to alter it and redistribute
13 .\" it freely, subject to the following restrictions:
14 .\"
15 .\" 1. The author is not responsible for any consequences of use of
16 .\" this software, even if they arise from flaws in it.
17 .\"
18 .\" 2. The origin of this software must not be misrepresented, either
19 .\" by explicit claim or by omission. Credits must appear in the
20 .\" documentation.
21 .\"
22 .\" 3. Altered versions must be plainly marked as such, and must not
23 .\" be misrepresented as being the original software. Credits must
24 .\" appear in the documentation.
25 .\"
26 .\" 4. This notice may not be removed or altered.
27 .\"
28 .\" Some of the stuff in this file is a bit contorted, because it's also
29 .\" the regression-test input.
30 .nr ES 5n
31 .de ES
32 .PP
33 .in +\\n(ESu
34 .nf
35 ..
36 .de EE
37 .in -\\n(ESu
38 .fi
39 .PP
40 ..
41 .de PT
42 .ie \\n(.$>1 .TP "\\$2"
43 .el .TP
44 .ie !'\\$1'' \\$1
45 .el \(bu
46 ..
47 .ds Nr \fInroff\fR
48 .TH CAWF 1 "November, 1992"
49 .BY "Purdue University"
50 .SH NAME
51 cawf, nroff \- C version of the nroff-like, Amazingly Workable (text) Formatter
52 .SH SYNOPSIS
53 .B cawf
54 .RB [ \-c\c
55 .IR config ]
56 .RB [ \-d\c
57 .IR device ]
58 .RB [ \-e ]
59 .RB [ \-f\c
60 .IR font ]
61 .RB [ \-h ]
62 .RB [ \-m\c
63 .IR acros ]
64 .RI [ file " ...]"
65 .SH DESCRIPTION
66 .I Cawf
67 formats the text from the input \fIfile\fR(s)
68 (standard input if none)
69 in an approximation of \*(Nr.
70 It comes closest to duplicating \*(Nr's
71 .B man
72 or
73 .B ms
74 macro package styles.
75 It has some limited support for \*(Nr's
76 .B me
77 macros.
78 .SH OPTIONS
79 Options must precede file names.
80 .TP
81 .BI \-c config
82 defines an alternate path to the device configuration file.
83 Normally the device configuration file is found in
84 .I device.cf
85 in the
86 .I cawf
87 library (see the
88 .B FILES
89 section).
90 .IP
91 The device configuration file contains device character strings for
92 selecting fonts and the bold or italic type faces.
93 See the
94 .B DEVICES
95 section for more information.
96 .TP
97 .BI \-d device
98 specifies the name of the output device.
99 There are three built\-in devices \- ANSI, NONE and NORMAL \- and
100 other devices may be defined in the device configuration file.
101 See the
102 .B DEVICES
103 section for more information.
104 .IP
105 The NORMAL device is the default.
106 .TP
107 .B \-e
108 directs
109 .I cawf
110 to issue an eject (FF or ^L) after the last page.
111 .TP
112 .BI \-f font
113 specifies the one font for the device, declared with the
114 .BI \-d device
115 option, that is to be used for the
116 entire document.
117 .I Font
118 must match a font associated with the device's stanza in the device
119 configuration file.
120 See the
121 .B DEVICES
122 section for more information.
123 .IP
124 No
125 .I font
126 may be specified for the built\-in devices ANSI, NONE or NORMAL.
127 .TP
128 .B \-h
129 requests a help display.
130 .TP
131 .BI \-m acro
132 specifies the macro file to be used.
133 The standard
134 .I cawf
135 distribution supplies macro files to support ``\-man'', ``\-me'' or ``\-ms''.
136 .I Cawf
137 finds a macro file by constructing its name from `m',
138 .I acro
139 and
140 .B .mac
141 \- e. g.,
142 .BI \-m an
143 is converted to
144 .BR man.mac .
145 The default directory for macro files is defined when
146 .I cawf
147 is compiled; it's \fIC:\\SYS\\LIB\\CAWF\fP in the MS\-DOS environment;
148 .I /usr/lib/cawf
149 in the UNIX environment.
150 .TP
151 file ...
152 are the names of files containing \*(Nr source text.
153 .SH NROFF COMPATIBILITY
154 .I Cawf
155 accepts the following raw \*(Nr requests:
156 .ES
157 \&.\e" .ad .bp .br .ce .de .di .ds
158 \&.el .fi .fl .ft .i0 .ie .if .in
159 \&.it .lg .li .ll .ls .na .ne .nf
160 \&.nr .ns .pl .po .ps .rm .rn .rr
161 \&.rs .so .sp .ta .ti .tm .tr
162 .EE
163 and the following in-text codes:
164 .ES
165 \e$ \e% \e* \e" \ec \ef \eh \ek
166 \en \es \ew
167 .EE
168 plus the full list of \*(Nr/\c
169 .I troff
170 special characters in
171 the original V7 \fItroff\fR manual.
172 .PP
173 Many restrictions are present; the behavior in general is a subset of
174 \*(Nr's. Of particular note are the following:
175 .IP \(bu 2
176 The fully supported nroff request control character is the period.
177 There is limited support for the non\-break, acute accent control
178 character.
179 .PT
180 Point sizes do not exist;
181 .B .ps
182 is ignored.
183 .PT
184 Special vertical spacing \- the
185 .B .vs
186 request included \- is ignored.
187 .PT
188 Conditionals cover only the numeric comparisons >, =, <, >= and <= on
189 .BR \en(.$ ;
190 string com\%par\%isons between a macro parameter and a literal;
191 .B n
192 (always true);
193 and
194 .BR t
195 (always false).
196 Only single line input is accepted from conditionals;
197 multi\-line input \- e.g., \\(\fIanything\fP\\) \- is not supported.
198 .PT
199 The handling of strings is generally primitive.
200 .IP \(bu
201 Horizontal motion via
202 .B \eh
203 must be supplied with a number register interpolation and must be
204 positive - e. g.,
205 .BR \ew\en(NN ,
206 where the value in NN is >= 0.
207 .IP \(bu
208 The
209 .B \ek
210 function is reliable only after TAB characters, so it is useful only
211 for measuring table positions.
212 .IP \(bu
213 The
214 .B .di
215 request only turns output on and off \- any macro name is ignored.
216 .IP \(bu
217 Expressions - e. g.,
218 .B .sp
219 - are reasonably general, but the
220 .BR | ,
221 .BR & ,
222 and
223 .BR :\&
224 operators do not exist, there must be white space between the end of the \*(Nr
225 function and the beginning of the expression, and
226 .B \ew
227 requires that quote (') be used as the delimiters.
228 .B \ew
229 counts the characters inside the quotes and scales the result in ens,
230 so that, for example, \ew'\e(bu' equals 4n, and \ew'\e(bu'/1n equals 4.
231 .PT
232 The only acceptable count for the
233 .B .it
234 request is one,
235 and it is effective only with
236 .BR man ,
237 .B me
238 or
239 .B ms
240 macros.
241 .PT
242 The default scaling factor is `v' for the
243 .BR .ne ,
244 .BR .sp ,
245 and
246 .B .pl
247 raw \*(Nr requests; it is `u' for
248 .BR .nr ;
249 and `n' for
250 .BR .in ,
251 .BR .ll ,
252 .BR .ls ,
253 .BR .po ,
254 .BR .ta
255 and
256 .BR .ti .
257 (A different scaling factor may be specified with a trailing character.)
258 .PT
259 Some obsolete or meaningless requests \-
260 .BR .i0 ,
261 .B .lg
262 and
263 .B .li
264 \&\- are silently ignored.
265 .P
266 White space at the beginning of lines,
267 and embedded white space within lines is dealt with properly.
268 Sentence terminators at ends of lines are understood to imply
269 extra space afterward in filled lines.
270 Tabs are im\%plemented crudely and not exactly, although
271 usually they work as expected.
272 Hyphenation is done only at explicit hyphens, em-dashes, and \*(Nr
273 discretionary hyphens.
274 By default bold and italic characters are emulated with backspacing and
275 overprinting, but the
276 .B \-d
277 and
278 .B \-f
279 options, combined with the contents of the device configuration file,
280 may be used to generate special codes for bold and italic characters.
281 (See the
282 .B DEVICES
283 section for more information.)
284 .SH "MAN MACROS"
285 The
286 .B man
287 macro set replicates the full V7 manual macros,
288 plus a few semi-random oddballs.
289 The full list is:
290 .ES
291 \&.AT .B .BI .BR .BY .DE .DT .HP
292 \&.I .IB .IP .IR .IX .LP .NB .P
293 \&.PD .PP .RB .RE .RI .RS .SH .SM
294 \&.SS .TH .TP .UC
295 .EE
296 .B .BY
297 and
298 .B .NB
299 each take a single string argument (respectively, an indi\%cation of
300 authorship and a note about the status of the manual page) and arrange
301 to place it in the page footer.
302 .B .AT
303 and
304 .B .IX
305 do nothing.
306 .SH "ME MACROS"
307 The
308 .B me
309 macro subset has been derived from the
310 .I cawf
311 .B ms
312 macros by Chet Creider <creider@csd.uwo.ca>.
313 It includes:
314 .ES
315 \&.(l .(q .)l .)q .b .bu .i .ip
316 \&.lp .np .pp .r .sh .sm .u .uh
317 .EE
318 The .(l C and .(l L options are supported.
319 In addition, the .AB, .AE, .AI, .AU, .DA, .ND, .TL and .UX macros have
320 been retained from the
321 .B ms
322 set, and the .XP macro has been borrowed from the Berkeley additions to the
323 .B ms
324 macro set.
325 .SH "MS MACROS"
326 The
327 .B ms
328 macro set is a substantial subset of the V7 manuscript macros.
329 The macros are:
330 .ES
331 \&.AB .AE .AI .AU .B .CD .DA .DE
332 \&.DS .I .ID .IP .LD .LG .LP .ND
333 \&.NH .NL .PP .QE .QP .QS .R .RE
334 \&.RP .RS .SH .SM .TL .TP .UL .UX
335 .EE
336 Size changes are recognized but ignored, as are
337 .B .RP
338 and
339 .BR .ND .
340 .B .UL
341 just prints its argument in italics.
342 .BR .DS / .DE
343 does not do a keep,
344 nor do any of the other macros that normally imply keeps.
345 .LP
346 The
347 .B DY
348 string variable is available.
349 The
350 .BR PD ,
351 .BR PI ,
352 and
353 .BR LL
354 number registers exist and can be changed.
355 .SH "HEADERS AND FOOTERS"
356 .I Cawf
357 allows the placement of text into the five line header and
358 footer sections from the
359 .BR LH ,
360 .BR CH ,
361 .BR RF ,
362 .BR LF ,
363 .BR CF ,
364 and
365 .B RF
366 string variables, via the control of the
367 .B .^b
368 request:
369 .LP
370 .ta \w'.^b HF 0'u+3n
371 .nf
372 \&.^b fh 1 enables header string placement on the first page
373 \&.^b fh 0 disables header string placement on the first page
374 \&.^b HF 1 enables header/footer string placement
375 \&.^b HF 0 disables header/footer string placement
376 .fi
377 .LP
378 There are appropriate
379 .B .^b
380 requests in the distribution
381 .BR man ,
382 .B me
383 and
384 .B ms
385 macro files.
386 (The
387 .B me
388 and
389 .B ms
390 macro files use another
391 .B .^b
392 request, \fB.^b NH\fP, to enable numbered header processing.)
393 .SH OUTPUT
394 The default output format supported by
395 .IR cawf ,
396 in its distributed form,
397 is that appropriate to a dumb terminal,
398 using overprinting for italics (via underlining) and bold.
399 The \*(Nr special characters are printed as some vague approximation
400 (it's sometimes extremely vague) to their correct appearance.
401 .PP
402 One part of
403 .IR cawf 's
404 knowledge of the output device, related to the formation of characters,
405 is established by a device file, which is read before the user's input.
406 The search for it begins in
407 .IR cawf 's
408 library directory, under the name \fIterm\fP.\fBdev\fP
409 (where \fIterm\fR is the value of the TERM environment variable).
410 Failing to find that,
411 .I cawf
412 searches for
413 .BR dumb.dev .
414 (See the
415 .B FILES
416 section for a description of the path to
417 .IR cawf 's
418 library directory.)
419 The device file
420 uses special internal requests
421 to set up resolution, special characters
422 and more normal \*(Nr functions to set up page length, etc.
423 .PP
424 .I Cawf
425 has limited support for fonts special forms of bold and italic characters.
426 It is provided through the
427 .B \-c
428 .IR config ,
429 .BI \-d device
430 and
431 .BI \-f font
432 options.
433 See the
434 .B DEVICES
435 section for more information.
436 .PP
437 Note the distinction between the device and the output device configuration
438 files.
439 The device file typically defines characters and constant output parameters.
440 The output device configuration file defines font and type face codes.
441 It is usually not necessary to define a separate device file for each
442 device represented in the output device configuration file \- the
443 .I dumb.dev
444 device file will suffice for almost all representations.
445 .SH DEVICES
446 .I Cawf
447 supports primitive output device configuration for font and type face
448 control.
449 One font may be selected for the entire document by directing
450 .I cawf
451 to issue a font selection control character string at the beginning
452 of the document, and control character strings may be selected for
453 switching between the bold, italic and Roman type faces.
454 .PP
455 The
456 .B \-c
457 .IR config,
458 .BI \-d device
459 and
460 .BI \-f font
461 options direct the font and type face selections.
462 .PP
463 The
464 .BI \-d device
465 option specifies the name of the device.
466 .I Cawf
467 has three built\-in devices \- ANSI, NONE and NORMAL.
468 When the ANSI device is selected,
469 .I cawf
470 issues the ANSI shadow mode control codes, ``ESC [ 7 m'', to represent
471 the bold face;
472 the ANSI underscore control codes, ``ESC [ 4 m'', to represent the italic
473 face;
474 and the ANSI control codes, ``ESC [ 0 m'', to represent the ROMAN face.
475 No
476 .BI \-f font
477 specification is permitted with the ANSI device.
478 .PP
479 When the NONE device is selected,
480 .I cawf
481 uses no special output codes to represent the type faces.
482 No
483 .BI \-f font
484 specification is permitted with the ANSI device.
485 .PP
486 The NORMAL output device is the default.
487 When it's selected,
488 .I cawf
489 overprints each bold character two times, using three issuances of each
490 bold character, separated by backspace characters;
491 it issues an underscore and backspace before each italic character.
492 No
493 .BI \-f font
494 specification is permitted with the ANSI device.
495 The
496 .IR bsfilt (1)
497 filter may be used to further process the backspace codes output for
498 a NORMAL device.
499 .PP
500 All other devices named in the
501 .BI \-d device
502 option must be represented by a stanza in the device configuration file.
503 The device configuration file is usually contained in
504 .I device.cf
505 in
506 .IR cawf's
507 library directory (see the
508 .B FILES
509 section for more information).
510 An alternate device configuration file path may be specified with the
511 .BI \-c config
512 option.
513 .PP
514 The
515 .B DEVICE CONFIGURATION FILE
516 section describes the organization of the device configuration file.
517 It is easy to add devices to the
518 .I device.cf
519 supplied in the
520 .I cawf
521 distribution.
522 .PP
523 The
524 .BI \-f font
525 option may be used with the
526 .BI \-d device
527 option, when the appropriate stanza in the device configuration file
528 contains an entry for the named
529 .IR font .
530 The
531 .B DEVICE CONFIGURATION FILE
532 section describes how fonts are defined in device configuration file
533 stanzas.
534 .SH DEVICE CONFIGURATION FILE
535 The device configuration file defines the special character codes
536 necessary to direct output devices to select fonts and to produce
537 bold, italic and Roman type faces.
538 .PP
539 The configuration file is usually found in
540 .I device.cf
541 in
542 .IR cawf 's
543 library directory (see the
544 .B FILES
545 section for more information).
546 It is organized into two main parts \- comments and device stanzas.
547 Comments are any lines that begin with the pound sign (`#') character.
548 They are informational only and
549 .I cawf
550 ignores them.
551 .I Cawf
552 also ignores empty lines, so they may be used as vertical white space.
553 .PP
554 Stanzas name devices and define their font and type face control strings.
555 A stanza begins with the name of the device, starting at the beginning
556 of a line and occupying the entire line.
557 The body of the stanza, defining fonts and type faces, is formed of
558 lines beginning with white space (a TAB or space characters) that
559 directly follow the device name.
560 .PP
561 Individual lines of the stanza body contain a key character, followed
562 by a equal sign, followed by the font name (if a font key) and the
563 output device control codes.
564 .I Cawf
565 issues the font control codes once, at the beginning of output, so
566 only one font may be selected.
567 The type face control codes are issued at each change of type face.
568 .PP
569 The key characters are:
570 .ne 4
571 .PP
572 .RS
573 .nf
574 b for bold
575 f for font definition
576 i for italic
577 r for Roman
578 .fi
579 .RE
580 .PP
581 The `b', `i' and `r' key codes are followed by an equal sign (`=') and
582 their control code definition.
583 The `f' key code is followed by an equal sign (`='), the font name,
584 another equal sign and the font control code definition.
585 .PP
586 Control code definitions may contain any printable ASCII characters.
587 Non\-printable characters may be encoded in octal notation with the `\\nnn'
588 form or in hexadecimal with the `\\xnn' form.
589 The special code, `\\E' (or `\\e') represents the ESC control
590 character (\\033 or \\x1b).
591 .PP
592 Here's a sample showing the definition for the HP LaserJet III.
593 The stanza name is ``lj3''.
594 All its non\-printable characters are ESCs; the first is coded in
595 octal form; the second with '\\E'; the rest, in hexadecimal form.
596 TAB is used as the leading white space character for the stanza
597 body lines.
598 .PP
599 .RS
600 .nf
601 # HP LaserJet III
603 lj3
604 b=\\033(s7B
605 i=\\E(s1S
606 r=\\x1b(s0B\\x1b(s0S
607 f=c10=\x1b&l0O\x1b(8U\x1b(s0p12h10v0s0b3T
608 f=c12ibm=\x1b&l0O\x1b(10U\x1b(s0p10.00h12.0v0s0b3T
609 f=lg12=\x1b&l0O\x1b(8U\x1b(s12h12v0s0b6T
610 .fi
611 .RE
612 .PP
613 The distribution
614 .I device.cf
615 file defines the following devices and fonts.
616 .LP
617 .ta \w'kxp1180'u+3n +\w'Italic:'u+3n +\w'bps10'u+6n
618 .nf
619 .ne 3
620 epson dot matrix printer in Epson FX-86e/FX-800 mode
621 Bold: Double-strike
622 Fonts: none
624 .ne 4
625 ibmppds IBM Personal Printer Data Stream (PPDS) protocol
626 Bold: Double-strike
627 Italic: Underline
628 Fonts: none
630 .ne 12
631 kxp1124 Panasonic KX\-P1124 dot matrix printer in PGM mode
632 Bold: Emphasized
633 Fonts: c10 10 Characters Per Inch (CPI) Courier
634 c12 12 CPI Courier
635 bps10 10 CPI Bold PS
636 bps12 12 CPI Bold PS
637 p10 10 CPI Prestige
638 p12 12 CPI Prestige
639 s10 10 CPI Script
640 s12 12 CPI Script
641 ss10 10 CPI Sans Serif
642 ss12 12 CPI Sans Serif
644 .ne 10
645 kxp1180 Panasonic KX\-P1180 dot matrix printer in PGM mode
646 Bold: Emphasized
647 Fonts: c10 10 Characters Per Inch (CPI) Courier
648 c12 12 CPI Courier
649 bps10 10 CPI Bold PS
650 bps12 12 CPI Bold PS
651 p10 10 CPI Prestige
652 p12 12 CPI Prestige
653 ss10 10 CPI Sans Serif
654 ss12 12 CPI Sans Serif
656 .ne 6
657 lj3 HP LaserJet III
658 Fonts: c10 10 point, 12 Characters Per Inch (CPI)
659 Courier
660 c12ibm 12 point, 10 CPI Courier, IBM\-PC
661 Symbol Set
662 lg12 12 point, 12 CPI Letter Gothic
664 .ne 4
665 vgamono VGA monochrome monitor for MS\-DOS
666 (ANSI.SYS driver required for MS\-DOS)
667 Italic: Reverse-video
668 Fonts: none
669 .SH FILES
670 .I Cawf
671 resource files are located in the
672 .I cawf
673 library directory \- \fI C:\\SYS\\LIB\\CAWF\fP, the MS\-DOS environment
674 default;
675 or
676 .IR /usr/lib/cawf ,
677 the UNIX environment default.
678 These defaults can be overridden by the CAWFLIB environment variable,
679 or changed in the cawflib.h header file.
681 .ta \w'device.cf'u+3n
682 .nf
683 common common device-independent initialization
684 device.cf output device configurations
685 *.dev device-specific initialization
686 m*.mac macro package files
687 .SH DIAGNOSTICS
688 Unlike
689 .IR nroff ,
690 .I cawf
691 complains whenever it sees unknown requests.
692 All diagnostics appear on the standard error file.
693 .ad
694 .SH HISTORY
695 Vic Abell of Purdue University <abe@cc.purdue.edu> derived
696 .I cawf
697 from
698 .IR awf ,
699 \&``the Amazingly Workable (text) Formatter,''
700 written by Henry Spencer of the University of Toronto.
701 The Toronto work was a supplement to the C News project.
702 The Purdue effort was aimed at producing a C language version that
703 would run on small systems, particularly MS\-DOS ones.
704 The adaptation of the
705 .B me
706 macros was done by Chet Creider <creider@csd.uwo.ca>.
707 Chet also contributed ideas for device, font and type face support.
708 .PP
709 The MS\-DOS version of
710 .I cawf
711 has been compiled with version 2.5 of Microsoft's Quick-C compiler.
712 It runs under the Mortis Kern Systems Toolkit KornShell,
713 .IR ksh (1),
714 and COMMAND.COM.
715 .SH BUGS
716 Nroff and troff mavens will have many complaints.
717 Some may even represent bugs and not deliberate omissions.
718 .PP
719 Watch out for scaling factors - especially on requests like
720 .BR \ew .
721 .PP
722 The overprinting required to create bold and italicized characters is
723 tiresome on a slow printer.
724 The
725 .IR bsfilt (1)
726 post\-filter from this distribution may be used to alleviate that
727 nuisance by managing the backspacing codes from
728 .IR cawf 's
729 NORMAL device output.
730 .PP
731 The printing of bold and italic characters is sometimes better handled by
732 special printer codes.
733 Use
734 .IR cawf 's
735 .B \-c
736 .IR config ,
737 .BI \-d device
738 and
739 .BI \-f font
740 options to produce special font and device output control codes.
741 .PP
742 .I Cawf
743 has a small amount of built-in code for the
744 .BR man ,
745 .B me
746 and
747 .B ms
748 macro packages, but none for any others.
749 .PP
750 The stacking for the
751 .B .so
752 request is limited.
753 .SH SEE ALSO
754 bsfilt(1),
755 colcrt(1),
756 man(7),
757 me(7),
758 ms(7)
759 and
760 nroff(1).