

nroff                        Command                        nroff




Text-formatting language

nnrrooffff [_o_p_t_i_o_n ...] [_f_i_l_e ...]

nnrrooffff   is  the   COHERENT  text-formatter   and  text-formatting
language.  By  embedding commands within  files of text,  you can
instruct  nnrrooffff 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.

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

***** nroff Input *****

nnrrooffff  processes each  _f_i_l_e,  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  nnrrooffff 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 nnrrooffff 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  nnrrooffff.   Four  types  of  commands  and  options  are
described: (1)  command line options; (2)  nnrrooffff's basic commands
(also called  _p_r_i_m_i_t_i_v_e_s); (3) escape sequences  that can be used
with nnrrooffff; and  (4) nnrrooffff'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d   Debug: print each request before execution.  This options is
     extremely useful when you are writing new macros.

-ff _n_a_m_e
     Write the temporary file in file _n_a_m_e.



COHERENT Lexicon                                           Page 1




nroff                        Command                        nroff



-kk   Keep: do not erase the temporary file.

-ii   Read from the standard input after reading the given _f_i_l_e_s.

-mm_n_a_m_e
     Include  the  macro  file  /uussrr/lliibb/ttmmaacc._n_a_m_e in  the  input
     stream.

-nn_N  Number the first page of output _N.

-rr_a_N Set number register _a to the value _N.

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

If the environmental variable NNRROOFFFF is set when nnrrooffff is invoked,
its  contents are  prefixed  to list  of command-line  arguments.
This let  you set commonly used options  once in the environment,
rather than having to retype them for each invocation of nnrrooffff.

***** Primitives *****

The following  gives the basic commands,  or _p_r_i_m_i_t_i_v_e_s, that are
built into nnrrooffff.  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  .bbrr, below),  the
latter does not.

.aabb _m_s_g
     Abort: print _m_s_g on the standard error and abort processing.

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

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

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


.aamm _X_X
     Append the following to macro _X_X. Used like .ddee, below.




COHERENT Lexicon                                           Page 2




nroff                        Command                        nroff



.aass _X_X
     Append the following to string _X_X. Used like .ddss, below.

.bbpp  Begin a new page.

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

.cc22 _c
     Set the  no-break control character to  _c. With no argument,
     reset it to the default apostrophe.

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

.ccee _N
     Center _N lines of text (default, one).

.cchh _X_X _N
     Change the  location of  the trap  for macro _X_X  to vertical
     position _N on the page.  Used like command .wwhh, below.

.ccoo _e_n_d_m_a_r_k
     Copy input directly to the output until _e_n_d_m_a_r_k is seen.  If
     no _e_n_d_m_a_r_k is given, copy until another .ccoo is seen.

.ccuu  Underline continuously.

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

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

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

.ddss _X _v_a_l_u_e
     Define string _X to have the given _v_a_l_u_e.

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

.eell _a_c_t_i_o_n
     Execute _a_c_t_i_o_n when the  test in an .iiee command fails.  This
     command must be used with an .iiee command.

.eemm _X_X
     Execute macro _X_X when processing is completed.



COHERENT Lexicon                                           Page 3




nroff                        Command                        nroff



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

.eevv _N
     Change  the environment.   When  followed by  0,  1, 2,  the
     command  _p_u_s_h_e_s  that  environment;  when  used  without  an
     argument,  the  command  _p_o_p_s  the present  environment  and
     returns to the previous environment.

.eexx  Exit from nnrrooffff without further ado.

.ffii  Enter fill mode.

.ffll  Flush; same as .bbrr.

.fftt _X
     Change the current font to  _X. nnrrooffff recognizes RR, BB, and II,
     for Roman, bold, and italic, respectively.

.iiee _c_o_n_d_i_t_i_o_n _a_c_t_i_o_n
     This command tests to see  if _c_o_n_d_i_t_i_o_n is true; if true, it
     then  executes  _a_c_t_i_o_n; otherwise,  it  performs the  action
     introduced by  an .eell primitive.  This  command must be used
     with the .eell command.

.iiff _c_o_n_d_i_t_i_o_n _a_c_t_i_o_n
     This command tests to see  if _c_o_n_d_i_t_i_o_n is true; if so, then
     _a_c_t_i_o_n  is  executed;  otherwise,  _a_c_t_i_o_n is  ignored.   The
     command .iiff  oo applies  if the page  number is odd,  and the
     command  .iiff ee  applies  if the  page number  is even.   The
     command .iiff nn applies if the text is processed by nnrrooffff, and
     the command .iiff tt applies if the text is processed by ttrrooffff.
     The command  .iiff ll applies  in landscape mode.   The command
     .iiff pp applies to  ttrrooffff PostScript mode.  Note that the last
     two conditions are  unique to the COHERENT implementation of
     nnrrooffff, and may not be portable to other implementations.

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

