.APPENDIX BUILDING RUNOFF
.SUBTITLE RSX-11M
This section of the RUNOFF documentation describes in detail how to
build RNO and change it for your specific needs.
First you build RNO, and then you build the documentation and help files.
The documentation and help files come in both big and small versions.
Both are generated for your convenience.
.s.x RSX-11M
^&RSX-11M mapped systems\&
.skip 
.fill 
Procedure: 
.list 1 
.le;The assembly and task build steps may be executed by:
.i5 ;^&@RNORSX\&
.br;This will build a standard RSX version of RNO.
If you wish to customize your version of RNO then you should follow the
following steps.
.list 0
.le 
Select the proper task build file: 
.list 0
.le;RNOBLD.CMD##Overlayed 
.le;FCSBLD.CMD##Overlayed, resident library 
.le;SMLBLD.CMD##Overlayed, smallest size
.le;BIGBLD.CMD##Non overlayed
.els
.LE Select the options you require by editing the RNPRE.MAC. 
This is only necessary if you wish to have a different set of defaults.
Some are mentioned in the section on CUSTOMIZATION.
.TP 5 
.le 
Edit the Task Build command file to reflect your individual system needs. The
Task Build command file contains parameters to set the default options,
default paper size (for /-FF) and default underline mode. The underline mode
is currently set as UL:L. If you use lots of index terms or otherwise make
heavy demands on dynamic memory RNO will run faster by increasing the EXTSK
parameter. The overlayed version has lots of room for dynamic memory extension
and runs nearly as fast as the non overlayed version. 
.le 
Assemble
.NOFILL 
.INDENT +5
MAC @RNOASM
.F.le ;Build the task 
.lm+5.NF 
TKB @RNOBLD .....or 
TKB @BLDFCS ..or 
TKB @BIGBLD 
.LM-5 
.FILL 
.els 1
.le ;The final RNO.TSK should be copied to LB:[1,54], and installed.
.le;Finally to generate RSX documentation:
.i10;@DOCRSX
.p
This builds both a document and a help file.  You will probably wish to
install the help file on your system.
The following guide will aid you in the installation.
.list 0.le You must copy the help RNORSX.HLP to uic [1,2]
.le The protection must be set W:R
.le An entry must be added to the main HELP.HLP referencing @RNORSX.HLP
.le It may be necessary to remove the first line in the RNORSX.HLP file.
.els 0
.ELS 
.S 
.tt6
^&RSX-11M+\&
.s
The mapped RSX procedure should be used.  It is possible to
separate the code into data and code using I/D space.  The .psects
have all been properly defined and M+ users may wish to experiment with
various methods of reducing the program size to make more dynamic memory
available.
.s
.tt 6
^&RSX-11M UNMAPPED SYSTEMS\&
.p
Users of unmapped systems should follow the procedure outlined for mapped
systems, but selecting UICs as appropriate. File RNOBLD.CMD will have to be
edited to delete the /MM option and to change the PAR directive to match
system requirements. The final RNO.TSK should be copied to LB:[1,50]. 
.SUBTITLE RSX-11D
.s2.tt 5
.x  RSX-11D
^&RSX-11D systems\&
.skip 
Users of RSX-11D should follow the procedure outlined for users of RSX-11M
Mapped systems.  Since the conventions for source and object files are
installation dependent, all .CMD and .ODL files should be edited accordingly. 
Additionally, RSX-11D users should alter RNOBLD.CMD to change the /MM
option to /MU and to change the PAR directive as needed. 
.SUBTITLE IAS
.s2 .tt 5
^&IAS systems\&
.x  IAS
.p 
IAS users may use command file RNOIAS.CMD to assemble and build
RUNOFF. The command file IASBLD.CMD may be used for just building RNO. The
command file contains parameters to set the default options, default paper
size (for /-FF) and default underline mode. 
.note
Indirect command files will not work with heavily overlayed versions under IAS.
IAS users must use only IASBLD or BIGBLD.
.end note
.p
To generate IAS documentation:
.i10;@DOCIAS
.p
Unfortunately an IAS help file is not generated.  IAS users may be able
to adapt the RSX help file created by @DOCRSX.
.SUBTITLE VMS
.s2.tt 8
.x  VMS
.c;^&VAX/VMS systems\&
.s
This program must be built under compatibility mode using MCR.
The commands are:
.i10;@RNOVMS
.i15;or ......
.i10;MCR MAC @RNOASM
.i10;MCR TKB @RNOBLD
.br;Otherwise the 11-M procedure should be used.
The final RNO.EXE should be copied to SYS_$SYSTEM
with W:E protection if all users are to be able to use it via the
 _$#MCR#RNO command.
