cawf.1

Unix操作系统minix 2.0源码

.\"	manual page for cawf(1)
.\"
.\"
.\"	Copyright (c) 1991 Purdue University Research Foundation,
.\"	West Lafayette, Indiana 47907.  All rights reserved.
.\"
.\"	Written by Victor A. Abell <[e-mail]>,  Purdue
.\"	University Computing Center.  Not derived from licensed software;
.\"	derived from awf(1) by Henry Spencer of the University of Toronto.
.\"
.\"	Permission is granted to anyone to use this software for any
.\"	purpose on any computer system, and to alter it and redistribute
.\"	it freely, subject to the following restrictions:
.\"
.\"	1. The author is not responsible for any consequences of use of
.\"	   this software, even if they arise from flaws in it.
.\"
.\"	2. The origin of this software must not be misrepresented, either
.\"	   by explicit claim or by omission.  Credits must appear in the
.\"	   documentation.
.\"
.\"	3. Altered versions must be plainly marked as such, and must not
.\"	   be misrepresented as being the original software.  Credits must
.\"	   appear in the documentation.
.\"
.\"	4. This notice may not be removed or altered.
.\"
.\" Some of the stuff in this file is a bit contorted, because it's also
.\" the regression-test input.
.nr ES 5n
.de ES
.PP
.in +\\n(ESu
.nf
..
.de EE
.in -\\n(ESu
.fi
.PP
..
.de PT
.ie \\n(.$>1 .TP "\\$2"
.el .TP
.ie !'\\$1'' \\$1
.el \(bu
..
.ds Nr \fInroff\fR
.TH CAWF 1 "November, 1992"
.BY "Purdue University"
.SH NAME
cawf, nroff \- C version of the nroff-like, Amazingly Workable (text) Formatter
.SH SYNOPSIS
.B cawf
[
.BI \-c config
] [
.BI \-d device
] [
.B \-e
] [
.BI \-f font
] [
.B \-h
] [
.BI \-m acros
] [ file ... ]
.SH DESCRIPTION
.if t .tm OOPS -- CAWF THINKS IT'S TROFF!!!
.I Cawf
formats the text from the input \fIfile\fR(s)
(standard input if none)
in an approximation of \*(Nr.
It comes closest to duplicating \*(Nr's
.B man
or
.B ms
macro package styles.
It has some limited support for \*(Nr's
.B me
macros.
.SH OPTIONS
Options must precede file names.
.TP
.BI \-c config
defines an alternate path to the device configuration file.
Normally the device configuration file is found in
.I device.cf
in the
.I cawf
library (see the
.B FILES
section).
.IP
The device configuration file contains device character strings for
selecting fonts and the bold or italic type faces.
See the
.B DEVICES
section for more information.
.TP
.BI \-d device
specifies the name of the output device.
There are three built\-in devices \- ANSI, NONE and NORMAL \- and
other devices may be defined in the device configuration file.
See the
.B DEVICES
section for more information.
.IP
The NORMAL device is the default.
.TP
.B \-e
directs
.I cawf
to issue an eject (FF or ^L) after the last page.
.TP
.BI \-f font
specifies the one font for the device, declared with the
.BI \-d device
option, that is to be used for the
entire document.
.I Font
must match a font associated with the device's stanza in the device
configuration file.
See the
.B DEVICES
section for more information.
.IP
No
.I font
may be specified for the built\-in devices ANSI, NONE or NORMAL.
.TP
.B \-h
requests a help display.
.TP
.BI \-m acro
specifies the macro file to be used.
The standard
.I cawf
distribution supplies macro files to support ``\-man'', ``\-me'' or ``\-ms''.
.I Cawf
finds a macro file by constructing its name from `m',
.I acro
and
.B .mac
\- e. g.,
.BI \-m an
is converted to
.BR man.mac .
The default directory for macro files is defined when
.I cawf
is compiled; it's \fIC:\\SYS\\LIB\\CAWF\fP in the MS\-DOS environment;
.I /usr/lib/cawf
in the UNIX environment.
.TP
file ...
are the names of files containing \*(Nr source text.
.SH NROFF COMPATIBILITY
.I Cawf
accepts the following raw \*(Nr requests:
.LP
	.\e"	.ad	.bp	.br	.ce	.de	.di	.ds
	.el	.fi	.fl	.ft	.i0	.ie	.if	.in
	.it	.lg	.li	.ll	.ls	.na	.ne	.nf
	.nr	.ns	.pl	.po	.ps	.rm	.rn	.rr
	.rs	.so	.sp	.ta	.ti	.tm	.tr
.LP
and the following in-text codes:
.ES
\e$	\e%	\e*	\e"	\ec	\ef	\eh	\ek
\en	\es	\ew
.EE
plus the full list of \*(Nr/\c
.I troff
special characters in
the original V7 \fItroff\fR manual.
.PP
Many restrictions are present; the behavior in general is a subset of
\*(Nr's.  Of particular note are the following:
.IP \(bu 2
The fully supported nroff request control character is the period.
There is limited support for the  non\-break, acute accent control
character.
.PT
Point sizes do not exist;
.B .ps
is ignored.
.PT
Special vertical spacing \- the
.B .vs
request included \- is ignored.
.PT
Conditionals cover only the numeric comparisons >, =, <, >= and <= on
.BR \en(.$ ;
string com\%par\%isons between a macro parameter and a literal;
.B n
(always true);
and
.BR t
(always false).
Only single line input is accepted from conditionals;
multi\-line input \- e.g., \\(\fIanything\fP\\) \- is not supported.
.PT
The handling of strings is generally primitive.
.IP \(bu
Horizontal motion via
.B \eh
must be supplied with a number register interpolation and must be
positive - e. g.,
.BR \ew\en(NN ,
where the value in NN is >= 0.
.IP \(bu
The
.B \ek
function is reliable only after TAB characters, so it is useful only
for measuring table positions.
.IP \(bu
The
.B .di
request only turns output on and off \- any macro name is ignored.
.IP \(bu
Expressions - e. g.,
.B .sp
- are reasonably general, but the
.BR | ,
.BR & ,
and
.BR :\&
operators do not exist, there must be white space between the end of the \*(Nr
function and the beginning of the expression, and 
.B \ew
requires that quote (') be used as the delimiters.
.B \ew
counts the characters inside the quotes and scales the result in ens,
so that, for example, \ew'\e(bu' equals 4n, and \ew'\e(bu'/1n equals 4.
.PT
The only acceptable count for the
.B .it
request is one,
and it is effective only with
.BR man ,
.B me
or
.B ms
macros.
.PT
The default scaling factor is `v' for the
.BR .ne ,
.BR .sp ,
and
.B .pl
raw \*(Nr requests; it is `u' for
.BR .nr ;
and `n' for
.BR .in ,
.BR .ll ,
.BR .ls ,
.BR .po ,
.BR .ta
and
.BR .ti .
(A different scaling factor may be specified with a trailing character.)
.PT
Some obsolete or meaningless requests \-
.BR .i0 ,
.B .lg
and
.B .li
\&\- are silently ignored.
.P
White space at the beginning of lines,
and embedded white space within lines is dealt with properly.
Sentence terminators at ends of lines are understood to imply
extra space afterward in filled lines.
Tabs are im\%plemented crudely and not exactly, although
usually they work as expected.
Hyphenation is done only at explicit hyphens, em-dashes, and \*(Nr
discretionary hyphens.
By default bold and italic characters are emulated with backspacing and
overprinting, but the
.B \-d
and
.B \-f
options, combined with the contents of the device configuration file,
may be used to generate special codes for bold and italic characters.
(See the
.B DEVICES
section for more information.)
.SH "MAN MACROS"
The
.B man
macro set replicates the full V7 manual macros,
plus a few semi-random oddballs.
The full list is:
.ES
\&.AT	.B	.BI	.BR	.BY	.DE	.DS	.DT	.HP	.I
\&.IB	.IP	.IR	.IX	.LP	.NB	.P	.PD	.PP	.RB
\&.RE	.RI	.RS	.SH	.SM	.SS	.TH	.TP	.UC
.EE
.B .BY
and
.B .NB
each take a single string argument (respectively, an indi\%cation of
authorship and a note about the status of the manual page) and arrange
to place it in the page footer.
.B .AT
and
.B .IX
do nothing.
.SH "ME MACROS"
The
.B me
macro subset has been derived from the
.I cawf
.B ms
macros by Chet Creider <[e-mail]>.
It includes:
.ES
\&.(l	.(q	.)l	.)q	.b	.bu	.i	.ip	.lp	.np
\&.pp	.r	.sh	.sm	.u	.uh
.EE
The .(l C and .(l L options are supported.
In addition, the .AB, .AE, .AI, .AU, .DA, .ND, .TL and .UX macros have
been retained from the
.B ms
set, and the .XP macro has been borrowed from the Berkeley additions to the
.B ms
macro set.
.SH "MS MACROS"
The
.B ms
macro set is a substantial subset of the V7 manuscript macros.
The macros are:
.ES
\&.AB	.AE	.AI	.AU	.B	.CD	.DA	.DE	.DS	.I
\&.ID	.IP	.LD	.LG	.LP	.ND	.NH	.NL	.PP	.QE
\&.QP	.QS	.R	.RE	.RP	.RS	.SH	.SM	.TL	.TP
\&.UL	.UX
.EE
Size changes are recognized but ignored, as are
.B .RP
and
.BR .ND .
.B .UL
just prints its argument in italics.
.BR .DS / .DE
does not do a keep,
nor do any of the other macros that normally imply keeps.
.LP
The
.B DY
string variable is available.
The
.BR PD ,
.BR PI ,
and
.BR LL
number registers exist and can be changed.
.SH "HEADERS AND FOOTERS"
.I Cawf
allows the placement of text into the five line header and
footer sections from the
.BR LH ,
.BR CH ,
.BR RF ,
.BR LF ,
.BR CF ,
and
.B RF
string variables, via the control of the
.B .^b
request:
.LP
.ta \w'.^b HF 0'u+3n
.nf
\&.^b fh 1	enables header string placement on the first page
\&.^b fh 0	disables header string placement on the first page
\&.^b HF 1	enables header/footer string placement
\&.^b HF 0	disables header/footer string placement
.fi