SUMMARY OF CHANGES MADE TO RUNOFF (version M3.0) ------------------------------------------------ This document highlights the changes which have been made to DECUS RUNOFF (version M02) to achieve version M3.0. A brief comparison with the current DECUS library version (M02.4) can be found on the last page. The RUNOFF manual has been revised to reflect these changes. Thus, you can refer to it for further details on most of the changes listed here. NEW FEATURES 1. Can now have up to three tables of contents created. One of them can be created automatically from chapter, section and appendix titles. The other tables are intended for figures and tables, and must be created with explicit commands in the input file. 2. 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 an /INC value. 3. New ALTERNATE [] command causes odd-numbered pages to be shifted to the right spaces. The initial setting is NO ALTERNATE . If is omitted, it defaults to zero. 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.) 4. New ALTERNATING TITLE command causes 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. Even if invoked, this command has no effect unless ALTERNATE is in effect. 5. New BLOCK command makes it possible to have segments of the input appear contiguous in the output even if that requires waiting until a later page in the output document. If deferral is necessary, the current output continues to fill normally. (This is for tables.) 6. 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.) 7. Multiple input files can now be specified. All parameters are unchanged between consecutive input files. The processing of any input file after the first one effectively begins with a BREAK. 8. 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. 9. 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. SUMMARY OF CHANGES TO RUNOFF Page 2 New Features 10. New /AP switch added to allow output to be appended to an existing file. The appended material starts a new page. 11. New LAYOUT 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. 12. New /DO , /LO , /LE , /WI switches allow the LAYOUT parameters to be set via the command line (overriding settings within the input). 13. New ENTRY command is similar to the INDEX command except that it does not cause a page number to be output (see below). 14. Subindexing can be specified. As an example, the commands .entry Maid .index Main>minor1 .index Main>minor1>minor2 will produce these index entries (using default indentation) Maid Main minor 1 . . . . . . . . . . . . . minor 2 . . . . . . . . . . . . 15. New AUTOSUBTITLE [] command causes HEADER LEVEL commands up to the given level automatically to set subtitle. (Level value of zero disables automatic setting of subtitle [initial setting].) 16. RUNOFF now exits with status--success, warning, error, or severe error. 17. Can now selectively include or exclude segments of the input file based on setting of "switches". Related commands are: 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 /IN and /EX switches permit setting options from the command line. SUMMARY OF CHANGES TO RUNOFF Page 3 New Features 18. New RIGHT JUSTIFY [][,] command forces the text (or the next line) against the requested column (defaults to the right margin). can be a signed value to indicate an offset relative to the current right margin. 19. New FOOTNOTE LINE [][,][] command provides for having footnotes automatically set off from the body of the text by a blank line and a line with characters . (The initial condition is equivalent to "FOOTNOTE LINE 15,_".) 20. 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). 21. New /CH:m:n switch limits the output to chapters m through n , inclusive. 22. New TEST LINES command has the same syntax and function as the old TEST PAGE command, but does not consider the current SPACING. 23. New QUOTE CHARACTER [] command allows the user to set the special character to be used as the quote character. If no character is provided, the default ("_") is selected. 24. "!" 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. 25. 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:). The default is currently 7 lines (it was 12). 26. 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. ENHANCEMENTS TO EXISTING FEATURES 1. Added arguments to the TEST PAGE command to control the number of lines output together at the _e_n_d of a group of lines. 2. Changed the TEST PAGE command and related functions of the LIST ELEMENT and PARAGRAPH commands 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. Added arguments to the PARAGRAPH command to control the number of lines output together at the _e_n_d of a paragraph. SUMMARY OF CHANGES TO RUNOFF Page 4 Feature Enhancements 4. Made PARAGRAPH permissible in footnotes (default arguments are saved/restored). 5. Added a text argument to the FIGURE command to make it possible to have a caption output with the figure space even if it is deferred. 6. Made the level parameter optional in the HEADER LEVEL command. 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. Expanded the meaning of the "=" character to include specification of hyphenation points to be used instead of those RUNOFF would pick. Then, 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. 8. Made "=" work even if "word" begins with non-alphabetic character. 9. Modified hyphenation to have words which are already hyphenated (e.g., "even-numbered") broken at the hyphen (and only there or at any other user-specified points) if necessary. 10. Added the ability to set characteristics of the hyphenation algorithm when the task file is built. 11. The SKIP and BLANK commands now allow negative arguments to move down to that many lines from the bottom of the page. 12. Added a warning message which 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.) 13. Added "BLANK" HEADER type in which the word "Page" is not output. 14. Added size parameters to the HEADER command to set the left and right margins of page headers and the height of headers. 15. Added /HL switch to allow header length to be set via command line. 16. The header right margin is set by the PAGE SIZE and LAYOUT commands (the latter only when its width parameter is provided). 17. Put two spaces after "", where is ".", "!", or "?" and is ")", "]", "}", or double quote. SUMMARY OF CHANGES TO RUNOFF Page 5 Feature Enhancements 18. Tab settings and AUTOPARAGRAPH mode are saved when footnotes are started and restored when normal text is resumed. 19. Added control of the white space between index letter groups. 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. 20. Made index storage more efficient by ignoring duplicate entries on an output page. 21. Fixed output of page references in the index so the right margin is not exceeded. Now a new line is started if there are too many page references to fit on one line. 22. Changed the NOTE command to accept the margin change as an optional command argument. If the argument is omitted, the margins are always reduced by five spaces. (The new syntax is compatible with the old syntax.) 23. Added an optional argument to the END NOTE and END LIST commands to specify the number of lines to skip. 24. Added a parameter 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. 25. Added a new error message 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. 26. Added an error check to NUMBER CHAPTER for argument less than or equal to zero. NUMBER CHAPTER accepts argument up to 128. 27. CHAPTER now turns on page numbering. 28. Expanded the scope of STANDARD to reset the tab stops, and the spacing and test-page parameters of LIST, LIST ELEMENT and PARAGRAPH commands. BUGS CORRECTED 1. Page numbers are now justified against the header right margin (e.g., as set by a PAGE SIZE command) rather than the local right margin. 2. Fixed quoted space so that "# " has the same effect as " #". 3. Changed format of header levels 3 up from "text - " to "text -- ". SUMMARY OF CHANGES TO RUNOFF Page 6 Bugs Corrected 4. Too many blank lines were output if a HEADER LEVEL command immediately followed a CHAPTER or APPENDIX command. 5. Fixed index creation: (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). 6. Fixed output of index 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). 7. Fixed the problem of having a new page started at the end of a chapter or appendix when there is no more text in that section (i.e., the last page is completely full). 8. Corrected page break when SPACING is greater than 1. (Eliminated output of blank lines at bottom of pages.) 9. Changed processing of command arguments so that a distinction is correctly made between no numeric argument provided (in which case a default is often used) and an explicit zero value is provided. 10. Fixed bug in SET TABS which prevented the tab table from being completely filled. Added check of new stops to make sure they are in ascending order. 11. Modified the FIGURE command so it 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 appearance in the input file.) 12. Fixed subpage processing so multiple subpages can be output after a SUBPAGE command. END SUBPAGE correctly terminates subpages and returns to normal page numbering. 13. Corrected spacing of index entries with underlining. (Note, however, that such entries may not be put in the correct order.) 14. Reworked footnote processing, fixing variety of bugs. 15. Corrected the test for too many nested lists. 16. Added NO FLAGS to command table--it was missing. 17. The last line of a paragraph used to be justified sometimes. SUMMARY OF CHANGES TO RUNOFF Page 7 Bugs Corrected 18. Fixed problem with AUTOPARAGRAPH which caused paragraph separation to be output twice if PARAGRAPH command was followed by either a blank line or a line starting with a space or tab while AUTOPARAGRAPH mode was in effect. 19. Ignore extra blank lines and formfeeds in AUTOPARAGRAPH mode. 20. Check argument input with /UL switch. Assume "N" if arg. is invalid. 21. Clear appendix letter when CHAPTER processed in case an APPENDIX or NUMBER APPENDIX has been processed. FEATURES CHANGED 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. Default HEADER type changed to "MIXED". 5. 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. 6. Made 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. 7. Made DO INDEX and PRINT INDEX commands not permitted when a NOTE is in process: 8. Made the following commands not permitted when a FOOTNOTE is in process: NUMBER, NO NUMBER, NUMBER APPENDIX, NUMBER CHAPTER. 9. Changed the PARAGRAPH command to assume 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. 10. Changed NUMBER to take the actual new page number as its argument. NUMBER now accepts a relative argument. SUMMARY OF CHANGES TO RUNOFF Page 8 Features Changed 11. Changed maximum title and subtitle lengths to 80 characters (were each 132). 12. Made changes to LITERAL processing to make it more "literal." In particular: 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. When END LITERAL is processed, blank lines are output. 13. Automatically do a DO INDEX at the end of the file if there is anything in the index buffer. 14. Eliminated the FIRST TITLE command. 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 costs 22 words of index buffer space. 15. Eliminated the blank page which was output at the end of the DOC file. MISCELLANEOUS CHANGES 1. Made command syntax 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, semicolon, carriage return (the text is assumed to start immediately after the separator when either a semicolon or carriage return is used). 2. Changed default page header to start on line 1. Added a blank line to the header. 3. Changed command scanner to ignore white space between words of command names. Can now type command names with multiple (or no) spaces/tabs between words. SUMMARY OF CHANGES TO RUNOFF Page 9 Miscellaneous Changes 4. Made multi-part error messages appear on one line. Changed error messages to mixed case. 5. The FOOTNOTE command can now be followed by other commands on the same line. 6. Expanded checks for valid parameter values for the LEFT MARGIN, INDENT and RIGHT MARGIN commands, and the indent parameter for the PARAGRAPH command. The current criteria are 0 <= lm < rm and 0 <= (lm + i) < rm 7. Never underline underbar characters from the input (to prevent double strike). 8. Made PAGE SIZE parameters available at task build as claimed in the manual. COMPARISON BETWEEN RUNOFF VERSIONS M02.4 AND M3.0 The current DECUS library version of RUNOFF was developed while the work toward version M3.0 was in progress. Unfortunately, there was no link between the two efforts. 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 M3.0. 1. M3.0 does _n_o_t support use under RT-11. 2. M3.0 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 M3.0 can also report "warning" and "severe error". 2. Version M02.4 incorporated changes in the processing of hyphenation. Version M3.0 makes most of those changes available for specification during task build.