Trailing-Edge
-
PDP-10 Archives
-
decuslib20-03
-
decus/20-0078/maint/tdi8.rno
There is 1 other file named tdi8.rno in the archive. Click here to see a list.
.sp 1;.nonum;.lm 9;.ps 50,72
.ts 1,9,17,25,33,41,49,57,65
.pg;.nm ch 8
.ch SIMULA FOR DEC SYSTEM 10#############TD, SYSTEM DESC
.nm 1
.st 740805####780302######6###########################Olof Bjorner
.pg;.lm 9;.p -8,0,10;I.8#####DOCUMENTATION STANDARD
.P -8,2,5;I.8.1###Introduction
.br;------------
.s;This standard covers the layout of the Technical Documentation
and describes the routine for revisions.
.p -8,2,10;I.8.2###Page headings
.br;-------------
.s;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:
.s;E#N#E#A##D#A#T#A###(large#boldface)
.s;.lt 5
+-----------------------+---------------------------------------+------+
! Project Part Page !
+-------+----------+----+----------------------+-----------------------+
! Date Rev.date No Identification Originator !
+----------------------------------------------------------------------+
.el
.s;"Project" should always be "SIMULA FOR DEC SYSTEM 10".
.s;The text in the Part field should be as shown in the following table:
.p 0,1,11;.lt 10
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.
.EL
.P-8,2,10;I.8.3###Section numbers and headings
.br;----------------------------
.s;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.
.p -8,2,8;I.8.4###Page numbers
.br;------------
.s;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.
.p -8,2,6;I.8.5###Revisions
.br;---------
.s;Revisions should be made as follows:
.lm 17;.p -8,1,5;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.
.p -8,1,3;2.######All revised pages should be rewritten completely.
In practice, this is not always done.
.p -8,1,5;3.######A revision page should be written. This page should
contain information about revised and new pages and cause of revision.
.p -8,1,5;4.######The revision page should have the Part text
.br;REVISION NO nn.
.p -8,1,6;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.
.lm 9;.pg;REVISION
.s;Revised pages
.br;-------------
.s 15;New pages
.br;---------
.s 15;Revision purpose
.br;----------------
.pg;.lm 9;.i -8;I.8.6###Updating the index to the Technical Documentation.
.br;-------------------------------------------------
.s;The index (section VII) has been developed using two programs:
INDEX.SNO and SUTIND.SIM.
.s;INDEX.SNO is a general purpose index program developed at FOA.
It supports the following functions:
.nf;(1) Updating an index file with new keywords
(2) Editing the sorted index file
(3) Listing the sorted index file.
.s;.f;The source index file is called TDINDX.USR.
The sorted and edited (by INDEX.SNO) file is named TDINDX.IND.
.s;SUTIND reads this file and outputs TDINDX.LST which contains standard
page headings and page numbers.
.s;The following dialogue takes place when SUTIND is executed:
.nf;.s;Enter revision date (yymmdd):
780302
Enter revision number (nn):
2
.f;.s;If no revision number is desired, enter a zero.
.s;Replace TDINDX.USR with TDINDX.SRT after an updating cycle has
been completed.
.p -8,2,10;I.8.7###Version numbers
.br;---------------
.s;Version numbers exist in the following contexts:
.p -3,1,7;*##in source code files for the compiler, the run time
system and SIMDDT.
.i -3;*##in the SIMULA source listings produced by the compiler
.i -3;*##in .JBVER and .JBHVR during execution and in .RBVER in the
RIB's (Retrieval Information Blocks) of executable files (.EXE, .SAV,
_.SHR, .HGH, .LOW).
.p 0,1,10;.nf;The version number is interpreted as follows:
.s;
# 9 6 18 number of bits
+---------+------+------------------+---+
! a ! b ! c ! d !
+---------+------+------------------+---+
.f;.p -4,1,6;a###Major version number
.br;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).
.p -4,1,7;b###Minor version number
.br;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.
.p -4,1,5;c###Edit level
.br;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.
.br;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.
.p -4,1,8;.nf;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
.p 0,1,6;.f;Since SIMULA is not a DIGITAL product, we use 0 for our
modifications.
.lm 9;.p 0,2,7;_.JBVER is defined in the modules I1,I2, I3 and SIMRTS.
.br;_.JBHVR will be copied from .JBVER.
.br;_.RBVER is created when the segment is SAVEd.
.br;_.JBVER is converted and edited into the compiler listing for
a SIMULA source program by pass 3.
.p 0,2,10;Version numbers in MACRO-10 source listings
.br;-------------------------------------------
.s;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.
.br;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.
.br;CTITLE and RTITLE expand to a TITLE pseudo-operation, whereas
CUNIV and RUNIV will expand to a UNIVERSAL pseudo-operation.
.p 0,1,8;Example:
.br;########CTITLE I1
.br;might give the following page header in the MACRO-10 compilation
listing:
.br;########I1 DECsystem-10 SIMULA %4AM(473)-5
.br;CTITLE, CUNIV, RTITLE and RUNIV are defined in SIMMAC.MAC.
.p 0,2,10;Revisions of source code
.br;------------------------
.s;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.
.p -4,0,10;The edit level is used in the following contexts:
.p -4,0,2;1.##Identifies a change documented in SIMULA.DOC.
.i-4;2.##In source code comments, surrounded by square brackets:
e.g_. [243]. This identifies the code changes.
.i -4;3.##In SIMMAC, the edit number appears in the macros CTITLE,
CUNIV, RTITLE, RUNIV which define the headings in assembly listings.
.i -4;4.##The EDIT macro is gradually being introduced to get
cross-references of edits via the symbols EDxxxx, where xxxx is the
edit number.