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.