]> thyrsus.com Git - mad.git/commitdiff
Chapter II is typed in.
authorEric S. Raymond <esr@thyrsus,com>
Thu, 11 Mar 2004 06:29:24 +0000 (06:29 +0000)
committerEric S. Raymond <esr@thyrsus,com>
Thu, 11 Mar 2004 06:29:24 +0000 (06:29 +0000)
doc/mad-manual.xml

index 9b76c6be822038ea450e63a3f39f84ad23532683..c3761874f7b59a8b45de6f42525e33f655fc9e71 100644 (file)
@@ -6,6 +6,7 @@
 <!ENTITY newton1 SYSTEM "../madhouse/newton1.mad">
 <!ENTITY newton2 SYSTEM "../madhouse/newton2.mad">
 <!ENTITY quadratic SYSTEM "../madhouse/quadratic.mad">
+<!ENTITY invsf SYSTEM "../madhouse/invsf.mad">
 <!ENTITY truthtable SYSTEM "../madhouse/truthtable.mad">
 <!ENTITY simpsfunc SYSTEM "../madhouse/simpsfunc.mad">
 <!ENTITY simpsmain SYSTEM "../madhouse/simpsmain.mad">
@@ -466,6 +467,7 @@ ugly by contrast.</para>
 
 </sect1>
 </preface>
+<!-- pagebreak -->
 <preface><title>The Michigan Algorithm Decoder</title>
 
 <para>The Michigan Algorithm Decoder (MAD) is a computer program
@@ -496,7 +498,7 @@ University of Michigan students and staff.</para>
                            R. Graham
 </literallayout>
 </preface>
-
+<!-- pagebreak I.1 -->
 <chapter><title>INTRODUCTION</title>
 
 <para>In order to present a problem to a digital computer for
@@ -545,7 +547,7 @@ number in the collection A.</para>
 Such words as "compare", "moving down the list", and "finally saved"
 should really be spelled out more exactly.</para>
 
-<!-- beginpage -->
+<!-- beginpage I.2 -->
 
 <para>The following restatement of the procedure would probably be
 more suitable:</para>
@@ -608,7 +610,7 @@ on the left."</para>
 </listitem>
 </orderedlist>
 
-<!-- beginpage -->
+<!-- beginpage I.3 -->
    
 <para>Although this problem does not require it, we frequently ask a
 question like "Does j = n?"  The "=" in this context is a
@@ -661,8 +663,9 @@ THROUGH BACK, FOR ALPHA = 12, 3 ALPHA .G. 90 .OR. .ABS. (X+Y) .LE. EPSLON
 <para>Here we have substituted ".G." for ">", ".LE." for "&le;",
 ".ABS. (X+Y)" for "|x + y|".  (The reason for these simple
 substitutions is the lack of characters such as >, &le; as input to
-the computer.  Such details are fully presented <!-- beginpage --> in
-Chapter II of this manual.)</para>
+the computer.  Such details are fully presented 
+<!-- beginpage I.4 --> 
+in Chapter II of this manual.)</para>
 
 <note><para>The IBM 704 on which MAD was implemented had a
 very primitive pre-ASCII character set.  It did not even include
@@ -707,7 +710,7 @@ to recognize the statement type with a minimum of analysis.</para>
 <para>Generality - a few restrictions on the construction of
 statements and expressions have been introduced as possible.</para>
 </listitem>
-<!-- beginpage -->
+<!-- beginpage I.5 -->
 <listitem>
 <para>Ease of adding to the language - desired additions can be
 made easily, since most of the necessary information can be stored in
@@ -755,14 +758,15 @@ action (Z = a<subscript>j</subscript>), otherwise just go on.</para>
 used in making decisions.  We have seen that such conditions may occur
 in iterations statements, and "WHENEVER" statements, etc., for the
 purose of making binary (i.e., "yes" or "no") choices.  An expression
