_R_U_N_O_F_F Version S1.4 Submitted by Charles H. Spalding III Adept Technology, Inc. 1202 Charleston Road Mountain View, CA 94043 This document highlights the changes which have been made to DECUS RUNOFF (version M02) to achieve version S1.4. A brief comparison with DECUS library version M02.4 (program 11-530) can be found on the last page. (Note: Version M02.4 was independently derived from M02. Thus, most of the changes described below are not present in M02.4.) The RUNOFF manual has been updated to reflect these changes. Thus, you can refer to it for further details on most of the changes listed here. This version of RUNOFF is currently supported by the RUNOFF Working Group of the RSX Special Interest Group (SIG). The Working Group intends to continue to add features to RUNOFF, and thus encourages user inputs about existing and desired features. Such inputs can be given to the submitter at the address shown above. _N_E_W _F_E_A_T_U_R_E_S 1. Up to three tables of contents can now be created. One of them can be created automatically from chapter, section and appendix titles. The other tables are intended for figures and tables, respectively, and are created with explicit commands. 2. New ALTERNATE command can be used to shift odd-numbered pages to the right a specified number of spaces. The initial setting is NO ALTERNATE . When ALTERNATE is active, the page numbers and titles appear on alternate sides of the pages. (These features are intended for output to be reproduced on both sides of the page.) 3. New ALTERNATING TITLE command can be used in conjunction with ALTERNATE to cause the title to be output right justified on even- numbered pages and the subtitle to be output left justified (on the top line) on odd-numbered pages. 4. New EVEN and ODD commands force the output to an even-numbered or odd-numbered page, respectively. (For example, to make chapters begin on right-hand pages.) SUMMARY OF RUNOFF (S1.4) Page 2 New Features 5. New PAGE FORMAT command sets top margin, page length, base left margin and default right margin. The left and right margins are now defined relative to the base left margin. 6. New switches allow the PAGE FORMAT parameters to be set via the command line (overriding settings within the input). 7. New BLOCK command makes it possible to have segments of the input (such as a table) appear contiguous in the output even if that requires waiting until a later page. If deferral is necessary, the output continues to fill normally. 8. Secondary input files can now be included by commands in the input file (REQUIRE & CHAIN). (RSX only) 9. Multiple input files can now be specified on the command line. All parameters are unchanged between consecutive input files. The processing of any input file after the first one effectively begins with a BREAK. 10. New LEVEL STYLE command sets the number of blank lines which will precede each level of section header, the number of text lines which are required to fit on the page, and the level at which the headers change to the "run-in" style. 11. New ENTRY command is similar to the INDEX command except that it does not cause a page number to be output (see below). 12. Subindexing can be specified. As an example, the commands .index Main>minor1 .entry Maid .index Main>minor1>minor2 will produce these index entries (using default indentation) Maid Main minor 1 . . . . . . . . . . . . . minor 2 . . . . . . . . . . . . 13. New AUTOSUBTITLE command causes HEADER LEVEL commands up to a specified level automatically to set the subtitle. 14. Can now selectively include or exclude segments of the input file based on settings of "switches". Related commands are: SUMMARY OF RUNOFF (S1.4) Page 3 New Features INCLUDE -- Turns on switch EXCLUDE -- Turns off switch OPTION -- Marks start of optional segment ELSE -- Inverts logic of active option END OPTION -- Marks end of optional segment Options can be nested to any depth, with "excluded" options overriding any inclosed "included" options. (Currently up to 32 switches are allowed.) Negative logic applies if a negative option number is supplied. New switches (/IN and /EX) permit setting options from the command line. 15. New RIGHT JUSTIFY command forces given text (or the next input line) against a requested column (defaults to the right margin). 16. New FOOTNOTE LINE command provides for having footnotes automati- cally set off from the body of the text by a blank line and a line with a specified number of a given character. (The initial setting causes a line with 15 underbar characters.) 17. New PAGE NAME command sets a name to be used as the prefix for page numbers (in place of a chapter number or appendix letter if there is one). 18. New switch (/CH:m:n) limits the output to chapters m through n , inclusive. 19. New TEST LINES command has the same syntax and function as the old TEST PAGE command, but does not consider the current SPACING. 20. New QUOTE CHARACTER command allows the user to set the special character to be used as the quote character. 21. "!" is now a comment flag. Appearance of exclamation mark on command line terminates command and causes remainder of line to be ignored. Also, any line beginning with a "!" is now ignored. 22. New ENABLE and DISABLE commands control various functions. For example, index and contents accumulation and writing to the output file can be turned off and on. The RUNOFF special characters (e.g., "^", and "&") can be disabled for literal processing. 23. The task can now expand itself to increase the index/footnote buffer as required. Thus, it is no longer necessary to install or run RNO with a /INC value. 24. Command-line switches are now processed from left to right, and they are now "sticky." That is, once a switch is applied, its effect continues until explicitly changed. SUMMARY OF RUNOFF (S1.4) Page 4 New Features 25. New switch (/AP) allows the output to be appended to an existing file. The appended material starts a new page. 26. RUNOFF now exits with status--success, warning, error, or severe error. (RSX only) 27. The number of blank lines output ahead of chapter and appendix headings has been made a variable which can be set at task build, and can be set with a command-line switch (/BL:n). The default is currently 7 lines (it was 12). _E_N_H_A_N_C_E_M_E_N_T_S _T_O _E_X_I_S_T_I_N_G _F_E_A_T_U_R_E_S This section describes changes to features of version M02. In many cases new arguments have been added to existing RUNOFF commands. In all those cases, the new arguments are optional and the old command syntax can still be used. 1. Arguments added to the TEST PAGE command to control the number of lines output together at the _e_n_d of a group of lines. 2. The TEST PAGE command (and related functions of the LIST ELEMENT and PARAGRAPH commands) is changed to consider the current SPACING. That is, these commands now check whether there is space for lines of _t_e_x_t rather than simply lines in the output. 3. Arguments added to the PARAGRAPH command to control the number of lines output together at the _e_n_d of a paragraph. 4. PARAGRAPH is now permissible in footnotes (default arguments are saved/restored). 5. Text argument added to the FIGURE command to make it possible to have a caption output with the figure space even if it is deferred. 6. The level parameter in the HEADER LEVEL command is now optional. It defaults to the current level (initially 1). The argument can also now be relative (i.e., a signed number). By making all level specifications relative (e.g., default or "+0" for the current level or "+1" for the next level) the insertion and removal of levels is simplified. 7. The meaning of the "=" character is expanded to include specifi- cation of hyphenation points to be used instead of those RUNOFF would pick. Thus, when activated by the FLAGS HYPHENATE command, one can use "=" to indicate desired hyphenation points as well as to disable completely hyphenation for a word. SUMMARY OF RUNOFF (S1.4) Page 5 Feature Enhancements 8. "=" now works even if "word" begins with non-alphabetic character. 9. Hyphenation modified to have words which are already hyphenated (e.g., "even-numbered") broken at the hyphen if necessary, and only there or at any other user-specified points. 10. Can now set some characteristics of the hyphenation algorithm when the task file is built. 11. Optional argument added to the HYPHENATION command to allow control of the extent to which hyphenation is done. 12. The SKIP and BLANK commands now allow negative arguments to move down to that many lines from the bottom of the page. 13. A new warning message is output to the user if footnotes over fill a page, or if more than two blank lines are left at the bottom of a page after footnotes are output. (The manual claimed that if there isn't room on the current page for the requested footnote space, it would be put on the next page. This is not true--the page just ends up being very long.) 14. "BLANK" HEADER type suppresses the word "Page". 15. Size parameters added to the HEADER command to set the left and right margins of page headers and the length of headers. (/HL switch added to allow header length to be set via command line.) The header right margin is set by the PAGE SIZE and PAGE FORMAT commands (the latter only when the width parameter is provided). 16. Two spaces are now put after "", where is ".", "!", or "?" and is ")", "]", "}", or double quote. 17. Tab settings and AUTOPARAGRAPH mode are saved when footnotes are started and restored when normal text is resumed. 18. Control of the white space between index letter groups has been added. For the DO INDEX command, the number of lines output between groups is set by the SPACING command. For the PRINT INDEX command a new parameter specifies the additional lines to be output between groups and the index entries themselves are spaced per the SPACING command. 19. Index storage has been made more efficient by completely ignoring duplicate entries on the same output page. 20. The right margin is not exceeded by page references in the index. A new line is started if there are too many page references to fit on one line. SUMMARY OF RUNOFF (S1.4) Page 6 Feature Enhancements 21. The NOTE command is changed to accept the margin change as an optional command argument. If the argument is omitted, the margins are always reduced by five spaces. 22. Optional skip argument added to the END NOTE and END LIST commands to specify the number of lines to skip. 23. Parameter added to the LIST command to provide the ability to have the list elements set off by a specified character (e.g., "-" or "o" [pseudo bullet]) instead of being numbered. 24. New error message added to differentiate between different types of "ILLEGAL COMMAND" errors. That is, between unknown command or one not accepted in the current context, and an invalid command parameter. 25. An error check has been added to NUMBER CHAPTER for an argument less than or equal to zero. NUMBER CHAPTER accepts argument up to 128. (The code is available to allow chapter numbers up to 256.) 26. CHAPTER now turns on page numbering. 27. The scope of STANDARD is expanded to reset the tab stops, and the spacing and test-page parameters of the PARAGRAPH, LIST and LIST ELEMENT commands. _B_U_G_S _C_O_R_R_E_C_T_E_D 1. Page numbers are now justified against the header right margin (e.g., as set by a PAGE SIZE command) rather than the local text right margin. 2. Quoted space is fixed so that "# " has the same effect as " #". 3. Too many blank lines were output if a command which starts with blank lines (e.g., HEADER LEVEL, PARAGRAPH and NOTE) immediately follows a command which ends with blank lines (e.g., CHAPTER, HEADER LEVEL and END NOTE). 4. Fixed the problem of having a new page started at the end of a chapter or appendix even when there is no more text in that section (i.e., the last page is completely full). 5. Corrected page break when SPACING is greater than 1. (Eliminated output of blank lines at bottom of pages.) 6. Processing of command arguments now correctly distinguishes between no numeric argument provided (in which case a default is often used) and an explicit zero value provided. SUMMARY OF RUNOFF (S1.4) Page 7 Bugs Corrected 7. The FIGURE command now works as claimed in the manual. That is, if there isn't room on the current page, it continues to be filled and the figure space is put on the next page. If there are pending figures when an APPENDIX, CHAPTER, DO INDEX, EVEN, or ODD command is encountered or the end of the input is reached, the figure allocations are all done. (Figures are always output in the order of their appearance in the input file.) 8. Bug in SET TABS used to prevent the tab table from being completely filled. (Check of new stops added to make sure they are in ascending order.) 9. Subpage processing has been fixed so multiple subpages can be output after a SUBPAGE command. END SUBPAGE correctly terminates subpages and returns to normal page numbering. 10. Subpages are now correctly referenced in the index. 11. Index creation is fixed: (1) entry longer than 52 characters used to overwrite code (now truncated to 50 characters); (2) entry longer than 50 characters did not get a page reference; (3) occurrences of entries differing only by case were not handled correctly (".x a" ... ".x A" ... ".x a" used to result in three entries in the index). 12. Output of the index is fixed so white space between letter groups is never output at the top of a new page. A TEST PAGE is done before the start of each letter group (currently the test count is three). 13. The spacing of index entries with underlining is now correct. (Note, however, that such entries may not be put in the correct alphabetical order.) 14. Footnote processing has been reworked, fixing a variety of bugs. 15. The format of run-in header levels has been changed from "text - " to "text -- ". 16. The test for too many nested lists was wrong. 17. The NO FLAGS command was missing from the command table. 18. The last line of a paragraph used to be justified sometimes. 19. AUTOPARAGRAPH used to cause the paragraph separation to be output twice if a PARAGRAPH command was followed by either a blank line or a line starting with a space or tab while AUTOPARAGRAPH mode was in effect. SUMMARY OF RUNOFF (S1.4) Page 8 Bugs Corrected 20. Extra blank lines and formfeeds are now ignored in AUTOPARAGRAPH mode. 21. The argument input with the /UL switch is now checked. "N" is assumed if the argument is invalid. _F_E_A_T_U_R_E_S _C_H_A_N_G_E_D 1. JUSTIFY now always turns on FILL. Reasoning: (1) it doesn't make much sense to justify without filling, (2) it was discouraged in the manual, and (3) it did not work correctly! 2. Hyphenation is not disabled when justification is turned off. 3. Eliminated automatic double space after semicolon. 4. The default HEADER type has been changed to "MIXED". 5. The default page header now starts on line 1. A line has been added to the default header length. 6. SPACING is now set to the default value (single spacing) within footnotes. The specified footnote length is no longer multiplied by the text line spacing. 7. Several changes to LIST commands: (1) Save vertical spacing and test-page count when nested list begins and restore when it ends; (2) do test page for LIST ELEMENT after skipping lines; (3) default test-page count changed from 2 to 1 [to compensate for change (2)]; (4) fix incorrect indent of first line when text followed command on next line; (5) adjust negative indent for list element numbers greater than 9. 8. DO INDEX and PRINT INDEX commands are not permitted when a NOTE is in process. 9. The following commands are not permitted when a FOOTNOTE is in process: NUMBER, NO NUMBER, NUMBER APPENDIX, NUMBER CHAPTER. 10. The PARAGRAPH command now assumes a previous test-page value if none is supplied. (The command used to ignore test page if no value was given.) Also changed the internal sequence so that lines are skipped before the test page is done. 11. NUMBER now takes the actual new page number as its argument; now accepts a relative argument. 12. Maximum title and subtitle lengths are now 80 characters (were each 132). SUMMARY OF RUNOFF (S1.4) Page 9 Features Changed 13. Changes to LITERAL processing to make it more "literal": LITERAL now saves the current line spacing and temporarily sets it to one so that the following text will in fact be processed literally. The previous spacing is restored when the END LITERAL command is processed. Temporarily set the right margin to 132 to prevent RUNOFF from breaking lines which exceed the normal right margin during processing of LITERAL sections. The right margin is restored when END LITERAL is processed. If an output line exceeds the normal right margin, a warning is output to the user's terminal. Formfeeds (i.e., page marks) in the input file cause new output pages to be started. When END LITERAL is processed, blank lines can be output (the code is in place but not currently assembled in). 14. DO INDEX is automatically done at the end of the file if there is anything in the index buffer. 15. The FIRST TITLE command has been eliminated. Reasoning: (1) it has never worked correctly (it does now, if included), (2) it doesn't provide a vital function (its effect can be achieved easily by other means), (3) it cost 22 words of index buffer space. 16. The blank page which was output at the end of the DOC file has been eliminated. _M_I_S_C_E_L_L_A_N_E_O_U_S _C_H_A_N_G_E_S 1. Command syntax is now the same for all commands with similar argument combinations. E.g., commands with numeric arguments can have them separated by white space with or without a comma; commands with a numeric argument and a text argument can have any of the following for separators: none, white space, comma, semi- colon, or carriage return (the text is assumed to start immediately after the separator when either a semicolon or carriage return is used). 2. The command scanner now ignores white space between words of command names. Thus, you can now type command names with multiple (or no) spaces/tabs between words. 3. Multi-part error messages now appear on one line. Error messages are output in mixed case. SUMMARY OF RUNOFF (S1.4) Page 10 Miscellaneous Changes 4. The FOOTNOTE command can now be followed by other commands on the same line. 5. The checks for valid values for the left margin (lm), right margin (rm), indent (i) and paragraph indent (p) have been expanded. The current criteria are for lm, rm: 0 <= lm < rm for lm, rm, i: 0 <= (lm + i) < rm for p: 0 <= (lm + p) < rm 6. Underbar characters from the input are never underlined (to prevent double strike). 7. The default PAGE SIZE parameters are now available at task build as claimed in the manual. _C_O_M_P_A_R_I_S_O_N__B_E_T_W_E_E_N__R_U_N_O_F_F__V_E_R_S_I_O_N_S__M_0_2_._4__A_N_D__S_1_._4 The following points appear from the M02.4 documentation to cover the new features in version M02.4 which are _n_o_t supported by version S1.4: 1. S1.4 does _n_o_t support use under RT-11. 2. S1.4 does _n_o_t support the "raw text" feature of M02.4. The following differences exist in the implementations of features present in both versions: 1. The exit status reported by M02.4 is either "success" or "error." Version S1.4 also reports "warning" and "severe error." 2. Version M02.4 incorporated changes in the processing of hyphen- ation. Version S1.4 makes most of those changes available for specification during task build.