The following symbol should be defined:
.i10;_$ RNO :== _$SYS_$SYSTEM:RNO
.p
To generate VMS documentation:
.i10;@DOCVMS
.p
both a document and help file are generated.  The help file may
be installed in the system help file.
To do this you need bypass privelege or you need to be in a system 
account.
.list 0
.le _$ LIBR /HELP/CREATE RNO RNOVMS
.le _$ COPY RNO.HLB SYS_$HELP
.le _$ SET PROT=W:R SYS_$HELP:RNO.HLB
.le _$ ASSIGN SYS_$HELP:RNO.HLB SYS_$LIBRARY/SYSTEM
.c;or . . .
.le _$ LIBR /help sys_$help:helplib rnovms
.els0
.SUBTITLE RT-11
.s2.tt 8
.x  RT-11/TSX
.c;^&RT-11/TSX\&
.s
RT11 and TSX users should copy all _.MAC and _.COM files to the device
assigned INP.  The output device for the .OBJ and .SAV files should
be assigned OUP.
.s
.i 10;ASS DEV INP
.i 10;ASS DEV OUP
.s
Before compiling the files, RNPRE.MAC may be edited to change the default
options. The macro files are assembled by initiating the command file
RTASM.COM: 
.s
.i 10;@RTASM
.s.tt 6
The resulting object files
are linked by:
.s
.i 10;@RTBLD
.i15; or...
.i10;@RTLINK
.p
RTBLD is for a non overlayed version while RTLINK produces an overlayed
version. The non overlayed version may be shortened by removing the 2 pass
mode, double buffering, autohyphenation, or the heuristic hyphenation. 
.s
To generate the appropriate RT11 documentation users should use
RUNOFF to create the documentation file from the _.RNO files supplied.
Copy all the _.RNO files to the default device.
.s
.i 10;RUN RUNOFF
.i 10;BRIEF=SMALL,RNORT
.i 10;RUNOFF.TXT,RUNOFF=RNORT
.i 10;RUNOFF.TOC=RUNOFF.RNT
.i 10;/X
.S
.i 10;COPY/CONCATENATE RUNOFF.TOC,RUNOFF.TXT RUNOFF.DOC
.s
The resulting file will be RUNOFF.DOC and BRIEF.DOC built specifically
for RT11 users.  No RT help file is available.
.bb
.p
The files for building RNO can be split very conveniently between 3 RX02: 
floppies.  All of the _.MAC, _.CMD, _.COM files fit onto 1 floppy.   All
of the _.RNO files onto another with all of the _.TST onto a third.
The magtape distribution contains RTCOP.COM a VMS command file which splits
up the distribution onto 3 floppies in a very convenient manner.
.eb
.SUBTITLE RSTS
.s2
.tt 8
.x  RSTS
^&RSTS/E\&
.s
The version of RNO that this originally grew from supported RSTS/E and a
symbol is in RNPRE.MAC to conditionalize this support.  I do not have
access to a RSTS system, and as a result RSTS users are on their own.
If a RSTS user comes up with a set of patches to make it work, I will
be glad to include them with the distribution.  Presumably you must
run this under RSX simulation available with RSTS.
.SUBTITLE ALL OPERATING SYSTEMS
.s2
^&ALL OPERATING SYSTEMS\&
.s.c;RESTRICTIONS
.p
This version of RNO uses the SOB instruction.  If your machine (11/20  or
11/10) doesn't have this instruction it may be simulated in the RNPRE.MAC
file. Since almost every PDP-11 has this instruction you will probably not
have to worry about this.  If your CPU doesn't have EIS (MUL and DIV 
instructions) you should disable the symbol _$EIS in RNPRE.MAC.
If you don't have EIS you need the system subroutines _$MUL and _$DIV.
.s.c;CUSTOMIZATION
.p
You may change many things in RNO to accomodate your requirements. The option
defaults may be modified by editing the build command file. All other defaults
are in the file RNPRE.MAC.  To make changes you may edit RNPRE.MAC and change
any parameters that are marked as user changeable. They are labeled and
commented for your convenience.  A few of the many available options are
mentioned here. 
.p
Support for specific printers is available in RNO. The default is configured
for a Florida data.  This will work with most Diablo compatible printers. The
prefix file RNPRE.MAC has a symbol _$FLORD to define a set of default escape
sequences for the Florida data printer. You can select Diablo escape sequences
with the symbol _$DIAB or you may define your own internal set of default
escape sequences by modifying the table in routine INIT. 
The default escape sequence for variable spacing may be either 10 or 12 pitch
Diablo style. 
.p
The symbol H_$_$PHN may be deleted to remove the AUTOHYPHENATION code.  The
autohyphenation can be made faster and the hyphenation routine is smaller if
the symbol _$DIGR is removed.  This allows only suffix and prefix hyphenation.
.p
You may pick default indentation, spacing, margins, pagesize, and parameter
limits. Input and output buffer sizes may be adjusted. 
The following limits may be adjusted. The current value is in parenthesis.
.list 0
.le;Maximum number of nested lists (6)
.le;Maximum number of header levels (6)
.le;Maximum characters/command (40)
.le;Maximum characters/substitution label (20)
.le;Maximum characters/if label (10)
.le;Maximum characters/pre or post-fix (10)
.els 0
.s.c;PROGRAM SIZE
.p
The RSX overlayed version size is around 38 kbytes. The non overlayed version
is about 56 kbytes.  The smallest overlayed version is around 34 kbytes.
The non overlayed RT-11 version is about 45 kbytes and the overlayed version
about 32 kbytes.  You may decrease the size by decreasing the buffer sizes.
You can also omit the AUTOHYPHENATION feature from non overayed versions by
removing the symbol H_$_$PHN in RNPRE.MAC.  The current RSX/IAS/VMS version
also keeps all input files open and the current block resident in memory. This
adds about 2 kbytes to the program size.  The code may be modified to
temporarily close unused files at the expense of program speed. A minimum of 2
Kbytes is necessary for the dynamic memory in addition to the program.  A
large number of definitions or index terms will stretch the need for dynamic
memory. A change in size is possible by specifying a smaller stack.  The
current size is probably too big and 64 is the bare minimum.  The current
version of RNO is much more stack hungry, so 128 should work for most
applications. 
.s.c;BUFFER SIZES
.p
The maximum input line is currently set to 512 characters.  If this is too
short you may redefine the symbol IBFSZ in RNPRE.MAC.  You should be aware
that if you do this the program will grow in size at the expense of dynamic
memory. In general you can get around this restriction by using substitutions.
For the RSX/VMS/IAS version the maximum output line is 256 characters. If this
is not correct you may redefine it by changing symbol OBFSZ in RNPRE.MAC. The
RT version has no output line limitation. This should only be necessary if you
need shorter lines to pass to another program, or if you need longer lines in
conjunction with the /-CR option. Normally each line of printed text will
occupy 1 output record, unless you have a large number of imbedded escape
sequences which cause it to grow beyond 256.  If it is longer than 256 it is
split into several records. This causes no problems as long as you do not use
/-CR. If you need to print more than 150 characters on a line and you use
/UL:S (/U:S) or /UL:L (/U:L) the underline buffer size may not be adequate. 
The current definition is symbol ULNSZ found in RNPRE.MAC. The RT-11 options
are indicated in parenthesis. 
.s.c;EFFICIENCY
.P
The underlining options have an effect on the efficiency or RNO. /UL:S (/U:S)
is the least efficient form of underlining and will slow execution especially
when /PA (/P) is used to omit a large number of pages. /UL:L (/U:L) is more
efficient with /UL:B (/U:B) the most efficient type of underlining. /UL:N
(/U:N) is of course the most efficient, but at the cost of losing the
underlining capability. 
.p
The overlay structure places all of the commonly used routines and the
hyphenation routine in the same overlay.  The _.LIST, _.LIST ELEMENT,
_.CHAPTER, _.APPENDIX, _.NOTE, _.HEADER LEVEL commands are in a separate
overlay.  The least used commands such as _.STYLE, _.LAYOUT, _.DISPLAY are in
a third overlay.  This structure should be only slightly slower than a non
overlaid program, and it contains a maximum of dynamic memory space (30+
Kbytes). With RUNOFF.DOC the non overlaid version was only about 10_% slower.
Anyone contemplating using the SUBSTITUTE commands, or indexing will probably
need the overlaid version.  If no indexing is done, and a limited number of
escape sequences, and substitutions are defined, the non overlaid version will
also probably do the job. 
.p
If you wish to try different overlay schemes a few tips are in order. First
RUNOFF,RNODYN,CMTAB,GCIN, and RSXIO or RT11IO should not be overlayed.
If the I/O routines are overlayed then START or RNORT call the open and close
file routines. HYPHEN, and RNCMD are the 2 most frequently used routines while
STYLE and FMTCM are much less frequently used.  COMND is called every time a
command is parsed, so it should probably be in the same overlay with RNCMD.
CMTAB may be split into 2 PSECTS of which STRING may be in the same overlay
with COMND, but DSPTCH must not be overlayed.  This is done in SMALBL.CMD. 
.p
One way of increasing the efficiency of RUNOFF is to turn off autohyphenation.
This will prevent excessive overlay switching as well as eliminating some
code.  For RUNOFF.DOC turning off hyphenation only decreased the time by about
6_%. One more way to increase efficiency is to increase the the task
extension. This only has an effect if large amounts of dynamic memory are
used. Large footnotes, large _.TEXT sections, or many large definitions may
make this option necessary.  In general most users will find existing dynamic
memory adequate. The RT version uses all available dynamic memory. 
.note
This program has been successfully run on RSX-11M, VAX/VMS, RT-11/SJ, TSX, and
IAS systems. It should run on RSTS under RSX emulation. It has not been tried
on unmapped systems.
.end note
.s.c;DOCUMENTATION
.p
It may be necessary to modify the documentation to accomodate a particular
printer.  All of the page sizes are determined by the commands in the file
CNTRL.RNO.  This file should be edited to reflect both your hardware and your
output format preference.  Currently the output occupies a page size of 62 by
79 with /UL:S (/U:S) for underlining. 
.s.c;HELP FILES
.p
Two help files are available with the current version of Bonner Lab Runoff. 
They are for the VAX/VMS systems and the RSX operating systems. They are
called RNOVMS.HLP and RNORSX.HLP.  They contain nearly the entire contents of
this manual.  If you are short on disk space you may not be able to use them. 
When you use DOCRSX or DOCVMS to generate the RNO manual the help files are
also generated.  Unfortunately it was not possible to generate a help file for
IAS or RT. 
.SUBTITLE TEST FILES
.s.c;TEST FILES
.p
A number of files .TST are included with the distribution.  They serve
as a test, and guide to the various features available in Bonner Lab Runoff.
The file RNOTST.CMD runs all of these through RNO.  It should do them without
any internal errors or bombs.
A partial guide to these is:
.list 0
.le COMAND.tst#-#How to define commands.
.le DISPLA.tst#-#Demonstrates display command on VT100 terminal.
.le LEVEL.tst#-#Demonstrates header levels.
.le DISLEV.tst#-#Demonstrates header levels modified by display commands.
.le LIST.tst#-#Demonstrates the _.LIST command.
.le DISLST.tst#-#Demonstrates the _.LIST command modified by _.DISPLAY.
.le CHAPT.tst#-#Demonstrates various chapter styles.
.le EQATN.TST#-#Demonstrates the equation formatting.
.els 0
.p
In addition some _.RNO and _.TST files are available as examples of escape
sequence and substitution handling. The _.RNO file defines escape sequences 
and the _.TST file illustrates their useage.
These are: 
.list 0
.le GREEKMATH#-#Defines mathematical symbols for a Florida Data printer.
The same ones should work on a Diablo printer.
.le VT100#-#Defines some VT100 escape sequences to produce bolding and 
underlining.
.le;LA50#-#Defines some escape sequences for an LA-50 printer.
.le;CIT161#-#Defines sequences for a CIT-121 color terminal.
.le;SPIN#-#Defines sequences for a spinwriter.
.els