nroff -- Command

Text-formatting language
nroff [option ...] [file ...]

nroff  is the  COHERENT  text-formatter and  text-formatting language.   By
embedding commands  within files of text, you can  instruct nroff to format
text,  create paragraphs,  subheadings,  headers, footers,  and in  general
perform  all tasks  required to  format text  for the  printed page  or for
screen display.

nroff is designed to  be used with character-display terminals or monospace
printers.  The  related program troff  performs typeset-quality formatting,
suitable  for  printing  on the  Hewlett-Packard  LaserJet  printer or  any
printer for  which the PostScript  language has been  implemented.  troff's
formatting language is a superset of that used by nroff. Text that you have
encoded for  formatting by nroff will  work with troff, but  the reverse is
not  always true.   See the  Lexicon  entry on  troff for  information that
applies to troff alone.

nroff Input

nroff processes each file, or the  standard input if none is specified, and
prints the formatted result on the standard output.  The input must contain
formatting instructions as well as the text to be processed.

Basic nroff  commands provide for such things as  setting line length, page
length,  and  page  offset,  generating  vertical and  horizontal  motions,
indentation, filling and  adjusting output lines, and centering.  The great
flexibility  of nroff  lies  in its  acceptance of  user-defined macros  to
control almost  all formatting.  For example,  the formation of paragraphs,
header and footer areas, and footnotes  must all be implemented by the user
via macros.

The following  summarizes the  commands and options  that can be  used with
nroff. Four  types of commands and options are  described: (1) command line
options; (2)  nroff's basic commands  (also called primitives);  (3) escape
sequences that  can be  used with nroff;  and (4) nroff's  dedicated number
registers, and what information each one keeps.

Command-line Options

Command-line options may be listed in  any order on the command line.  They
are as follows:

-d   Debug: print each request before execution.  This options is extremely
     useful when you are writing new macros.

-f name
     Write the temporary file in file name.

-k   Keep: do not erase the temporary file.

-i   Read from the standard input after reading the given files.

-mname
     Include the macro file /usr/lib/tmac.name in the input stream.

-nN  Number the first page of output N.

-raN Set number register a to the value N.

-rabN
     Set number  register ab  to value N.   For obvious reasons,  ab cannot
     contain a digit.

-v   Return the number of your version.

-x   Do not eject to the bottom  of the last page when text ends.  Use this
     option when  you wish to use nroff interactively.   It, too, is useful
     when debugging macros.

nroff  appends the  contents  of the  environmental variable  NROFF to  the
beginning of the list of command-line arguments.  This let you set commonly
used  options once  in the  environment, rather than  retype them  for each
invocation of nroff.

Primitives

The following gives the basic  commands, or primitives, that are built into
nroff.  These  primitives can be  assembled into macros, or  can be written
directly into the text of your  document.  Commands may begin either with a
period  `.' or  with an  apostrophe; the  former causes  a break  (see .br,
below), the latter does not.

.ab msg
     Abort: print msg on the standard error and abort processing.

.ad [bclr]
     Enter adjust mode: that is, insert white space between words to create
     right-justified  output.  b  adjusts  for both  margins;  this is  the
     default.  c  adjusts and centers  on the line.  l  adjusts, flush with
     the left margin.  r adjusts, flush with the right margin.

.af R X
     Assign format X  to number register R. The assigned  format may be one
     of the following:

         1   Arabic numerals (default)
         i   Lower-case Roman numerals
         I   Upper-case Roman numerals
         a   Lower-case alphabetic characters
         A   Upper-case alphabetic characters

.am XX
     Append the following to macro XX. Used like .de, below.

.as XX
     Append the following to string XX. Used like .ds, below.

.bp  Begin a new page.

.br  Break;  print any  fraction of  a line  of text that  is in  the input
     buffer before reading new text.

.c2 c
     Set the no-break control character to c. With no argument, reset it to
     the default character, which is the apostrophe.

.cc c
     Set the normal  control character to c. With no  argument, reset it to
     the default character, which is the period.

.ce N
     Center N lines of text (default, one).

.ch XX N
     Change the location of the trap for macro XX to vertical position N on
     the page.  Used like command .wh, below.

.co endmark
     Copy  input directly  to  the output  until  endmark is  seen.  If  no
     endmark is given, copy until another .co is seen.

.cu N
     Underline the  next N lines.  When used without  an argument, one line
     is underlined.  The instruction

         .cu 0

     turns off  underlining.  Note that  unlike the UNIX  version of nroff,
     .cu does  not perform continuous  underlining -- it  underlines words,
     but not spaces.

.da X
     Divert  and append  the following  text into macro  X. A  diversion is
     ended by a .da command that has no argument.

.de X
     Define macro X. The macro definition  is ended by a line that contains
     only two periods ``..''.

.di X
     Divert the  following text into macro  X. Diversion is ended  by a .di
     command that has no argument.

.ds X value
     Define string X to have the given value.

.ec c
     Set  the escape  characer to  c.  With no  argument, reset  it to  the
     default backslash character `\'.

