RUNOFF Documentation Preparation Program - User's Manual - Program Version: M3.0 Program Revision 16 April 1983 Document Revision 16 April 1983 Contributed by Charles H. Spalding III 1202 Charleston Road Mountain View, CA General permission to copy (but not for profit) is hereby granted pro- vided that reference is made to the fact that reproduction privileges were granted by DECUS. The information in this document is subject to change without notice and should not be construed as a commitment by the contributor, DECUS or Digital Equipment Corporation. No warranty, expressed or implied, is made by the contributor, DECUS or Digital Equipment Corporation as to the accuracy of this document or the functioning of the described software and related material, and no responsibility is assumed by these parties in connection therewith. The described software is currently supported by the contributor as the RUNOFF Working Group of the DECUS RSX Special Interest Group, but con- tinuance of that support is not assured. Thus, if you are responsible for implementation of this system, you may have to understand and modify the source code if you encounter problems in implementing or maintaining the software. DECUS, IAS, RSTS and RSX are trademarks of Digital Equipment Corp. CONTENTS 1.0 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 1.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . 1-2 1.2 NOTATION . . . . . . . . . . . . . . . . . . . . . . . . 1-2 2.0 INPUT FILE FORMAT . . . . . . . . . . . . . . . . . . . . . . 2-1 2.1 SPECIAL CHARACTERS . . . . . . . . . . . . . . . . . . . 2-2 3.0 RUNOFF COMMANDS . . . . . . . . . . . . . . . . . . . . . . . 3-1 3.1 COMMAND SYNTAX . . . . . . . . . . . . . . . . . . . . . 3-1 3.1.1 Numeric Arguments . . . . . . . . . . . . . . . . 3-1 3.1.2 Text Arguments . . . . . . . . . . . . . . . . . 3-2 3.1.3 Optional Arguments . . . . . . . . . . . . . . . 3-2 3.1.4 Initial and Default Values . . . . . . . . . . . 3-3 3.2 PAGE FORMAT COMMANDS . . . . . . . . . . . . . . . . . . 3-3 3.3 PAGE HEADER COMMANDS . . . . . . . . . . . . . . . . . . 3-5 3.4 PAGINATION COMMANDS . . . . . . . . . . . . . . . . . . 3-8 3.5 MODE SETTING COMMANDS . . . . . . . . . . . . . . . . . 3-11 3.6 TEXT FORMATTING COMMANDS . . . . . . . . . . . . . . . . 3-16 3.7 DEFERRED-OUTPUT COMMANDS . . . . . . . . . . . . . . . . 3-21 3.8 INDEX PROCESSING COMMANDS . . . . . . . . . . . . . . . 3-27 3.9 TABLE OF CONTENTS COMMANDS . . . . . . . . . . . . . . . 3-29 3.10 OPTIONAL-INPUT COMMANDS . . . . . . . . . . . . . . . . 3-32 4.0 RSX/IAS OPERATING PROCEDURES . . . . . . . . . . . . . . . . . 4-1 4.1 INITIATING RUNOFF . . . . . . . . . . . . . . . . . . . 4-1 4.2 RUNOFF COMMAND STRING . . . . . . . . . . . . . . . . . 4-1 4.2.1 File Specifications . . . . . . . . . . . . . . . 4-2 4.2.2 RUNOFF Switches . . . . . . . . . . . . . . . . . 4-2 4.3 RUNOFF OUTPUT FILE . . . . . . . . . . . . . . . . . . . 4-5 4.3.1 Editing RUNOFF Output . . . . . . . . . . . . . . 4-5 A.0 RUNOFF MESSAGES . . . . . . . . . . . . . . . . . . . . . . . A-1 B.0 PAGE LAYOUT AND MARGIN CONTROL . . . . . . . . . . . . . . . . B-1 B.1 VERTICAL POSITIONING . . . . . . . . . . . . . . . . . . B-1 B.2 HORIZONTAL POSITIONING . . . . . . . . . . . . . . . . . B-2 C.0 CASE INFORMATION . . . . . . . . . . . . . . . . . . . . . . . C-1 D.0 SPECIAL CHARACTERS . . . . . . . . . . . . . . . . . . . . . . D-1 E.0 AUTOMATIC POSITIONING OF CONTENTS . . . . . . . . . . . . . . E-1 F.0 INITIAL AND DEFAULT CONDITIONS . . . . . . . . . . . . . . . . F-1 G.0 ALPHABETICAL LIST OF COMMANDS . . . . . . . . . . . . . . . . G-1 INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I-1 CHAPTER 1 INTRODUCTION RUNOFF (RNO) is a program to facilitate the preparation of typed or printed manuscripts, such as memos, manuals, etc. To use RUNOFF, the user prepares his material on any regular terminal, writing it onto a file using a text editor. The user includes not only the textual material of the document, but also instructions to RUNOFF which deter- mine how the information will appear in the final manuscript. RUNOFF takes the file and reproduces it onto the line printer, the terminal or another file to produce a final copy or final file image. In the pro- cess RUNOFF follows the user instructions embedded in the file, perform- ing such formatting actions as line justification, page numbering and titling, etc. RUNOFF can also perform additional functions such as compilation of an index. The principal benefit of such a program is that documents prepared with it may be easily edited and corrected. Small or large amounts of text may be added or deleted, and unchanged material need not be retyped. After a set of changes, RUNOFF may be run to produce a new output copy which is properly formatted and paginated. Documentation may thus be updated as necessary without requiring extensive retyping or editing. Briefly, the procedure for producing a manuscript using RUNOFF is as follows: 1. Use a text editor to compose the input file, including commands to RUNOFF to control the format of the final manuscript. 2. Apply RUNOFF to the input file, producing an output document. 3. Review the output document for anything which doesn't satisfy you. For example, you can scan the output file with the same text editor that was used to create the input file, or the document can be printed for review. 4. If necessary, edit the _i_n_p_u_t file to change the text and RUNOFF commands. 5. Repeat the above sequence of steps as required to achieve the desired manuscript. INTRODUCTION 1-2 Overview 1.1 OVERVIEW The next chapter describes the format of the input file(s) read by RUNOFF to create the desired output document file. Certain characters which have special significance to RUNOFF are explained. Chapter 3 describes all the RUNOFF commands in detail. The final chapter explains how to use RUNOFF to process input files into formatted document files. That includes the use of command-line switches to con- trol the operation of RUNOFF in ways which may override commands in the input file(s). The appendices include: o A complete list of the messages output by RUNOFF to the user's terminal, o A discussion of the provisions for controlling the page layout and margins of the output document, o A description of how case information can be specified with a terminal capable of only uppercase operation, o A review of the characters with special meaning to RUNOFF, o A list of the initial conditions in effect when RUNOFF execution begins, o A complete list of all RUNOFF commands and their abbreviations. 1.2 NOTATION Two shortened notations are used in this manual. Angle brackets (< >) are used to enclose an item which describes the actual argument to ap- pear. Thus the user can supply the appropriate item in that position when entering the command. Note that these brackets are used in this manual only for clarification and are _n_e_v_e_r to be included as part of a command. Many RUNOFF commands have optional arguments. In the descriptions in this manual, optional arguments are enclosed in square brackets ([ ]). Once again, the square brackets are never included when a command is used. CHAPTER 2 INPUT FILE FORMAT As mentioned above, the input or source file contains the textual material which will appear in the final copy, plus information to speci- fy formatting. Case-control information also may be supplied so that copy can be prepared on a terminal or other such device which can input only uppercase letters (see Appendix C). All command information con- sists of regular ASCII printing characters so that a listing of the input file may be examined if the final copy is not exactly as desired. All material in the input file is taken to be source text except those lines with a period in column one. A line beginning with a period is assumed to contain command information to RUNOFF. The commands must be among those listed in Chapter 3. The commands provide the formatting information, and control various modes of operation. Usually, the text is filled and justified as it is processed. That is, the program fills each line by adding successive words from the source text until one more word would cause the text right margin to be exceed- ed. The line is then justified by making the word spacings larger until the last word in the line exactly meets the text right margin. If desired, the last word on a line can automatically be hyphenated if that will help make the filling more even. You should be aware, however, that RUNOFF's hyphenation algorithm is not perfect. If you want the output document to be correctly literate, you should review all the hyphenations introduced by RUNOFF to make sure they are correct. There is a special character which can be used to either disable hyphen- ation of a specific word, or to specify where a word should be hyphen- ated, if a break is needed. This control must be applied to every word not handled correctly by RUNOFF, which is admittedly inconvenient. The added control characters are transparent, however, so once they are put into the input file they need not be removed if the text changes and an affected word moves away from the margin. The user may occasionally wish to reproduce the source text exactly, which is done by disabling filling and justification or by use of the LITERAL command. The program may be set to fill but not justify, in which case the output will be normal except that lines will not be justified to the text right margin. When fill mode is on, spaces, and carriage returns occurring in the input text are treated only as word separators. Multiple separators are treated as one separator. Thus, material in the input can be entered without concern for its appearance and RUNOFF will take care of making the output document tidy. INPUT FILE FORMAT 2-2 Some of the commands cause a "break" in the output. A break means that the current line is output without justification, and the next word goes at the beginning of the next line. For example, this occurs at the end of paragraphs. The program will advance to new pages as necessary, placing the title (if given) and the page number at the top of each page. The user may call explicitly for a page advance where desired, and may inhibit the occurrence of a page advance within specified material. This manual was prepared with RUNOFF, so you can get an idea how things are formatted by looking at its input file. For example, the page and chapter headings, page numbering, footnotes, notes within the text, lists, the index, etc. were all produced with RUNOFF commands. 2.1 SPECIAL CHARACTERS The following characters have special interpretations whenever they are encountered in an input file. This must always be kept in mind because it is sometimes desired to have these characters appear in the output. The first special character described below is used to achieve that. _ Underbar Quote next character * To allow the appearance of the special characters in the output, the underbar character ("_" [137 octal]) is used as a quote char- acter. That is, the character immediately following an underbar will be transmitted to the output with no formatting effect. The underbar itself is thus another case requiring quoting. The fol- lowing cases can occur: "__", "_&", "_#", "_^", "_\", "_=", "_<" and "_>". # Number Sign Explicit space It is occasionally necessary to include spaces in the text which should not be treated as word separators. For this purpose, RUNOFF treats the number-sign character ("#" [43 octal]) as a quoted space. That is, it will print as exactly one space in the output and will never be expanded nor changed to a carriage return. To have a number sign appear in the printed text, it must be preceded by the quote character ("_#"). _______________ * The QUOTE CHARACTER command can be used to change the character used as the quote character. If the quote character is changed, the new quote character becomes a "special character" and the underbar character ceases to be one. INPUT FILE FORMAT 2-3 Special Characters & Ampersand Underscoring The ampersand character ("&" [046 octal]) is used to specify under- scoring. The ampersand will cause the character following it to be underlined; for example, "&f&o&o" becomes "_f_o_o". Underlining of a string of characters can also be specified in a manner similar to that of a shift-lock operation. An appearance of ampersand preceded by circumflex ("^&") will cause underlining of all following characters except tab, space and underbar. An ap- pearance of ampersand preceded by backslash ("\&") will disable this mode. To have an ampersand appear in the printed text, it must be preceded by the quote character ("_&"). ^ Circumflex Upper-case shift or mode lock The circumflex character ("^" [136 octal]) is used to convert the letter following to uppercase (see Appendix C). It is also used to lock the case mode in uppercase, and the underline mode to "under- line all text." If it is to appear in the printed text, a circum- flex must be preceded by the quote character ("_^"). \ Backslash Lower-case shift or mode unlock The backslash character ("\" [134 octal]) is used to output the letter following in lowercase (see Appendix C). It is also used to lock the case mode in lowercase, and to disable underlining. If it is to appear in the printed text, a backslash must be preceded by the quote character ("_\"). = Equal sign Hyphenation disable/specification If a FLAGS HYPHENATE command has been issued, the equal-sign character ("=" [75 octal]) takes on two functions intended to allow overriding of RUNOFF's hyphenation algorithm. If an equal sign precedes a word, hyphenation is disabled for the word. If an equal sign is embedded within a word, it specifies a point at which the word should be hyphenated if necessary. In the latter case, the word will be hyphenated only at such marked points, or at explicit hyphens in the input. If a FLAGS HYPHENATE command has been issued and an equal sign is to appear in the printed text, it must be preceded by the quote character ("_="). < Less than Capitalize next word If a FLAGS CAPITALIZE command has been issued, the less-than character ("<" [74 octal]) is used to capitalize the entire word it INPUT FILE FORMAT 2-4 Special Characters precedes. Then, if it is to appear in the printed text, a less- than character must be preceded by the quote character ("_<"). > Greater than Subindex next word If FLAGS SUBINDEX is in effect (the initial condition), the greater-than character (">" [76 octal]) is a special character used in ENTRY or INDEX commands to indicate that the following text is to be entered in the index as a subentry under the text preceding the greater-than character. Unlike the other special characters above, the greater-than char- acter can appear in the text without having to use the quote char- acter. In order to have a greater-than character appear in the index, however, one must disable it as a special character with the NO FLAGS SUBINDEX command, or precede the greater-than character with the quote character ("_>"). CHAPTER 3 RUNOFF COMMANDS The commands described in this chapter will be recognized if they are in a command line. Any line in the input file with a period in column one is assumed to be a command line. If a command line is found to contain an invalid command, an error message will be displayed on the user's terminal and the remainder of that command will be ignored. 3.1 COMMAND SYNTAX Commands can be entered in either uppercase or lowercase (for clarity, all commands are shown in uppercase in this manual). Multi-word command names may appear either spaced out or compressed. Thus, for example, both "PAGE SIZE" and "PAGESIZE" are legal. When spaced out, command words can be separated by one or more spaces and/or tabs. Many commands may be abbreviated. Acceptable abbreviations are shown along with the commands in this chapter. In general, more than one command may be entered on a single command line. However, those commands which accept a text argument must be the last command on a line. If multiple commands are on a line, each com- mand must begin with a period. Semicolons may optionally be used to further separate commands. Some commands take one or more arguments. These are separated from the command name by one or more spaces and/or tabs. If a command can have multiple arguments, the arguments can generally be separated by commas, spaces or tabs. (For clarity, commas are used to separate arguments in the command descriptions and examples in this manual.) 3.1.1 Numeric Arguments Numeric arguments are always considered to be decimal values. Some com- mands accept signed numeric arguments. In most cases such signed values are used to modify the current value for the corresponding parameter. For example, ".LEFT MARGIN 5" would set the left margin to five spaces from the left edge of the page, but ".LEFT MARGIN +5" would move the left margin five spaces to the right from its position at the time. RUNOFF COMMANDS 3-2 Syntax The following commands will accept relative numeric arguments: ALTERNATE LEVEL STYLE AUTOSUBTITLE NUMBER CENTER PAGE SIZE CENTRE PAPER SIZE HEADER RIGHT JUSTIFY HEADER LEVEL RIGHT MARGIN LAYOUT STANDARD LEFT MARGIN TAB STOPS 3.1.2 Text Arguments Several RUNOFF commands take a text argument. For example, the TITLE command takes the text string to be used for the title in page headers. Commands which take a text argument cannot be followed by any other com- mand on the same line because the remainder of the line is taken to be the text argument. The text argument is generally assumed to begin with the first non-blank character after the command name (e.g., see the TITLE command) or preceding command argument (e.g., see the CENTER command). However, if a semicolon precedes the text argument, then the text begins immediately after the semicolon. This is useful if you want the text argument to have leading tabs or spaces. Some commands allow the text argument to be placed on the line after the command line--if that is done, a comma is not needed and a semicolon cannot be used. 3.1.3 Optional Arguments Many RUNOFF commands will assume a default value for an argument which is omitted. Thus those arguments are optional. (Recall that optional arguments are shown enclosed in brackets in this manual.) If an option- al argument is omitted, and a subsequent argument for the command is explicitly specified, commas must be provided as required to properly position the arguments. For example, the LAYOUT command has the syntax .LAYOUT [],[],[],[] If only the second and third arguments are to be specified (i.e., the defaults are acceptable for the others), the command can be entered as .LAYOUT ,54,10 Note that a leading comma must be included to properly position the second argument, and no comma is needed after the third argument since no more arguments follow. For commands which take a numeric argument and a text argument: if the numeric argument is optional and is omitted, a comma or semicolon must RUNOFF COMMANDS 3-3 Syntax be used to set off the text only if it begins with a number or sign (i.e., when it could be confused for the numeric argument). 3.1.4 Initial and Default Values _I_n_i_t_i_a_l _v_a_l_u_e_s are assumed for all parameters whenever RUNOFF execution begins. Those values are noted in the descriptions of the commands in this chapter and are summarized in Appendix E. A _d_e_f_a_u_l_t _v_a_l_u_e is assumed whenever an optional argument is omitted from a command. The individual command descriptions describe the default value assumed for each optional argument. 3.2 PAGE FORMAT COMMANDS The following commands are used to set the values of parameters used by RUNOFF while formatting the output document. .LAYOUT [],[],[],[] Sets several parameters for the page layout. The parameters are: Top The number of blank lines to be output at the top of every page before the page header, or text if headers are disabled. Length The total number of lines to be on each page (not counting "top"). Left base The base column from which LEFT MARGIN, RIGHT MARGIN and TAB STOP settings are to be made. Width The default right margin to be used. The initial settings are 0, 56, 0, and 60, respectively. If any parameter is omitted, it remains unchanged. This command also sets the right margins for the text and page headers (see the HEADER command) if the "width" argument is given. That is, the respective right margins are set to if a value is present, otherwise the right margins are not affected. See Appendix B for descriptions of page layout and margins. RUNOFF COMMANDS 3-4 Page Format .PAGE SIZE [],[] .PS [],[] .PAPER SIZE [],[] Sets the size of pages to lines by columns and sets the header and text right margins to . The initial settings are 56,60 and the defaults are the current page length and header right margin, respectively. Also see the /PA switch. (See Appendix B for a further explanation of the parameters.) .SPACING .SP Sets the line spacing. The number can range from 1 to 5, the initial setting is 1. SPACING 1 is like single spacing on a type- writer and SPACING 2 is like double spacing. That is, SPACING 2 puts one blank line between lines of text. .LEFT MARGIN [] .LM [] Sets the text left margin to columns from the base margin set by the LAYOUT command. If "number" has a sign, it is inter- preted as a relative change to the current left margin. The result must be less than the text right margin but not less than 0. The initial setting and the default are both 0. (See Appendix B for a further description of text margins.) .RIGHT MARGIN [] .RM [] Sets the text right margin to columns from the base margin set by a LAYOUT command. If "number" has a sign, it is interpreted as a relative change to the current right margin. The result must be greater than the text left margin. The initial setting is 60; the default is the current width set by a LAYOUT or PAGE SIZE com- mand. (See Appendix B for a further description of text margins.) .TAB STOPS [],[],... .TS [],[],... Sets up to 32 tab stops. The numbers must be greater than 0 and listed in ascending order. The TAB STOPS command clears all exist- ing tabs before setting new ones. The initial tabs are set at eight-column intervals to match the hardware standard. These tabs are at columns 8, 16, 24, 32, 40, 48, ..., 240, and 248. Tab characters in the input are converted to the appropriate number of non-expandable spaces. If there are no space characters to the left of tab characters, they will print out at the appropriate position, even if FILL is on. If LITERAL is on, tabs are not converted to spaces, but are output as tab characters. Tab stops are set relative to the "left base" (see the LAYOUT com- mand) and are independent of the left margin. Any tabs which are less than the left margin will not be seen. If a tab appears at a RUNOFF COMMANDS 3-5 Page Format point where no further tab stops have been set on the line, the tab will be treated as though it had been a space. An error message is output if an attempt is made to set more than 32 stops, or if a value is not in ascending order. In either case, the tab stops up to the cause of the error _a_r_e set. .STANDARD [] .SD [] Returns parameters to their initial settings and sets the header and text right margins to (the default is the current width set by a LAYOUT command). For example, if STANDARD 72 is specified, parameters are reset as follows: HEADER length 5, left margin 0, right margin 72; LAYOUT 0,56,0,72; SPACING 1; LEFT MARGIN 0; RIGHT MARGIN 72; TAB STOPS 8,16,24,...,248; PARAGRAPH indent 5, skip 1, test 2; LIST skip 1; LIST ELEMENT test 1. Also, FILL and JUSTIFY are enabled. This command is useful if settings are changed and it becomes necessary to reinitialize the standard format. 3.3 PAGE HEADER COMMANDS The following commands can be used to control the appearance of a header at the top of each page of the output document. .HEADER [