Google
 

Trailing-Edge - PDP-10 Archives - decuslib10-05 - 43,50337/25/tdi8.mem
There is 1 other file named tdi8.mem in the archive. Click here to see a list.











                               CHAPTER 8

          SIMULA FOR DEC SYSTEM 10             TD, SYSTEM DESC



SIMULA FOR DEC SYSTEM 10             TD, SYSTEM DESC             I.8-1

740805    780302      6                           Olof Bjorner








 I.8     DOCUMENTATION STANDARD


 I.8.1   Introduction
         ------------

         This standard covers the layout of the Technical  Documentation
         and describes the routine for revisions.


 I.8.2   Page headings
         -------------

         The page headings are according to ENEA standard.   Originally,
         it  was  intended to use preprinted ENEA forms for all pages of
         the documentation.  This intention has not  been  upheld  since
         FOA took over maintenance completely in 1976.  The ENEA heading
         has the following layout:

         E N E A  D A T A   (large boldface)

         +-----------------------+---------------------------------------+------+
         ! Project                 Part                                    Page !
         +-------+----------+----+----------------------+-----------------------+
         ! Date    Rev.date   No   Identification         Originator            !
         +----------------------------------------------------------------------+

         "Project" should always be "SIMULA FOR DEC SYSTEM 10".

         The text in the Part field should be as shown in the  following
         table:

         section         text
         -------         ----
           I             TD, SYSTEM DESC
          II             TD, COMPILER
          II.A           TD, COMPILER PASS 1
          II.B           TD, COMPILER PASS 2
          II.C           TD, COMPILER PASS 3
          IV             TD, SIMDDT
           V             TD, UTILITIES
          VI             TD, MODULE DOC.
SIMULA FOR DEC SYSTEM 10             TD, SYSTEM DESC             I.8-2

740805    780302      6                           Olof Bjorner








 I.8.3   Section numbers and headings
         ----------------------------

         The section number is always typed in the left margin  and  the
         heading starts to the left in the main text field.  Headings on
         the first level with no outer level should be  typed  in  upper
         case  letters  and  underlined.   Headings on the second level,
         with one outer level, should be typed in upper  case,  but  not
         underlined.   Headings  on  the  third level should be in lower
         (mixed) case and underlined.  Headings on the fourth and  inner
         levels should be typed in lower case.  Headings without section
         number should be typed as written in the manuscript.


 I.8.4   Page numbers
         ------------

         Pages should be numbered sequentially within each  second-level
         section,  e.g.  I.2-1,  I.2-2  etc.   Exceptions  are  the pass
         documentation sections,  II.A,  II.B,  II.C,  where  pages  are
         numbered on the third level.


 I.8.5   Revisions
         ---------

         Revisions should be made as follows:

         1.      The revised pages and  any  new  pages  should  have  a
                 revision  date  and  a  revision number.  Note that all
                 revised pages should have the same  revision  date  and
                 revision number.

         2.      All revised pages should be rewritten  completely.   In
                 practice, this is not always done.

         3.      A revision page should be written.   This  page  should
                 contain  information  about  revised  and new pages and
                 cause of revision.

         4.      The revision page should have the Part text
                 REVISION NO nn.
SIMULA FOR DEC SYSTEM 10             TD, SYSTEM DESC             I.8-3

740805    780302      6                           Olof Bjorner








         5.      The  revision  page  should  be  kept   last   in   the
                 documentation  in order of revisions.  In the original,
                 each revision page should be followed by  the  replaced
                 pages if practically feasible.
SIMULA FOR DEC SYSTEM 10             TD, SYSTEM DESC             I.8-4

740805    780302      6                           Olof Bjorner








         REVISION

         Revised pages
         -------------















         New pages
         ---------















         Revision purpose
         ----------------
SIMULA FOR DEC SYSTEM 10             TD, SYSTEM DESC             I.8-5

740805    780302      6                           Olof Bjorner








 I.8.6   Updating the index to the Technical Documentation.
         -------------------------------------------------

         The index (section VII) has been developed using two  programs:
         INDEX.SNO and SUTIND.SIM.

         INDEX.SNO is a general purpose index program developed at  FOA.
         It supports the following functions:
         (1) Updating an index file with new keywords
         (2) Editing the sorted index file
         (3) Listing the sorted index file.

         The source index file is called  TDINDX.USR.   The  sorted  and
         edited (by INDEX.SNO) file is named TDINDX.IND.

         SUTIND reads this file and outputs  TDINDX.LST  which  contains
         standard page headings and page numbers.

         The following dialogue takes place when SUTIND is executed:

         Enter revision date (yymmdd):
         780302
         Enter revision number (nn):
         2

         If no revision number is desired, enter a zero.

         Replace TDINDX.USR with TDINDX.SRT after an updating cycle  has
         been completed.


 I.8.7   Version numbers
         ---------------

         Version numbers exist in the following contexts:

      *  in source code files for the compiler, the run time system  and
         SIMDDT.
      *  in the SIMULA source listings produced by the compiler
      *  in .JBVER and .JBHVR during execution  and  in  .RBVER  in  the
         RIB's (Retrieval Information Blocks) of executable files (.EXE,
         .SAV, .SHR, .HGH, .LOW).