.el action
     Execute action  when the test  in an .ie command  fails.  This command
     must be used with an .ie command.

.em XX
     Execute macro XX when processing is completed.

.eo  Escape off: turn off special handling of all escape sequences.

.ev N
     Change the environment.  When followed  by 0, 1, 2, the command pushes
     that environment; when used  without an argument, the command pops the
     present environment and returns to the previous environment.

.ex  Exit from nroff without further ado.

.fi  Enter fill mode.

.fl  Flush; same as .br.

.ft X
     Change the current font to X. nroff recognizes R, B, and I, for Roman,
     bold, and italic, respectively.

.ie condition action
     This  command tests  to see  if condition  is true;  if true,  it then
     executes action;  otherwise, it performs  the action introduced  by an
     .el primitive.  This command must be used with the .el command.

.if condition action
     This command tests to see if  condition is true; if so, then action is
     executed; otherwise, action is  ignored.  The command .if o applies if
     the page  number is  odd, and  the command .if  e applies if  the page
     number is even.  The command .if n applies if the text is processed by
     nroff,  and the  command .if  t applies  if the  text is  processed by
     troff. The command .if l applies in landscape mode.  The command .if p
     applies to  troff PostScript mode.  Note that  the last two conditions
     are unique  to the  COHERENT implementation of  nroff, and may  not be
     portable to other implementations.

.ig X
     Ignore all  input until macro .X  is called; if no  argument is given,
     ignore input until two periods ``..''.

.in NX
     Change the normal indentation to N units of X scale.  X can be u or i,
     for machine  units or inches,  respectively.  If N is  used without X,
     nroff  assumes the  indentation to  be given  in number  of character-
     widths (in picas, or tenths of an inch).  Default indentation is zero.

.it N XX
     Set  an input  trap  to execute  macro  XX after  N  input lines  (not
     counting request lines).

.lc c
     Set the leader dot character to c. When nroff sees the escape sequence
     \a, it fills space to the next tab stop with the leader dot character.
     lc with no argument tells nroff to use spaces to fill leaders.

.ll NX
     Set the line length.  Used like the .in command, above.

.ls X
     Leave  spaces;  insert X  vertical  spaces after  each  line of  text.
     Default is zero.

.lt NX
     Length of title.  Used like the .in command, above.

.na  Enter no-adjust mode.  Line lengths are not changed.

.ne NX
     Confirm that  at least N  portions of X  units of measure  of vertical
     space are needed before the next trap.  If this amount of space is not
     available, then move the text to the top of the next page.  X can be i
     or v,  for inches or  vertical spaces, respectively.   This command is
     used in display macros and  in paragraph macros to help prevent widows
     and orphans.

.nf  Enter no-fill mode; no right justification is performed, although line
     lengths are changed to approximate uniform line length.

.nh  Turn  off   hyphenation.   nroff  hyphenates   according  to  built-in
     algorithms that are correct most of the time, but not always.

.nr X N1 N2
     Set number register X to value N1; set its default increment/decrement
     to N2.  For example, .nr X  2 3 sets number register X  to 2, and sets
     its default increment to 3.

     The basic  unit of measurement for  nroff 1/120th of an  inch; this is
     also called  the machine unit.  It  is indicated by the  suffix u to a
     measurement.   Unless  otherwise  stated,  all number  registers  that
     information  about a  page  holds that  information  in nroff  machine
     units.

     Other units of measure convert into nroff units as follows:

          inch:                         1i = 120u
          vertical line space:          1v = 20u
          centimeter:                   1c = 47u
          em:                           1m = 12u
          en:                           1n = 12u
          pica:                         1P = 20u
          point:                        1p = 1u

