STANDARDS FOR RUNOFF MANUALS 005 003 026 00 ABSTRACT The standards in this document are a guide to writers and typists who are involved in preparing manuals on-line using the DECsystem-10 RUNOFF program. These standards govern formatting procedures only and should be used in conjunction with the documentation style guide being prepared by the Software Documentation Style Committee. DIGITAL EQUIPMENT CORPORATION . MAYNARD, MASSACHUSETTS Page 2 THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY ONLY BE USED OR COPIED IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE. COPYRIGHT (c) DIGITAL EQUIPMENT CORPORATION 1973,1986. ALL RIGHTS RESERVED. The following are trademarks of Digital Equipment Corporation. CDP DIGITAL INDAC PS/8 COMPUTER LAB DNC KA10 QUICKPOINT COMSYST EDGRIN LAB-8 RAD-8 COMTEX EDUSYSTEM LAB-8/e RSTS DDT FLIP CHIP LAB-K RSX DEC FOCAL OMNIBUS RTM DECCOMM GLC-8 OS/8 RT-11 DECTAPE IDAC PDP SABR DIBOL IDACS PHA TYPESET 8 UNIBUS Page 3 CONTENTS Page 1.0 INTRODUCTION 1 2.0 TITLE AND COPYRIGHT PAGES 2 2.1 Title Page 2 2.2 Copyright Page 2 3.0 CONTENTS PAGE(S) 2 3.1 Sample Contents Page 3 4.0 PREFACE/ABSTRACT 6 5.0 CHAPTERS 6 6.0 SECTIONS 6 6.1 Section Headings 6 6.2 Headings for Nonchapter-Oriented Manuals 7 7.0 LISTS 7 8.0 EXAMPLES 8 9.0 NOTES 8 10.0 FOOTNOTES 8 11.0 TABLES AND FIGURES 8 11.1 Tables 9 11.2 Figures 9 12.0 INDEXES 10 13.0 PAGE NUMBERING 10 13.1 Chapter-Oriented Manuals 10 13.2 Nonchapter-Oriented Manuals 10 13.3 Pre- and Post-Chapter Material 10 14.0 SAMPLE CHAPTER-ORIENTED TEXT 11 Page 4 STANDARDS FOR RUNOFF MANUALS 1.0 INTRODUCTION This document presents a guide for preparing manuals on-line using the DECsystem-10 RUNOFF program. The document itself adheres to the standards set within and serves as an example of nonchapter-oriented text. In general all software manuals are to be produced via RUNOFF for a reduction to 85% using a repro page size of 7" X 10 3/8". A page of text is typed single-spaced with lines 70 characters wide and pages 64 lines long. This format will fill the space within the light blue lines on a repro page. NOTE The RUNOFF program currently inserts a margin of five lines at the top of each page in the following format: one blank line; PAGE n; three blank lines; user text starts on sixth line. (During NOVAR output, the PAGE number can be suppressed so that the line is blank.) These five lines are included in the line count for total page length and can be used for correction of widows. If additional blank lines are to appear at the top of a page (as indicated in Paragraph 5.0, for example), the user must be sure to adjust his RUNOFF commands accordingly by taking these blank lines into consideration. In standardizing the format of lists, table columns, and character spacing, it is necessary to reference specific character columns. As an example, consider the following two lines: EVERY GOOD BOY DOES FINE. WHAT DID YOU SAY? Using a left margin of 0, the first E of the word EVERY is in column 9; the G is in column 15. The W of the word WHAT in the second line has been indented 15 spaces; that is, there are 15 blank spaces preceding it, and it appears in column 15 immediately below the G. Currently,there are a few limitations in using the RUNOFF program to produce manuals. The output devices that are available at present necessitate special handling in the following cases: 1. Because italics are not available, the names of any documents Page 5 referenced within the text must be typed using initial caps and underlined by hand on the finished repro page. 2. Any vertical or horizontal lining (e.g., in tables or examples) should not be attempted using RUNOFF. These lines must be drawn by hand on the finished repro page. 3. Any subscripted number should be placed in parentheses following the argument to which it refers (e.g., s(1), s(2), etc). However, subscripted numbers should be typed and cut into the repro page before printing. When base numbers are used (octal, decimal), the word should be spelled out (e.g., 10(decimal), 6(octal)). 4. Any superscripted number should be preceded by an up-arrow (e.g., 10^2 represents 10 squared). However, superscripted numbers should be typed and cut into the repro page before printing. When typesetting is available, these limitations should be removed. 2.0 TITLE AND COPYRIGHT PAGES 2.1 Title Page The standard boilerplate should be used for the title page; this may also appear in the RUNOFF file to facilitate identification of the file. 2.2 Copyright Page The standard boilerplate should be used for the copyright page. This page should appear in the RUNOFF file. 3.0 CONTENTS PAGE(S) Any manual with more than one chapter or with more than 10 headings requires a Contents page. The name of this page is CONTENTS and is centered at the top of the page. Seven blank lines appear before the word CONTENTS and three blank lines follow it. The column heading (Page) appears on the next line and is indented 65 spaces. Both chapter titles and section names are represented in the contents. The name of a section or chapter is separated from its number by a tab which is three spaces larger than the longest possible section number; all chapter titles and section names will then be aligned. Lines containing chapter numbers and titles are separated from the previous line by one blank line; they begin at the left margin (0) and are typed in upper case. Two spaces separate the word CHAPTER from its corresponding number. Page 6 Lines containing first level headings (see Paragraph 6.1) are separated from the previous line by one blank line. These lines are indented 10 spaces (so that they are aligned with the chapter number) and are typed in upper-case. Lines for second and third level headings are upper and lower case, unless the heading itself requires all caps. Refer to Paragraph 3.1 for an example. Appendixes are formatted in the same manner as chapters with the exception that only one space separates the identifying letter from the word APPENDIX. Figures and tables are listed separately following any appendixes. Three blank lines separate the last entry of an appendix from the word FIGURES. The word FIGURES is centered on the page and is followed by three blank lines. The column headings Number and Page appear on the next line; Number begins at column 0 and Page at column 65. One blank line separates the headings and the entries. The numbers of the figures and their page numbers are centered under the headings; the titles of the figures are indented to be in line with chapter and section names. Three blank lines separate the last entry under FIGURES from the word TABLES. The title TABLES and its column headings and entries are formatted in the same manner as FIGURES. (See the example in Paragraph 3.1.) Contents pages are numbered in consecutive order using small Roman numerals. These numbers must be manually typed on the finished repro as they cannot currently be entered using RUNOFF. Refer to Paragraph 13.0 for the placement of page numbers. 3.1 Sample Contents Pages The following are sample Contents pages. Page 7 CONTENTS Page CHAPTER 1 INTRODUCTION 1.1 PROCESSOR MODES 1-1 1.1.1 User Mode 1-2 1.1.2 User I/O Mode 1-2 1.1.3 Executive Mode 1-2 1.2 PROGRAMMED OPERATORS 1-4 1.2.1 User UUOs 1-6 1.2.2 Monitor UUOs 1-7 1.2.2.1 CALL and CALLI 1-8 1.2.2.2 Restriction on Monitor UUOs 1-17 1.2.3 Unimplemented Op Codes 1-18 1.2.4 Illegal Operation Codes 1-19 CHAPTER 2 NON-I/O UUOS 2.1 EXECUTION CONTROL 2-1 2.1.1 Starting 2-2 2.1.2 Stopping 2-4 2.1.3 Trapping 2-5 2.1.4 Suspending 2-7 2.2 CORE CONTROL 2-8 2.2.1 Definitions 2-8 2.2.2 LOCK UUO 2-10 2.2.2.1 Swapping KA10 Systems 2-11 2.2.2.2 Core Allocation Resource 2-12 2.2.3 CORE UUO 2-12 2.2.4 SETUWP UUO 2-13 2.3 SEGMENT CONTROL 2-14 2.3.1 RUN UUO 2-16 2.3.2 GETSEG UUO 2-17 2.3.3 REMAP UUO 2-18 2.4 PROGRAM AND PROFILE 2-19 2.4.1 SETNAM UUO 2-19 2.4.2 SETUUO UUO 2-20 2.4.3 LOCATE UUO 2-20 APPENDIX A SUMMARY OF UUOS A.1 MONITOR UUOS A-1 A.2 USER UUOS A-5 A.3 UNIMPLEMENTED UUOS A-10 APPENDIX B ERROR MESSAGES Page 8 FIGURES Number Page 1-1 User Address Mapping 1-3 2-1 Locking Jobs in Core 2-11 TABLES Number Page 1-1 Monitor Programmed Operators 1-8 1-2 CALL and CALLI Monitor Operations 1-10 Page 9 4.0 PREFACE/ABSTRACT A preface or abstract is to be included in every manual. If the manual is chapter-oriented, the preface appears on the first right-hand page following the Contents page. The name of this page is PREFACE. Twelve blank lines precede the word PREFACE and three blank lines follow it. If the manual is nonchapter-oriented, an abstract is used in lieu of a preface and must appear on the title page of the manual. Twelve blank lines separate the word ABSTRACT and the manual number. One blank line separates ABSTRACT from the text of the abstract. 5.0 CHAPTERS Each new chapter begins a new right-hand page. The number and title of a chapter are typed in upper case using two lines. The first line contains the chapter number (i.e., Chapter 3) and is preceded by twelve blank lines and followed by one blank line. The next line contains the chapter title; three blank lines separate the title from the beginning of the text. Refer to Paragraph 14.0 for the format of the first page of a chapter. 6.0 SECTIONS Paragraphs appear in block style and begin in column 0. 6.1 Section Headings Each section heading is preceded by a number (containing one or more decimal points) which identifies the section. The first digit of the number corresponds to the current chapter; remaining digits of the number correspond to sections within the current chapter. Two spaces separate the entire number from the heading. One blank line separates the section heading from the text (except for third level headings, see below); one blank line separates each paragraph within the section. Three blank lines separate the end of a section from the heading of the next section. There are three levels of headings; numbering beyond the third level should be avoided: 1. First level - A first level heading is typed in upper case; for example: 2.2 CORE CONTROL 2. Second Level - A second level heading is typed in upper and lower case; for example: 2.1.3 Trapping 3. Third Level - A third level is also typed in upper and lower case. However, the text of the paragraph begins on the same line as the heading and is separated from the heading by a Page 10 space, a dash, and a space. For example: 1.2.2.2 Restriction on Monitor UUOs - The text begins here... 6.2 Headings for Nonchapter-Oriented Manuals One exception to the above rules for numbering sections is the following: Any short, nonchapter-oriented manuals (such as this RUNOFF Standards document and specifications published by the DECsystem-10 Documentation Group) are numbered as follows: 1.0 FIRST LEVEL HEADING (1) 1.1 Second Level Heading 1.1.1 Third Level Heading - Text begins here... 7.0 LISTS The order of elements in a primary list is indicated by numbers, indented 5 spaces from a left margin of 0 ( i.e., beginning in column 5) followed by a period. Text of a primary list is indented an additional 4 spaces (i.e., beginning in column 9) and runs to the right margin. The order of elements in a secondary list is indicated by lower-case letters, indented 9 spaces from a left margin of 0 (i.e., beginning in column 9) followed by a period. Text of a secondary list is indented an additional 4 spaces (i.e., beginning in column 13) and runs to the right margin. Lists beyond the secondary level should be avoided. Numbers in a list which contains more than 9 elements are indented one less space to align the periods. In all lists the text is blocked and does not flow under the identifying number or letter. One blank line separates elements within a list, and one blank line separates the list itself from preceding and following text. If the list is at the end of a section, three blank lines separate it from the next section heading. 8.0 EXAMPLES Examples are indented 9 spaces from a left margin of 0 (i.e., beginning in column 9); otherwise they are indented 4 spaces from the left margin of the preceding text. For example, in tables or lists the example is indented 4 spaces from the left margin of the table or --------------- (1) Note that a heading identified by a n.0 number is used only in nonchapter-oriented manuals. Page 11 list. One blank line appears before and after the example. If the example is the last item in a section, three blank lines appear between the example and the next section heading. The examples should appear as part of the RUNOFF source file. However, actual computer output of examples should be obtained and cut into the finished repro page before printing. 9.0 NOTES Notes are centered within the margins of the preceding text. When a note appears within paragraph text, the margins for the note are 15 and 55. When a note appears in a list or table, the margins are indented an additional 4 spaces from the margins used for the list or table. The word NOTE is centered within the allowed margins of the note and is preceded by two blank lines and followed by one blank line. Two blank lines appear between the last line of the note and the following text. However, if the note precedes a new section, three blank lines appear between the note and the next section heading. 10.0 FOOTNOTES Footnotes should not be used in the text unless unavoidable (e.g., registered trademarks that are not Digital's are cases of unavoidable footnotes). If used, footnotes must be identified by numbers enclosed in parentheses, and a separating line must be drawn manually on the finished repro page. 11.0 TABLES AND FIGURES Tables and figures are centered on the page. Tables and figures are numbered independently of each other using a "chapter-number" numbering scheme (e.g., Figure 3-5, Table 3-5). However, if the manual is nonchapter-oriented, tables and figures are numbered independently in sequential order (e.g., Table 3, Figure 3, Table 4). Page 12 11.1 Tables The number and title of a table are typed using two lines, each of which is centered above the table itself. The first line contains the table number, and the second contains the table name typed in upper and lower case. For example: Table 1-1 Error Messages Two blank lines separate the preceding text from the table number and the table name from the text of the table. Two blank lines appear between the last line of the table and the following text. However, if the table precedes a new section, three blank lines appear between the table and the next section heading. Column headings are centered over each column of the table. Tables should be completely boxed with horizontal and vertical lines; these must be manually drawn on the finished repro page and not attempted using RUNOFF. If a table is one page or less in length, it should not be split across two pages. When a table is longer than one page, continuation is indicated at: 1. The bottom of each continued page; the phrase (Continued on next page) is right justified below the horizontal closing line. 2. The top of subsequent pages; the abbreviation (Cont.) follows the table number and is separated from it by two spaces. Both the table number and table name are repeated on continuation pages. Refer to Paragraph 14.0 for an example of continuing a table. 11.2 Figures The number and title of a figure are typed using two lines, each of which is centered below the figure. The first line contains the figure number, and the second contains the figure name typed in upper and lower case. If a figure is one page or less in length, it should not be split across two pages. When a figure is longer than one page, continuation is indicated in the same manner as used for tables. For example: Figure 1-1 (Cont.) Figure Title Two blank lines separate a figure title from following text. If the figure title precedes a new section, three blank lines appear between the figure title and the next section heading. 12.0 INDEXES Page 13 Any manual with more than one chapter or with more than 10 headings requires an index. As an aid in generating an index, refer to the memo entitled Index Construction (A Suggested Method). Copies of this memo can be obtained from Gladys Pannell, Building 3-4. 13.0 PAGE NUMBERING 13.1 Chapter-Oriented Manuals Pages of a chapter-oriented manual are numbered using the "chapter-number" numbering scheme (i.e., 1-2, 2-5, etc.). Placement of page numbers occurs as follows: 1. The number of the first page of a new chapter is not printed. 2. Numbers of following pages occur in the upper outermost corner of the page. The page number should appear immediately above the blue line. NOTE At present page numbers must be entered manually on the finished repro page. RUNOFF will be modified to handle this function. 13.2 Nonchapter-Oriented Manuals All pages of nonchapter-oriented manuals are numbered sequentially (i.e., 1, 2, 3, etc.) using the current standard RUNOFF format (that is, PAGE n is not suppressed and appears in the upper right corner). 13.3 Pre- and Post-Chapter Material The Contents and Preface pages of chapter-oriented manuals are numbered using small consecutive Roman numerals and are placed according to the format above. No numerals appear on the title and copyright pages, although they are included in the count. Roman numerals must be entered manually on the finished repro page. Appendixes of chapter-oriented manuals are numbered in the "chapter-number" numbering scheme, using the letter of the appendix (i.e., A-1, A-2, etc.) in the format presented in Paragraph 13.1. The index of a chapter-oriented manual is numbered in the chapter-number numbering scheme using the word Index, thus Index-1, Index-2. The formats presented in Paragraphs 13.1 and 13.2 apply. 14.0 SAMPLE CHAPTER-ORIENTED TEXT An example of the standards as applied to a chapter-oriented manual follows. Page 14 CHAPTER 4 EDITING THE SOURCE PROGRAM The Text Editor (EDIT) is used to create and modify ASCII source files. Controlled by user commands from the keyboard, EDIT reads ASCII files from cassette, makes specified changes, and writes ASCII files back to cassette or lists them on the line printer or console terminal. The Editor considers a file to be divided into logical units called pages. A page of text is generally 50-60 lines long (delimited by form feed characters) and corresponds approximately to a physical page of a program listing. The Editor reads one page of text at a time from the input file into its internal buffer (called the Text Buffer) where the page becomes available for editing. Editing commands can then be used: 1. To locate text to be changed 2. To execute and verify changes 3. To output a page of text to the output file 4. To list an edited page on the line printer or console terminal 4.1 CALLING AND USING THE EDITOR The Editor is called from the System Cassette by typing: .R EDIT in response to the dot printed by the Keyboard Listener. When the Editor is in memory and ready to accept I/O specifications, an asterisk (*) is printed at the left margin of the console terminal page. 4.1.1 Editor Options None of the options previously listed in Chapter 3 are used by the Editor. An automatic overflow feature is provided, however; if the Editor discovers an end-of-tape condition, it prompts the user to mount a new cassette and output is continued on this cassette under the same output filename originally specified by the user. Page 15 4.1.2 Input and Output Specifications (Edit Read and Edit Write) The Edit Read command opens a file for input. The form of the command is: *ER#:FILENA.EXT where # represents the unit drive number and FILNAM.EXT the file to be opened. If no drive number is specified, the System Cassette (drive 0) is assumed. 4.2 SPECIAL KEY COMMANDS Special EDIT key commands are listed in Table 4-1. (Control commands are typed by holding down the CTRL key while typing the appropriate character.) Table 4-1 EDIT Key Commands Command Meaning ALTMODE Echoes as a $ character. A single ALTMODE terminates a text string. A double ALTMODE executes the command string. For example: *GMOV A,BL$-1D$$ CTRL/C Echoes at the terminal as ^C. Typing this command terminates execution of EDIT commands and initiates a return to the KBL. Any open files are first closed, and the contents of the Text Buffer are lost (refer to Chapter 3, Paragraph 3.2.5). CTRL/O Echoes as ^O. This command inhibits printing on the console terminal until completion of the current command string. Typing a second CTRL/O will resume output (refer to Chapter 3, Paragraph 3.2.5). CTRL/P Echoes as ^P and restarts the Editor (refer to Paragraph 4.1.3). CTRL/U Echoes as ^U. This command deletes all the characters on the current input line (refer to Chapter 3, Paragraph 3.2.5). (Continued on next page) Page 16 Table 4-1 (Cont.) EDIT Key Commands Command Meaning RUBOUT The RUBOUT key is used to delete a character from the current line and may be used in both Command and Text Modes; it echoes a backslash followed by the character deleted. Each succeeding RUBOUT typed by the user deletes and echoes another character. An enclosing backslash is printed when a key other than RUBOUT is typed. This erasure is done right to left up to the last CR/LF. Note that RUBOUT used under control of the Editor echoes deleted characters somewhat differently than when using other system programs. TAB Spaces to the next tab stop. Tab stops are positioned every 8 spaces on the terminal; typing the TAB key causes the carriage to advance to the next tab position. Several commands can be strung together and executed in sequence. For example: *BGMOV PC,R0$-2CR1$5K$GCLR @R2$$ NOTE If a command currently being entered by the user is within 10 characters of exceeding the space available in the Command Buffer, the message: * CB ALMOST FULL * is printed (the Command Buffer holds the command string until it is executed). If the command can be completed within 10 characters, the user may finish entering the command; otherwise he should type the ALTMODE key twice to execute that portion of the command line already completed. The message is printed each time a character is entered in one of the last 10 spaces. Execution of a command string begins when a double ALTMODE is typed and proceeds from left to right.