.;SETUP .; .; Last edited 16-Apr-83 by C. Spalding .; .; NOTE: This RNO file must be processed with RUNOFF, .; version M3.0 (830416) or later. .; .; Settings for optional text segments .; .; INCLUDE one or more of the following three options: .; .include 1 ! Operating procedures for RSX/IAS .exclude 2 ! Operating procedures for RSTS/E .exclude 3 ! Operating procedures for RT-11 (reserved for future use) .; .; INCLUDE or EXCLUDE each of the following options: .; .exclude 4 ! Alternating output .exclude 5 ! Description of FIRST TITLE command .; .; End of option settings .; .; DOCUMENT SETUP .; .option 4 ! Optionally alternate with 6-space offset .alternate 6 .alternating title .end option 4 .; .flags hyphenate .layout ,57,,72 .level style 2,2 ! Set format of section headers .level style 3,1 .level style -4,1 .no header .no number .paragraph 0,1,2 .; .; END OF DOCUMENT SETUP .;TITLE PAGE .figure 15 .c RUNOFF Documentation Preparation Program .s 3 .c,- User's Manual - .s 12 .c Program Version: M3.0 .s .c Program Revision# .c,16 April 1983 .s .c Document Revision .c,16 April 1983 .s 5 .c Contributed by .s .c Charles H. Spalding III .c,1202 Charleston Road .c Mountain View, CA .;DISCLAIMER PAGE .; .fill .page .figure 15 General permission to copy (but not for profit) is hereby granted provided that reference is made to the fact that reproduction privileges were granted by DECUS. .s 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. .s 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. .s The described software is currently supported by the contributor as the RUNOFF Working Group of the DECUS RSX Special Interest Group, but continuance 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. .s -3 DECUS, IAS, RSTS and RSX are trademarks of Digital Equipment Corp. .;T of C .header blank .pg .nf .c TABLE OF CONTENTS .c Move the table of contents to here from the end of the output. .f .;INTRODUCTION .header blank .t .st .option 4 .even (This page intentionally left blank.) .end option 4 .number .chapter 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 determine 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 process RUNOFF follows the user instructions embedded in the file, performing such formatting actions as line justification, page numbering and titling, etc. RUNOFF can also perform additional functions such as =compilation of an index. .s 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. .s Briefly, the procedure for producing a manuscript using RUNOFF is as follows: .list .le Use a text editor to compose the input file, including commands to RUNOFF to control the format of the final manuscript. .le Apply RUNOFF to the input file, producing an output document. .le 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. .le If necessary, edit the ^&input\& file to change the text and RUNOFF commands. .le Repeat the above sequence of steps as required to achieve the desired manuscript. .end list 0 .st Overview .hl 1 OVERVIEW .x 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. .p ,,2,5 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 control the operation of RUNOFF in ways which may override commands in the input file(s). .s The appendices include: .list 1,o .le A complete list of the messages output by RUNOFF to the user's terminal, .le A discussion of the provisions for controlling the page layout and margins of the output document, .le A description of how case information can be specified with a terminal capable of only uppercase operation, .le A review of the characters with special meaning to RUNOFF, .le A list of the initial conditions in effect when RUNOFF execution begins, .le A complete list of all RUNOFF commands and their abbreviations. .end list 0 .hl 1 NOTATION .x Notation .x Angle brackets Two shortened notations are used in this manual. Angle brackets (<#>) are used to enclose an item which describes the actual argument to appear. 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 ^&never\& to be included as part of a command. .p ,,5 .x Brackets .x Square brackets .y Parameter>command (see Argument) .x Command>arguments>optional .x Arguments>optional .x Optional>command arguments 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. .;INPUT FILE .t .st .option 4 .even (This page intentionally left blank.) .end option 4 .chapter INPUT FILE FORMAT .x Input>file format .x Source file format As mentioned above, the input or source file contains the textual =material which will appear in the final copy, plus information to specify 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 consists 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. .s .x Command>line .x Period character .x #_. (command character) 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. .s .x Filling of text .x Justification of text 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 exceeded. The line is then justified by making the word spacings larger until the last word in the line exactly meets the text right margin. .s .x Hyphenation 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. .s .x Literals 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. .s .x Space .x Word>spacing 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. .s .x Break 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. .p ,,2,4 .x Page>numbering 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. .p ,,2,4 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. .st Special Characters .tp 9 .hl 1 SPECIAL CHARACTERS .x 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. .lm +5.p -5,1,4 __##Underbar#######Quote next character * .footnote 5 .lm 3.p -3,1 *##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. ! .x Underbar character .x #__ (quote character) .x Quote character .s To allow the appearance of the special characters in the output, the underbar character ("__"#[137#octal]) is used as a quote character. 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 following cases can occur: "____", "___&", "___#", "___^", "___\", "___=", "___<" and "___>". .p -5,,4 _###Number Sign####Explicit space .x Number-sign character .x #_# (explicit-space character) .x Space .x Explicit space .x Quoted space .s 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 ("___#"). .p -5,,4 _&##Ampersand######Underscoring .x Ampersand character .x #_& (underscore character) .x Underlining .s The ampersand character ("_&"#[046#octal]) is used to specify underscoring. The ampersand will cause the character following it to be underlined; for example, "_&f_&o_&o" becomes "^&foo\&". .s 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 appearance of ampersand preceded by backslash ("_\_&") will disable this mode. .s To have an ampersand appear in the printed text, it must be =preceded by the quote character ("___&"). .p -5,,4,7,3 _^##Circumflex#####Upper-case shift or mode lock .x Carat character .x Circumflex character .x #_^ (shift character) .x Shift lock .x Mode>lock .s 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 "underline all text." If it is to appear in the printed text, a circumflex must be preceded by the quote character ("___^"). .p -5,,4 _\##Backslash######Lower-case shift or mode unlock .x Backslash character .x #_\ (unlock character) .x Shift lock .x Mode>unlock .s 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 ("___\"). .p -5,,4 _=##Equal sign#####Hyphenation disable/specification .x Equal-sign character .x #_= (hyphenation flag character) .x Word>hyphenation .x Hyphenation>disable/specification .x Preferred hyphenation .s 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 hyphen=ated only at such marked points, or at explicit hyphens in the input. .p 0,,3 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 ("___="). .p -5,,4,6,2 _<##Less than######Capitalize next word .x Less-than character .x #_< (capitalization character) .x Word>capitalization .x Capitalize word .s If a #FLAGS#CAPITALIZE# command has been issued, the less-than character ("_<"#[74#octal]) is used to capitalize the entire word it precedes. Then, if it is to appear in the printed text, a less-than character must be preceded by the quote character ("___<"). .p -5,,4 _>##Greater than###Subindex next word .x Greater-than character .x #_> (subindex flag character) .x Subindex>flag character .s 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. .p 0,,2 Unlike the other special characters above, the greater-than character can appear in the text without having to use the quote character. 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 ("___>"). .lm -5.rm .;COMMANDS .t .st .option 4 .even (This page intentionally left blank.) .end option 4 .chapter RUNOFF COMMANDS .x RUNOFF commands .x Period character .x #_. (command character) 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 ter=minal and the remainder of that command will be ignored. .st Syntax .hl 1 COMMAND SYNTAX .x Command>syntax .x Syntax, command 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. .s 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 command must begin with a period. Semicolons may optionally be used to further separate commands. .s 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.) .hl 2 Numeric Arguments .x Numeric arguments .x Relative arguments .x Arguments>numeric .x Arguments>relative .x Command>arguments>numeric .x Command>arguments>relative Numeric arguments are always considered to be decimal values. Some commands 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. .p ,,9 The following commands will accept relative numeric arguments: .p ,,7 .c ALTERNATE LEVEL STYLE # .c AUTOSUBTITLE NUMBER # .c CENTER PAGE SIZE # .c CENTRE PAPER SIZE # .c HEADER RIGHT JUSTIFY .c HEADER LEVEL RIGHT MARGIN# .c LAYOUT STANDARD # .c LEFT MARGIN TAB STOPS # .hl 2 Text Arguments .x Text>arguments .x Arguments>text .x Command>arguments>text 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 command on the same line because the remainder of the line is taken to be the text argument. .s 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. .hl 2 Optional Arguments .x Arguments>optional .x Command>arguments>optional .x Optional>command arguments .x Commas 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 optional 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 .s .c _.LAYOUT [],[],[],[] .s 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 .s .c _.LAYOUT ,54,10 .s 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. .p ,,2,4,2 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 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). .hl 2 Initial and Default Values .x Values>default .x Values>initial .x Default values .x Initial settings .x Arguments>default values .x Arguments>initial settings .x Command>arguments>default values .x Command>arguments>initial settings ^&Initial values\& 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. .s A ^&default value\& is assumed whenever an optional argument is omitted from a command. The individual command descriptions describe the default value assumed for each optional argument. .;PAGE FORMAT .st Page Format .tp 12 .hl 1 PAGE FORMAT COMMANDS .x Page>format .x Parameter>setting .x Commands>page format .x Commands>parameter setting The following commands are used to set the values of parameters used by RUNOFF while formatting the output document. .lm +5 .p -5,2,6 _.LAYOUT [],[],[],[] .x LAYOUT command .x Format, page .x Page>format .x Page>length .x Page>width .x Length>page .x Margin>base .x Margin>text .x Margin>top .x Top margin .x Base margin .x Width>page .x Text>margin .s Sets several parameters for the page layout. The parameters are: .lm +14 .p -11,1,2 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. .p Length#####The total number of lines to be on each page (not counting "top"). .p Left#base##The base column from which LEFT MARGIN, RIGHT MARGIN and TAB STOP settings are to be made. .p ,,1 Width######The default right margin to be used. .lm -14 .p 0,1,2 The initial settings are 0, 56, 0, and 60, respectively. If any par=ameter is omitted, it remains unchanged. .p ,,2,4 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. .s See Appendix B for descriptions of page layout and =margins. .p -5,,7 _.PAGE SIZE [],[] .rj _.PS [],[] .i -5 _.PAPER SIZE [],[] .x PAPER SIZE command .x PAGE SIZE command .x Page>length .x Length>page .x Margin>text .x Text>margin .x Width>page .s 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.) .p -5,,6 _.SPACING .rj _.SP .x SPACING command .s 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. .p -5,,5 _.LEFT MARGIN [] .rj _.LM [] .x LEFT MARGIN command .x Margin>text .x Text>margin .s Sets the text left margin to columns from the base margin set by the LAYOUT command. If "number" has a sign, it is interpreted 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.) .p -5,,4 _.RIGHT MARGIN [] .rj _.RM [] .x RIGHT MARGIN command .x Margin>text .x Text>margin .x Width>text .s 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 command. (See Appendix B for a further description of text margins.) .p -5,,7 _.TAB STOPS [],[],... .rj _.TS [],[],... .x TAB STOPS command .s Sets up to 32 tab stops. The numbers must be greater than 0 and listed in ascending order. The TAB STOPS command clears all existing 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. .p 0,,2,5,2 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. .p 0,,2,5,2 Tab stops are set relative to the "left base" (see the LAYOUT command) 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 point where no further tab stops have been set on the line, the tab will be treated as though it had been a space. .p 0,,3 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 ^&are\& set. .p -5,,6 _.STANDARD [] .rj _.SD [] .x STANDARD command .x Margin>header .x Margin>text .x Text>margin .s 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. .p 0,,2 This command is useful if settings are changed and it becomes =necessary to reinitialize the standard format. .;PAGE HEADER .lm -5 .st Page Header .tp 12 .hl 1 PAGE HEADER COMMANDS .x Page>header .x Commands>page header The following commands can be used to control the appearance of a header at the top of each page of the output document. .lm +5 .p -5,2,6 _.HEADER [