.ns  No-space mode.

.nx file
     Terminate processing  of the current  input file and  begin processing
     file instead.

.pl NX
     Set the  page length to N.  The unit of measure  X can be V  or i, for
     vertical  spaces (sixths  of an  inch)  or inches,  respectively.  The
     default unit of measure is vertical spaces.

.pn N
     Set the page number to N.

.po NX
     Set the default page offset to  N. The unit of measure X can be set to
     i, for inches.  The default unit of measure is number of characters.

.rb file
     Read binary:  read the given file  and copy it directly  to the output
     without processing.

.rd prompt
     Read  an insertion  from the  standard input  after issuing  the given
     prompt.

.rf XX YY
     Rename font XX as YY. For example, to have calls to font K remapped to
     Roman font, use the call:

         .rf K R

.rm XX
     Remove macro or string XX.

.rn XX YY
     Change the name of a macro or string from XX to YY.

.rr X
     Remove register X.

.rs  Restore normal space mode.

.so file
     Open file, read its contents, and  process them.  When the end of file
     is reached, resume processing the contents of the present file.

.sp [|]NX
     Space down  N. The unit  of measure X  can be i, for  inches, with the
     default unit  of measure being vertical spaces, or  sixths of an inch.
     The optional  vertical bar `|' indicates that N  is an absolute value;
     for example,  .sp |1.5i means to  move to 1.5 inches  below the top of
     the  page, whereas  .sp 1.5i  means to  move to  1.5 inches  below the
     present position.

.sy command
     Execute command  under the shell.  Please note  that this primitive is
     non-standard.  Macros  that use it cannot  be formatted under standard
     AT&T nroff.

.ta NX ...
     Set the tab  to N. The unit of measure X  can be set to i, for inches;
     the default unit  of measure is number of characters,  or tenths of an
     inch.  A tab  setting, of course, is for an  absolute, not a relative,
     value.  If more than one tab setting is defined, the first defines the
     first  tabulation character  on a  text line,  the second  defines the
     second  tabulation  character,  etc.   Any undefined  tabulations  are
     thrown away.

.tc X N
     Fill any unused space within  a tabulation field with the character X.
     If the optional N is present,  it specifies a width for the character;
     for example,  .tc . .1i  fills tabs with  dots spaced one-tenth  of an
     inch apart.

.ti NX
     Temporary  indent;  indent only  the  next line.   Used  like the  .in
     command, above.

.tl 'left'center'right'
     Set a  three-part title, with left being set  flush left, center being
     centered on the  line, and right being set flush  right.  Note the use
     of  the apostrophes  to separate  the fields;  the apostrophes  for an
     undefined  field must  still be  present,  or a  syntax error  will be
     generated.

.tm message
     Print message  on the standard error device.  This  is often used with
     .if or .ie commands to indicate an error condition.

.tr xy
     Translate character x to y on output.

.ul N
     This behaves the same as .cu.

.vs Np
     Reset the normal vertical spacing to N points p. One point equals 1/72
     of an inch.   The default setting one pica, which  equals is 12 points
     or 1/6 of an inch.

.wh NX action
     Set  a  trap to  perform  action  when point  N  is  reached on  every
     formatted page.  If  N is negative, it is measured  up from the bottom
     of the  page.  The  unit of  measure X may  be i  or v, for  inches or
     number of vertical lines, respectively; the default unit of measure is
     v.

Escape Sequences

The following  lists nroff's escape sequences, or  commands that suspend or
work  around  the normal  operation  of nroff.   Each  escape sequences  is
introduced by the escape character, normally the backslash character `\':

