some corrections, added modula-2 docs

doc/Makefile

@@ -28,7 +28,7 @@ v7bugs.$(SUF):	v7bugs.doc
 install.$(SUF):	install.doc
 		$(TBL) install.doc | $(NROFF) $(MS) >$@
 pcref.$(SUF):	pcref.doc
-		$(NROFF) pcref.doc >$@
+		$(TBL) pcref.doc | $(NROFF) >$@
 val.$(SUF):	val.doc
 		$(NROFF) val.doc >$@
 6500.$(SUF):	6500.doc

doc/crefman.doc

@@ -56,10 +56,10 @@ The words are not interpreted by the compiler.
 .SH
 2.4.1 Integer Constants
 .PP
-An octal or hex constant which is less than or equal to the largest unsigned
+The type of an integer constant is the first of the corresponding list
-(target) machine integer is taken to be \f5unsigned\fP.
+in which its value can be represented. Decimal: \f5int, long, unsigned long\fP;
-An octal or hex constant which exceeds the largest unsigned (target) machine
+octal or hexadecimal: \f5int, unsigned, long, unsigned long\fP; suffixed by
-integer is taken to be \f5long\fP.
+the letter L or l: \f5long, unsigned long\fP.
 .SH
 2.4.3 Character Constants
 .PP

doc/m2ref.doc

