






                                 RUNOFF

                             Version M3.0X



                                   by


                        Charles H. Spalding III

                             Unimation Inc.
                          1202 Charleston Road
                        Mountain View, CA 94043

                             (415) 965-0557
                       (8:30-10:00 Pacific time)


                            December 5, 1982




Here is yet another version of RUNOFF!  This version is the result of an
effort to achieve the ability to  produce  an  extensive  system  manual
without having to do any editing of the RUNOFF output.  Toward that end,
several  new  commands  have  been added, several existing commands have
been enhanced, and many bugs have been fixed.

This version is derived from DECUS version M02.  An earlier  edition  of
this  version was submitted at the Spring '82 symposium--this edition is
the result of continued work.  There are still several features  I  plan
to  include  (and  subtle bugs to be fixed).  I also intend to review as
many other versions as I can to see what features should be incorporated
from them.  The ultimate intention is to submit a  new  version  to  the
DECUS library.  (I am open to suggestions as to how to best proceed with
the whole issue of RUNOFF support.)

There are undoubtedly bugs in this version.  I would  appreciate  it  if
bugs  were reported.  There may also be differences of opinion about how
certain features should behave.  Please report any characteristics which
seem  undesirable.  The preferred method of reporting these things is to
send annotated copies of the input and output.  

Almost all changes to the  code  have  been  made  with  assembly-switch
control  so  that undesired changes can be easily removed.  It should be
noted, however, that there is a good chance that  bugs  will  appear  if
current  features  are  disabled.  There are many interactions, and they
may not be handled correctly in all combinations.  

                                                                Readme-2




One final caveat:  this version has been used  only  under  RSX-11M.   I
have  no  idea  whether  it will still run correctly under RSTS or IAS--
presumably it will.

The user's manual has been edited extensively  to  correct  errors,  add
clarity  (hopefully),  and  document  changes  to  the program.

The following sections very briefly describe some of the  changes  made.
An  annotated list of the files in this submittal is included at the end
of this document.  


