nnrrooffff -- Command

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.

_n_r_o_f_f _I_n_p_u_t
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.

_C_o_m_m_a_n_d-_l_i_n_e _O_p_t_i_o_n_s
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.

-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.

-rr_a_b_N
     Set number  register _a_b  to value _N.   For obvious reasons,  _a_b cannot
     contain a digit.

-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.

nnrrooffff  appends the  contents  of the  environmental variable  NNRROOFFFF 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 nnrrooffff.

_P_r_i_m_i_t_i_v_e_s
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.

.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 character, which is the apostrophe.

.cccc _c
     Set the normal  control character to _c. With no  argument, reset it to
     the default character, which is the 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 _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 nnrrooffff,
     .ccuu does  not perform continuous  underlining -- it  underlines words,
     but not spaces.

.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.

.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 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.

     The basic  unit of measurement for  nnrrooffff 1/120th of an  inch; this is
     also called  the _m_a_c_h_i_n_e _u_n_i_t.  It  is indicated by the  suffix uu to a
     measurement.   Unless  otherwise  stated,  all number  registers  that
     information  about a  page  holds that  information  in nnrrooffff  machine
     units.

     Other units of measure convert into nnrrooffff units as follows:

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

.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 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. For example, to have calls to font K remapped to
     Roman font, use the call:

         .rf K R

.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  .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
     This behaves the same as .ccuu.

.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.

_E_s_c_a_p_e _S_e_q_u_e_n_c_e_s
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.   Each  escape sequences  is
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 literal period.

\'   Print a literal apostrophe.  This should  be used in text that will be
     manipulated by the \ww escape sequence or the .ttll 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.

\&   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  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 `.').

\dd   Move _d_o_w_n  by one-half em (ttrrooffff) or  one-half line (nnrrooffff).  Normally
     used to do crude subscripting, or  to undo the effect of the \uu escape
     sequence.

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

\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 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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.

\kk_x  Record the current vertical position into register _x.

\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.

\ss_N  Change the current size of the type to _N points.

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

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

\tt   Print a tab.

\uu   Move _u_p  by one-half  em (ttrrooffff)  or one-half line  (nnrrooffff).  Normally
     used to  do crude superscripting, or  to reverse the effect  of the \dd
     escape sequence.

\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

         \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.   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  nnrrooffff reserves the
     following values for its internal use:

          <Ctrl-SP> X00  Ignored
          <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 nnrrooffff
     and ttrrooffff.  Code that uses  it will behave differently  when ported to
     other implementations.

\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.

_D_e_d_i_c_a_t_e_d _N_u_m_b_e_r _R_e_g_i_s_t_e_r_s
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 passed to a macro.

%   Present page number.

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

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

ddll  Maximum width of last completed diversion.

ddnn  Height of last completed diversion.

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

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

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

.h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.

hhpp  Horizontal position on current input line.

.ii  Present amount of indentation.

.jj  Current type and mode of text adjustment.

.ll  Present line length.

llnn  Current line number in the output.

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

.n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.

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

.oo  Present page offset.

.pp  Page length.

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

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

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

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

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

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

.zz  Name of the current diversion.

_P_r_i_n_t_e_r _C_o_n_f_i_g_u_r_a_t_i_o_n
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 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.

_M_i_s_c_e_l_l_a_n_e_o_u_s
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.

_F_i_l_e_s
/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

_S_e_e _A_l_s_o
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, pprriinntteerr, 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