@@ -0,0 +1,382 @@
+.TL
+The ACK Modula-2 Compiler
+.AU
+Ceriel J.H. Jacobs
+.AI
+Department of Mathematics and Computer Science
+Vrije Universiteit
+Amsterdam
+The Netherlands
+.AB no
+.AE
+.NH
+Introduction
+.PP
+This document describes the implementation-specific features of the
+ACK Modula-2 compiler. It is not intended to teach Modula-2 programming.
+For a description of the Modula-2 language, the reader is referred to [1].
+.PP
+The ACK Modula-2 compiler is currently available for use with the VAX,
+Motorola MC68020, Motorola MC68000,
+PDP-11, and Intel 8086 code-generators.
+For the 8086, MC68000, and MC68020,
+floating point emulation is used. This is made available with the \fI-fp\fP
+option, which must be passed to \fIack\fP[4,5].
+.NH
+The language implemented
+.PP
+This section discusses the deviations from the Modula-2 language as described
+in the "Report on The Programming Language Modula-2", as it appeared in [1],
+from now on referred to as "the Report".
+Also, the Report sometimes leaves room for interpretation. The section numbers
+mentioned are the section numbers of the Report.
+.PP
+Basically, the compiler recognizes the language as described in [1], and
+most of [2], for backwards compatibility. It warns the user for old-fashioned
+constructions (constructions that [1] does not allow).
+If the \fI-Rm2-3\fP option (see [6]) is passed to \fIack\fP, this backwards
+compatibility feature is disabled. Also, it may not be present on some
+smaller machines, like the PDP-11.
+.NH 2
+Syntax (section 2)
+.PP
+The syntax recognized is that of the Report, with some extensions to 
+also recognize the syntax of an earlier definition, given in [2].
+Only one compilation unit per file is accepted.
+.NH 2
+Vocabulary and Representation (section 3)
+.PP
+The input "\f510..\fP" is parsed as two tokens: "\f510\fP" and "\f5..\fP".
+.PP
+The empty string \f5""\fP has type
+.DS
+.ft 5
+ARRAY [0 .. 0] OF CHAR
+.ft P
+.DE
+and contains one character: \f50C\fP.
+.PP
+When the text of a comment starts with a '\f5$\fP', it may be a pragma.
+Currently, two pragmas exist:
+.DS
+.ft 5
+(*$F (F stands for Foreign) *)
+(*$R[+|-] (Runtime checks, on or off) *)
+.ft P
+.DE
+The Foreign pragma is only meaningful in a \f5DEFINITION MODULE\fP,
+and indicates that this
+\f5DEFINITION MODULE\fP describes an interface to a module written in another
+language (for instance C, Pascal, or EM).
+Runtime checks are: range-checks, checks when assigning CARDINALS to INTEGERS
+and vice versa, and checks that FOR-loop control-variables are not changed
+in the body of the loop.
+.PP
+Constants of type \f5LONGINT\fP are integers with a suffix letter \f5D\fP
+(for instance \f51987D\fP).
+Constants of type \f5LONGREAL\fP have suffix \f5D\fP if a scale factor is missing,
+or have \f5D\fP in place of \f5E\fP in the scale factor (f.i. \f51.0D\fP,
+\f50.314D1\fP).
+This addition was made, because there was no way to indicate long constants,
+and also because the addition was made in Wirth's newest Modula-2 compiler.
+.NH 2
+Declarations and scope rules (section 4)
+.PP
+Standard identifiers are considered to be predeclared, and valid in all
+parts of a program. They are called \fIpervasive\fP.
+Unfortunately, the Report does not state how this pervasiveness is accomplished.
+However, page 87 of [1] states: "Standard identifiers are automatically
+imported into all modules". Our implementation therefore allows
+redeclarations of standard identifiers within procedures, but not within
+modules.
+.NH 2
+Constant expressions (section 5)
+.PP
+Each operand of a constant expression must be a constant:
+a string, a number, a set, an enumeration literal, a qualifier denoting a
+constant expression, a typetransfer with a constant argument, or
+one of the standard procedures 
+\f5ABS\fP, \f5CAP\fP, \f5CHR\fP, \f5LONG\fP, \f5MAX\fP, \f5MIN\fP, \f5ODD\fP, \f5ORD\fP,
+\f5SIZE\fP, \f5SHORT\fP, \f5TSIZE\fP, or \f5VAL\fP, with constant argument(s);
+\f5TSIZE\fP and \f5SIZE\fP may also have a variable as argument.
+.PP
+Floating point expressions are never evaluated compile time, because
+the compiler basically functions as a cross-compiler, and thus cannot
+use the floating point instructions of the machine on which it runs.
+Also, \f5MAX(REAL)\fP and \f5MIN(REAL)\fP are not allowed.
+.NH 2
+Type declarations (section 6)
+.NH 3
+Basic types (section 6.1)
+.PP
+The type \f5CHAR\fP includes the ASCII character set as a subset. Values range from
+\f50C\fP to \f5377C\fP, not from \f50C\fP to \f5177C\fP.
+.NH 3
+Enumerations (section 6.2)
+.PP
+The maximum number of enumeration literals in any one enumeration type
+is \f5MAX(INTEGER)\fP.
+.NH 3
+Record types (section 6.5)
+.PP
+The syntax of variant sections in [1] is different from the one in [2].
+Our implementation recognizes both, giving a warning for the older one.
+However, see section 2.
+.NH 3
+Set types (section 6.6)
+.PP
+The only limitation imposed by the compiler is that the base type of the
+set must be a subrange type, an enumeration type, \f5CHAR\fP, or
+\f5BOOLEAN\fP. So, the lower bound
+does not have to be positive. However, if a negative lower bound is used,
+the compiler gives a warning of the \fIrestricted\fP class (see the manual
+page of the compiler).
+.PP
+The standard type \f5BITSET\fP is defined as
+.DS
+.ft 5
+TYPE BITSET = SET OF [0 .. 8*SIZE(INTEGER)-1];
+.ft P
+.DE
+.NH 2
+Expressions (section 8)
+.NH 3
+Operators (section 8.2)
+.NH 4
+Arithmetic operators (section 8.2.1)
+.PP
+The Report does not specify the priority of the unary operators \f5+\fP or \f5-\fP:
+It does not specify whether
+.DS
+.ft 5
+- 1 + 1
+.ft P
+.DE
+means
+.DS
+.ft 5
+- (1 + 1)
+.ft P
+.DE
+or
+.DS
+.ft 5
+(-1) + 1
+.ft P
+.DE
+I have seen some compilers that implement the first alternative, and others
+that implement the second. Our compiler implements the second, which is
+suggested by the fact that their priority is not specified, which might
+indicate that it is the same as that of their binary counterparts.
+And then the rule about left to right decides for the second.
+On the other hand, one might argue that, since the grammar only allows
+for one unary operator in a simple expression, it must apply to the
+whole simple expression, not just the first term.
+.NH 2
+Statements (section 9)
+.NH 3
+Assignments (section 9.1)
+.PP
+The Report does not define the evaluation order in an assignment.
+Our compiler certainly chooses an evaluation order, but it is explicitly
+left undefined. Therefore, programs that depend on it, may cease to
+work later.
+.PP
+The types \f5INTEGER\fP and \f5CARDINAL\fP are assignment-compatible with
+\f5LONGINT\fP, and \f5REAL\fP is assignment-compatible with \f5LONGREAL\fP.
+.NH 3
+Case statements (section 9.5)
+.PP
+The size of the type of the case-expression must be less than or equal to
+the word-size.
+.PP
+The Report does not specify what happens if the value of the case-expression
+does not occur as a label of any case, and there is no \f5ELSE\fP-part.
+In our implementation, this results in a runtime error.
+.NH 3
+For statements (section 9.8)
+.PP
+The Report does not specify the legal types for a control variable.
+Our implementation allows the basic types (except \f5REAL\fP),
+enumeration types, and subranges.
+A runtime warning is generated when the value of the control variable
+is changed by the statement sequence that forms the body of the loop,
+unless runtime checking is disabled.
+.NH 3
+Return and exit statements (section 9.11)
+.PP
+The Report does not specify which result-types are legal.
+Our implementation allows any result type.
+.NH 2
+Procedure declarations (section 10)
+.PP
+Function procedures must exit through a RETURN statement, or a runtime error
+occurs.
+.NH 3
+Standard procedures (section 10.2)
+.PP
+Our implementation supports \f5NEW\fP and \f5DISPOSE\fP
+for backwards compatibility,
+but issues warnings for their use. However, see section 2.
+.PP
+Also, some new standard procedures were added, similar to the new standard
+procedures in Wirth's newest compiler:
+.IP \-
+\f5LONG\fP converts an argument of type \f5INTEGER\fP or \f5REAL\fP to the types \f5LONGINT\fP or
+\f5LONGREAL\fP.
+.IP \-
+\f5SHORT\fP performs the inverse transformation, without range-checks.
+.IP \-
+\f5FLOATD\fP is analogous to \f5FLOAT\fP, but yields a result of type
+\f5LONGREAL\fP.
+.IP \-
+\f5TRUNCD\fP is analogous to \f5TRUNC\fP, but yields a result of type
+\f5LONGINT\fP.
+.NH 2
+System-dependent facilities (section 12)
+.PP
+The type \f5BYTE\fP is added to the \f5SYSTEM\fP module.
+It occupies a storage unit of 8 bits.
+\f5ARRAY OF BYTE\fP has a similar effect to \f5ARRAY OF WORD\fP, but is
+safer. In some obscure cases the \f5ARRAY OF WORD\fP mechanism does not quite
+work properly.
+.PP
+The procedure \f5IOTRANSFER\fP is not implemented.
+.NH 1
+Compile time errors
+.PP
+The compile time error messages are intended to be self-explanatory,
+and not listed here. The compiler also sometimes issues warnings, 
+recognizable by a warning-classification between parentheses.
+Currently, there are 3 classifications:
+.IP "(old-fashioned use)"
+.br
+These warnings are given on constructions that are not allowed by [1], but are
+allowed by [2].
+.IP (strict)
+.br
+These warnings are given on constructions that are supported by the 
+ACK Modula-2 compiler, but might not be supported by others.
+Examples: functions returning structured types, SET types of subranges with
+negative lower bound.
+.IP (warning)
+.br
+The other warnings, such as warnings about variables that are never assigned,
+never used, etc.
+.NH 1
+Runtime errors
+.PP
+The ACK Modula-2 compiler produces code for an EM machine as defined in [3].
+Therefore, it depends on the implementation
+of the EM machine for detection some of the runtime errors that could occur.
+.PP
+The \fITraps\fP module enables the use to install his own runtime error handler.
+The default one just displays what happened and exits.
+Basically, a trap handler is just a procedure that takes an INTEGER as
+parameter. The INTEGER is the trap number. This INTEGER can be one of the
+EM trap numbers, listed in [3], or one of the numbers listed in the
+\fITraps\fP definition module.
+.PP
+The following runtime errors may occur:
+.IP "array bound error"
+.br
+The detection of this error depends on the EM implementation.
+.IP "range bound error"
+.br
+Range bound errors are always detected, unless runtime checks are disabled.
+.IP "set bound error"
+.br
+The detection of this error depends on the EM implementation.
+The current implementations detect this error.
+.IP "integer overflow"
+.br
+The detection of this error depends on the EM implementation.
+.IP "cardinal overflow"
+.br
+This error is detected, unless runtime checks are disabled.
+This message is also given on cardinal underflow.
+.IP "real overflow"
+.br
+The detection of this error depends on the EM implementation.
+.IP "real underflow"
+.br
+The detection of this error depends on the EM implementation.
+.IP "divide by 0"
+.br
+The detection of this error depends on the EM implementation.
+.IP "divide by 0.0"
+.br
+The detection of this error depends on the EM implementation.
+.IP "undefined integer"
+.br
+The detection of this error depends on the EM implementation.
+.IP "undefined real"
+.br
+The detection of this error depends on the EM implementation.
+.IP "conversion error"
+.br
+This error occurs when assigning a negative value of type INTEGER to a
+variable of type CARDINAL,
+or when assigning a value of CARDINAL, that is > MAX(INTEGER), to a
+variable of type INTEGER.
+It is detected, unless runtime checking is disabled.
+.IP "stack overflow"
+.br
+The detection of this error depends on the EM implementation.
+.IP "heap overflow"
+.br
+The detection of this error depends on the EM implementation.
+Might happen when ALLOCATE fails.
+.IP "case error"
+.br
+This error occurs when non of the cases in a CASE statement are selected,
+and the CASE statement has no ELSE part.
+The detection of this error depends on the EM implementation.
+All current EM implementations detect this error.
+.IP "stack size of process too large"
+.br
+The current implementation limits the stack size of processes to 1024 bytes.
+.IP "too many nested traps + handlers"
+.br
+This error can only occur when the user has installed his own trap handler.
+It means that during execution of the trap handler another trap has occurred,
+and that several times.
+In some cases, this is an error because of overflow of some internal tables.
+.IP "no RETURN from procedure function"
+.br
+This error occurs when a procedure function does not return properly
+("falls" through).
+.IP "illegal instruction"
+.br
+This error might occur when you use floating point operations on an
+implementation that does not have floating point.
+.NH 1
+Calling the compiler
+.PP
+See [4,5,6] for a detailed explanation.
+.NH 1
+References
+.IP [1]
+Niklaus Wirth,
+.I
+Programming in Modula-2, third, corrected edition,
+.R
+Springer-Verlag, Berlin (1985)
+.IP [2]
+Niklaus Wirth,
+.I
+Programming in Modula-2,
+.R
+Stringer-Verlag, Berlin (1983)
+.IP [3]
+A.S.Tanenbaum, J.W.Stevenson, Hans van Staveren, E.G.Keizer,
+.I
+Description of a machine architecture for use with block structured languages,
+.R
+Informatica rapport IR-81, Vrije Universiteit, Amsterdam
+.IP [4]
+UNIX manual \fIack\fP(1)
+.IP [5]
+UNIX manual \fImodula-2\fP(1)
+.IP [6]
+UNIX manual \fIem_m2\fP(6)

