Google
 

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.