.iif micro.type RUNOFF building build documentation
.iif micro.type
.iif micro.flags substitute
.iif micro.first title $$DATE Building Bonner Lab Runoff
.iif micro.fg 5
.iif micro.c;How to Build Bonner Lab Runoff
.iif micro.s5
.iifnot micro .APPENDIX BUILDING RUNOFF
This appendix describes in detail how to build RUNOFF, and how to modify it
for your specific needs.   An executable RUNOFF file (called RNO on most
systems) should be built first.  It then can be used to build the
documentation and help files. The documentation and help files come in big,
small, and microscopic versions. All three are generated for your convenience.
The instructions in this appendix should work on your system, but you
may find that you will have to modify them slightly since it was not
possible to anticipate all possible system configurations.
.SUBTITLE RSX-11M
.s.x RSX-11M
.c;^&RSX-11M mapped systems\&
.skip 
.fill 
Procedure: 
.list 1 
.le;It is assumed that the default CLI is MCR.
.le;The assembly and task build steps can be executed by:
.i5 ;^&@RNORSX\&
.br;This will build a standard RSX version of RNO.
It is assumed that you are using MCR rather than DCL.
If you wish to customize your version of RNO, perform 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;MEMBLD.CMD##Overlayed, memory resident overlays
.le;SMLBLD.CMD##Overlayed, smallest size
.le;SMLFCS.CMD##Overlayed, small size, resident library
.le;BIGBLD.CMD##Non overlayed
.els
.LE Select the options you require by editing the RNPRE.MAC. 
This step is only necessary if you wish to have a different set of defaults.
(See 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, RUNOFF will run faster if you increase 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:
.i5;@DOCRSX
.p
This command builds both a document and a help file.  To install the help
file on your system, follow these steps:
.list 0.le Copy the help RUNOFF.HLP to uic [1,2]
.le Set the protection W:R
.le Add an entry to the main HELP.HLP that references @RUNOFF.HLP
.le It may be necessary to remove the first line in the RUNOFF.HLP file.
.els 0
.ELS 
.S 
.tt6
.c;^&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
.c;^&RSX-11M UNMAPPED SYSTEMS\&
.p
Users of unmapped systems should follow the procedure outlined for mapped
systems, 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
.c;^&RSX-11D systems\&
.skip 
Users of RSX-11D should follow the procedure outlined for 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
.c;^&IAS systems\&
.x  IAS
.p 
To build a standard version of RUNOFF:
.brl.i5;^&@RNOIAS\&
The command file IASBLD.CMD can be used to build just RUNOFF.  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:
.i5;@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 P/OS
.s2.tt 8
.x P/OS
.c;^&P/OS on PRO\&
.s
Building for P/OS is essentially the same as for RSX-11m except that
the build commands have been customized for the PRO.
To build RUNOFF, PRO users use the command:
.i5;@RNOPRO
.br
After installing RUNOFF,  you can produce documentation for P/OS with the
command:
.i5;@DOCPOS
.subtitle VMS
.s2.tt8
.x  VMS
.c;^&VAX/VMS systems\&
.s
^&To build this program for VMS native mode:\&
.i5;@RNOVMS
.p
Once built, you must copy RUNOFF.EXE
to sys_$system: ,or some other convenient directory, with protection=w:re.
Then define the command RUNOFF by:
.i5;RUNOFF = _$sys_$system:RUNOFF
.br
This command should be added to the default login proceedure.
This supersedes Digital Standard Runoff.  If you wish to keep DSR
and Bonner Lab Runoff on the same system, you should not copy
RUNOFF.EXE to sys_$system:.
.p
If you wish to customize the native mode version, you can edit VAXPRE.MAR.
.s
^&To build RUNOFF for compatability mode:\&
.i5;@RNOVMS.CMD
.p
The RNO.EXE file should be copied to a directory that can be accessed
by all users.  The following symbol then needs to be defined:
.i5;RNO	:==_$directory:RNO
.br
where "directory" is the directory where RNO is located.
You can only run the compatability mode version if the RSX
emulator is available on your VMS system.  If you do not have it, you may
have to purchase it from DEC:  it is called VAX-11#RSX.  If your VAX
was upgraded from V3.7, you should be able to get it free for a limited
time period.
.br
.s2.c;NOTE
.s
The native mode version has several advantages over the compatability mode
version. 
.c;Advantages
.list 0
.le It is faster by about a factor of 2.
.le It has essentially unlimited buffer space for footnotes, text sections, and
definitions. 
.le The maximum sizes for labels, lists etc. are larger.
.le The command structure is consistent with other VMS commands, including
DSR.
.le It will work on all VAXes, including the MicroVAX, because it does not
require RSX-11M emulation.
.le It is cheaper, because you need not buy the RSX emulator to use it.
.els 0
.p
To generate VMS documentation:
.i5;@DOCVMS
.i10;Or for the compatabilty mode version:
.i5;@docvms.cmd
.p
Both a document and help file are generated.  The help file should
be installed in the system help file.
To do this you need bypass privilege, or you need to be in a system 
account.  Then follow these steps:
.list 0
.le _$ LIBR /HELP/CREATE RNO RUNOFF
.le _$ COPY RNO.HLB SYS_$HELP
.le _$ SET PROT=W:R SYS_$HELP:RNO.HLB
.le _$ ASSIGN SYS_$HELP:RNO.HLB SYS_$LIBRARY/SYSTEM
.le;The ASSIGN should be included in the system startup file.
.i5;or . . .
.le _$ LIBR /HELP SYS_$HELP:HELPLIB RUNOFF
.els0
.SUBTITLE RT-11
.s2.tt 8
.x  RT-11/TSX
.c;^&RT-11/TSX\&
.s
RT-11 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
.i5;ASS DEV INP
.i5;ASS DEV OUP
.s
Before compiling the files, RNPRE.MAC can be edited to change the default
options. The macro files are assembled by initiating the command file
RTASM.COM: 
.s
.i5;@RTASM
.s.tt 6
.iif fall86 .bb
The resulting object files are linked by:
.s
.i5;@RTBLD
.i10; or...
.i5;@RTBLDO
.i10; or...
.i5;@RTBLDV
.p
RTBLD creates a non-overlayed version, RTBLDO creates an overlayed version,
and RTBLDV creates a virtual-job version.  If you are running /XM, you
will probably want to run the virtual-job version, since it will always
run if you have enough extended memory.  If you are non running /XM, then
you should try the non-overlayed version first.  Some systems may not
have enough free memory to run this version, in which case you should
try the overlayed version.
The non overlayed version could be shortened by removing the 2 pass
mode, double buffering, autohyphenation, or the heuristic hyphenation. 
.iif fall86 .eb
.s
To generate the appropriate RT11 documentation use
RUNOFF to create the documentation file from the _.RNO files supplied.
Copy all the _.RNO files to the default device.
.s
.i5;_. RUN RUNOFF
.i5;*MICRO=MICRO,RT,RUNOFF
.i5;*BRIEF=SMALL,RT,RUNOFF
.i5;*RUNOFF.TXT,RUNOFF=RT,RUNOFF
.i5;*RUNOFF.TOC=RT,RUNOFF.RNT
.i5;*/X
.S
.i5;_. COPY/CONCATENATE RUNOFF.TOC,RUNOFF.TXT RUNOFF.DOC
.i5;_. DEL RUNOFF.TXT,RUNOFF.TOC
.s
The resulting files will be RUNOFF.DOC, BRIEF.DOC, and MICRO.DOC built
specifically for RT11 users.  No RT help file is available. 
.iif fall86 .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, and all of the _.TST onto a third.
For convenience, DOC*.CMD, DOC*.COM, and *DOC.CMD should be included with
the .RNO files, as these are used to build documentation on other systems.
In addition, a copy of README.1st, and BUILD.DOC are included as a guide
to building RUNOFF.
.iif fall86 .eb
.SUBTITLE RSTS
.s2.tt 8
.x  RSTS
.c;^&RSTS/E\&
.s
The version of RNO that this RUNOFF originally grew from supported RSTS/E,
and a symbol is in RNPRE.MAC to conditionalize this support.  A RSTS system
was not available to test this version, so RSTS users are on their own.
If a RSTS user comes up with a set of patches to make it work, the author
will gladly include them with the distribution.  Presumably you will have to
run under the RSX simulation available with RSTS.
.SUBTITLE ALL OPERATING SYSTEMS
.s2
.c;^&ALL PDP-11 OPERATING SYSTEMS\&
.s.c;RESTRICTIONS
.p
This version of RUNOFF uses the SOB instruction.  If your machine (11/20  or
11/10) doesn't have this instruction, it can be simulated in the RNPRE.MAC
file by enabling the symbol _$SOB. 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 from the system library.
.test page 6
.s.c;CUSTOMIZATION
.p
You can change many things in RUNOFF  to accomodate your own requirements.
The option defaults can be modified by editing the build command file.
All other defaults are located in the file RNPRE.MAC or VAXPRE.MAR.
You should be able to modify any parameters in RNPRE.MAC or VAXPRE.MAR
that are marked as user changeable; they are labeled and commented for your
convenience.  If you customize RUNOFF, you should edit CNTRL.RNO to
customize the documentation.  For example, if you increase the maximum
nesting of lists, you should change the substitution /listmax_$/ to reflect
this modification. 
.p
Support for specific printers is available in RUNOFF. The default support
is for a Florida data printer. The default will work with most Diablo
compatable printers. The prefix file RNPRE.MAC or VAXPRE.MAR has several
symbols that can be defined for various printers.
.list 0
.le;_$FLORD for the Florida data printer
.le;_$DIAB for Diablo printers
.le;_$LA50 for an LA-50 or LA-100 terminal
.le;_$HPLJ for Hewlett Packard Laser Jet printer
.els 0
You can define your own internal set of default escape sequences by
modifying the table in routine INIT. 
The default escape sequence for variable spacing can specify either 10 or 12
pitch Diablo style. 
.p
The symbol H_$_$PHN can be deleted to remove the AUTOHYPHENATION code.
Autohyphenation can be made faster and the hyphenation routine is smaller if
the symbol _$DIGR is removed.  If this is done, only suffix and prefix
hyphenation will be performed.
.p
You can change the default indentation, spacing, margins, pagesize, and
parameter limits. Input and output buffer sizes can also be adjusted. 
The variables shown below can be adjusted.  The current value is in
parenthesis.  If you decrease these, more space will be available.
.list 0
.le;Maximum number of nested lists (6, vms=10)
.le;Maximum number of header levels (6)
.le;Maximum characters/command (40)
.le;Maximum characters/substitution label (20)
.le;Maximum characters/if label (10,40)
.le;Maximum nesting of IFs (32)
.le;Maximum characters/pre or post-fix (10,40)
.le;Index Optimization (0)
.els 0
.p
MACRO wizards may want to make more modifications, but they should
consult the INTERNALS.RNO file first.  If you make any significant
modifications to this version of RUNOFF, the author would appreciate
receiving a listing of them so that they can be considered for incorporation
in future general releases.
.s.c;PROGRAM SIZE
.p
The size of the RSX overlayed version 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.  The virtual-job RT-11 version requires about 2
kbytes of low memory and about 45 Kbytes of extended memory.
You can decrease the memory requirements 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 or VAXPRE.MAR.  The current
RSX/IAS/VMS version keeps all input files open and the current block
resident in memory. This adds about 2 kbytes to the program size.  The code
can be modified to temporarily close unused files at the expense of program
speed. A minimum of 2 Kbytes is necessary for dynamic memory in addition to
the program.  A large number of definitions or index terms will stretch the
need for dynamic memory. The size of RUNOFF could be lowered by specifying
a smaller stack.  The current size is probably too big, and 64 is the bare
minimum.  The current version of RUNOFF 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 can redefine the symbol IBFSZ in RNPRE.MAC or VAXPRE.MAR.
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 adequate, you can redefine it by changing symbol OBFSZ
in RNPRE.MAC or VAXPRE.MAR. The RT version has no output line limitation.
Changing the maximum size of the input line
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 that cause it to grow beyond 256.  If the
line 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 or VAXPRE.MAR. The RT-11 options are indicated in parenthesis. 
.p
The VMS version does not use dynamic memory allocation.  Instead, a fixed
buffer of 32768 bytes is allocated for each feature.  Footnotes, text,
substitutions,  and conditional labels each occupy a full buffer.  At the
present, it is not possible to expand the buffers to a larger size.
.s.c;EFFICIENCY
.P
The underlining options have an effect on the efficiency of
RUNOFF.  /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, and /UL:B (/U:B) is the most
efficient form of underlining. /UL:N (/U:N) is, of course, even more
efficient, but you lose the underlining capability. 
.p
The RSX and  RT versions use overlays to conserve memory.
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 allows a maximum of dynamic memory space (30+
Kbytes). In creating RUNOFF.DOC, the non-overlaid version was only
about 10_% slower.
If you are contemplating using SUBSTITUTE commands or indexing, you will
probably need to use the overlaid version.  If no indexing is done, and a
limited number of escape sequences and substitutions are defined, the
non-overlaid version will 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 should 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 as RNCMD.  CMTAB can be split into 2 PSECTS:  STRING can be in the
same overlay with COMND, but DSPTCH must not be overlayed.  See SMALBL.CMD
for an example of overlaying.
.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.  In building RUNOFF.DOC, turning off hyphenation only decreased the
time by about 6_%. Another way to increase efficiency is to increase the the
task extension. This will only be effective 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, TSX,
P/OS 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
The documentation comes in 3 sizes:  regular, small, and micro.  "Regular"
occupies nearly 700 blocks of disk space, while "small" is under 200 blocks.
"Micro" (under 70 blocks) is designed as a small pocket guide to RUNOFF.
.p
It may be necessary to modify the documentation files to accomodate printing
them on a particular printer.  All the page sizes are determined by the
commands in the file CNTRL.RNO.  This file should be edited to reflect both
your hardware and 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
Three help files are available for 2 operating systems: VAX/VMS and RSX.
RUNOFF.HLP contains nearly the entire contents of
the manual.  If you are short on disk space, you may not be able to use it.
The alternative BRIEF.HLP and MICRO.HLP are considerably smaller.
When you use DOCRSX or DOCVMS to generate the RUNOFF manual, the help files
are also generated.  Help files are not generated for IAS or RT. 
.SUBTITLE TEST FILES
.s.c;TEST FILES
.p
The primary test of RUNOFF is the creation of the document and help files
that you produce after building RUNOFF.  For additional testing, a number of
files with extension .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 RUNOFF. It should process
them without any internal errors or bombs.
A partial list of the test files is shown below:
.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 files define escape sequences 
and the _.TST files illustrate their useage.
Since these files come from several authors, not all escape sequences in
these files are accessed by the same flag characters.
A partial list of these sample files is:
.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;DIABLO#-#Define some sequences for Diablo style printers.
.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