cw(1) cw(1)
NAME
cw, checkcw - prepare constant-width text for otroff
SYNOPSIS
cw [-d] [-fn] [-lxx] [-rxx] [-t] [+t] [files]
checkcw [-lxx] [-rxx] files
DESCRIPTION
cw is a preprocessor for otroff(1)) input files that contain
text to be typeset in the constant-width (CW) font.
Text typeset with the CW font resembles the output of
terminals and of line printers. This font is used to
typeset examples of programs and of computer output in user
manuals, programming texts, etc. (An earlier version of
this font was used in typesetting The C Programming Language
by B. W. Kernighan and D. M. Ritchie.) It has been designed
to be quite distinctive (but not overly obtrusive) when used
together with the Times Roman font.
Because the CW font contains a non-standard set of
characters and because text typeset with it requires
different character and inter-word spacing than is used for
standard fonts, documents that use the CW font must be
preprocessed by cw.
The CW font contains the 94 printing ASCII characters:
abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
0123456789
!$%&()`'*+@.,/:;=?[]|-_^~"<>{}#\
plus eight non-ASCII characters represented by four-
character otroff(1) names (in some cases attaching these
names to non-standard graphics):
character symbol troff name
___________________________________________
Cents sign ¢ \(ct
EBCDIC not sign \(no
Left arrow <- \(<-
Right arrow -> \(->
Down arrow \(da
Vertical single quote ' \(fm
Control-shift indicator † \(dg
Visible space indicator [] \(sq
Hyphen - \(hy
The hyphen is a synonym for the unadorned minus sign (-).
Certain versions of cw recognize two additional names: \(ua
Page 1 (last mod. 1/16/87)
cw(1) cw(1)
for an up arrow and \(lh for a diagonal left-up (home)
arrow.
cw recognizes five request lines, as well as user-defined
delimiters. The request lines look like otroff(1) macro
requests, and are copied in their entirety by cw onto its
output; thus, they can be defined by the user as otroff(1)
macros; in fact, the .CW and .CN macros should be so defined
(see HINTS below). The five requests are:
.CW Start of text to be set in the CW font; .CW causes a
break; it can take precisely the same flag options, in
precisely the same format, as are available on the cw
command line.
.CN End of text to be set in the CW font; .CN causes a
break; it can take the same flag options as are
available on the cw command line.
.CD Change delimiters and/or settings of other flag
options; takes the same flag options as are available
on the cw command line.
.CP arg1 arg2 arg3 ... argn
All the arguments (which are delimited like otroff(1)
macro arguments) are concatenated, with the odd-
numbered arguments set in the CW font and the even-
numbered ones in the prevailing font.
.PC arg1 arg2 arg3 ... argn
Same as .CP, except that the even-numbered arguments
are set in the CW font and the odd-numbered ones in the
prevailing font.
The .CW and .CN requests are meant to bracket text (e.g., a
program fragment) that is to be typeset in the CW font as
is. Normally, cw operates in the transparent mode. In that
mode, except for the .CD request and the nine special four-
character names listed in the table above, every character
between .CW and .CN request lines stands for itself. In
particular, cw arranges for periods (.) and apostrophes (')
at the beginning of lines, and backslashes (\) everywhere to
be hidden from otroff(1). The transparent mode can be
turned off (see below), in which case normal otroff(1) rules
apply; in particular, lines that begin with . and ' are
passed through untouched (except if they contain
delimiters-see below). In either case, cw hides the effect
of the font changes generated by the .CW and .CN requests;
cw also defeats all ligatures (fi, ff, etc.) in the CW font.
The only purpose of the .CD request is to allow the changing
of various flag options other than just at the beginning of
Page 2 (last mod. 1/16/87)
cw(1) cw(1)
a document.
The user can also define delimiters. The left and right
delimiters perform the same function as the .CW/.CN
requests; they are meant, however, to enclose CW words or
phrases in running text (see example under BUGS below). cw
treats text between delimiters in the same manner as text
enclosed by .CW/.CN pairs, except that, for aesthetic
reasons, spaces and backspaces inside .CW/.CN pairs have the
same width as other CW characters, while spaces and
backspaces between delimiters are half as wide, so they have
the same width as spaces in the prevailing text (but are not
adjustable). Font changes due to delimiters are not hidden.
Delimiters have no special meaning inside .CW/.CN pairs.
The flag options are:
-lxx The one- or two-character string xx becomes the left
delimiter; if xx is omitted, the left delimiter
becomes undefined, which it is initially.
-rxx Same for the right delimiter. The left and right
delimiters may (but need not) be different.
-fn The CW font is mounted in font position n; acceptable
values for n are 1, 2, and 3 (default is 3, replacing
the bold font). This flag option is only useful at
the beginning of a document.
-t Turn transparent mode off.
+t Turn transparent mode on (this is the initial
default).
-d Print current flag option settings on file descriptor
2 in the form of otroff(1) comment lines. This flag
option is meant for debugging.
cw reads the standard input when no files are specified (or
when - is specified as the last argument), so it can be used
as a filter. Typical usage is:
cw files | otroff ...
checkcw checks that left and right delimiters, as well as
the .CW/.CN pairs, are properly balanced. It prints out all
offending lines.
HINTS
Typical definitions of the .CW and .CN macros meant to be
used with the mm(1) macro package:
Page 3 (last mod. 1/16/87)
cw(1) cw(1)
.de CW
.DS I
.ps 9
.vs 10.5p
.ta 16m/3u 32m/3u 48m/3u 64m/3u 80m/3u 96m/3u ...
..
.de CN
.ta 0.5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i 6i
.vs
.ps
.DE
..
At the very least, the .CW macro should invoke the otroff(1)
no-fill (.nf) mode.
When set in running text, the CW font is meant to be set in
the same point size as the rest of the text. In displayed
matter, on the other hand, it can often be profitably set
one point smaller than the prevailing point size (the
displayed definitions of .CW and .CN above are one point
smaller than the running text on this page). The CW font is
sized so that, when it is set in 9-point, there are 12
characters per inch.
Documents that contain CW text may also contain tables
and/or equations. If this is the case, the order of
preprocessing should be: cw, tbl, and eqn. Usually, the
tables contained in such documents will not contain any CW
text, although it is entirely possible to have elements of
the table set in the CW font; of course, care must be taken
that tbl(1) format information not be modified by cw.
Attempts to set equations in the CW font are not likely to
be either pleasing or successful.
In the CW font, overstriking is most easily accomplished
with backspaces: letting <- represent a backspace, d<-<-†
yields d†. Because spaces (and, therefore backspaces) are
half as wide between delimiters as inside .CW/.CN pairs (see
above), two backspaces are required for each overstrike
between delimiters.
EXAMPLE
cw text | tbl | otroff -mm
processes the text file text, sends the output to tbl(1) and
then sends the output for final formatting to otroff(1) and
mm(1).
FILES
/bin/cw
Page 4 (last mod. 1/16/87)
cw(1) cw(1)
/usr/lib/font/ftCW
SEE ALSO
eqn(1), mmt(1), tbl(1), troff(1), mm(5), mv(5),
``Other Text Procesing Tools'' in Oreo Programming Languages
and Tools, Volume 2.
WARNINGS
If text preprocessed by cw is to make any sense, it must be
set on a typesetter equipped with the CW font or on a STARE
facility; on the latter, the CW font appears as bold, but
with the proper CW spacing.
Do not use periods (.), backslashes (\), or double quotes
(") as delimiters, or as arguments to .CP and .PC.
Do not use cw with nroff, since nroff already makes
everything constant-width.
BUGS
Certain CW characters don't concatenate gracefully with
certain Roman characters, e.g., a CW ampersand (&) followed
by a Roman comma(,); in such cases, judicious use of
otroff(1) half- and quarter-spaces (\| and \^) is most
salutary, e.g., one should use _&_\^ (rather than just plain
_&_) to obtain & (assuming that _ is used for both
delimiters).
The output of cw is hard to read. See also BUGS under
otroff(1).
Page 5 (last mod. 1/16/87)