18 Nov 1985 Building Bonner Lab Runoff Page 1 How to Build Bonner Lab Runoff This 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 big, small, and microscopic versions. All are generated for your convenience. Unfortunately since it is not possible to anticipate all configurations so these instructions are not guaranteed to work. This document covers all known DEC operating systems. RSX-11M mapped systems ------- ------ ------- Procedure: 1. The assembly and task build steps may be executed by: @RNORSX ------- This will build a standard RSX version of RNO. This assumes you are using MCR rather than DCL. If you wish to customize your version of RNO then you should follow the following steps. 1. Select the proper task build file: 1. RNOBLD.CMD Overlayed 2. FCSBLD.CMD Overlayed, resident library 3. SMLBLD.CMD Overlayed, smallest size 4. BIGBLD.CMD Non overlayed 2. 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. 3. 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 increas- ing the EXTSK parameter. The overlayed version has lots of room for dynamic memory extension 18 Nov 1985 Building Bonner Lab Runoff Page 2 RSX-11M and runs nearly as fast as the non overlayed version. 4. Assemble MAC @RNOASM 5. Build the task TKB @RNOBLD .....or TKB @BLDFCS ..or TKB @BIGBLD 2. The final RNO.TSK should be copied to LB:[1,54], and installed. 3. Finally to generate RSX documentation: @DOCRSX 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. 1. You must copy the help RUNOFF.HLP to uic [1,2] 2. The protection must be set W:R 3. An entry must be added to the main HELP.HLP referencing @RUNOFF.HLP 4. It may be necessary to remove the first line in the RUNOFF.HLP file. RSX-11M+ -------- 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. RSX-11M UNMAPPED SYSTEMS ------- -------- ------- 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]. RSX-11D systems ------- ------- 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 18 Nov 1985 Building Bonner Lab Runoff Page 3 RSX-11D and .ODL files should be edited accordingly. Additionally, RSX-11D users should alter RNOBLD.CMD to change the /MM op- tion to /MU and to change the PAR directive as needed. IAS systems --- ------- To build a standard version of RNO: @RNOIAS ------- 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. To generate IAS documentation: @DOCIAS Unfortunately an IAS help file is not generated. IAS users may be able to adapt the RSX help file created by @DOCRSX. P/OS on PRO ---- -- --- Building for P/OS is essentially the same as for RSX-11m ex- cept that the build commands have been customized for the PRO. To build RNO PRO users use the command: @RNOPRO After installing RNO you get documentation for P/OS with the command: @DOCPOS VAX/VMS systems ------- ------- To build this program for VMS native mode: -- ----- ---- ------- --- --- ------ ----- @RNOVMS 18 Nov 1985 Building Bonner Lab Runoff Page 4 VMS Once built, you must copy RUNOFF.EXE and RUNOFF.CLD to sys$system: ,or some other convenient directory, with protection=w:re. Then define the command RUNOFF by: SET COMMAND sys$system:RUNOFF This command should be added to the default login pro- ceedure. If you wish to customize the native mode version you can edit VAXPRE.MAR. To build this for compatability mode: -- ----- ---- --- ------------- ----- @RNOVMS.CMD The RNO.EXE file should be copied to a directory that may be used by all users. The following symbol then needs to be defined: RNO :==$directory:RNO Where directory is the directory you have picked for RNO. You can only run the compatability mode version if you have the RSX emulator 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. NOTE The native mode version has a few disadvantages, and several advantages. Advantages 1. It is faster by about a factor of 2 2. It has more buffer space for footnotes, text sec- tions, and definitions. 3. The maximum sizes for labels, lists etc. are larger. 4. The command structure is consistent with other VMS commands. 5. It will work on all VAXes including the MicroVAX because it does not require RSX-11M emulation. It is cheaper because you need not buy the RSX emula- tor to use it. Disadvantages 1. The /2p switch is missing. 2. The /TT switch doesn't work. To generate VMS documentation: @DOCVMS Or for the compatabilty mode version: @docvms.cmd 18 Nov 1985 Building Bonner Lab Runoff Page 5 VMS 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 ac- count. 1. $ LIBR /HELP/CREATE RNO RUNOFF 2. $ COPY RNO.HLB SYS$HELP 3. $ SET PROT=W:R SYS$HELP:RNO.HLB 4. $ ASSIGN SYS$HELP:RNO.HLB SYS$LIBRARY/SYSTEM 5. The ASSIGN should be included in the system startup file. or . . . 6. $ LIBR /HELP SYS$HELP:HELPLIB RUNOFF RT-11/TSX --------- 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. ASS DEV INP ASS DEV OUP 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: @RTASM The resulting object files are linked by: @RTLINK or... @RTBLD RTLINK is the recommended version. RTBLD is for a non overlayed version while RTLINK produces an overlayed ver- sion. On many systems the non overlaid version may not work due to memory limitations. The non overlayed version may be shortened by removing the 2 pass mode, double buffering, au- tohyphenation, or the heuristic hyphenation. 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. . RUN RUNOFF *MICRO=MICRO,RT,RUNOFF *BRIEF=SMALL,RT,RUNOFF *RUNOFF.TXT,RUNOFF=RT,RUNOFF *RUNOFF.TOC=RT,RUNOFF.RNT */X 18 Nov 1985 Building Bonner Lab Runoff Page 6 RT-11 . COPY/CONCATENATE RUNOFF.TOC,RUNOFF.TXT RUNOFF.DOC . DEL RUNOFF.TXT,RUNOFF.TOC The resulting file will be RUNOFF.DOC, BRIEF.DOC, and MICRO.DOC built specifically for RT11 users. No RT help file is available. The files for building RNO can be split very con- veniently 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. For convenience DOC*.CMD,DOC*.COM, and *DOC.CMD should be with the .RNO files as these are used to build documentation. In addition a copy of README.1st, and BUILD.DOC are included as a guide to building RNO. RSTS/E ------ 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 in- clude them with the distribution. Presumably you must run this under RSX simulation available with RSTS. I have been informed by a RSTS user that very little work was required to make RNO work. Good Luck! ALL PDP-11 OPERATING SYSTEMS --- ------ --------- ------- RESTRICTIONS 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 by enabling the sym- bol $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 dis- able the symbol $EIS in RNPRE.MAC. If you don't have EIS you need the system subroutines $MUL and $DIV from the sys- tem library. CUSTOMIZATION You may change many things in RNO to accomodate your requirements. The option defaults may be modified by edit- ing the build command file. All other defaults are in the file RNPRE.MAC or VAXPRE.MAR. To make changes you may edit RNPRE.MAC or VAXPRE.MAR and change any parameters that are 18 Nov 1985 Building Bonner Lab Runoff Page 7 ALL OPERATING SYSTEMS marked as user changeable. They are labeled and commented for your convenience. A few of the many available options are mentioned here. In addition the cntrl.rno file should be edited to customize the documentation. For example if you increase the maximum nesting of lists, you should change the substitution /listmax$/ to reflect the modification. Support for specific printers is available in RNO. The default is configured for a Florida data. This will work with most Diablo compatable printers. The prefix file RNPRE.MAC or VAXPRE.MAR has several symbols for various printers. 1. $FLORD for the Florida data printer 2. $DIAB for Diablo printers 3. $LA50 for an LA-50 or LA-100 terminal 4. $HPLJ for Hewlett Packard Laser Jet printer You may define your own internal set of default escape se- quences by modifying the table in routine INIT. The default escape sequence for variable spacing may be either 10 or 12 pitch Diablo style. The symbol H$$PHN may be deleted to remove the AUTOHY- PHENATION 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. You may pick default indentation, spacing, margins, pagesize, and parameter limits. Input and output buffer sizes may be adjusted. The following limits may be ad- justed. The current value is in parenthesis. If you decrease these, more space will be available. 1. Maximum number of nested lists (6, vms=10) 2. Maximum number of header levels (6) 3. Maximum characters/command (40) 4. Maximum characters/substitution label (20) 5. Maximum characters/if label (10,40) 6. Maximum nesting of IFs (32) 7. Maximum characters/pre or post-fix (10,40) 8. Index Optimization (0) The wizard in macro can make more modifications, but the INTERNALS.RNO file should be consulted first. If you make any significant mods. I would appreciate a listing of them, so I can incorporate them into future releases. I can not incorporate all mods, as some may be incompatable with the current features. PROGRAM SIZE 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 18 Nov 1985 Building Bonner Lab Runoff Page 8 ALL OPERATING SYSTEMS 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 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. BUFFER SIZES The maximum input line is currently set to 512 characters. If this is too short you may redefine the sym- bol IBFSZ in RNPRE.MAC or VAXPRE.MAR. You should be aware that if you do this the program will grow in size at the ex- pense 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 or VAXPRE.MAR. 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, un- less 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 or VAXPRE.MAR. The RT-11 options are indicated in parenthesis. The VMS version does not use dynamic memory allocation, rather a fixed buffer 32768 bytes in size is allocated for each feature. Footnotes, text, substitutions, and condi- tional labels each occupy a full buffer. At the present mo- ment it is not possible to expand the buffers to a larger size. EFFICIENCY The underlining options have an effect on the effi- ciency 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 18 Nov 1985 Building Bonner Lab Runoff Page 9 ALL OPERATING SYSTEMS underlining. /UL:N (/U:N) is of course the most efficient, but at the cost of losing the underlining capability. The RSX, RT versions all use overlays to conserve memory. The overlay structure places all of the commonly used routines and the hyphenation routine in the same over- lay. 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 max- imum 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 substi- tutions are defined, the non overlaid version will also probably do the job. 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. One way of increasing the efficiency of RUNOFF is to turn off autohyphenation. This will prevent excessive over- lay switching as well as eliminating some code. For RUN- OFF.DOC turning off hyphenation only decreased the time by about 6%. One more way to increase efficiency is to in- crease 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 ex- isting 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, P/OS and IAS systems. It should run on RSTS under RSX emulation. It has not been tried on unmapped systems. DOCUMENTATION 18 Nov 1985 Building Bonner Lab Runoff Page 10 ALL OPERATING SYSTEMS The documentation comes in 3 sizes regular, small, and micro. The regular occupies nearly 700 blocks of disk space while the small is under 200 blocks. The micro (under 70 blocks) is designed as a small pocket guide to RNO. It may be necessary to modify the documentation to ac- comodate 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 out- put format preference. Currently the output occupies a page size of 62 by 79 with /UL:S (/U:S) for underlining. HELP FILES Three help files are available with Bonner Lab Runoff for 2 operating systems, VAX/VMS and RSX. RUNOFF.HLP con- tains nearly the entire contents of the manual. If you are short on disk space you may not be able to use it so as al- ternatives BRIEF.HLP and MICRO.HLP are considerably smaller. 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. TEST FILES The primary test of RUNOFF are the document and help files which you produce after building RNO. In addition 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 in- ternal errors or bombs. A partial guide to these is: 1. COMAND.tst - How to define commands. 2. DISPLA.tst - Demonstrates display command on VT100 terminal. 3. LEVEL.tst - Demonstrates header levels. 4. DISLEV.tst - Demonstrates header levels modified by display commands. 5. LIST.tst - Demonstrates the .LIST command. 6. DISLST.tst - Demonstrates the .LIST command modi- fied by .DISPLAY. 7. CHAPT.tst - Demonstrates various chapter styles. 8. EQATN.TST - Demonstrates the equation formatting. 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 il- lustrates their useage. I have tried to keep common usage, but since some of these files are by other authors, not all escape sequences are accessed by the same flag characters. These are: 1. GREEKMATH - Defines mathematical symbols for a Florida Data printer. The same ones should work on a Diablo printer. 18 Nov 1985 Building Bonner Lab Runoff Page 11 TEST FILES 2. VT100 - Defines some VT100 escape sequences to pro- duce bolding and underlining. 3. DIABLO - Define some sequences for Diablo style printers. 4. LA50 - Defines some escape sequences for an LA-50 printer. 5. CIT161 - Defines sequences for a CIT-121 color ter- minal. 6. SPIN - Defines sequences for a spinwriter.