RUNOFF Documentation Preparation Program - User's Manual - Program Version: M03X Program Revision 16 April 1982 Document Revision 16 April 1982 Copyright (c) 1982, DECUS General permission to copy or modify, but not for profit, is hereby granted provided that the above copyright notice is included and refer- ence 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 Digital Equipment Corporation or by DECUS. 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. The described software is made available without any support whatsoever. If you are responsible for implementation of this system, you should ex- pect to have to understand and modify the source code if you encounter any problems in implementing or maintaining the software. DECUS, IAS, RSTS and RSX are trademarks of Digital Equipment Corp. 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 Chapter 4: 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-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 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 com- pilation 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 _O_V_E_R_V_I_E_W 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 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 _N_O_T_A_T_I_O_N 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 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. 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 hyphe- nation of a specific word, or to specify where a word should be hyphe- nated 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. The program may also be set to justify but not fill, although this would probably produce peculiar results and is not recommended. 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 INPUT FILE FORMAT 2-2 without concern for its appearance and RUNOFF will take care of making the output document tidy. 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