-which can be labelled <!-- beginpage -->
-"True" or "False" is exactly what is needed
-here.  Such expressions are called
-<emphasis>Boolean</emphasis><footnote><para>After the logician George
-Boole.</para></footnote> <emphasis>expressions</emphasis>, and usually
-involve "and", "or", "not", and possibly other such words connecting
-shorter expressions involving &lt;, &le;, =, &ne;, &gt;, and &ge;.
-For example, the following is a Boolean expression:</para>
+which can be labelled 
+<!-- beginpage I.6 -->
+"True" or "False" is exactly what is needed here.  Such expressions
+are called <emphasis>Boolean</emphasis><footnote><para>After the
+logician George Boole.</para></footnote>
+<emphasis>expressions</emphasis>, and usually involve "and", "or",
+"not", and possibly other such words connecting shorter expressions
+involving &lt;, &le;, =, &ne;, &gt;, and &ge;.  For example, the
+following is a Boolean expression:</para>
 
 <programlisting>
 ((x - 3)<superscript>3</superscript> &lt; y and i &le; j) or x &ge; 3
@@ -802,7 +806,7 @@ give it a name, say MAX., since it will be written and translated
 externally with respect to the program which will later call upon it.
 The program will now be written:</para>
 
-<!-- page break after "FUNCTION RETURN Z" in this listing -->
+<!-- beginpage I.7 after "FUNCTION RETURN Z" in this listing -->
 <programlisting>
 &maxfunc;
 </programlisting>
@@ -860,8 +864,10 @@ x is replaced by x - f(x)/f'(x)
 </programlisting>
 
 <para>Often a left arrow (&larr;) is used to mean "is replaced by" but
-in the actual <!-- beginpage --> statements produced for the computer
-the "=" symbol conventionally has this meaning.</para>
+in the actual 
+<!-- beginpage I.8 --> 
+statements produced for the computer the "=" symbol conventionally has
+this meaning.</para>
 
 <para>It is important to realize what the "=" means in this context; it is
 different from the usual use of the symbol where it indicated a
@@ -897,7 +903,7 @@ flow diagram.</para>
   </imageobject>
 </mediaobject>
 
-<!-- beginpage -->
+<!-- beginpage I.9 -->
 
 <para>The corresponding statements are:</para>
 
@@ -934,7 +940,7 @@ log<subscript>e</subscript> and the item in parentheses following this
 name indicated the variable whose natural logarithm is
 desired.</para></listitem>
 
-<!-- beginpage -->
+<!-- beginpage I.10 -->
 
 <listitem><para>The following statement is a simple conditional which
 causes the function and iterative formula to be evaluated
@@ -981,7 +987,7 @@ computer would continue until it has exhausted the given input
 values of a, x, &epsi;.</para></listitem>
 </orderedlist>
 
-<!-- beginpage -->
+<!-- beginpage I.11 -->
 
 <para>The final example before the description of the language in
 Chapter II is a more general and more elaborate illustration of
@@ -1034,7 +1040,7 @@ with more than two successive aproximations to the root &mdash; say x
 and x<subscript>m</subscript> (for next x) &mdash; and that the
 incrementing of i is not really necessary.</para>
 
-<!-- beginpage -->
+<!-- beginpage I.12 -->
 
 <!-- The "NO CONVERGENCE" literal in figure 4 was missing a trailing quote. -->
 <mediaobject>
@@ -1043,7 +1049,7 @@ incrementing of i is not really necessary.</para>
   </imageobject>
 </mediaobject>
 
-<!-- beginpage -->
+<!-- beginpage I.13 -->
 
 <!-- This listing in the original was defective,
 missing continuation punches everywhere but in INTERNAL FUNCTION
@@ -1063,7 +1069,7 @@ actually has as values the format information in alphabetic form
 (sometimes called HOllerith, or binary-coded decimal (BCD) form). The
 con&shy;struction and analysis of format information is thoroughly
 discussed in Chapter II.</para>
-<!-- page break at the soft hyphen above -->
+<!-- beginpage I.14 at the soft hyphen above -->
 
 <para>The second statement in the program causes the inout information,
 properly labeled., to print out, preceded by the title "SOLUTION OF
@@ -1091,6 +1097,7 @@ description of format, in problems where the format may change from
 one set of data to another.</para>
 </chapter>
 
