RUNOFF INTERNALS Page 1 RUNOFF INTERNALS This is a quick guide to RUNOFF for those who wish to modify it. It is in- tended as a guide, and not a complete explanation. The novice programmer should confine changes to those documented in the BUILD file. Since all mod- ules are heavily commented, the comments are a more detailed guide. MACRO modules 1. RNODYN - Dynamic memory routines that store character strings for use by RUNOFF. The routines essentially simulate a sequential file ac- cessed by record number. 1 Record = 1 byte You should learn how these routines work it you wish to implement changes. 2. FMTCM - All special purpose routines to format output, including chapters, lists, notes, and header levels. 3. GCIN - All character interpretation routines. 4. RUNOFF - Main program with line formatting routines, and input parameter parsing routines. 5. CMTAB - Command tables - defines commands and routines they call. 6. COMND - Command parser. 7. ERMSG - Error message routines and messages. 8. HYPHEN - Autohyphenation routine 9. ESCAPE - All DEFINE, DELETE, RESET commands. 10. INDEX - Indexing routines. 11. INIT - General initialization and all flags commands. 12. PINDX - Index printing routines. 13. RNCMD - General purpose commands- skip, page, indent, footnote, text etc. 14. RNORSX - RSX I/O tables. 15. RSXIO - I/O routines for RSX. 16. RTIO - RT-11 I/O routines. 17. RNORT - RT-11 startup, command line parsing, and .REQUIRE commands. 18. START - RSX startup, file parsing routines, command line parsing, and .REQ commands. RUNOFF INTERNALS Page 2 19. STYLE - Most style, layout, and display commands. Structure of program 1. Certain register conventions are used throughout: R0 - is completely volatile. Unless otherwise stated, it can not be trusted on return from subroutines. R1 - is completely volatile. It is often used to be the current character. R2 - is preserved in general across subroutine calls unless otherwise stated. R3 - points to a header for a buffer chain as defined in RNODYN. R4 - is preserved. It points to the numeric input routines when a com- mand interpretation routine is called. R5 - is preserved across calls. C - is generally clear if the call is ok, and set if not. The command interpretation routines are not assumed to save or restore any registers, so they have free use of all registers. Not all routines use consistent conventions, because this version of RUN- OFF evolved from an older version from DECUS. 2. A stack structure, used for all input, is the heart of this program. A set of headers are used to point to various places in the input. Whenever a substitution is made, the stack depth increases by 1 header. Some routines, such as the chapter routine, call SETINS to increase the stack depth and then add strings to input; then stan- dard routines are used to format the output. There is a big trap for the unwary here. When the stack depth is increased, the user may add data to the end of input, and when the stack depth is decreased, the added data evaporates. At stack depth 0 only the input line read from the input file is available, but at higher stack depths the substitution buffer is used as input. 3. The character width is now variable. To get the width you should use the character width routines in GCIN. 4. The number conversion routines accept input on the stack. These routines want to find a series of numbers terminated by a zero word. The output is put into the buffers pointed to by R3. 5. All input is parsed to discard all control characters except for TAB, CR, and LF. Each input line ends with CR,LF. Fake input may end with only LF. 6. The input interpretation in GCIN is table driven. There is a set of tables defining the characteristics of each character. The charac- teristics table defines autobreak, flags, period, and underlinable characters. Characters are marked as available as non-alphanumeric, and as to availability for use as a flag. Another table defines the disposition of each character. The disposition table points to a vector table that dispatches to a specific routine. The disposition table is modifiable by the FLAGS commands. The definition table is RUNOFF INTERNALS Page 3 modifiable by the FLAGS, PERIOD, AUTOBREAK, AUTOHYPHENATE, and UNDER- LINE commands. Upper/lowercase characters are distinguished by the entries in the disposition table. 0 and 2 mark the possible values. All values are symbolic. Two values are used in the disposition table: negative and positive. Positive defines allowed input characters, negative defines characters that trigger an action on output, and are not printed. This keeps the table sizes small, though the program is a little slower. An additional table of character widths has been added to facilitate proportional fonts. 7. Most error messages call ERMSG, except when overlay switching could be fatal. Then imbedded messages are used. ERMSG contains error messages, and since it is in a separate overlay, the messages are only available when ERMSG is called. 8. The initial stack pointer is saved, and periodically restored. After each fatal error and before each new line of input it is restored. This simplifies stack cleanup. 9. If you make major changes in RUNOFF, you should enable the symbol $DEBUG. This attempts to catch bugs by checking the dynamic buffer structure in RNODYN. In addition, it creates a routine called CHROUT that will display the current value of R1. You can then sprinkle calls to CHROUT in your routines to view the character being handled. 10. All changes should use the defined macro calls so the resulting ver- sion is compatible across operating systems. MACRO-16 with extra de- finitions is used and translated to MACRO-32 for the VAX.