Significant feature enhancements since the Spring '82 version include:

     1.  It is now possible to keep  segments  of  the  input  (e.g.,  a
         table)  intact in the output without just forcing a new page if
         the material won't  fit  on  the  current  page.   Normal  page
         filling continues and the material is output on the next page.

     2.  Orphan control has been added to the PARAGRAPH command.

     3.  A text argument has been added to the FIGURE command to make it
	 possible to have a caption output with the figure space.

     4.  Unnumbered  lists  are  now  possible,  with  a  user-specified
         "bullet" character.

     5.  Header levels can now be  specified  relative  to  the  current
         level.  (This simplifies insertion and removal of levels.)

     6.  Tests for space available on the current page now consider  the
         line  spacing in effect when it makes sense to do that.  (There
         is a new command which doesn't consider the line spacing.)


Significant feature enhancements in the Spring '82 version included:

     1.  The task now expands  itself  when  the  index/footnote  buffer
         fills.   Thus,  RNO now does not occupy any more memory than it
         actually needs, and uses all the memory it can if necessary.  

     2.  An assortment of functions  have  been  added  for  making  the
         output  alternate  left/right for reproduction on both sides of
         the page.  

     3.  Multiple input files can be specified.  

     4.  Points at which a word can  be  hyphenated  can  be  explicitly
         specified (to overrule RUNOFF's error-prone algorithm).  

     5.  The index can include subentries, as well  as  entries  without
         page references (for headings above subentries).  

                                                                Readme-3




     6.  A base left margin can be set from which the text  margins  are
         measured.  

     7.  Command syntax is now the same for all  commands  with  similar
         argument combinations.  

     8.  Sections of the input can be set off with command-line  control
         over whether or not they are to be included in the output.

     9.  It is now possible to keep lines together at the _e_n_d of a group
         of lines.


The following list summarizes the new commands which have been added:  

     ALTERNATE               - control left/right alternation of the
     NO ALTERNATE              page header, with optional offset of
                               odd-numbered pages

     ALTERNATING TITLE       - control mode which places subtitle on the
     NO ALTERNATING TITLE      top line of odd-numbered pages in place
                               of the title

     AUTOSUBTITLE            - controls setting of subtitle by HEADER
                               LEVEL commands

     ENTRY                   - records an index entry without a page
                               reference

     EVEN                    - used to force output to an even-numbered
     ODD                       or odd-numbered page, respectively

     FLAGS SUBINDEX          - control special character (">") for
     NO FLAGS SUBINDEX         indicating index subentries

     FOOTNOTE LINE           - specifies characteristics of separation
                               automatically output above footnote(s)

     BLOCK		     - defines a segment of input which is to be
			       kept intact in the output, but without
			       interrupting page composition if the
			       material must be deferred to a later page

     INCLUDE                 - control processing of optional sections
     EXCLUDE                   of the input file
     OPTION
     ELSE
     END OPTION

     LAYOUT                  - sets layout of the output on the page,
                               including top margin and base left margin

                                                                Readme-4




     PAGE NAME               - sets text string to be used as prefix for
                               page numbers

     QUOTE CHARACTER         - assigns character to be used for the
                               quote character (normally "_")
      
     RIGHT JUSTIFY           - pushes line of text against right margin

     TEST LINES		     - acts like TEST PAGE but does not consider
			       the current line spacing


The following switches can now be specified on the command line:  

     /AP                     - append the output to an existing file
      
     /BL:n                   - output  n  blank lines in chapter header
      
     /CH:m:n                 - limit output to chapters  m  through  n
      
     /DO:n                   - set top margin to  n  lines
      
     /EX:m,n,...             - set options to "exclude"
      
     /HL:n                   - set length of page header to  n  lines
      
     /IN:m,n,...             - set options to "include"
      
     /LE:n                   - set base left margin to  n  spaces
      
     /LO:n                   - set page length to  n  lines
      
     /WI:n                   - set default right margin to  n

Several of these switches override  corresponding  commands  within  the
input file.  

If you have existing RNO files which you would like to use with this new
version  of  RUNOFF,  the following changes should yield essentially the
same output as from version M02.  

     At the start of the input, add:	 .LAYOUT 1
					 .HEADER UPPER,4
					 .FOOTNOTE LINE
					 .NO FLAGS SUBINDEX
      
     Replace ".NUMBER 0" with:		 .NUMBER 1
      
     After every NUMBER command except
             NUMBER 0, add:		 .NUMBER +1
      
     On the command line, use:		 /BL:11

                                                                Readme-5




     Replace ".FIRST TITLE" with:	 .TITLE

     Make sure no commands follow ".FIGURE" on a command line


Files included in this submittal:  

     README.1ST      This document
      
     SUMMARY.	     Overview of changes made to RUNOFF

     CHANGES.        Complete list of changes made to RUNOFF
      
     LOG.	     Edit history of recent bug fixes.

     RUNOFF.DOC      Updated user's manual for RUNOFF
      
     RUNOFF.RNO      RUNOFF input file for user's manual
      
     *.MAC           Source code
      
     RNO.OLB         Object library for configuration documented in
                             RUNOFF.DOC
      
     RNOASM.CMD      Command file for assembling all modules
      
     REPLACE.CMD     Command file for assembling a module and
                             replacing it in RNO.OLB
      
     RNOBLD.CMD      Command file for task building RUNOFF
      
     RNOBLD.ODL      Overlay description for task building RUNOFF
      
     FILES.          Lists of source files affected by each change


Unfortunately I have not been able to prepare a document  detailing  the
steps  for  task  building  the  program.   Presumably recipients of the
symposium tape won't need help with that.

In theory, all that needs to be done is edit RNOBLD.CMD  and  RNOBLD.ODL
to  make  them compatible with your system (e.g., presence or absence of
FCSRES) and the default conditions you want (e.g., underlining mode  and
page layout).  Then the command

                              TKB @RNOBLD

will create the task file from the object library, RNO.OLB.

If you want to disable any of the changes which have been made, you must
change the corresponding assembly switch(es) in RNPRE.MAC  and  assemble

                                                                Readme-6




all the affected modules.  (The file FILES. lists all the files affected
by  each  change.)  To  assemble  a  module and replace it in the object
library, use the command

                          @REPLACE <file name>

where <file name> is the name of the file to  be  assembled,  _w_i_t_h_o_u_t  a
file type.  When the last module is being replaced, the command

                         @REPLACE <file name> C

will compress the object library after the replacement.

As an alternative, RNOASM.CMD can be used to assemble  all  the  modules
and create a new object library.

In either case, the TKB command shown above is used  to  create  a  task
file from the object library.