+<!-- beginpage II.1 -->
 <chapter><title>DESCRIPTION OF THE LANGUAGE</title>
 
 <sect1><title>Constants, Variables, Operations, and Expressions</title>
@@ -1134,7 +1141,7 @@ preceded by a sign (although a "+" sign may be omitted), and must
 satisfy the condition -38 &ge; m &ge; 38.  Examples of floating-point
 constants with exponent are; 
 
-<!-- beginpage -->
+<!-- beginpage II.2 -->
 
 .05E-2(= .05 &times; 10<superscript>-2</superscript>) -.05E2(= -.05
 &times; 10<superscript>2</superscript>),
@@ -1185,10 +1192,10 @@ following are "single variables:": X51, ALPHA6, LAMBDA, GROSS, while
 the following are elements of arrays: BETA(C1, C2, 6), X15(Y, Z1),
 J(6), J(Z1 + 5 *Z2, 5). (See <xref linkend='subscripts'/> for the
 description of subscripts.) Parentheses enclosing subscripts may not
-be <!-- beginpage --> omitted.</para>
+be omitted.</para>
 </sect2>
 
-<!-- begin page -->
+<!-- beginpage II.3 -->
 
 <sect2 id='statement_labels'><title>Statement Labels</title> 
 
@@ -1238,7 +1245,7 @@ are integers, the result is again an integer; e.g., the
 rounded).  For example, if Z5 = 7, and D = 3, the Z5 = D will
 have the value 2.</para></listitem>
 
-<!-- beginpage -->
+<!-- beginpage II.4 -->
 <listitem><para>Exponentiation, written as ".P.", e.g., Z5.P.D, and
 meaning (Z5)<superscript>D</superscript>, i.e., Z5 raised to the power
 D.</para></listitem>
@@ -1290,7 +1297,7 @@ have the value 1B.</para></listitem>
 <listitem><para>M.THEN.P has the value 0B if and only if M has the
 value 1B and P has the value 0B.</para></listitem>
 
-<!-- beginpage -->
+<!-- beginpage II.5 -->
 
 <listitem><para>M.EQV.P has the value 1B if and only if M and P have
 the same values.</para></listitem>
@@ -1340,7 +1347,7 @@ parentheses are allowed.</para>
 <para>(A) Within any expression the sequence of computation, unless
 otherwise indicated by parentheses, is:</para>
 
-<!-- beginpage -->
+<!-- beginpage II.6 -->
 <literallayout>
 .ABS., + (as unary operations)
 .P.
@@ -1378,7 +1385,7 @@ otherwise indicated by parentheses, is:</para>
 of the list in (A) are to be performed from left to right, unless
 otherwise indicated by parentheses.</para>
 
-<!-- beginpage -->
+<!-- beginpage II.7 -->
 <para>Examples:</para>
 
 <orderedlist>
@@ -1431,7 +1438,7 @@ I + GCD.(I, J)
 I + 1
 GCD.(I, J)/I
 </literallayout>
-<!-- beginpage -->
+<!-- beginpage II.8 -->
 <para>are all integer expressions.</para>
 
 <para>If an expression has subexpressions of different modes, a conversion
@@ -1484,8 +1491,9 @@ division of two integers.  In the computation of
 T<subscript>4</subscript>, however, we have "mixed modes", since Y is
 floating point and T<subscript>3</subscript> is integer.  There
 I<subscript>3</subscript> will be automatically converted to floating
-point before adding.  Likewise, in the next step, <!-- beginpage
--->the integer T<subscript>2</subscript> will be converted to floating
+point before adding.  Likewise, in the next step, 
+<!-- beginpage II.9 -->
+the integer T<subscript>2</subscript> will be converted to floating
 point before adding to the floating point number.</para>
 
 <para>In other words, although the mode of the expression is floating
@@ -1539,7 +1547,7 @@ MP(A, B + 6 * J, I * 6/TDX), MA(K(Z + 5) + T(1) + 6).</para>
 
 <sect2 id='substitution'><title>Substitution Statement</title>
 
-<!-- beginpage -->
+<!-- beginpage II.10 -->
 <para>This statement has the form illustrated by</para>
 
 <para role='centered'>
