.;SETUP .; Last edited 16-Apr-82 by C. Spalding .; .; NOTE: This RNO file was derived from a version received from DECUS .; with RUNOFF, version M02. However, this file is NOT compatible .; with that version of RUNOFF. Version M03X must be used. .; .; Settings for optional text segments .; .; Select ONE of the following three options: .; (otherwise changes to the table of contents are required) .; .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? .include 5 ! Editing directions on first page in DOC file? .include 6 ! Note on editing output file for RSX? .; .; End of option settings .; .; DOCUMENT SETUP .; .option 4 ! Optionally alternate with 6-space offset .alternate 6 .alternating title .end option 4 .fill .flags hyphenate .layout ,57,,72 .no header .no number .paragraph 0 .; .; The following lines are output to the DOC file if option 5 is selected .; .option 5 .no fill .; POST-EDITING TO BE DONE TO THE OUTPUT "DOC" FILE: 1. Pg. I-5 Compare page numbers with CONTENTS; delete to bottom of the page 2. Pg. 1 Delete the page .; .number 1 ! Reset page number for correct even/odd alternating .no number ! But don't number the pages yet .page .end option 5 .;TITLE PAGE .fill # .skip 20 .center RUNOFF Documentation Preparation Program .s 3 .center ,- User's Manual - .s 18 .center Program Version: M03X .s .center Program Revision# .center ,16 April 1982 .s .center Document Revision .center ,16 April 1982 .;COPYRIGHT PAGE .page # .skip 12 .c Copyright (c) 1982, DECUS .s 3 General permission to copy or modify, but not for profit, is hereby granted provided that the above copyright notice is included and 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 Digital Equipment Corporation or by DECUS. .s No warranty, expressed or implied, is made by the contributor(s), DECUS or Digital Equipment Corporation as to the accuracy or functioning of the software or related material, and no responsibility is assumed by these parties in connection therewith. .s The described software is made available without any support whatsoever. If you are responsible for implementation of this system, you should expect to have to understand and modify the source code if you encounter any 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 Chapter 1: INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 1-1 1.1 Overview . . . . . . . . . . . . . . . . . . . . . 1-2 1.2 Notation . . . . . . . . . . . . . . . . . . . . . 1-2 Chapter 2: INPUT FILE FORMAT . . . . . . . . . . . . . . . . . . . 2-1 2.1 Special Characters . . . . . . . . . . . . . . . . 2-2 Chapter 3: 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 Default Values . . . . . . . . . . . . . . 3-3 3.2 Page Header Commands . . . . . . . . . . . . . . . 3-3 3.3 Mode Setting Commands . . . . . . . . . . . . . . 3-5 3.4 Parameter Setting Commands . . . . . . . . . . . . 3-9 3.5 Text Formatting Commands . . . . . . . . . . . . . 3-11 3.6 Page Formatting Commands . . . . . . . . . . . . . 3-17 3.7 Index Processing Commands . . . . . . . . . . . . 3-20 .option 1 Chapter 4: RSX/IAS OPERATING PROCEDURES . . . . . . . . . . . . . 4-1 .end option 1.option 2 Chapter 4: RSTS/E OPERATING PROCEDURES . . . . . . . . . . . . . . 4-1 .end option 2 4.1 Initiating RUNOFF . . . . . . . . . . . . . . . . 4-1 4.2 RUNOFF Command String . . . . . . . . . . . . . . 4-1 4.2.1 File Specifications . . . . . . . . . . . . 4-1 4.2.2 RUNOFF Switches . . . . . . . . . . . . . . 4-2 Appendix A: RUNOFF ERROR MESSAGES . . . . . . . . . . . . . . . . A-1 Appendix B: PAGE LAYOUT AND MARGIN CONTROL . . . . . . . . . . . . B-1 B.1 Vertical Positioning . . . . . . . . . . . . . . B-1 B.2 Horizontal Positioning . . . . . . . . . . . . . B-1 Appendix C: CASE INFORMATION . . . . . . . . . . . . . . . . . . . C-1 Appendix D: SPECIAL CHARACTERS . . . . . . . . . . . . . . . . . . D-1 Appendix E: INITIAL PARAMETER AND MODE SETTINGS . . . . . . . . . E-1 Appendix F: ALPHABETICAL LIST OF COMMANDS . . . . . . . . . . . . F-1 INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1 .f .;INTRODUCTION .header blank .t .st .even (This page intentionally left blank.) .number .chapter INTRODUCTION .x ~>C1 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 .st Overview .hl 1 ^&OVERVIEW\& .x ~>C1.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. .s.tp 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 .s.lm +8 .i -3 o# Complete list of the messages output by RUNOFF to the user's terminal .s.i -3 o# A discussion of the provisions for controlling the page layout and margins of the output document .s.i-3 o# A description of how case information can be specified with a terminal capable of only uppercase operation .s.i-3 o# A review of the characters with special meaning to RUNOFF .s.i-3 o# A list of the initial conditions in effect when RUNOFF execution begins .s.i -3 o# A complete list of all RUNOFF commands and their abbreviations .lm -8 .hl 1 ^&NOTATION\& .x ~>C1.2 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. .s.tp 5 .x Brackets .x Square brackets .y Arguments .x Arguments>optional .y 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 .even (This page intentionally left blank.) .chapter INPUT FILE FORMAT .x ~>C2 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 source 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 hyphenation of a specific word, or to specify where a word should be hyphenated 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. The program may also be set to =justify but not fill, although this would probably produce peculiar =results and is not recommended. .s .x Space .y Word .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. .s.tp 2,4 .x Page#>numbering .x Title 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. .s.tp 2,4 This manual was prepared with RUNOFF, so you can get an idea how things are formatted by looking at its source 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 ~>C2.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. .s.tp 4.lm +5 .i -5,__##Underbar#######Quote next character * .footnote 5 .s *##The #QUOTE CHARACTER# command can be used to change the character used as the quote character. This is useful in certain special cases. 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 "___>". .s.tp 4 .i -5,_&##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 space and tab. An appearance of ampersand preceded by backslash ("_\_&") will disable this mode. .s To make an ampersand appear in the printed text, it must be =preceded by the quote character ("___&"). .s.tp 4 .i -5,_###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 make a number sign appear in the printed text, it must be preceded by the quote character ("___#"). .s.tp 4,7,3 .i -5,_^##Circumflex#####Upper-case shift or mode lock .x Carat character .x Circumflex character .x #_^ (shift character) .x Shift lock .y Mode .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 ("___^"). .s.tp 4 .i -5,_\##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 ("___\"). .s.tp 4 .i -5,_=##Equal sign#####Hyphenation disable/specification .x Equal-sign character .x #_= (hyphenation flag character) .x Word>hyphenation .x Hyphenation>disable/specification .x Preferred hyphen .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 this case the word will only be hyphen=ated at such marked points, or at explicit hyphens in the input). .s.tp 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 ("___="). .s.tp 4,6,2 .i -5,_<##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 ("___<"). .s.tp 4 .i -5,_>##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. .s.tp 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 .even (This page intentionally left blank.) .chapter RUNOFF COMMANDS .x ~>C3 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 source 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 ~>C3.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 "NO#HEADER" and "NOHEADER" 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. .hl 2 Numeric Arguments .x ~>C3.1.1 Numeric Arguments .x Numeric arguments .x Relative arguments .x Arguments>numeric .x 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. .s .x Relative arguments .x Arguments>relative The following commands will accept relative numeric arguments: .s.tp 6 .c ALTERNATE NUMBER # .c AUTOSUBTITLE PAGE SIZE # .c CENTER RIGHT JUSTIFY .c HEADER RIGHT MARGIN# .c LAYOUT STANDARD # .c LEFT MARGIN TAB STOPS # .hl 2 Text Arguments .x ~>C3.1.2 Text Arguments .x Text arguments .x 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. The text argument is assumed to begin with the first non-blank character after the command name. 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 There are several commands which take a numeric argument and a text argument (e.g., the CENTER command). A semicolon can be used to separate the numeric argument from the text argument, in which case the text =argument starts immediately after the semicolon. Otherwise, all spaces and tabs between the arguments are ignored. Some commands allow the text argument to be placed on the line after the command line--if that is done, a semicolon cannot be used and a comma is not needed. .hl 2 Optional Arguments .x ~>C3.1.3 Optional Arguments .x 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 #HEADER# command has the form .s .c _.HEADER [