Trailing-Edge
-
PDP-10 Archives
-
cuspmar86binsrc_2of2_bb-fp63a-sb
-
10,7/runoff/rnfdoc.std
There are 5 other files named rnfdoc.std in the archive. Click here to see a list.
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.