@@ -1602,7 +1610,7 @@ following floating point numbers:</para>
 <para>This statement has the form:  TRANSFER TO &scriptS;</para>
 
 <para>Here &scriptS; may be any statement label or any expression in
-<!-- beginpage -->
+<!-- beginpage II.11 -->
 statement label mode which labels an executable statement.  Execution
 of this statement causes the computation to continue from the
 statement whose label is the value of &scriptS;.  Examples: TRANSFER TO
@@ -1660,7 +1668,7 @@ WHENEVER I.GE.N.AND.J.NE.I-1, I=0
         
 <para>Often the last condition B<subscript>k</subscript> is always
 true.  This may be expressed by the statement</para>
-<!-- beginpage -->
+<!-- beginpage II.12 -->
 
 <programlisting>
 OR WHENEVER 1B
@@ -1715,7 +1723,7 @@ END OF CONDITIONAL
 
 <para>This section of program could be rewritten in another way.</para>
 
-<!-- beginpage after "Y = X" -->
+<!-- beginpage II.13 after "Y = X" -->
 <programlisting>
 WHENEVER 0. .LE. X .AND. X .L. 1.
 Y = X
@@ -1778,13 +1786,15 @@ The block of statements following (and not including) the THROUGH
 statement, up to <emphasis>and including</emphasis> the statement
 whose label is &scriptS;, will be called the "scope" of the THROUGH
 statement.  Following the word OF appears the name of the iteration
-variable (in <!-- beginpage -->the illustration: V), which may be
-either an individual variable or subscripted array variable of any
-mode.  To the right of the "=" sign may appear any number of
-expressions E<subscript>1</subscript>, ... E<subscript>m</subscript>.
-The modes of the E<subscript>1</subscript> bear the same relationship
-to the mode of V as they would in the statement V =
-E<subscript>1</subscript> (see <xref linkend='substitution'/>).</para>
+variable (in 
+<!-- beginpage II.14 -->
+the illustration: V), which may be either an individual variable or
+subscripted array variable of any mode.  To the right of the "=" sign
+may appear any number of expressions E<subscript>1</subscript>,
+... E<subscript>m</subscript>.  The modes of the
+E<subscript>1</subscript> bear the same relationship to the mode of V
+as they would in the statement V = E<subscript>1</subscript> (see
+<xref linkend='substitution'/>).</para>
 
 <para>The execution of this statement causes the statements within its
 "scope" to be executed, first with V = E<subscript>1</subscript>, then
@@ -1792,9 +1802,10 @@ again with V = E<subscript>2</subscript>, and so on, until the list of
 expressions is exhausted.  Computation then proceeds with the
 statement immediately following statement &scriptS;.  At this time the
 iteration variable will have the value of the expression
-E<subscript>m</subscript> unless <!-- beginpage -->its value was
-changed during the final iteration. An example of this type of
-statement is:</para>
+E<subscript>m</subscript> unless 
+<!-- beginpage II.15 -->
+its value was changed during the final iteration. An example of this
+type of statement is:</para>
 
 <programlisting>
        THROUGH A, FOR VALUES OF BETA = 3, 4, X5, Y(6 + I) + 3
@@ -1839,12 +1850,13 @@ the transfer was made.</para>
 
 <para>In all cases, every reference to an expression
 E<subscript>1</subscript> will involve its current value at the time
-of reference.  Moreover, the variable <!-- beginpage --> V may have
-its value changed at any time during the execution of the scope.  In a
-statement of the form (a), the value of V will be reset by the value
-of the next E<subscript>1</subscript> for the next computation of the
-scope.  In a statement of form (b), the current value of V will be
-used for incrementing, testing, etc.</para>
+of reference.  Moreover, the variable 
+<!-- beginpage II.16 --> 
+V may have its value changed at any time during the execution of the
+scope.  In a statement of the form (a), the value of V will be reset
+by the value of the next E<subscript>1</subscript> for the next
+computation of the scope.  In a statement of form (b), the current
+value of V will be used for incrementing, testing, etc.</para>
 
 <para>Examples:</para>
 
