NROFF(1) Commands and Applications NROFF(1)
NAME
nroff - text processing typesetter
SYNOPSIS
nroff [ options ] file [...]
DESCRIPTION
nroff is a text processor and formatter based on the design provided in
"Software Tools" by Kernighan and Plauger. It has been modified to
closely resemble the Unix(tm) nroff command. The text and commands
found in the file(s) are processed to generate formatted text. Note
that one (and only one) of the files can be "-" which reads input from
stdin at that point. The output always goes to stdout which can be
redirected by the shell. The -o option lets you redirect error output
to the specified file rather than stderr. Debugging information always
goes to the file "nroff.dbg" and is generally used only for program de‐
velopment.
OPTIONS
The following command line options are available:
-d Set debug mode.
-h Hold before exit (Atari TOS only).
-m<name>
Process macro file tmac.<name>. Thus -man would cause the
file tmac.an to be loaded. Note that files processed in this
way should contain only macro definitions, no immediate output
should be generated from this file (see ENVIRONMENT).
-o<file>
Set error log file (default is stderr).
-raN Preset number register 'a' (single character) to N (decimal in‐
teger only).
-po<n> Shift output right n spaces (like .po).
-pn<n> Initial page number (like .pn).
-v Prints the version information to stdout.
+<n> Causes output to start with page n.
-<n> Causes output to stop after page n.
- Input from stdin.
ENVIRONMENT
nroff recognizes the following environment variables from the shell:
TMACDIR
An alternate directory to find the files tmac.* ("." for exam‐
ple). The default is c:\lib\tmac under TOS and /usr/lib/tmac
under Minix or Unix(tm).
TMPDIR An alternate directory to place any temporary files. The de‐
fault is the current directory. Note that nroff does not cur‐
rently use any temporary files.
COMMANDS
Commands typically are distinguished by a period in column one of the
input followed by a two character abbreviation for the command funtion.
The abbreviation may then be followed by an optional numeric or charac‐
ter argument. The numeric argument may be an absolute value such as
setting the right margin to a particular column, or the argument may be
preceded by a plus sign or a minus sign to indicate that the parameter
should be modified relative to a previous setting. The following com‐
mands are recognized (those marked "extension" are requests added to
the basic set provided by Unix(tm) nroff):
.ad Begin line adjustment. If fill mode is not on, adjustment is
defered until it is back on. If a type indicator is present,
the adjustment type is changed as follows:
Indicator Type
l adjust left margin only
r adjust right margin only
c center
b or n adjust both margins (default)
absent unchanged
.af Assign format to number register. The available formats are:
Format Numbering Sequence
1 0,1,2,3,4,...
001 000,001,002,...
i 0,i,ii,iii,iv,v,...
I 0,I,II,III,IV,V,...
a 0,a,b,...,z,aa,ab,...zz,aaa,...
A 0,A,B,...,Z,AA,AB,...ZZ,AAA,...
The second format above indicates that the field width, i.e.
number of digits, is specified by the number of digits in the
format type.
.bd Ignored by nroff.
.bo Causes the following lines of text to appear in boldface. The
optional argument specifies the number of lines to be typed in
boldface. Boldface and underlining are mutually exclusive fea‐
tures. The appearance of a boldface command will cause any un‐
derlining to cease.
.bp Causes succeeding text to appear at the top of a new page. The
optional argument specifies the page number for the new page.
The initial value is one and the default value is one more than
the previous page number.
.br Causes succeeding text to start on a new line at the current
left margin. There is no numeric argument for this command.
.bs Enables or disables the appearance of backspaces in the output
text. Underlining and boldface options are implemented by in‐
serting character - backspace - character combinations into the
output buffer. This is fine for devices which properly recog‐
nize the backspace character. Some printers, however, do not
recognize backspaces, so the option is provided to overprint one
line buffer with another. The first line buffer is terminated
with just a carriage return rather than the carriage return -
linefeed combination. A zero argument or no argument to the
backspace command removes backspaces from the output. A non-
zero argument leaves them in the output. The default is to re‐
move backspaces.
.cc Changes the nroff command character to that specified by the
character argument. If no argument is provided, the default is
a period (.).
.ce Causes the next line of text to appear centered on the output.
The optional argument specifies if more than one line is to be
centered.
.cs Ignored by nroff.
.cu Causes the next line(s) of text to be continuously underlined.
Unlike the underline command (see .ul) which underlines only al‐
phanumerics, continuous underlining underlines all printable
characters. The optional argument specifies the number of lines
of text to underlined. Any normal underlining or boldface com‐
mands currently in effect will be terminated.
.c2 Changes the nroff no break character to that specified by the
character argument. If no argument is provided, the default is
a single quote.
.de Causes all text and commands following to be used to define a
macro. The definition is terminated by a .en command or the de‐
fault .. terminator. The first two characters of the argument
following the .de command become the name of the new command.
It should be noted that upper and lower case arguments are con‐
sidered different. Thus, the commands .PP and .pp could define
two different macros. Care should be exercised since existing
commands may be redefined.
A macro may contain up to nine arguments. In the macro defini‐
tion, the placement of arguments is designated by the two char‐
acter sequences, $1, $2, ... $9. When the macro is invoked,
each argument of the macro command line is substituted for its
corresponding designator in the expansion. The first argument
of the macro command is substituted for the $1 in the expansion,
the second argument for the $2, and so forth. Arguments are
typically strings which do not contain blanks or tabs. If an
argument is to contain blanks, then it should be surrounded by
either single or double quotes.
.ds Define a string. To initiate the string with a blank or include
blanks in the string, start it with a single or double quite.
The string can contain other defined strings or number registers
as well as normal text. Strings are stored on the macro name
space.
.ec Changes the nroff escape character to that specified by the
character argument. If no argument is provided, the default is
a backslash.
.ef Specifies the text for the footer on even numbered pages. The
format is the same as for the footer command (see .fo).
.eh Specifies the text for the header on even numbered pages. The
format is the same as for the footer command (see .fo).
.en Designates the end of a macro definition.
.eo Turn the escape mechanism off.
.ex Exit nroff at this point in the processing. Ex forces all files
closed and flushes the output.
.fi Causes the input text to be rearranged or filled to obtain the
maximum word count possible between the previously set left and
right margins. No argument is expected.
.fl Causes the output buffer to be flushed immediately.
.fo Specifies text to be used for a footer. The footer text con‐
tains three strings seperated by a delimiter character. The
first non-blank character following the command is designated as
the delimiter. The first text string is left justified to the
current indentation value (specified by .in). The second string
is centered between the current indentation value and the cur‐
rent right margin value (specified by .rm). The third string is
right justified to the current right margin value. The absence
of footer text will result in the footer being printed as one
blank line. The presence of the page number character (set by
.pc) in the footer text results in the current page number being
inserted at that position. Multiple occurrances of the page
number character are allowed.
.ft Changes the current font. The choices are R (Times Roman), I
(Times Italic), B (Times Bold), S (math special), and P used to
request the previous font. P resets the next previous font to
be the one just changed, amounting to a swap.
.he Specifies text to be used for a header. The format is the same
as for the footer (see .fo).
.if Execute a command if the condition is true. Format is:
.if c command
.if !c command
.if N command
.if !N command
.if "str1"str2" command
.if !"str1"str2" command
Here c is a single letter: n (true if nroff), t (true if troff),
e (true if even page), or o (true if odd page). N is a numeri‐
cal experssion and can include operators +, -, *, /, % (mod), >,
<, >=, <=, = (or ==), & (and), or : (or). If the result is
greater than 0, the condition evaluates true. Numbers in the
expression can be either constants or contents of number regis‐
ters. Strings are tested using delimeter / or " only at this
time. Note that "block" conditionals like:
.if c \{\
...
...
... \}
are not yet supported. Also the .ie/.el conditional is not yet
supported.
.in Indents the left margin to the column value specified by the ar‐
gument. The default left margin is set to zero.
.ju Causes blanks to be inserted between words in a line of output
in order to align or justify the right margin. The default is
to justify.
.lg Ignored by nroff.
.ll Sets the current line length. The default is eighty.
.ls Sets the line spacing to the value specified by the argument.
The default is for single spacing.
.lt Set length of three-part titles. Line length and title length
are independent. Indents do not apply to titles but page off‐
sets do.
.m1 Specifies the number of lines in the header margin. This is the
space from the physical top of page to and including the header
text. A value of zero causes the header to not be printed. A
value of one causes the header to appear at the physical top of
page. Larger argument values cause the appropriate number of
blank lines to appear before the header is printed.
.m2 Specifies the number of blank lines to be printed between the
header line and the first line of the processed text.
.m3 Specifies the number of blank lines to be printed between the
last line of processed text and the footer line.
.m4 Specifies the number of lines in the footer margin. This com‐
mand affects the footer the same way the .m1 command affects the
header.
.mc Margin character. The first argument is the character to use,
the second is the distance to the right of the right margin to
place the margin character. Useful for change bars. No argu‐
ments turns the capability off. Note that with this nroff, the
margin character is always a single character only and this dis‐
tance is prefered to be in inches (e.g. 0.2i). The default
space is 0.2i (2 spaces).
.na Noadjust. Ajdustment is turned off; the right margin is ragged.
The adjustment type for .ad is not changed. Output line filling
still occurs if fill mode is on.
.ne Specifies a number of lines which should not be broken across a
page boundary. If the number of lines remaining on a page is
less than the value needed, then a new output page is started.
.nf Specifies that succeeding text should be printed without re‐
arrangement, or with no fill. No argument is expected.
.nj Specifies that no attempt should be made to align or justify the
right margin. No argument is expected.
.nr Causes the value of a number register to be set or modified. A
total of twenty-six number registers are available designated
\na through \nz (either upper or lower case is allowed). When
the sequence \nc is imbedded in the text, the current value of
number register c replaces the sequence, thus, such things as
paragraph numbering can be accomplished with relative ease.
.of Specifies the text for the footer on odd numbered pages. The
format is the same as the footer command (see .fo).
.oh Specifies the text for the header on odd numbered pages. The
format is the same as the footer command (see .fo).
.pc Specifies the page number character to be used in headers and
footers. The occurrance of this character in the header or
footer text results in the current page number being printed.
The default for this character is the percent sign (%).
.pl Specifies the page length or the number of lines per output
page. The default is sixty-six.
.pm Print macros. The names and sizes of the macros are printed to
stdout. This is useful when building a macro package to see how
much of the total namespace is consumed by the package.
.pn Changes the page number of the current page and all subsequent
pages to its argument. If no argument is given, the command is
ignored.
.po Specifies a page offset value. This allows the formatted text
to be shifted to the right by the number of spaces specified.
This feature may also be invoked by a switch on the command
line.
.ps Ignored by nroff.
.rr Removes a number register.
.so Causes input to be retrieved from the file specified by the com‐
mand's character string argument. The contents of the new file
are inserted into the output stream until an EOF is detected.
Processing of the original file is then resumed. Command nest‐
ing is allowed.
.sp Specifies a number of blank lines to be output before printing
the next line of text.
.ss Ignored by nroff.
.ti Temporarily alters the indentation or left margin value for a
single succeeding input line.
.tl Specifies text to be used for a page title. The format is the
same as for the header (see .he).
.ul Causes the next line(s) of text to be underlined. Unlike the
.cu command, this command causes only alphanumerics to be under‐
lined, skipping punctuation and white space. Underline and
boldface are mutually exclusive.
The following nroff commands, normally available, are currently not im‐
plemented in this version: .fp, .mk, .rt, .vs, .sv, .os, .ns, .rs, .am,
.as, .rm, .rn, .di, .da, .wh, .ch, .dt, .it, .em, .ta, .tc, .lc, .fc,
.lg, .uf, .tr, .nh, .hy, .hc, .hw, .nm, .nn, .ie, .el, .ev, .rd, .ex,
.nx, .pi, .tm, and .ig.
ESCAPE SEQUENCES
Escape sequences are used to access special characters (such as Greek
letters) which may be outside the normal printable ASCII character set.
The are also used to toggle certain actions such as font selection.
The escape sequences include:
\\ backslash character
\e printable version of escape character
\' accute accent (equivalent to \\(aa)
\` grave accent (equivalent to \\(ga)
\- minus sign
\. period
\<space> a single, unpaddable space
\0 digit-width space
\| 1\6em space (zero space in nroff)
\^ 1\12em space (zero space in nroff)
\& non-printing zero-width character
\" beginning of comment
\% default hyphenation character
\(xx special character named xx
\*x,\*(xx interpolate string x or xx
\fc font change (c = R,I,B,S,P)
\nx interpolate number register x
\t horizontal tab
The Atari ST (TOS) version of nroff includes the following special
characters. NOTE: THESE ARE NOT AVAILABLE UNDER Minix OR Unix(tm)!
\(co copyright
\(rg registered
\(tm trademark
\(12 1/2
\(14 1/4
\(p2 exponent 2
\(p3 exponent 3
\(pn exponent n
\(aa acute
\(ga grave
\(de degree
\(dg dagger
\(ct cent
\(bu bullet
\(pp paragraph
\(^g ring bell
\(ua up arrow
\(da dn arrow
\(-> rt arrow
\(<- lf arrow
\(di divide
\(sr sq root
\(== ==
\(>= >=
\(<= <=
\(+- +-
\(~= ~=
\(ap approx
\(no not
\(mo memeber
\(ca intersect
\(cu union
\(*a alpha
\(*b beta
\(*g gamma
\(*d delta
\(*s sigma
\(*p pi
\(*m mu
PREDEFINED GENERAL NUMBER REGISTERS
The following number registers are available for both reading and writ‐
ing. They are accessed with the \n(xx and \nx escape and can be set
with .nr:
% current page number
dw current day of the week (1-7)
dy current day of the month (1-31)
hh current hours (0-23)
ln current line number
mm current minutes (0-59)
mo current month (1-12)
ss current seconds (0-59)
yr last 2 digits of current year
The following number registers are available for reading only:
.$ number of args available in current macro
.A always 1 in nroff
.H available horizontal resolution
.T always 0 in nroff
.V available vertical resolution
.c number of lines read from current file
.f current font (1-4)
.i current indent
.l current line length
.o current page offset
.p current page length
.v current vertical spacing
NOTES
There are several missing features, notably diversions, traps, condi‐
tionals, all the hard stuff. This means you can't use some existing
macro packages (yet, I hope). There is no complete -ms and -me pack‐
ages as a result. The goal is to make this nroff work with all the
SunOS macro packages sometime before Unix becomes obsolete!
If you make additions to this code, please mail the changes to me so I
can make formal distributions.
BUGS
Undoubtedly more than I know about. Here are a few:
[GNO] This program uses recursion, which is Not a Good Thing on the
IIgs. The current implementation has been compiled to use 6k of stack,
which is entirely too much for a well behaved program of this size.
Stack checking has been left activated, so if you run out of stack the
worst you should get is an error message.
[GNO] The tmac.s macro package has not been reviewed recently and is
not believed to be generally usable.
[GNO] The nroff(1), man(1), and ms(1) man pages don´t completely follow
the GNO style guidelines.
The ability to perform numerical calculations on registers is not im‐
plemented.
All dimensional units are in em's or inches only.
Lines with multiple string instances (i.e. \*(xx) don't seem to work.
Lines with font changes (e.g. for italics) use vt52 escape sequences to
go to highlight mode. This should read termcap/terminfo to do it
right.
Some interpolations don't work properly.
The code uses statically allocated arrays for macros, strings, and reg‐
isters. This should be changed to dynamically allocated buffers or
write to intermediate files on small memory systems (i.e. Minix).
FILES
/lib/tmac/tmac.* predefined macros (see ENVIRONMENT)
nroff.dbg debugging output
stderr default error output stream
stdout output stream
AUTHOR
Various bug fixes for GNO by Devin Reade <gdr@gno.org>,
March 1997.
Adapted for Atari ST (TOS) and Minix by Bill Rosenkranz 11/89
net: rosenkra@convex.com
CIS: 71460,17
GENIE: W.ROSENKRANZ
Original author:
Stephen L. Browning
5723 North Parker Avenue
Indianapolis, Indiana 46220
HISTORY
Originally written in BDS C (by Stephen L. Browning?)
Adapted for standard C by W. N. Paul
Heavily hacked up to conform to the "real" nroff with numerous addi‐
tions by Bill Rosenkranz 11/89
Bug fixes (termcap) and Minix 1.5.5 compatibility by Wim 'Blue Baron'
van Dorst (wsincc@tuerc3.urc.tue.nl)
Modified for GNO v2.0.6 by Devin Reade.
VERSION
This manual page documents nroff version 1.2.1.
RECOMMENDATIONS
I envisioned this rather limited version as a way of formatting man
pages for my Atari ST system. It works just fine for that. The man
macro package is certainly adequate for that purpose. However, it
would be nice to have more. I suggest you limit yourself to things
which would port easily to other environments. All the man macros
available here should port without effort to a more complete Unix(tm)
environment.
nroff as it stands can certainly be useful. I recommend you don't use
the commands marked "extension". Study the source for the man pages
nroff(1), ms(7), and man(7) as well as the macro packages (tmac.an and
tmac.s) and the examples to find out the quirks. Some things may not
quite work like they do under Unix(tm), but it is fairly close for what
is here.
REFERENCES
This document briefly describes the workings of nroff. It is certainly
not the definitive work on text processing. I suggest you go out and
get a good book (there are several on the market) or refer to the
Unix(tm) manuals for more help. nroff is just like a compiler and is
much more complicated than (say) the C language which only has a hand‐
ful of rules and is much more thoroughly documented.
REQUEST SUMMARY
The following table summarizes the nroff requests currently available:
Request Form Initial Default Notes Explanation
-------------- ------- ------- ------- ----------------------
Font and Character Size Control
.ps +-N 10pt prev E point size (ignored)
.ss N 12/36em ignored E space size (ignored)
.cs F N M off - P constant space mode (ign)
.bd F N off - P embolden font F (ignored)
.bd S F N off - P embolden special font
.ft F Roman prev E change to font F
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 1000) . pl +(320u - 1000u + 1v)
Page Control
.pl +-N 11in 11in v page length
.bp +-N N=1 - B,v eject page
.pn +-N N=1 ignored - next page number N
.po +-N 0 prev v page offset
.ne N - N=1V D,v need N vertical space
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 560) . pl +(320u - 560u + 1v)
Text Filling, Adjusting, and Centering
.br - - B break
.fi fill - B,E fill mode
.nf fill - B,E no fill or adjust
.ad c adj,both adjust E adjust output, mode c
.na adjust - E no adjust
.ce N off N=1 B,E center N lines
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 80) . pl +(320u - 80u + 1v)
Vertical Spacing
.ls N N=1 prev E output N-1 Vs
.sp N - N=1V B,v space vertical
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 2560) . pl +(320u - 2560u + 1v)
Line Length and Indenting
.ll +-N 6.5i prev E,m line length
.in +-N N=0 prev B,E,m indent
.ti +-N - ignored B,E,m temporary indent
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 2200) . pl +(320u - 2200u + 1v)
Macros, Strings, Diversions, and Position Traps
.de xx yy - .yy=.. - define macro xx
.ds xx str - ignored - define string xx
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 1880) . pl +(320u - 1880u + 1v)
Number Registers
.nr R +-N M - u define and set num reg
.af R c arabic - - assign format to reg
.rr R - - - remove register
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 1520) . pl +(320u - 1520u + 1v)
I/O Conventions and Character Translation
.ec c - set escape char
.eo on - - turn off escape mech
.lg N - - - ligature mode (ignored)
.ul N off N=1 E underline N lines
.cu N off N=1 E cont. underline
.cc c . . E set control char
.c2 c ' ' E set nobreak control char
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 1000) . pl +(320u - 1000u + 1v)
Three-part Titles
.tl 'l'c'r' - - three-part title
.pc c % off - page number char
.lt +-N 6.5in prev E,m length of title
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 640) . pl +(320u - 640u + 1v)
Conditional Acceptence of Input
.if c cmd - - if c true, accept cmd
.if !c cmd - - if c false, accept cmd
.if N cmd - - if N > 0, accept cmd
.if !N cmd - - if N <= 0, accept cmd
.if "s1"s2" cmd - - if strings same, accept cmd
.if !"s1"s2" cmd - - if strings differ, accept cmd
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 160) . pl +(320u - 160u + 1v)
Input/Output File Switching
.so filename - - switch source file
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 2680) . pl +(320u - 2680u + 1v)
Miscellaneous
.mc c N - off E,m margin char c, seperation N
.pm t - all - print macro names
.fl - - B flush output buffer
.ie 1 . nr an-ne (v;4)
.el . nr an-ne 1v
.if (320 >= 2320) . pl +(320u - 2320u + 1v)
Notes
B causes a break
D mode or parameters associated with current diversion level
E relevant parameters are a part of the current environment
O must stay in effect until logical output
P mode must be still or again in effect at time of physical output
v,p,m,u default scale indicators
GNO 19 October 1997 NROFF(1)
Man(1) output converted with
man2html