.iinn _N_X
     Change the normal indentation to  _N units of _X scale.  _X can
     be uu or ii, for  _m_a_c_h_i_n_e _u_n_i_t_s or _i_n_c_h_e_s, respectively.  If _N
     is used without _X, nnrrooffff assumes the indentation to be given
     in  number of  character-widths (in picas,  or tenths  of an
     inch).  Default indentation is zero.

.iitt _N _X_X
     Set an  input trap to  execute macro _X_X after  _N input lines
     (not counting request lines).

.llcc _c
     Set  the leader  dot  character to  _c. When  nnrrooffff sees  the
     escape sequence \aa, it fills space to the next tab stop with


COHERENT Lexicon                                           Page 4




nroff                        Command                        nroff



     the leader  dot character.  llcc with  no argument tells nnrrooffff
     to use spaces to fill leaders.

.llll _N_X
     Set the line length.  Used like the .iinn command, above.

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

.lltt _N_X
     Length of title.  Used like the .iinn command, above.

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

.nnee _N_X
     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i or  vv, for  inches or
     vertical  spaces,  respectively.  This  command  is used  in
     display  macros  and in  paragraph  macros  to help  prevent
     widows and orphans.

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

.nnhh  Turn off hyphenation.   nnrrooffff hyphenates according to built-
     in algorithms  that are  correct most  of the time,  but not
     always.

.nnrr _X _N_1 _N_2
     Set  number  register   _X  to  value  _N_1;  set  its  default
     increment/decrement  to _N_2.  For  example, .nnrr  XX  22 33  sets
     number register XX to 2, and sets its default increment to 3.

.nnss  No-space mode.

.nnxx _f_i_l_e
     Terminate  processing of  the current  input file  and begin
     processing _f_i_l_e instead.

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

.ppnn _N
     Set the page number to _N.

.ppoo _N_X
     Set the default page offset to  _N. The unit of measure _X can
     be set  to ii,  for inches.  The  default unit of  measure is


COHERENT Lexicon                                           Page 5




nroff                        Command                        nroff



     number of characters.

.rrbb _f_i_l_e
     Read binary: read the given _f_i_l_e and copy it directly to the
     output without processing.

.rrdd _p_r_o_m_p_t
     Read an insertion  from the standard input after issuing the
     given _p_r_o_m_p_t.

.rrff _X_X _Y_Y
     Rename font _X_X as _Y_Y.

.rrmm _X_X
     Remove macro or string _X_X.

.rrnn _X_X _Y_Y
     Change the name of a macro or string from _X_X to _Y_Y.

.rrrr _X
     Remove register _X.

.rrss  Restore normal space mode.

.ssoo _f_i_l_e
     Open _f_i_l_e,  read its contents,  and process them.   When the
     end of  _f_i_l_e is reached,  resume processing the  contents of
     the present file.

.sspp [|]_N_X
     Space down  _N. The unit of  measure _X can be  i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, .sspp |11.55ii means to
     move to  1.5 inches below  the top of the  page, whereas .sspp
     11.55ii means to move to 1.5 inches below the present position.

.ttaa _N_X ...
     Set the tab to _N. The unit of measure _X can be set to i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.

.ttcc _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, .ttcc  . .11ii fills tabs
     with dots spaced one-tenth of an inch apart.

.ttii _N_X
     Temporary indent; indent  only the next line.  Used like the


COHERENT Lexicon                                           Page 6




nroff                        Command                        nroff



     .iinn command, above.

.ttll '_l_e_f_t'_c_e_n_t_e_r'_r_i_g_h_t'
     Set  a three-part  title, with  _l_e_f_t  being set  flush left,
     _c_e_n_t_e_r being centered on the line, and _r_i_g_h_t 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.

.ttmm _m_e_s_s_a_g_e
     Print _m_e_s_s_a_g_e  on the standard error  device.  This is often
     used  with  .iiff   or  .iiee  commands  to  indicate  an  error
     condition.

.ttrr _x_y
     Translate character _x to _y on output.

.uull _N
     Underline the next _N lines.

.vvss _N_p
     Reset the  normal vertical spacing to _N  points pp. One point
     equals 1/72 of an inch; the default setting is 12 points, or
     1/6 of an inch.

.wwhh _N_X _a_c_t_i_o_n
     Set  a trap  to perform  _a_c_t_i_o_n 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i
     or vv, for  inches or number of vertical lines, respectively;
     the default unit of measure is vv.

***** Escape Sequences *****