@@ -1891,7 +1903,7 @@ iteration is to be performed for those multiples of 2 which are not
 multiples of 5 and which are less than the value of the integer K, one
 might write the iteration as follows:</para>
 
-<!-- beginpage -->
+<!-- beginpage II.17 -->
 
 <programlisting>
        THROUGH END, FOR J = 2, .GE. K
@@ -1938,7 +1950,7 @@ themselves, be iteration statements.  However, if iteration statement
 be entirely within the scope of <emphasis>a</emphasis>.  The following
 diagrams represent some valid configurations:</para>
 
-<!-- beginpage -->
+<!-- beginpage II.18 -->
 &scope1;
 
 <para>Here, although the scopes of <emphasis>a</emphasis> and
@@ -1953,7 +1965,7 @@ iteration <emphasis>b</emphasis> is completed before iteration
 
 &scope3;
 
-<!-- beginpage -->
+<!-- beginpage II.19 -->
 <para>When iteration statements occur in the scope of other iteration
 statements, they are said to be "nested".  The "nesting depth" of an
 iteration statement is the number of iteration statements in whose
@@ -1973,7 +1985,7 @@ statements in the scope of an iteration.</para>
 
 </sect2>
 
-<!-- beginpage -->
+<!-- beginpage II.20 -->
 <sect2><title>Pause Statement</title>
 
 <programlisting>
@@ -3372,22 +3384,161 @@ statements define a function).  If this is defining an external
 function, the declaration would be EXTERNAL FUNCTION (X).  Following
 the words INTERNAL (or EXTERNAL) FUNCTION is the dummy variable list
 ((X) in this example).  The END OF FUNCTION declaration is the last
