SysIII/usr/src/man/man1/cw.1

Compare this file to the similar file:
Show the results in this format: 

'\" ct
.if n .tr%\&
.CD -l% -r%
.de CW
.PP
.RS
.nf
.ps -1
.vs -1p
.ta 16m/3u 32m/3u 48m/3u 64m/3u 80m/3u 96m/3u 112m/3u
..
.de CN
.DT
.vs
.ps
.fi
.RE
.PP
..
.TH CW 1
.SH NAME
cw, checkcw \- prepare constant-width text for troff
.SH SYNOPSIS
.B cw
[
.BR -l xx
] [
.BR -r xx
] [
.BR -f n
] [
.B -t
] [
.B +t
] [
.B -d
] [ files ]
.PP
.B checkcw
[
.BR -l xx
] [
.BR -r xx
] files
.SH DESCRIPTION
.I Cw\^
is a preprocessor for
.IR troff (1)
input files that contain text to be typeset in the constant-width
(\s-1CW\s+1)
font.
.PP
Text typeset with the
.SM 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
.I "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.
.PP
Because the
.SM CW
font contains a ``non.ds ^ \f3\^\s+4\v'.3m'^\v'-.3m'\s-4\^\fP
.TH BS 1
.SH NAME
bs \- a compiler/interpreter for modest-sized programs
.SH SYNOPSIS
.B bs
[ file [ args ] ]
.SH DESCRIPTION
.I Bs\^
is a remote descendant of Basic and Snobol4
with a little C language thrown in.
.I Bs\^
is designed for programming tasks where program development time
is as important as the resulting speed of execution.
Formalities of data declaration and file/process manipulation
are minimized.
Line-at-a-time debugging, the
.I trace\^
and
.I dump\^`not'' sign	%\(no%	%\%%(no%
Left arrow	%\(<-%	%\%%(<-%
Right arrow	%\(->%	%\%%(->%
Down arrow	%\(da%	%\%%(da%
Vertical single quote	%\(fm%	%\%%(fm%
Control-shift indicator	%\(dg%	%\%%(dg%
Visible space indicator	%\(sq%	%\%%(sq%
Hyphen	%\(hy%	%\%%(hy%
.TE
.}}
.RE
.PP
The hyphen is a synonym for
the unadorned minus sign
.RB ( - ).
Certain versions of
.I cw\^
recognize two additional names:
.CD -t
.if t %\e(ua%
.if n \e(ua
for an up arrow and
.if t %\e(lh%
.CD +t
.if n \e(lh
for a diagonal left-up (home) arrow.
.PP
.I Cw\^
recognizes five request lines, as well as user-defined delimiters.
The request lines look like
.IR troff (1)
macro requests, and are copied in their entirety by
.I cw\^
onto its output;
thus, they can be defined
.I "by the user\^"
as
.IR troff (1)
macros;
in fact, the %.CW% and %.CN% macros
.I should\^
be so defined (see
.SM
.I HINTS\^
below).
.PP
The five requests are:
.TP
.SM
.B .CW
Start of text to be set in the
.SM CW
font;
%.CW%
causes a break; it
can take precisely the same options, in precisely the same format,
as are available on the
.I cw\^
command line.
.TP
.SM
.B .CN
End of text to be set in the
.SM CW
font;
%.CN%
causes a break; it
can take the same options
as are available on the
.I cw\^
command line.
.TP
.SM
.B .CD
Change delimiters and/or settings of other options;
takes the same options
as are available on the
.I cw\^
command line.
.TP
.SM
.BI .CP "\*S \^arg1 \^arg2 \^arg3 " ... " \^argn\^
All the
arguments (which are delimited like
.IR troff (1)
macro arguments) are concatenated, with the odd-numbered arguments
set in the
.SM CW
font and the even-numbered ones in the prevailing font.
.TP
.SM
.BI .PC "\*S \^arg1 \^arg2 \^arg3 " ... " \^argn\^
Same as %.CP%, except that the even-numbered (rather than odd-numbered) arguments are
set in the
.SM CW
font.
.PP
The %.CW% and %.CN% requests are meant to bracket text (e.g., a program fragment) that is
to be typeset in the
.SM CW
font ``as is.''\ 
Normally,
.I cw\^
operates in the
.I 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,
.I cw\^
arranges for periods
.RB ( . )
and apostrophes
.RB ( ' )
at the beginning of lines, and
backslashes
.if t (%\%)
.if n (\e)
and ligatures (%fi%, %ff%, etc.)
everywhere to be ``hidden'' from
.IR troff (1).
The transparent mode can be turned off (see below), in which case
normal
.IR troff (1)
rules apply.
In any case,
.I cw\^
hides from the
.I user\^
the effect of the font changes generated by the %.CW% and %.CN% requests.
.PP
The only purpose of the %.CD% request is to allow the changing of various
options other than just at the beginning of a document.
.PP
The user can also define
.IR delimiters .
The left and right delimiters perform the same function
as the %.CW%\|/%.CN% requests; they are meant, however,
to enclose
.SM CW
``words''
or ``phrases''
in running text (see the example under
.SM
.I BUGS\^
below).
.I Cw\^
treats text enclosed by delimiters in precisely the same manner as text
bracketed by %.CW%\|/%.CN% pairs,
except that, for aesthetic reasons,
spaces in text bracketed by %.CW%\|/%.CN% pairs have the same width as any
other
.SM CW
character,
while spaces between delimiters
are half as wide, so that they
have the same width as spaces in the prevailing
text (but are
.I not\^
adjustable).
.PP
Delimiters have no special meaning inside %.CW%\|/%.CN% pairs.
.PP
The options are:
.TP
.BI -l xx\^
The one- or two-character string
.I xx\^
becomes the left delimiter;
if
.I xx\^
is omitted,
the left delimiter becomes undefined,
which it is initially.
.TP
.BI -r xx\^
Same for the right delimiter.
The left and right delimiters may (but need not) be different.
.TP
.BI -f n\^
The
.SM CW
font is mounted in font position
.IR n ;
acceptable values for
.I n\^
are 1, 2, and 3
(default is 3, replacing the bold font).
This option is only useful at the beginning of a document.
.TP
.B -t
Turn transparent mode
.IR off .
.TP
.B +t
Turn transparent mode
.I on\^
(this is the initial default).
.TP
.B -d
Print current option settings on file descriptor 2
in the form of
.IR troff (1)
comment lines.
This option is meant for debugging.
.PP
.I Cw\^
reads the standard input when no
.I files\^
are specified,
so it
can be used as a filter.
Typical usage is:
.CW -t
cw \f2files\fP | troff ...
.CN +t
.I Checkcw\^
checks that left and right delimiters, as well as the %.CW%\|/%.CN% pairs, are properly
balanced.
It prints out all offending lines.
.br
.ne 14v
.SH HINTS
Typical definitions of the %.CW% and %.CN% macros meant to be used with the
.IR mm (7)
macro package:
.if n .ig }}
.CW
.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
..
.CN
.}}
.if t .ig }}
.PP
.RS
.nf
\&.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 .5i 1i 1.5i 2i 2.5i 3i ...
\&.vs
\&.ps
\&.DE
\&..
.fi
.RE
.PP
.}}
.PP
At the very least, the %.CW% macro should invoke the
.IR troff (1)
no-fill (%.nf%) mode.
.PP
When set in running text, the
.SM 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
.I 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
.SM CW
font is sized so that,
when it is set in 9-point,
there are 12 characters per inch.
.PP
Documents that contain
.SM CW
text may also contain tables and/or equations.
If this is the case, the order of preprocessing should be:
.IR cw ,
.IR tbl ,
and
.IR eqn .
Usually, the tables contained in such documents will not contain
any
.SM CW
text, although it is entirely possible
to have
.I elements\^
of the table set in the
.SM CW
font;
of course, care must be taken that
.IR tbl (1)
format information not be modified by
.IR cw .
Attempts to set equations in the
.SM CW
font are not likely to be either
pleasing or successful.
.PP
In the
.SM CW
font,
overstriking is most easily accomplished with backspaces:
letting %\(<-% represent a backspace,
%d\(<-\(<-\(%%dg% yields %d\(dg%.
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.
.SH FILES
/usr/lib/font/ft\s-1CW\s+1\ \ \ \ 
.SM CW
font-width table
.SH SEE ALSO
eqn(1),
mmt(1),
tbl(1),
troff(1),
mm(7),
mv(7).
.SH WARNINGS
If text preprocessed by
.I cw\^
is to make any sense, it must
be set on a typesetter equipped with the
.SM CW
font or on the
.SM MHCC
.SM STARE
facility;
on the latter, the
.SM CW
font appears as bold, but with the proper
.SM CW
spacing.
.SH BUGS
Only a masochist would use periods (%.%) or backslashes
(%\%) as delimiters.
.br
Certain
.SM CW
characters don't concatenate gracefully
with certain Times Roman characters, e.g., a
.SM CW
ampersand (%&%)
followed by a Times Roman comma(%,%);
in such cases, judicious use of
.IR troff (1)
half- and quarter-spaces
.if t (%\|% and %\^%)
.if n (\e| and \e^)
is most salutary,
e.g., one should use
.if t %_&_\^,%
.if n _&_\e^,
(rather than just plain %_&_,%)
to obtain %&%\^,
(assuming that %_% is used for both delimiters).
.br
Using
.I cw\^
with
.I nroff\^
is silly.
.br
The output of
.I cw\^
is hard to read.
.br
See also
.SM
.I BUGS\^
under
.IR troff (1).