\(xx Print special character xx, as  defined by a .dc request.  nroff reads
     default      special     character      definitions     from      file
     /usr/lib/roff/nroff/specials.r.  For   example,  the  escape  sequence
     \(<= prints the less-than-or-equal-to symbol <=.

\.   Print a literal period.

\'   Print a literal apostrophe.  This should  be used in text that will be
     manipulated by the \w escape sequence or the .tl primitive.

\\   Delay interpretation of  a backslash character.  This normally is used
     to defer the  interpretation of a macro or string  from the time it is
     processed to the time that it is called.

\-   Print a minus sign.

\&amp;
     Ignore what is normally a command string.

\$N  Call macro argument N.

\''  Introduce a comment  within your text.  All text to  the right of this
     escape sequence  will be  ignored by  nroff.  This sequence  must read
     .\'' when used at the beginning of a line.

\*S  Call string S.

\*(ST
     Call string ST.

\a   Fill the space to the next tab stop with leader dots (normally `.').

\d   Move down  by one-half em (troff) or  one-half line (nroff).  Normally
     used to do crude subscripting, or  to undo the effect of the \u escape
     sequence.

\e   Print  the  escape  character  in  the  output  text  --  normally,  a
     backslash.

\fX  Set font  to X; this can  be either R, I, B, or  P, for Roman, italic,
     bold, or previous font, respectively.

\h'[|]NX'
     Move  horizontally by  N units  of X.  If N is  positive, move  to the
     right; if negative, move to the left.  The unit of measure X may be i,
     for inches;  the default unit of  measure is ems.  (One  em equals one
     pica, which is one-sixth of  an inch).  When the optional vertical bar
     `|' is  used, move to an  absolute position on the  line.  For example
     \h'|1.5i' moves to 1.5 inches to the right of the left margin, whereas
     \h'1.5i' moves 1.5 inches to the right of the current position.

\kx  Record the current vertical position into register x.

\l'NX'
     Draw a horizontal  line N units of X long.   The unit of measure X may
     be i, for inches; the default unit of measure is character-widths.

\L'NX'
     Draw a vertical line; used like \l, above.

\nX  Read the value of number register X.

\n(XY
     Read the value of number register XY.

\o'chars'
     Overstrike the given chars, centered on the widest.

\sN  Change the current size of the type to N points.

\s+N Increment the current point size by N points.

\s-N Decrement the current point size by N points.

\t   Print a tab.

\u   Move up  by one-half  em (troff)  or one-half line  (nroff).  Normally
     used to  do crude superscripting, or  to reverse the effect  of the \d
     escape sequence.

\v'NX'
     Vertical motion; move N units of X vertically.  If N is positive, move
     down; if negative, move up.  The  unit of measure X may be i or v, for
     inches  or vertical  spaces (sixths  of  an inch),  respectively.  The
     default unit of measure is v.

\w'argument'
     Measure the width of argument.  For example

         \w'stuff and nonsense'

     measures the width of the phrase stuff and nonsense; or

         \w'\$1'

     measures the  width of the first argument passed  to a macro, whatever
     that argument might happen  to be.  Therefore, the command .in \w'\$1'
     will indent a line by the width of argument 1.

\Xdd Output  the character  with  hexadecimal value  dd, where  dd are  two
     hexadecimal digits.   Users can use  this option to  encode characters
     that  are  not  part  of  the  English-language  character  set.   The
     hexadecimal values  to which characters map  depend upon the character
     set that  you (or your  printer) use.  Please note  nroff reserves the
     following values for its internal use:

          <Ctrl-SP>     X00Ignored
          <Ctrl-A> X01  Leader dots, same as ``\a''
          <Ctrl-I> X09  Tab, same as ``\t''
          <Ctrl-J> X10  Newline

     This escape sequence is unique to the COHERENT implementation of nroff
     and troff.  Code that uses  it will behave differently  when ported to
     other implementations.

\zc  Print character c with zero width.

\<newline>
     Ignore this <newline> character.

\{   Begin  conditional commands;  used after  an  .if, an  .ie, or  an .el
     command.

\{\  Begin conditional commands, and ignore the following carriage return.

\}   End conditional commands.

Dedicated Number Registers

The following lists the number registers that are predefined in nroff.  You
can read or  reset these registers to suit the  need of any special formats
that you wish to devise.

$$  Process identifier of the  current nroff process.  This usually is used
    with the primitive .sy to name temporary files.

.$  Number of arguments passed to a macro.

%   Present page number.

.c  Number of lines read from the  current input file.  This can be used to
    help set an input-line trap.

.d  Current vertical position in the current diversion.  If no diversion is
    opened,  this  register's  contents equal  those  of  the nl  register,
    described below.

dl  Maximum width of last completed diversion.

dn  Height of last completed diversion.

dw  Day of the week (one through seven; one indicates Sunday).

dy  Day of the month, as set by COHERENT.

.F  Name of input file being read.   This is very useful for printing error
    messages.  This  register applies  only the COHERENT  implementation of
    nroff. Code that uses it is not portable to other implementations.

.h  Vertical  position  of  the  current  line's  base-line.   This  number
    register gives  you the best idea of your  current vertical position on
    the page.

hp  Horizontal position on current input line.

.i  Present amount of indentation.

.j  Current type and mode of text adjustment.

.l  Present line length.

ln  Current line number in the output.

mo  Month, as set by COHERENT.

.n  Width of  the text portion of the previously  printed line.  Useful for
    underlining, shading, or otherwise modifying the previous line of text.
    For example

        \l'\n(.nu'

    draws a line under the previously printed line of text.

nl  Vertical position of the base-line of the last printed line of text.

.o  Present page offset.

.p  Page length.

.s  Size of the type currently being printed, in points.

sb  Depth to which  a string hangs below its base  line.  This is generated
    by the width function.

st  Height  to  which  a string  extends  above  its  base  line.  This  is
    generated by the width function.

.t  Distance to  the next trap.  Check  this register to see  if the object
    you wish to print on a page will fit.

.v  Size of a line, in points.  This is set by the vs primitive.

yr  Last two digits of the year, as set by COHERENT.

.z  Name of the current diversion.

Printer Configuration

nroff reads several files in directory /usr/lib/roff/nroff to find printer-
specific  information.  It  reads special  character definitions  from file
specials.r. If  file fonts.r exists, nroff reads  font information from it;
nroff understands  only Roman, bold and italic fonts,  but .rf requests may
define alternative font names.  If file .pre exists, nroff copies it at the
beginning of the output.  If file  .post exists, nroff copies it at the end
of  the output.   In landscape  mode, nroff looks  for files  .pre_land and
.post_land  instead.  You  can  change these  files as  desired to  include
printer-specific commands in nroff output.

Miscellaneous

The -ms macro  package is kept in file /usr/lib/tmac.s.  The macros in this
package  are  more  than  sufficient  for  most ordinary  text  processing.
Beginners should work through this macro package rather than trying to deal
at once with the basic program.

The  tutorial to  nroff, which  is  included with  this manual,  provides a
detailed  introduction to  nroff. Error  messages for  nroff appear  in the
appendix to this manual.

Files

/tmp/rof* -- Temporary files
/usr/lib/tmac.* -- Standard macro packages
/usr/lib/roff/nroff/ -- Support files directory
/usr/lib/roff/nroff/.pre --  Output prefix
/usr/lib/roff/nroff/.pre_land -- Output prefix, landscape mode
/usr/lib/roff/nroff/.post -- Output suffix
/usr/lib/roff/nroff/.post_land -- Output suffix, landscape mode
/usr/lib/roff/nroff/fonts.r -- Alternative font name definitions
/usr/lib/roff/nroff/specials.r -- Special character definitions

See Also

col,
commands,
deroff,
man,
ms,
printer,
troff
nroff, The Text-Formatting Language, tutorial

Diagnostics

nroff returns the following error messages.  Most are self-explanatory.

-f option requires file argument (fatal)
.bd not implemented yet
.co: unexpected EOF before string (error)
.dt not implemented yet
.el without .ie (error)
.fc not implemented yet
.hc not implemented yet
.hw not implemented yet
.hy not implemented yet

.ie nested more than N levels (error)
     The .ie/.el combination can be nested only 15 levels deep.

.ie without matching .el (error)
     Every .ie must be followed by an .el.

.lf: string, file ``string'' (error)
     troff could not load a font-width table from file string.

.lf: ``string'' is not a PCL font width table (error)
     troff expects  a PCL font-width table,  but file string is  not in the
     PCL font-width format.

.lf: ``string'' is not a PostScript font width table (error)
     troff expects a PostScript font-width table, but file string is not in
     the PostScript font-width format.

.lf: cannot load more than N fonts (error)
     troff has a  static limit on the number of  font-width tables that can
     be loaded at one time.

.lf: cannot open file ``string'' (error)
.lf: requires fontname and filename (error)
.nm not implemented yet
.nn not implemented yet
.pi not implemented yet
.rb: cannot open file string (error)
.rb: no file specified (error)
.rf: requires name and new name (error)

\} without matching \{ (error)
     Every \} must be preceded by a \{.

arguments too long (error)
attempted zero divide (error)
attempted zero modulus (error)
bad adjustment type (error)
bad argument reference (error)
bad directive N (fatal)
bad font N (fatal)
bad font N at dev_font, nfonts=N (fatal)
bad font N, nfonts=N (fatal)
bad pattern (fatal)
bad tab stop (error)
bad tab stop (error)

botch: fontname(N) (fatal)
     nroff cannot handle font N and must abort processing.

botch: swdmul=N psz=N swddiv=N (fatal)
     An undefined error has occurred within nroff. The printed numbers give
     the  value of  nroff's internal  registers.  If  such an  error occurs
     regularly when you process a given piece of text, please send the text
     in question and a copy of the error message to Mark Williams technical
     support.

bracket building not implemented yet
cannot create temp file (fatal)
cannot dehyphenate (fatal)

cannot end diversion (error)
     You attempted to close a diversion without first opening one.
cannot find current file (error)

cannot find font XX (error)
     Font XX  has not  been opened; therefore  [nt]roff cannot use  it.  To
     open a font, use the load-font primitive .lf.

cannot find font N (error)

cannot find register string (error)
     You attempted to read a  number register without first loading a value
     into it.

cannot open string (error)
cannot open file ``string'' (error)

cannot pop environment (error)
     You popped an environment without first pushing one.

cannot read environment (fatal)
cannot remove string (error)
cannot reopen temp file (fatal)
cannot write environment (fatal)
delimiter argument too large (error)
diversion buffer odd alignment (fatal)
environment does not exist (error)
environments stacked too deeply (error)
field with too large (error)
file ``string'' not found (error)
flushd -- current diversion null (fatal)
font position out of range (error)

fonts.r not found (fatal)
     nroff  and troff  read the  list  of fonts  to use  from a  file named
     fonts.r. If  you do not  have such a  file in your  current directory,
     nroff  and  troff  read   the  one  out  of  their  home  directories:
     /usr/lib/roff/nroff,            /usr/lib/roff/troff_pcl,            or
     /usr/lib/roff/troff_ps,  depending which  variety of  output  you have
     requested.  This error  message means that your current directory does
     not  hold a  file named  fonts.r,  and that  [nt]roff cannot  open the
     fonts.r file in its appropriate home directory.

illegal hex digit (error)
     The escape sequence \XNN prints a character by its literal hexadecimal
     value.  This  should be used  when processing characters  that are not
     normally  printable  on  the terminal  screen.   Digit  N  can be  the
     numerals `0' through `9', the  letters `a' through `f', or the letters
     `A' through `F'.  All other characters will trigger this error.

illegal option: string (fatal)

incomplete macro in trap (fatal)
     A trap has  jumped to a macro, but that  macro does not terminate, for
     whatever  reason.   Usually  this indicates  that  you  have opened  a
     diversion but failed to close it.

line buffer overflow (fatal)
no room for new font name XX (error)
out of space - memory string (fatal)
request 'string' not found (error)
section N of title too large (error)
special character XX not found (error)

syntax error (error)
     This message  any number of errors with your  nroff source.  Check the
     line number given in the message.

temporary file write error (fatal)
     nroff  cannot  write  a temporary  file,  for  whatever reason.   This
     usually indicates that you lack permission to write into the directory
     into which nroff is attempt to write its temporary files.

too many tab stops (error)
     nroff allows a maximum of nine  tab stops in one line.  It ignores all
     tab stops that exceed that limit.

unexpected end of file (fatal)
     This error indicates that nroff is in the middle of processing a macro
     when  the  file ends.   This  error  usually occurs  when  you open  a
     diversion and fail to close it.


unknown macro/register type N (fatal)
vertical line drawing not implemented yet (error)
word buffer overflow (fatal)

© 2012 by Stephen A. Ness