edmoy@ucbopal.CC.Berkeley.ARPA (07/04/85)
For all of you who are interested in the enhanced ditroff that we run
at the UCB computer center, the following is a copy of the Addendum
to the Nroff/Troff Users Manual that explains many of our changes, plus
the original ones in ditroff. This copy has been run through our new
nroff (which has similar enhancements) and then colcrt, so that
pagination is all messed up, but underlining and superscripts show
up and can be mailed safely.
Changes that aren't discussed there are (just off the top of my head):
1) All macro, string, diversion and number registers names are hashed.
Special character names are found with a binary search.
2) Multiple ranges are supported (for devices like the APS-Micro5, where
the 5-80 point size range is divided into 4 ranges, which don't scale up
linearly).
3) Each typesetter description table may have a set of characters defined
that ditroff may use to hyphenate lines. Thus, for each dash, we have
one name that is hyphenable, and one that isn't.
4) Strings and macros are now usually stored as characters rather than
tchar (4 bytes on a VAX), since they don't have font and size info.
5) Lots of bug fixes.
6) Some speed improvements.
And with this all, we have a version of ditroff, with all similar
functionality, that runs on a PDP (though we have to be careful with
the font table size, to prevent running out of core).
Let me repeat again, for those that missed the first message, that we
at Academic Computing Services are unable to distribute this software,
but we are talking with CSRG (the ones who distribute BSD UNIX) to
combine their version, which contains graphics enhancement for Gremlin,
with ours and distribute that (someday).
Edward Moy
Academic Computing Services
University of California
Berkeley, CA 94720
edmoy@ucbopal.APRA
ucbvax!ucbopal!edmoy
----- cut here ----------------------------------- cut here ----------
Addendum to the
-------- -- ---
NROFF/TROFF User's Manual
=> This addendum supersedes all previous addenda to this manual.
---- -------- ---------- --- -------- ------- -- ---- ------
0. Key
- ---
The changes made in NROFF and TROFF since the NROFF/TROFF User's Manual
----- ----- ---- - ------
was produced in October 1976 fall into three groups, here marked as fol-
lows:
(O) ``Old'' changes - a small group of changes described on a one-page
addendum dated May 15, 1977.
(D) Changes that form part of device-independent TROFF (ditroff), an
-------
improved version of NROFF/TROFF released by AT&T Bell Labs in the
early 1980's.
(C) Further changes made by UC Berkeley's Academic Computing Services
(ACS) and implemented on the central campus computer center
machines, maintained by Computer Facilities and Communications (CFC)
department.
In addition, this addendum includes a group of command-line options which
are unique to the CFC environment:
(Q) Options relating to the CFC system of queueing and output distribu-
tion.
Finally, there are a few items marked
(U) ``Undocumented'' - features that are not new, but are not mentioned
in the original manual or are incorrectly described there.
1. Command-Line Options
- ------- ---- -------
1.1. New Options
- - --- -------
-.cmd The NROFF/TROFF command .cmd is executed before normal process-
--- ---
ing and before any macro packages are read. If .cmd contains
---
spaces or other characters of significance to the shell, it
should be quoted. (C)
-bbox Specifies the box number in which the output is to be placed.
---
May 1985 - 1 -
NROFF/TROFF User's Manual
The use of box numbers is typesetter dependent. (Q)
-Fdir The -F option causes terminal information for NROFF and font
--- -
information for TROFF to be accessed from the directory dir
---
instead of the default /usr/ucb/lib/term (for NROFF) or
--- --- --- ----
/usr/ucb/lib/font/devname (for TROFF, where name is the output
---- ----
device name). (D, C)
-h (NROFF only) Causes output tabs to be used during horizontal
spacing to speed output and reduce output byte count. Device
tab 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. (O)
-Iident Use the string ident (which should be quoted if it contains
----- -----
spaces or other characters of significance to the shell) to
identify the typeset job. This string is used for confirmation
of enqueuing and on job completion. If not given, TROFF will
try to use the list of file(s) given it as the string, if
any. (Q)
-Mmailaddr
--------
Send mail to the mail address given in mailaddr rather than to
---- --------
the user who submitted the job. (Q)
-N Don't write enqueuing confirmation directly to terminal. Send
mail instead. (Q)
----
-Olist Directs trr to typeset only the specified pages. This is use-
---- ---
ful with the -S option. (Q)
-
-Sfilename
--------
Save the intermediate ASCII output in the file filename, while
--------
still typesetting (using the -Q or -V options). (Q)
- -
-Tname Specifies the output device for both NROFF and TROFF. The
----
default output devices are defined locally (currently Teletype
+
Corporation Model 37 for NROFF and Autologic APS-Micro5 for
TROFF). These defaults may be overriden by the environment
variable TROFF for TROFF and NROFF for NROFF (C), which may in
turn be overridden by the -T command-line option (D). The case
-
of letters used in the name argument is ignored (C).
----
-un Set the amount of embolding (see .bd command) on font position
- --
3 to n typesetter units. (D)
-
-V (TROFF only.) Produce intermediate ASCII output for the speci-
fied typesetter but tell trr (see -t below) to process it for
--- -
previewing on the Versatec V80 Printer-Plotter. A -V preview
-
uses the Versatec's Hershey type faces, similar to the Times
-------------------------
+
As of July 1, 1985, the APS-Micro5 replaced the
previous default device, the Graphics System C/A/T.
May 1985 - 2 -
NROFF/TROFF User's Manual
family but with somewhat bulkier characters than the photo-
typesetter fonts. Line and page breaks occur in the preview
exactly as they would on the typesetter. (Q)
-x Interpret NROFF/TROFF commands in expanded mode (see section 5
below). The environment variable EXPANDED, if defined, also
sets expanded mode. (C)
-z Process text, but suppress formatted output. Diagnostics and
messages from .tm and .ab requests will still be output and .sy
-- -- --
commands will still be executed. (O)
1.2. Modified Options
- - -------- -------
-s For TROFF only, the -s flag is ignored (the typesetting system
-
imposes its own stop count). (Q)
-t The TROFF command normally initiates two other processes. The
real text processing process sends its ASCII output (which is
in a device-independent format (D)) to the postproces-
sing/enqueuing process, trr. The -t option causes TROFF to
--- -
only call the real text processing process, so that the
device-independent output, which would be sent to the standard
output (D), may be stored in a file and later re-typeset using
trr. (Q)
---
-p, -g, +n
-
These options have been eliminated. (D)
2. Requests
- --------
2.1. New Requests
- - --- --------
Request Initial If No
------- ------- -- --
Form Value Argument Notes Explanation
---- ----- -------- ----- -----------
.ab text - - - Abort. Print text on the diagnostic out-
----
put (normally, the terminal) and ter-
minate without further processing. If
text is missing, the message ``User
----
Abort'' is printed. The output buffer is
flushed. (O)
.cf file - - - Copy file to output. Copies the contents
----
of file into the NROFF/TROFF output file
----
at this point, uninterpreted (U). For
TROFF, the contents of file should be
----
compatible with the form of TROFF ASCII
output if the results are to be
reasonable (D).
.kn kern off - E Kerning mode on. (Kerning means the
adjustment of inter-character spacing for
specific character-pairs.) If the kern-
ing entry for a character pair, as stored
in the width tables, is non-zero, the
character pair is kerned if this mode is
May 1985 - 3 -
NROFF/TROFF User's Manual
turned on. (C)
.nk kern off - E Kerning mode off. (C)
.im file - - - Input macro file. The input-macro com-
----
mand reads from file the macros, strings
----
and diversions stored there by the
output-macro command .om. (C)
--
.om file - - - Output macro file. The output-macro com-
----
mand writes to file the currently defined
----
macros, strings and diversions in a
binary form that can be quickly read back
in using the input-macro command
.im. (C)
--
.rv +N off previous E,m Start reverse-printing mode. Text is
--
printed from right-to-left across the
page. The right paper margin is set by
+N as measured from the current left
--
paper margin (page offset). A value of
zero for N restores the normal left-to-
-
right printing. (C)
.sy cmd - - - Execute a system command. The UNIX com-
mand cmd is executed (D), using the
---
current login shell (C). The standard
input for cmd is normally closed (D). If
---
the command line ends with the characters
``<<'', standard input is taken from the
following lines (read in copy mode), up
to (but not including) a line begining
with ``..''. If a name of a macro fol-
lows ``<<'', then standard input ter-
minates when the command ``.macroname''
---------
is encountered, and the macro is then
executed. (C) (The command `.!' was pre-
viously a synonym for .sy, but since !
--
is frequently used as a string name in
macro packages, this form has been
disabled (C).)
2.2. Modified Requests
- - -------- --------
.ad c The adjustment type indicator c may now be a number obtained
- -
from the .j register described in Section 4 below. (O)
-
.fp n F dir
- - ---
The .fp command now accepts a third argument that causes the
--
width table for the font to be loaded from directory dir (D).
---
A value of zero for n specifies the next available
-
position (C).
.ft F This command (or \fF and \f(FF) causes the font F, if not
- - -- -
currently mounted by default or by a previous command, to be
loaded in the next free font position. (D, C)
May 1985 - 4 -
NROFF/TROFF User's Manual
.fz This request (O) has been eliminated (D).
.ht N Sets the hyphenation threshold to N. This threshold, which is
- -
initially set to the number 160, is the limit above which a
calculated hyphenation point is considered acceptable. The
higher N, the less hyphenation will occur. (U)
-
.li Has been eliminated. (D)
.pi cmd This command, which causes the output to be piped into cmd
--- ---
instead of the standard output, now exists for TROFF as well as
NROFF. (D)
.po +N Default units are m, not v as stated. (U)
-- - -
.ps +N N may now contain a scale indicator (default is still p). The
-- -
point size used is that size greater than or equal to the value
of N, rounded to the nearest whole point size.
-
.so file If either file ends with the suffix ``.im'' (input macro) or if
---- ----
a file named file.im exists, and if this file is of the proper
----
format, a (fast) .im command is done on the file (otherwise, a
--
normal .so is done) (C). The contents of file are now interpo-
-- ----
lated at the point the .so request is encountered (O).
--
+
3. Escape Sequences
- ------ ---------
3.1. New Escape Sequences
- - --- ------ ---------
\#'expression'
----------
The numeric expression is evaluated and the result is available
----------
in-line. (C)
\+ This is a breakable, but unpaddable space. (C)
\?'expression'true'false'
---------- ---- -----
If expression, which may be a numeric expression or a string
----------
comparison (as in the .if command) is true, the entire escape
--
sequence is replaced with the sequence true, otherwise with
----
false. Both true and false may contain further \?
----- ---- ----- -
sequences. (D)
\D'c n1 n2 ...'
- -- --
This is the general form of a group of diagram-drawing com-
mands, which can be enlarged further. The character c speci-
-
fies the type of element to be drawn (see list below). The
parameters n1 n2 ... may be number or expression, and may
-- --
-------------------------
+
The character used as delimeters ('...' here) may
be any character not already within the delimeters and,
for safety, not part of a numerical expression (like +
and -). However, escape sequences using the same del-
imeters may be nested.
May 1985 - 5 -
NROFF/TROFF User's Manual
specify a unit scaling (default is m for horizontal and v for
- -
vertical parameters). The character c and the numerical param-
-
eters are separated by spaces. These requests are all ignored
by NROFF. (D)
\D'l dh dv'
-- --
Draw a line from the current position to a point dh to the
--
right and dv down.
--
\D'c d'
-
Draw a circle of diameter d with left side at the current
-
position.
\D'e d1 d2'
-- --
Draw an ellipse of horizontal diameter d1 and vertical
--
diameter d2, with left side at current position.
--
\D'a dh1 dv1 dh2 dv2'
--- --- --- ---
Draw an arc whose center is at dh1 to the right and dv1
--- ---
down from the current position. The arc extends from the
current position counterclockwise, until it intersects the
line (or an extension of the line) from the arc's center
to a point that is dh2 to the right of and dv2 down from
--- ---
the center. The final position after drawing the arc is
dh1+dh2 to the right and dv1+dv2 down from the initial
--- --- --- ---
position.
\D'~ dh1 dv1 dh2 dv2 ...'
--- --- --- ---
Draw a B-spline going from current position by dh1, dv1,
--- ---
then by dh2, dv2, then ... .
--- ---
\E This escape sequence can be used in place of the normal escape
character (usually a backslash \) at the beginning of another
-
escape sequence and will prevent this second sequence from
being interpreted in copy mode (if it normally was). It will
be interpreted only in non-copy mode, i.e., in normal text out-
put mode and in diversions. Thus, \nx is interpreted in copy
---
mode, while \Enx is not. (C)
----
\gx, \g(xx
- --
Return the format of register x or xx; return nothing if x or
- -- -
xx has not yet been referenced in a .nr, .af, \n or \k request,
-- -- -- -- --
or is read-only. The value returned can be saved and used
later in a .af request to restore a previous format. Inter-
--
preted in copy mode. (D)
\H'n' Character heights are set to the value n (the default scale
- -
factor is points (C)), without changing widths. A height of
the form +n is an increment on the current point size (not on
-- ---
previous height if this has been reset by an earlier \H); a
--
height of zero restores the height to the point size (C).
Ignored in NROFF, and effective in TROFF only if the output
device allows modification of height independent of width. (D)
May 1985 - 6 -
NROFF/TROFF User's Manual
\I This escape sequence can be used in place of the normal escape
character (usually a backslash \) at the beginning of another
-
escape sequence and will cause this second sequence to be
interpreted immediately (copymode or not). (C)
\Kx If kerning mode is turned on, treat the character x as the
- -
first character in a character pair for possible kerning with
the next occurring character. The character x does not print,
-
but is only used for possible kerning calculation. (C)
\P Output the last character saved with the ``\R'' command. (C)
\R Save the last printed character. This saved character can be
reissued with the ``\P'' command. (C)
o o
\S'n' Output is slanted n degrees (-180 < n < 180 ). Ignored in
- - - - -
NROFF, while the effect in TROFF depends on what slants, if
any, the output device can produce. (D).
\Tx If x is an alphanumeric character, this escape sequence returns
- -
0 if the character is a short lower case letter without a des-
cender (like e), 1, if the character has a descender (like y),
- -
2, if the character is tall and without a descender (like H)
-
and 3 if it is tall and has a descender. The number register
\n(ct is also affected. (C)
-- --
\~ This is a paddable, but unbreakable space. (C)
3.2. Modified Escape Sequences and Corrections to Documentation
- - -------- ------ --------- --- ----------- -- -------------
\! Transparent mode has been fixed, so it can not only carry code
transparently from diversions to file level (or to other diver-
sions), but also from file level to output. It may thus be
used to send commands to a postprocessor. (D)
\: This undocumented character of pre-ditroff NROFF/TROFF (non-
-------
printing unless translated) (U) has been eliminated in
ditroff (D).
-------
\jx This undocumented escape sequence of pre-ditroff NROFF/TROFF,
- -------
which stored in the register x (one-character only) the current
-
horizontal position on the output line (U) has been eliminated
------
in ditroff (D).
-------
\k This sequence can store its output in a two-character register
using \k(xx as well as in a one-character register using \kx.
-- -
Whichever form is used, the value found is also recorded in the
----
register hp. (U)
--
4. Predefined Number Registers and Strings
- ---------- ------ --------- --- -------
4.1. New Number Registers
- - --- ------ ---------
$$ Read-only. Contains the process-id of the NROFF/TROFF
May 1985 - 7 -
NROFF/TROFF User's Manual
process. (D)
.B Emboldening factor of the current font, as set by the .bd
--
command. (C)
.K Read-only. Set to 1 if kerning mode is turned on; 0
otherwise. (C)
.L Read-only. Contains the current line-spacing parameter, i.e.,
the value of the argument of the most recent .ls request. (O)
--
.M Read-only. For TROFF, if non-zero, contains the maximum print-
able page length in machine units. (C)
.O - Read-only. For TROFF, contains the initial value of the page
offset (see section 5.2). (C)
.P Read-only. Contains 1 if the current page is being printed, 0
otherwise, i.e., if the current page does not appear in the -o
--- -
option list. (O)
.R Count of number registers that remain available for use. (D)
.W Read-only. For TROFF, contains the printable paper width of
the typesetting device in machine units. (C)
.X Read-only. Set to 1 in expanded mode; 0 otherwise. (C)
.b Pre-line extra line-space from last printed line. This is
nonzero if a \x'N' with negative N occurred in that line. (C)
- -
.j Read-only. Indicates the current adjustment mode and type.
Can be saved and used later as the argument to the .ad request
--
(q.v.) to restore a previous adjustment mode. (O)
.k Read-only. Contains the horizontal size of the text portion
including the size of the current indent, if any) of the
current, partially-collected output line, if any, in the
------
current environment. When fill mode is in effect this text
portion does not include the current partially-collected word,
---
if any. (O)
c. Provides general register access to the input line-number in
the current input file. Contains the same value as the read-
only .c register. (O)
-
hp Contains the value returned by the most recent \k request. (U)
--
4.2. Modified Number Registers
- - -------- ------ ---------
.a This register now contains the post-line extra line-space of
the last printed line, as opposed to that of the last line in
which \x'N' was used. (C)
-
May 1985 - 8 -
NROFF/TROFF User's Manual
4.3. New String
- - --- ------
.T The string \*(.T contains the name of the NROFF/TROFF output
- -
device, e.g., 37 or aps (D). The name will be entirely in
-- ---
lower case (C).
5. Other Important Changes
- ----- --------- -------
1. For TROFF, the size of a basic machine unit is dependent on the
typesetter. Hence units such as inches, points, em's etc. should be
used whenever possible, so as to give consistent results on dif-
ferent typesetters. (D)
2. For TROFF, the initial page offset may not be 26/27 of an inch (as
it is for the C/A/T), but is that offset that will cause the left
margin to be one inch from the edge of the paper. This value may be
obtained from the \n(.O register. (C)
-- -
3. For TROFF, the number of fonts is not necessarily limited to four
(as on the C/A/T), but depends on the capabilities of the
typesetter. For typesetters that allow the loading of different
+
fonts , this can be accomplished either by an .fp command, or simply
--
by using the .ft or \f commands to switch to the desired font. (D)
-- --
4. There is now an expanded mode, obtainable by using -x on the command
-------- ---- -
line or by setting the EXPANDED environment variable to some non-
--------
null value. All macro, number register, string and diversion names
may be up to 8 characters long. Commands now may be called with a
longer synonym (see following table). Because of the longer,
variable-length names, spaces are now required to separate commands
and arguments (e.g., .nr XX 4, .nrXX 4, .nr XX4, etc. are no longer
equivalent).
Strings, number registers and fonts of any length name may be
called with \*[x..x], \n[x..x] and \f[x..x], respectively. Special
- - - - - -
characters may also be called with \[x..x]. The format of a number
- -
register may be accessed with \g[x..x], and the current input-line
- -
horizontal position may be recorded in register x..x with
- -
\k[x..x]. Size changes of any number of digits may be called with
- -
\s[x..x].
- -
While the standard (unexpanded mode) forms of most escape
sequences will still function correctly, \sN is interpreted dif-
-
ferently in expanded mode. This form of the command accepts only
one digit in expanded mode, while in normal mode it accepts one or
two digits depending on whether the C/A/T phototypesetter has that
size. A new form has been added in expanded mode for two digits,
namely \s(NN. The number may be preceded with a plus or minus sign
--
to indicate a relative size change, e.g., \s+4 and \s(-10. (C)
-- - -- --
5. For TROFF, there are no longer specific fonts named R, I, B and S.
Instead, for the font change commands, these are synonymous with
-------------------------
+
The APS-Micro5 and the Versatec allow fonts to be
automatically loaded; the C/A/T does not.
May 1985 - 9 -
NROFF/TROFF User's Manual
Optional Expanded Mode Command Names
---------------------------------------------------------------
| ab | abort | eo | escoff | lt | lentitle | rm | rmmacro |
| ad | adjust | ev | environ | mc | margchar | rn | rename |
| af | assgnfmt | ex | exit | mk | mark | rr | rmreg |
| am | apndmac | fc | fieldch | na | noadjust | rs | restore |
| as | apndstr | fi | fill | ne | need | rt | return |
| bd | bold | fl | flush | nf | nofill | rv | reverse |
| bp | beginpg | fp | fontpos | nh | nohyphen | so | source |
| br | break | ft | font | nk | nokern | sp | space |
| c2 | ctrlchr2 | hc | hyphchar | nm | numlin | ss | spsize |
| cc | ctrlchr | ht | hyphthr | nn | nonumlin | sv | save |
| ce | center | hw | hyphword | nr | numreg | sy | system |
| cf | copyfile | hy | hyphen | ns | nospace | ta | tab |
| ch | chngtrap | ie | ifelse | nx | nextfile | tc | tabchar |
| cs | constsp | if | if | om | outmacro | ti | tempind |
| cu | contul | ig | ignore | os | outsave | tl | title |
| da | divapnd | im | inmacro | pc | pagechar | tm | termmesg|
| de | define | in | indent | pi | pipe | tr | translat|
| di | divert | it | inptrap | pl | pagelen | uf | ulfont |
| ds | defstr | kn | kern | pm | prmacro | ul | underln |
| dt | divtrap | lc | leadchar | pn | pagenum | vs | vertsp |
| ec | escchar | lg | ligature | po | pgoffset | wh | when |
| el | else | ll | linelen | ps | ptsize | | |
| em | endmacro | ls | linesp | rd | read | | |
---------------------------------------------------------------
whatever is mounted on font positions 1, 2, 3 and n, where n is the
font position of the (first) mounted special font. For the .fp com-
--
mand, R, I, B and S may be used for the first argument (font posi-
tion) but not for the second (font name). Thus .fp I hI is valid
-- - --
(on a device where hI is a valid font name), but .fp 3 B is
-- -- - -
not. (C)
6. NROFF/TROFF command names cannot be used, accidently or otherwise,
as names of strings, macros or diversions. However, they can be
renamed (with the .rn command) and then the original name may be
--
used. (C)
7. The number of environments has been increased from 3 to 5. Since
most macro packages use environments 1 and 2 in addition to the
standard environment 0, users may feel free to use the two new
environments, 3 and 4. (C)
8. The conditionally accepted part of an .ie or .if request is now com-
-- --
pletely ignored if the test fails, rather than being read in copy
mode. Thus there is no augmentation of number-registers if this
material contains \n+ calls. (However, material concealed using .ig
--- --
rather than .ie or .if is still read in copy mode.) (C)
-- --
9. If the current login shell is the csh, then .so, .nx, etc. will
--- -- --
interpret ~ and ~user in the path for the filename. (C)
----
May 1985 - 10 -