SIMULA FOR DEC SYSTEM 10             TD, SYSTEM DESC             I.8-6

740805    780302      6                           Olof Bjorner






         The version number is interpreted as follows:

              9        6           18             number of bits
         +---------+------+------------------+---+
         !    a    !   b  !        c         ! d !
         +---------+------+------------------+---+

     a   Major version number
         Common version number for the compiler  and  run  time  system.
         Changed only when new features are added or when older programs
         cannot be run with the new version due to a  redesign.   Listed
         as  an  octal  number  in  the  range  0-777.   Note  that some
         modifications must be made if  the  version  number  exceeds  7
         (e.g. names of SIMDDT and SIMRTS files).

     b   Minor version number
         The minor version  is  changed  between  major  revisions  when
         fairly important or numerous changes have been made.  Different
         components may have different  minor  versions  and  should  be
         compatible  as  long  as  the  major version is identical.  The
         minor version is edited as one or two letters:  A through BK.

     c   Edit level
         The edit level is an octal number in the range  0-777777.   The
         edit  level is changed with each modification to one or more of
         the source modules in the SIMULA system -  compiler,  run  time
         system, SIMDDT, SIMDIR.  The number is never decreased.
         Before release 3, edit numbers were used in a different fashion
         -  different  sequences in each of the compiler passes, the RTS
         and  SIMDDT.   In  the   compiler,   six-digit   numbers   were
         interpreted  as  a  concatenation  of 2-digit numbers for the 3
         passes.  2-digit numbers < 40 were assigned in the old fashion.
         Edit numbers starting with 40 are system-wide.

     d   Identification
         This number is intended to show who last changed the component:
         0       Digital development group
         1       Other Digital employees
         2-4     Reserved for customers (installations)
         5-7     Reserved for customer's users
SIMULA FOR DEC SYSTEM 10             TD, SYSTEM DESC             I.8-7

740805    780302      6                           Olof Bjorner








         Since SIMULA is not  a  DIGITAL  product,  we  use  0  for  our
         modifications.


         .JBVER is defined in the modules I1,I2, I3 and SIMRTS.
         .JBHVR will be copied from .JBVER.
         .RBVER is created when the segment is SAVEd.
         .JBVER is converted and edited into the compiler listing for  a
         SIMULA source program by pass 3.


         Version numbers in MACRO-10 source listings
         -------------------------------------------

         In each MACRO-10 module one of the macros CTITE, CUNIV,  RTITLE
         or  RUNIV  is  invoked.   CTITLE  is  used in compiler modules,
         RTITLE in RTS modules and in SIMDDT.  In the  parameter  files,
         CUNIV or RUNIV is used.
         Each of these macros takes one parameter which should be a text
         starting  with  the  module  name, possibly followed by a short
         explanatory text which must be  short  enough  to  fit  in  the
         heading.
         CTITLE and RTITLE expand to a TITLE  pseudo-operation,  whereas
         CUNIV and RUNIV will expand to a UNIVERSAL pseudo-operation.

         Example:
                 CTITLE I1
         might  give  the  following  page  header   in   the   MACRO-10
         compilation listing:
                 I1 DECsystem-10 SIMULA %4AM(473)-5
         CTITLE, CUNIV, RTITLE and RUNIV are defined in SIMMAC.MAC.


         Revisions of source code
         ------------------------

         All  revisions  are  numbered  consecutively  (note  the  octal
         radix).  A short explanation is placed in SIMULA.DOC indicating
         the reason for the change, normally by reference  to  an  error
         report  number.   For  each distinct code sequence changed, the
         module and subroutine are listed.  The revision number  updates
         the edit level of the SIMULA system.
SIMULA FOR DEC SYSTEM 10             TD, SYSTEM DESC             I.8-8

740805    780302      6                           Olof Bjorner








     The edit level is used in the following contexts:
     1.  Identifies a change documented in SIMULA.DOC.
     2.  In source code comments, surrounded by square  brackets:   e.g.
         [243].  This identifies the code changes.
     3.  In SIMMAC, the edit number appears in the macros CTITLE, CUNIV,
         RTITLE, RUNIV which define the headings in assembly listings.
     4.  The  EDIT  macro  is  gradually   being   introduced   to   get
         cross-references of edits via the symbols EDxxxx, where xxxx is
         the edit number.