-statement in the function definition program.  (In an external
-<!-- beginpage -->
+statement in the function definition program.  (In an external 
+<!-- beginpage --> 
 function definition this is also the last statement in the program.)
 An entry must provided for each function being defined, but several
 functions may share any number of FUNCTION RETURN statements.  An
 entry statement merely marks a point of entry, and does not effect the
 sequence of computation in any way.  The expression after the word
 "RETURN" indicates that on this return the value of the function is to
-be the value of that expression.</para>
+be the value of that expression. This expression must agree in mode
+with the function whose value it supplies; this agreement is not
+checked.  The definitions of functions whose calls are intended to be
+included in expressions must have an expression following the FUNCTION
+RETURN statement.  If the calls for a function are to appear in an
+EXECUTE STATEMENT (generally such functions have multiple outputs) the
+FUNCTION RETURN statement may appear without an accompanying
+expression.</para>
 
-<!-- MORE GOES HERE -->
+<para>An example of a definition for procedures is as follows:</para>
 
+<programlisting>
+EXTERNAL FUNCTION (M, N, I, P, Q)
+STATEMENT LABEL N, I
+...
+...
+...
+FUNCTION RETURN
+...
+...
+...
+WHENEVER B, TRANSFER TO I
+...
+...
+...
+TRANSFER TO N
+END OF FUNCTION
+</programlisting>
+
+<para>In this example, N and I are actual alternate exits, and B represents
+some Boolean expression.</para>
+
+<para>It is important to note that internal function definitions of
+any kind whatever (including the single statement definition of <xref
+linkend='internal_functions'/>) may occur anywhere in the program,
+except within another internal function definition.  Internal function
+definitions may occur within external function definitions, however.
+External function definitions may not occur within any other programs,
+not even within other external function definitions.  Each external
+function definition must be a complete, self-contained program.</para>
+<!-- beginpage II.47 after the last hyphen -->
+
+<para>The following is an example of a function whose value is 1/x if
+0 &lt; x &le; 1 and 1/x^2 if x &gt; 1.  If x &le; 0, one obtains an
+error return (see <xref linkend='ERROR_RETURN'/>).</para>
+
+<programlisting>
+&invsf;
+</programlisting>
+
+<para>(Here the statments are all labelled only for reference in what
+follows.)</para>
+
+<para>The list of dummy variables in the declaration statement itself
+(statement A in the preceding paragraph) may contain only
+nonsubscripted variable names (either individual or array) or function
+names (without arguments).  Within the definition program itself (the
+statements between statement A and statement B), a function name will
+usually occur with arguments, and an array variable will usually occur
+with subscripts.</para>
+
+<para>A few comments about the last example.  This definition program
+defines a single-valued function of X, called INVSF..  Since no mode
+declaration is given it is assumed by the translator that X is
+floating point.  The value of INVSF.(X) is computed by the use of a
+compound conditional.  If 0 &lt; x &le; 1, (statement G) then statement C
+is executed, causing a return to the calling program with the value
+1/x.  If the condition 0 &lt; x &le; 1 is not true, then the condition X
+> 1 is tested (statement H).  If X &gt; 1, statement D is executed.
+Finally, if neither of the conditions 0 &lt; x &le; 1 or x &gt; 1 is true,
+then statement I finds that X &le; 0 and statement E (the error
+return) is executed.  If</para>
+
+<!-- beginpage II.48 after Z = T(I) + INVSP.(Y) *T(I-1) -->
+
+<programlisting>
+         A = B - D
+         Z = T(I) + INVSF.(Y) *T(I-1)
+         Y(I) = Z + R(J) * 2.5
+</programlisting>
+
+<para>is part of a program and the error return statement is executed during
+the evaluation of INVSF.(Y) (i.e., Y &le; 0), then control is returned to
+the system in which the translated program is embedded, with an error
+flag set.  If</para>
+
+<programlisting>
+       A = B - D
+     F  Z = T(X) + INVSF.(Y, ER)* T(I-1)
+     S Y(I) = Z = R(J) * 2.5
+       ...
+       ...
+    ER  Z = 0
+    L   Y(I) = 1.
+       ...
+</programlisting>
+
+<para>is part of a program and Y &le; 0, then when the ERROR RETURN
+statement is executed control transfers to statement ER (then goes on
+to L), instead of finishing the execution of statement F (and then
+going on to S).  Note that the END OF FUNCTION statement will never be
+executed, but must be present in the definition.</para>
 </sect3>
 </sect2>
+</sect1>
+<sect1><title>Restrictions</title>
+
+<para>Variable names appearing as <emphasis>dummy</emphasis> arguments in
+any function declaration may not appear in a PROGRAM COMMON, ERASABLE,
+or EQUIVALENCE declaration.</para>
+
+<para>The name of a function with the period deleted must not be used as the
+name of a variable or as a statement label.  A statement label must
+not be identical with any variable name.</para>
+
+<para>The translator automatically calls on some subroutines, hence the
+following names may not be used as variable names or statement labels
+in a MAD program.  They may be used as function names only when
+referring to these subroutines.  (These subroutines will be described
+in Chapter 4).</para>
+
+<programlisting>
+       SYSTEM.         SETEOF.         PRINT.          READ.
+       ERROR.          SETETT.         COMMNT.         TAPERD.
+       TAPEWR.         PUNCH.                          SETERR.
+</programlisting>
+<!-- beginpage II.49 -->
+
+<para>If a block designation
+A(i<superscript>1</superscript>,...,i<superscript>n</superscript>)...A(j<superscript>i</superscript>,...,j<superscript>n</superscript>)
+is used in an input-output list &scriptL; for reading or writing
+<emphasis> binary tape </emphasis> or <emphasis> drum </emphasis>, the
+linear subscript corresponding to
+i<superscript>i</superscript>,...i<superscript>n</superscript> may not
+be greater than the linear subscript corresponding to
+J<superscript>1</superscript>,...,j<superscript>n</superscript>.
+While the list for a binary tape or drum statement is transmitted in
+the sequence written, a block
+A(i<superscript>1</superscript>,...,i<superscript>n</superscript>)...A(j<superscript>1</superscript>,...,j<superscript>n</superscript>)
+within the list is actually transmitted in reverse order, i.e., in the
+sequence
+A(j<superscript>1</superscript>,...,j<superscript>n</superscript>) to
+A(i<superscript>1</superscript>,...,i<superscript>n</superscript>).</para>
+
 </sect1>
 </chapter>
+<!-- beginpage III.1 -->
 <chapter><title>EXAMPLES</title>
 
 <para>Note:The following illustrates how some programs may be writtten