SysIII/usr/src/man/docs/troff/add1

.br
.rs
.S 12 14
.sp 3
.ce 50
.B "Addendum to the"
.br
.I "N\s-2ROFF/TROFF\s+2 User's Manual"
.br
April 1980
.ce 0
.S 10 12
.sp 2
.I Note:
This addendum supercedes the previous two addenda to the
.I "nroff/troff User's Manual"
by
J.\ F.\ Ossanna,
dated October 11, 1976.
.SP 2
.H 1 "Command Line Options"
.HU "Removed Options"
.VL 1i
.LI \fB+\fIn\fR,\ \fB\-\fIn\fR
Use the \fB\-o\fR option instead.
.LE
.HU "Modified Options"
.VL 1i
.LI \fB\-s\fIn\fR
As well as stopping the output every \fIn\fR pages, this option also
causes the bell control character to be output to the terminal when stopping between pages.
(in \fItroff\fR, a message, ``page stop'', is output
to the terminal).
.LE
.HU "Additional Options"
.VL 1i
.LI \fB\-h\fR
.RI ( nroff \ only)
Use output tabs during horizontal spacing to speed up output as well
as to reduce output byte count.
Device tabs settings are assumed to be every 8 nominal character widths.
The default settings of input (logical) tabs is also initialized
to every 8 nominal character widths.
.LI \fB\-z\fR
Efficiently suppresses formatted output.
Only message output will occur (from
.B .tm
requests and diagnostics).
.LI \fB\-c\fIname\fR
Use the compacted version of macro package
.I name ,
if it exists.
If it doesn't,
.I nroff/troff
will try the equivalent ``\fB\-m\fIname\fR'' option instead.
This option should be used instead of \fB-m\fR because it makes
.I nroff/troff
execute significantly faster.
.LI \fB\-k\fIname\fR
Produce a compacted macro package from this invocation of
.I nroff/troff .
This option has no effect if no \fB.co\fR request is used in the
.I nroff/troff
input.
Otherwise, the compacted output is produced in files
.BI d. name
and
.BI t. name.
.LI \fB\-u\fIn\fR
.RI ( nroff \ only)
Set the emboldening factor (number of character overstrikes in \fInroff\fR)
for the third font position
(bold) to be \fIn\fR (zero if \fIn\fR is missing).
.LE
.H 1 "Requests"
.HU "Removed Requests"
.VL 1i
.LI \fB.li\fR
The transparent input mode request has been removed.
.LE
.HU "Modified Requests"
.VL 1i
.LI \fB.ad\ \fIc\fR
The adjustment type indicator \fIc\fR may now also be a number obtained from the
``\fB.j\fR'' register (see ``Additional Predefined Number Registers'' below).
.LI \fB.so\fI\ name\fR
The contents of file
.I name
will be interpolated at the point the \fB.so\fR request is encountered.
Previously, the interpolation was done upon return to the file-reading
input level.
.LI \fB.bd\fR
The emboldening request now works in
.I nroff ,
and causes overprinting of bold characters.
The default setting for font position 3 (the bold
font) is 3 (causing each bold character to be printed 4 times in
the same position).
The \fB\-u\fR command line option may be used to change the emboldening
factor for the bold font.
.LE
.HU "Additional Requests"
.VL 1i
.LI \fB.ab\ \fItext\fR
Prints
.I text
on the message output and terminates without further processing.
If
.I text
is missing, ``User Abort.'' is printed.
This request does
.I not
cause a break.
The output buffer is flushed.
.LI \fB.co\fR
If the
.BI \-k name
command line option was given, compact the current state of
.I nroff/troff .
If the
.BI \-k name
wasn't used, \fB.co\fR has no effect.
.LI \fB.!\ \fIcmd\ args\fR
The UNIX\*(Tm command
.I cmd
is executed and its output becomes
.I nroff/troff
input.
The standard input for
.I cmd
is closed.
.LE
.H 1 "Additional Predefined Number Registers"
.VL 1i
.LI \fB.k\fR
Read-only.
Contains the horizontal size of the text portion (without indent)
of the current partially-collected output line,
if any, in the current environment.
.LI \fB.j\fR
Read-only.
Indicates the current adjustment mode and type.
Can be saved and later given to the
.B .ad
request to restore a previous mode.
.LI \fB.P\fR
Read-only.
Contains the value 1 if the current page is being printed, and is zero
otherwise, i.e., if the current page did
.I not
appear in the \fB\-o\fR option list.
.LI \fB.L\fR
Read-only.
Contains the current line-spacing parameter (the value of the most recent
.B .ls
request).
.LI \fBc.\fR
Provides general register access to the input line-number in the current
input file.
Contains the same value as the read-only ``\fB.c\fR'' register.
.LI \fB.R\fR
Number of number registers that remain available for use.
.LI \fB.b\fR
Emboldening factor of the current font (\fInroff\fR and \fItroff\fR).
.LE
.H 1 "Additional Escape Sequences"
.VL 1i
.LI \fB\ej\fIx\fR,\fB\ej(\fIxx\fR
Mark the current horizontal output position in register
.I x \ or\  xx .
.LI \fB\eg\fIx\fR,\fB\eg(\fIxx\fR
Return the
.B .af -type
format of the register
.I x \ or\  xx .
Returns nothing if
.I x \ ( xx )
has not yet been referenced.
.LE
.H 1 "New Feature \- Compacted Macros"
.AL A
.LI
.B "User Information"
.P
The time required to read a macro package by
.I nroff/troff
may be greatly lessened by using a pre-processed version of that
macro package, called ``compacted macros''.
The compacted version of a macro package is completely
equivalent to the non-compacted version, except that a compacted macro
package can not be read by the
.B .so
request.
.P
A compacted version of a macro package,
.I name ,
is used by the
.BI \-c name
command line option,
while the uncompacted version is used by the
.BI \-m name
option.
Because
.BI \-c name
defaults to
.BI \-m name
if the
.I name
macro package hasn't been compacted, the user should always use
.B \-c
rather than
.B \-m .
.P
The next
section describes how to build a compacted version of a macro package.
.LI
.B "Building a Compacted Macro Package"
.P
If one has a macro package and wishes to make a compacted version of it,
the following simple steps should be followed:
.AL 1
.LI
Separate the Compactable from Non-compactable Parts.
.P
Only the following
.I nroff/troff
entities can be compacted:
macro, string, diversion, number register and trap settings and definitions.
For example, the following are
.I not
compactable:
environment settings, end macro setting, or any commands
that interact (during package interpretation) with command line settings, like
a reference to \fB\enP\fR, which could be set on the command line).
.P
All the non-compactable material should be placed at the end of the
macro package, with a
.B .co
request separating the compactable from non-compactable parts:
.DS I
Compactable Material
	.
	.
	.
.B .co
Non-Compactable Material
	.
	.
	.
.DE
.P
The
.B .co
request indicates to
.I nroff/troff
when to compact its ``current'' internal state.
.LI
Produce Compacted Files.
.P
Once compactable and non-compactable segments have been set up
as above,
.I nroff/troff
may be run with the
.BI \-k name
option to build the compacted files.
.P
For example,
if the macro file produced by step 1 is called
.RB `` mac '',
then the following may be used to build the compacted files:
.DS I
.B "$ nroff -kmac mac"
or
.B "$ troff -kmac mac"
.R
.DE
.P
Each of these commands causes
.I nroff/troff
to create two files in the current directory,
.RB `` d.mac ''
and
.RB `` t.mac ''.
.LI
Install Compacted Files.
.P
The two compacted files produced in step 2 must be installed into the system
macro library
.RB ( /usr/lib/macros )
with the proper names.
.P
If the
files were produced by
.I nroff ,
.RB `` cmp.n. ''
must be prepended to their names.
If produced by
.I troff ,
.RB `` cmp.t. ''
must be prepended to their names.
.P
Still assuming that the macro package with which we are dealing is called
.B mac ,
the two
.RI ( nroff )
compacted files may be installed by:
.DS I
.B
$ cp d.mac /usr/lib/macros/cmp.n.d.mac
.sp .5
$ cp t.mac /usr/lib/macros/cmp.n.t.mac
.R
.DE
.LI
Install Non-compactable Segment.
.P
The non-compactable segment from the original
macro package must also be installed on the system as
.DS I
.B /usr/lib/macros/ucmp.[nt].\fIname\fB
.DE
where
.RB `` n ''
of
.B [nt]
means the
.I nroff
version, and
.RB `` t ''
means the
.I troff
version.
The non-compactable segment must be produced ``by hand'', for example, by using
the editor.
.P
Again using the
.B mac
package as an example, the following could be used to install the
.RI ( nroff )
non-compactable segment:
.DS I
.B
$ ed mac
/^\e.co$/+,$w /usr/lib/macros/ucmp.n.mac
.R
.DE
.LE
.LI
.B "Warnings"
.P
Compacted macro packages depend heavily on the particular version of
.I nroff/troff
that produced them.
This means that each package needs to be compacted separately by both
.I nroff
and
.I troff .
It also means that any compacted macro packages must be recompacted
when a new version of
.I nroff
or
.I troff
is installed.
.P
If
.I nroff/troff
discovers that a macro package was produced by a different version of
.I nroff/troff
than that attempting to read it, the
.B \-c
will be abandoned, and the equivalent
.B \-m
option attempted instead.
.P
If
.I nroff/troff
actually reads a compacted package that was produced by a different
version of
.I nroff/troff
(because the version number of
.I nroff/troff
was not updated),
very peculiar action will result.
.LE
.H 1 "Other New Features"
.AL A
.LI
.I nroff/troff
now accepts multiple \fB\-m\fR/\fB\-c\fR macro package requests
on the command line.
.LI
The ASCII
.B esc
and
.B bel
characters are treated as regular characters.
.LI
The third font position (bold) causes overprinting in
.I nroff .
.LI
Hyphenation is off by default.
.LE
.H 1 "Notable Changes"
.AL A
.LI
The conditionally accepted part of an
.B .ie
or
.B .if
request is now
.I completely
ignored if the test failed, rather than being read in copy mode,
as was previously the case.
.LI
The
.B .cu
request has been enhanced to provide up to about three lines
of continuously underlined text,
and the underlining is not lost when the
.B .cu
is used
inside a diversion.
.LE
.SP 1
.I "April 1980"