doc/pcref.doc

@@ -418,31 +418,31 @@ not checked.
 For those who wish the use the interface between C and Pascal we
 give an incomplete list of corresponding formal parameters in C and Pascal.
 .sp 1
-.ta 8 37
+.TS
-.nf
+l l.
-	Pascal	C
+Pascal	C
-	a:integer	int a
+a:integer	int a
-	a:char	int a
+a:char	int a
-	a:boolean	int a
+a:boolean	int a
-	a:real	double a
+a:real	double a
-	a:^type	type *a
+a:^type	type *a
-	var a:type	type *a
+var a:type	type *a
-	procedure a(pars)	struct {
+procedure a(pars)	struct {
-		     void (*a)() ;
+	     void (*a)() ;
-		     char *static_link ;
+	     char *static_link ;
-		}
+	}
-	function a(pars):type	struct {
+function a(pars):type	struct {
-		     type (*a)() ;
+	     type (*a)() ;
-		     char *static_link ;
+	     char *static_link ;
-		}
+	}
-.fi
+.TE
 The Pascal runtime system uses the following algorithm when calling
 function/procedures passed as parameters.
-.nf
+.TS
-.ta 8 16
+l l.
-	if ( static_link ) (*a)(static_link,pars) ;
+if ( static_link )	(*a)(static_link,pars) ;
-	else               (*a)(pars) ;
+else	(*a)(pars) ;
-.fi
+.TE
 .IT 6.7.2.1
 The order of evaluation of the operands of a dyadic operator
 shall be implementation-dependent.