The following  lists nnrrooffff's  escape sequences, or  commands that
suspend or work around the normal operation of nnrrooffff.  All escape
sequences are  introduced by  the _e_s_c_a_p_e _c_h_a_r_a_c_t_e_r,  normally the
backslash character `\'.

\(_x_x Print  special character  _x_x, as defined  by a  .ddcc request.
     nnrrooffff reads default  special character definitions from file
     /uussrr/lliibb/rrooffff/nnrrooffff/ssppeecciiaallss.rr.  For   example,  the  escape
     sequence \(<= prints the less-than-or-equal-to symbol <_.

\\   Print a  backslash character.  This  can be used  to print a
     literal backslash character  in the output text, or 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.

\&   Ignore what is normally a command string.

\$_N  Call macro argument _N.



COHERENT Lexicon                                           Page 7




nroff                        Command                        nroff



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

\*_S  Call string _S.

\*(_S_T
     Call string _S_T.

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

\ee   Print the escape character in the output text.

\ff_X  Set font to _X; this can  be either RR, II, BB, or PP, for Roman,
     _i_t_a_l_i_c, bboolldd, or previous font, respectively.

\hh'[|]_N_X'
     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i,  for inches; the default unit of measure
     is character-widths.  When  the optional vertical bar `|' is
     used, move to an absolute position on the line.  For example
     \hh'|11.55ii'  moves to  1.5  inches to  the right  of the  left
     margin, whereas  \hh'11.55ii' moves 1.5  inches to the  right of
     the current position.

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

\LL'_N_X'
     Draw a vertical line; used like \ll, above.

\nn_X  Read the value of number register _X.

\nn(_X_Y
     Read the value of number register _X_Y.

\oo'_c_h_a_r_s'
     Overstrike the given _c_h_a_r_s, centered on the widest.

\tt   Print a tab.

\vv'_N_X'
     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i  or  vv, for  inches or  vertical spaces
     (sixths  of an  inch),  respectively.  The  default unit  of
     measure is vv.

\ww'_a_r_g_u_m_e_n_t'
     Measure the width of _a_r_g_u_m_e_n_t.  For example


COHERENT Lexicon                                           Page 8




nroff                        Command                        nroff



             \w'stuff and nonsense'

     measures the width of the phrase ssttuuffff aanndd nnoonnsseennssee; or

             \w'\$1'

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

\XX_d_d Output the character with hexadecimal value _d_d, where _d_d are
     two hexadecimal digits.

\zz_c  Print character _c with zero width.

\<nneewwlliinnee>
     Ignore this <nneewwlliinnee> character.

\{   Begin conditional commands; used after an .iiff, an .iiee, or an
     .eell 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
nnrrooffff.  You can read or reset these registers to suit the need of
any special formats that you wish to devise.

.$  Number of arguments in a call to a macro.

%   Present page number.

ddyy  Day of the month, as set by COHERENT.

.ii  Present level of indentation.

.ll  Present line length.

mmoo  Month, as set by COHERENT.

.oo  Present page offset.

.pp  Page length.

yyrr  Year, as set by COHERENT.

***** Printer Configuration *****

nnrrooffff  reads several  files in  directory  /uussrr/lliibb/rrooffff/nnrrooffff to
find  printer-specific information.   It reads  special character


COHERENT Lexicon                                           Page 9




nroff                        Command                        nroff



definitions from  file ssppeecciiaallss.rr. If file  ffoonnttss.rr exists, nnrrooffff
reads  font information  from it;  nnrrooffff understands  only Roman,
bold and  italic fonts, but  .rrff requests may  define alternative
font  names.   If  file  .pprree  exists,  nnrrooffff copies  it  at  the
beginning of  the output.  If file .ppoosstt  exists, nnrrooffff copies it
at the  end of  the output.  In  landscape mode, nnrrooffff  looks for
files  .pprree_llaanndd and  .ppoosstt_llaanndd instead.   You can  change these
files as  desired to  include printer-specific commands  in nnrrooffff
output.

***** Miscellaneous *****

The -mmss macro package is kept in file /uussrr/lliibb/ttmmaacc.s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  nnrrooffff, which  is  included  with this  manual,
provides  a detailed  introduction to  nnrrooffff. Error  messages for
nnrrooffff appear in the appendix to this manual.

***** Files *****

/ttmmpp/rrooff* -- Temporary files
/uussrr/lliibb/ttmmaacc.* -- Standard macro packages
/uussrr/lliibb/rrooffff/nnrrooffff/ -- Support files directory
/uussrr/lliibb/rrooffff/nnrrooffff/.pprree --  Output prefix
/uussrr/lliibb/rrooffff/nnrrooffff/.pprree_llaanndd -- Output prefix, landscape mode
/uussrr/lliibb/rrooffff/nnrrooffff/.ppoosstt -- Output suffix
/uussrr/lliibb/rrooffff/nnrrooffff/.ppoosstt_llaanndd -- Output suffix, landscape mode
/uussrr/lliibb/rrooffff/nnrrooffff/ffoonnttss.rr -- Alternative font name definitions
/uussrr/lliibb/rrooffff/nnrrooffff/ssppeecciiaallss.rr -- Special character definitions

***** See Also *****

ccooll, ccoommmmaannddss, ddeerrooffff, mmaann, mmss, ttrrooffff
_n_r_o_f_f, _T_h_e _T_e_x_t-_F_o_r_m_a_t_t_i_n_g _L_a_n_g_u_a_g_e, tutorial




















COHERENT Lexicon                                          Page 10


