]> thyrsus.com Git - mad.git/commitdiff
First draft complete.
authorEric S. Raymond <esr@thyrsus,com>
Wed, 30 Jun 2004 00:46:19 +0000 (00:46 +0000)
committerEric S. Raymond <esr@thyrsus,com>
Wed, 30 Jun 2004 00:46:19 +0000 (00:46 +0000)
doc/mad-manual.xml

index 7bbbb8e67f8d6a686ad20cc2065e9e504a035a9e..be130e744d699f8fb7f1ab234af71b4908e04aed 100644 (file)
@@ -729,7 +729,8 @@ written in a single box to indicate the correspondence to a single
 statement.</para>
 
 <para>The question still remains: How does one communicate the
-algorithm to the computer?  A translator such as MAD is designed
+algorithm to the computer?  A translator such as
+MAD<indexterm><primary>Translator</primary></indexterm> is designed
 according to the philosophy: Once the algorithm has been stated, as in
 a flow diagram, it should be presented to the computer directly in
 that form, or as near to it as possible.  The "translator" then has
@@ -963,13 +964,13 @@ flow diagram.</para>
 </programlisting>
 
 <orderedlist>
-<listitem><para>The first statement, labelled ST, causes a value for a,x,
-and &epsi; to be read into computer storage.  A block of adjacent
+<listitem><para>The first statement, labelled ST, causes a value for
+a,x, and &epsi; to be read into computer storage.  A block of adjacent
 storage location in the computer (a "vector") named ALPHA is
-designated as containing a description of how the three
-numbers were punched on the card.  (This description &ndash; which
-is the value of ALPHA &ndash; is described in a later statement; see
-(9) below.)</para></listitem>
+designated as containing a description of how the three numbers were
+punched on the card.  <indexterm><primary>Vector</primary></indexterm>
+(This description &ndash; which is the value of ALPHA &ndash; is
+described in a later statement; see (9) below.)</para></listitem>
 
 <listitem><para>The second statement is a simple conditional which causes
 the statement labelled PRT to be the next one executed if a &lt;
@@ -999,14 +1000,16 @@ again if |f(x)| &ge; &epsi;.  Otherwise, (i.e., |f(x)| &lt;
 &epsi;), the next statement in sequence is executed.</para></listitem>
 
 <listitem><para>The PRINT statement<indexterm><primary>PRINT
- Statement</primary></indexterm> causes three numbers - the current
- values of a, x and &epsi; to be printed.  The arrangement and form of
- the numbers on the printed page are controlled by the format
- description which is the value of the vector named
- ALPHA.<indexterm><primary>Format</primary></indexterm></para></listitem>
+Statement</primary></indexterm> causes three numbers - the current
+values of a, x and &epsi; to be printed.  The arrangement and form of
+the numbers on the printed page are controlled by the format
+description which is the value of the vector named
+ALPHA.<indexterm><primary>Format</primary></indexterm></para></listitem>
 
 <listitem><para>The TRANSFER statement following causes the statement
-labelled ST to be the next one performed.</para></listitem>
+labelled ST to be the next one performed.
+<indexterm><primary>TRANSFER Statement</primary></indexterm>
+</para></listitem>
 
 <listitem><para>The statement labelled PRT is the one executed immediately
 after the first statement whenever a &lt; 1.0.  This statement
@@ -1018,7 +1021,8 @@ alphabetic information preceding thenumber; namely, the remark
 
 <listitem><para>The next two statements following the last TRANSFER TO
 ST set the initial values of two vectors named ALPHA and BETA.
-Although VECTOR VALUES statements can be used to preset vectors to
+Although VECTOR VALUES statements<indexterm><primary>VECTOR VALUES
+Statements</primary></indexterm> can be used to preset vectors to
 specified numeric values, in both instances here the values are
 <emphasis>format descriptions</emphasis>.  The strings of characters
 between the dollar signs (MAD quotation marks!) are to be taken
@@ -1128,11 +1132,13 @@ discussed in Chapter II.</para>
 
 <!-- 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
-CUBIC EQUATION".  The appropriate alphabetic information is contained
-in the format information which is t be found in the vecvtor TITLE, as
-set by a VECTOR VALUES statement later in the program.</para>
+<para>The second statement in the program causes the inout
+information, properly labeled., to print out, preceded by the title
+"SOLUTION OF CUBIC EQUATION".  The appropriate alphabetic information
+is contained in the format information which is t be found in the
+vector TITLE, as set by a VECTOR VALUES statement
+<indexterm><primary>VECTOR VALUES
+Statements</primary></indexterm>later in the program.</para>
 
 <!-- in the original, there was a run-on typo, "NO CONVERGENCEis" -->
 <para>Two functions are defined in this program, and each is
@@ -1225,7 +1231,8 @@ Constants</primary></indexterm> <indexterm><primary>Constants,
 Alphabetic</primary></indexterm> consists of from one to six
 admissible characters<indexterm><primary>Admissible
 Characters</primary></indexterm> preceded and followed by the
-character "$".  The admiss- ible characters include all letters of the
+character "$".<indexterm><primary>$ Sign</primary></indexterm>
+The admiss- ible characters include all letters of the
 alphabet, the digits 0 through 9, the special characters +, -(minus
 sign), -(dash), *, /, =, ). (. ., the comma "," and the blank space,
 to be represented here occasionally (but not punched on input cards),
@@ -1260,11 +1267,15 @@ being indistinguishable).</para>
 
 <para>There are two Boolean constants &ndash; "true", which is written
 1B, and "false" which is written 0B.
-<indexterm><primary>Boolean Constants</primary></indexterm></para> 
+<indexterm><primary>Boolean Constants</primary></indexterm>
+<indexterm><primary>0B</primary></indexterm>
+<indexterm><primary>1B</primary></indexterm></para> 
 </sect3>  
 </sect2>  
 <sect2><title>Variables</title>
 
+<indexterm><primary>Variable</primary></indexterm> 
+
 <para>The name of a variable consists of one to six letters or digits,
 the first of which must be a letter.  If the variable is defined as an
 n-dimensional array variable<indexterm><primary>Array
@@ -1287,6 +1298,7 @@ enclosing subscripts may not be omitted.</para>
 <sect2 id='statement_labels'><title>Statement Labels</title> 
 
 <indexterm><primary>Statement Labels</primary></indexterm>
+<indexterm><primary>Vector, Statent Label</primary></indexterm>
 
 <para>A statement may be labelled or unlabelled.  Labels are used to
 refer to a statement in other statements.  A statement label consists
@@ -1412,7 +1424,9 @@ have the value 1B.
 <indexterm><primary>.AND.</primary></indexterm></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>
+value 1B and P has the value 0B.</para>
+<indexterm><primary>.THEN.</primary></indexterm>
+</listitem>
 
 <!-- beginpage II.5 -->
 
@@ -1761,6 +1775,8 @@ following floating point numbers:</para>
 
 <sect2><title>Transfer Statement</title>
 
+<indexterm><primary>TRANSFER Statement</primary></indexterm>
+
 <para>This statement has the form:  TRANSFER TO &scriptS;</para>
 
 <para>Here &scriptS; may be any statement label or any expression in
@@ -2032,13 +2048,13 @@ value of V will be used for incrementing, testing, etc.</para>
 <para>Examples:</para>
 
 <para>(i) To evaluate the polynomial
- c<subscript>n</subscript>x<superscript>n</superscript> +
- c<subscript>n-1</subscript>x<superscript>n+1</superscript> + ...+
- c<subscript>1</subscript>x + c<subscript>0</subscript> using the
- formula (...((c<subscript>n</subscript>x +
- c<subscript>n-1</subscript>)x + c<subscript>n-2</subscript>)x + ...+
- c<subscript>1</subscript>)x + c<subscript>0</subscript> (nested
- multiplication), we may write the program:</para>
+c<subscript>n</subscript>x<superscript>n</superscript> +
+c<subscript>n-1</subscript>x<superscript>n+1</superscript> + ...+
+c<subscript>1</subscript>x + c<subscript>0</subscript> using the
+formula (...((c<subscript>n</subscript>x +
+c<subscript>n-1</subscript>)x + c<subscript>n-2</subscript>)x + ...+
+c<subscript>1</subscript>)x + c<subscript>0</subscript> (nested
+multiplication), we may write the program:</para>
 
 <programlisting>
        INTEGER J,N
@@ -2070,10 +2086,11 @@ using the criterion "|f(x)| &lt; &epsi; and |x<subscript>k</subscript>
 
 <para>(iii) If the transformation of the iteration variable is to be
 performed within the scope of the iteration, one may use a zero
-increment.  E.g., if J is an integer variable, and the scope of the
-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>
+increment.  <indexterm><primary>Zero Increment for
+Iteration</primary></indexterm> E.g., if J is an integer variable, and
+the scope of the 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 II.17 -->
 
@@ -2126,6 +2143,8 @@ be entirely within the scope of <emphasis>a</emphasis>.  The following
 diagrams represent some valid configurations:</para>
 <indexterm><primary>Scope</primary></indexterm> 
 
+<indexterm><primary>Valid Iteration Configuration</primary></indexterm> 
+
 <!-- beginpage II.18 -->
 &scope1;
 
@@ -2189,6 +2208,8 @@ waits for the user to press Enter.</para></note>
 
 <para>Normally, the value of a function will occur as part of an expression, as in the statement:</para>
 
+<indexterm><primary>Value of a Function</primary></indexterm> 
+
 <programlisting>
 Z = COS.(X)/SIN.(X + 2.)
 </programlisting>
@@ -2442,6 +2463,8 @@ produced, allowing the operator to read the comment.
 according to format &scriptF;.
 <indexterm><primary>READ BCD TAPE</primary></indexterm>
 <indexterm><primary>READ BINARY TAPE</primary></indexterm>
+<indexterm><primary>WRITE BCD TAPE</primary></indexterm>
+<indexterm><primary>WRITE BINARY TAPE</primary></indexterm>
 </para>
 </listitem>
 </varlistentry>
@@ -2455,8 +2478,8 @@ according to format &scriptF;.
 <term>WRITE BINARY TAPE &scriptN;, &scriptL;</term>
 <!-- beginpage II.24 -->
 <listitem>
-<para>Transmits &scriptL; to tape &scriptN; in binary form as one
-record.</para>
+<para>Transmits &scriptL; to tape &scriptN; in binary form as one record.
+<indexterm><primary>WRITE BINARY TAPE</primary></indexterm></para>
 </listitem>
 </varlistentry>
 <varlistentry>
@@ -2466,6 +2489,7 @@ record.</para>
 <para>Transmits &scriptL; to or from drum &scriptN; starting with drum
 address &scriptA; (where &scriptA; is an integer expression).</para>
 <indexterm><primary>READ DRUM</primary></indexterm>
+<indexterm><primary>WRITE DRUM</primary></indexterm>
 </listitem>
 </varlistentry>
 <varlistentry>
@@ -3216,12 +3240,15 @@ Name</primary></indexterm> constant is assigned function name mode
 <listitem><para>A vector appearing as the dimension vector of some
 array<indexterm><primary>Array Variables</primary></indexterm> in a
 dimension declaration is assigned integer mode (see <xref
-linkend='dimension_declaration'/>).</para></listitem>
+linkend='dimension_declaration'/>).
+<indexterm><primary>Vector</primary></indexterm>
+</para></listitem>
 
 <listitem><para>A vector which is preset by a vector values
 declaration is assigned a mode consistent with the assigned values
 (see <xref linkend='VECTOR_VALUES'/>).<indexterm><primary>Dimension
-Vector</primary></indexterm> </para></listitem>
+Vector</primary></indexterm> <indexterm><primary>VECTOR VALUES
+Statements</primary></indexterm></para></listitem>
 </orderedlist>
 
 </sect2>
@@ -3240,7 +3267,7 @@ each element of an array its "linear
 subscript."<indexterm><primary>Linear Subscript</primary></indexterm>
 If A is an array then the name A is equivalent to A(0), e.e., the name
 A written without a subscript is assumed to have a subscript of
-zero.</para>
+zero.<indexterm><primary>Zero subscript</primary></indexterm></para>
 
 <para>Two dimensional matrices are stored internally by rows, i.e., an
 m &times; n matrix will be stored in the order: a<subscript>11</subscript>,
@@ -3325,9 +3352,11 @@ the defined ranges of the subscripts are positive.</para>
 although these do not all have to be used.  The base element of YT,
 i.e., YT(1,1, 1) will correspond to the element YT(4) since K(4) = 4.</para>
 
-<para>If the array is a vector, i.e., one-dimensional, a special convention
-is adopted.  Only the first argument is given to the DIMENSION
-declaration.  Thus, in the statement</para>
+<para>If the array is a
+ vector,<indexterm><primary>Vector</primary></indexterm> i.e.,
+ one-dimensional, a special convention is adopted.  Only the first
+ argument is given to the DIMENSION declaration.  Thus, in the
+ statement</para>
 
 <para role='centered'>
 DIMENSION V(10)
@@ -3351,9 +3380,10 @@ dimension declaration in which case the highest linear subscript is
 used.</para>
 
 <para>(b) If part of all of a linear array is set by a VECTOR VALUES
-declaration the array need not appear in a dimension statement unless
-the maximum linear subscript implied by the initial values is not
-sufficiently high.</para>
+declaration<indexterm><primary>VECTOR VALUES
+Statements</primary></indexterm> the array need not appear in a
+dimension statement unless the maximum linear subscript implied by the
+initial values is not sufficiently high.</para>
 
 </sect2>
 <sect2><title>Equivalence Declaration</title>
@@ -3497,7 +3527,8 @@ of the following form:</para>
 <indexterm><primary>Hollerith (BCD)</primary></indexterm> 
 
 <para>(a) VECTOR VALUES &scriptV; = c<subscript>0</subscript>,
-c<subscript>1</subscript>, ... c<subscript>&scriptL;</subscript></para>
+c<subscript>1</subscript>, ... c<subscript>&scriptL;</subscript>
+<indexterm><primary>VECTOR VALUES Statements</primary></indexterm></para>
 
 <para>Here &scriptV; is of the form N(n) or simply N, if n = 0.  The
 elements N(n), ... N(n + &scriptL;) are preset to the values
@@ -3514,7 +3545,8 @@ c<subscript>1</subscript> must all be of the same mode.</para>
 
 <para>(b) VECTOR VALUES &scriptV; = $ k<subscript>1</subscript>
 ... k<subscript>m$</subscript>,
-$k<subscript>m</subscript>+1... k<subscript>p$</subscript>, ...</para>
+$k<subscript>m</subscript>+1... k<subscript>p$</subscript>, ...
+<indexterm><primary>$ Sign</primary></indexterm></para>
 
 <!-- the m/6 here is $m over 6$ in eqn notation -->
 <para>Here the k<subscript>i</subscript> may be any valid characters
@@ -3901,7 +3933,9 @@ Declaration</primary></indexterm></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.<indexterm><primary>Statement Labels</primary></indexterm></para>
+name.<indexterm><primary>Statement Labels</primary></indexterm>
+<indexterm><primary>Variable</primary></indexterm> 
+</para>
 
 <para>The translator automatically calls on some subroutines, hence the
 following names may not be used as variable names or statement labels
@@ -3922,6 +3956,8 @@ in Chapter 4).</para>
 <indexterm><primary>SETEOF Subroutine</primary></indexterm> 
 <indexterm><primary>SETETT Subroutine</primary></indexterm>
 <indexterm><primary>SYSTEM Subroutine</primary></indexterm>
+<indexterm><primary>TAPERD Subroutine</primary></indexterm>
+<indexterm><primary>TAPEWR Subroutine</primary></indexterm>
 <indexterm><primary>Subroutines</primary></indexterm>
 <!-- beginpage II.49 -->
 
@@ -4029,6 +4065,8 @@ idea!).</para>
 </sect2>
 <sect2><title>Example 2<emphasis role='note'>: Printing the truth table of a Boolean expression</emphasis></title>
 
+<indexterm><primary>Truth Table</primary></indexterm>
+
 <para><emphasis>Problem:</emphasis> A logical (Boolean) expression
 such as (P .AND. Q) .OR.(.NOT. P .AND. R .AND. S).OR.(R .OR. P) will
 have a value TRUE or FALSE (represnted here by 1B and 0B,
@@ -5043,6 +5081,8 @@ recursive functions.</para>
 </programlisting>
 <!-- beginpage III.54 -->
 
+<indexterm><primary>Value of a Function</primary></indexterm> 
+
 <!-- used in the listing above -->
 <indexterm><primary>SET LIST TO Statement</primary></indexterm> 
 
@@ -5069,6 +5109,9 @@ statements always refer to the current list.</para>
 </sect2>
 <!-- beginpage III.56 -->
 <sect2><title><emphasis role='note'>Example 4: Evaluate Tschebychev polynomials</emphasis></title>
+
+<indexterm><primary>Tschebychev Polynomial Example</primary></indexterm>
+
 <para><emphasis>Problem:</emphasis> To evaluate Tschebychev polynomials.</para>
 
 <para><emphasis>Analysis:</emphasis> The Tschebychev polynomial T(N,X)
@@ -5130,7 +5173,8 @@ Spaces are not relevant.</para>
 <para>1.3 The statement may start anywhere in cols. 12-72.  With the
 exception of characters enclosed between "$" spaces are not relevant.
 (Spaces may not be relevant even if they are so enclosed (see section
-2.15) on format specifications).</para>
+2.15) on format specifications).<indexterm><primary>$
+Sign</primary></indexterm></para>
 
 <para>1.4 The identification information in cols. 73-80 is not used by
 the computer for any purpose but printing during translation and is
@@ -5312,6 +5356,7 @@ here.</para>
 <listitem><para>Entry to this routine causes a return to the operating
 system.  The END OF PROGRAM statement produces a call for this
 routine.  <indexterm><primary>END OF PROGRAM Statement</primary></indexterm> 
+<indexterm><primary>SYSTEM Subroutine</primary></indexterm>
 </para></listitem>
 </varlistentry>
 
@@ -5334,7 +5379,11 @@ location of the format specification, (2) tape number, and (3) a list of
 <!-- beginpage IV.5 -->
 variables to be written.  The WRITE BCD TAPE ... statement produces
 a call for this subroutine.
-<indexterm><primary>Hollerith (BCD)</primary></indexterm></para></listitem>
+<indexterm><primary>Hollerith (BCD)</primary></indexterm>
+<indexterm><primary>TAPEWR Subroutine</primary></indexterm>
+<indexterm><primary>WRITE BCD TAPE</primary></indexterm>
+<indexterm><primary>WRITE BINARY TAPE</primary></indexterm>
+</para></listitem>
 </varlistentry>
 
 <varlistentry>
@@ -5355,6 +5404,7 @@ The READ BCD TAPE . . . statement produces a call for this
 routine.
 <indexterm><primary>READ BCD TAPE</primary></indexterm>
 <indexterm><primary>READ BINARY TAPE</primary></indexterm>
+<indexterm><primary>TAPERD Subroutine</primary></indexterm>
 </para></listitem>
 </varlistentry>
 
@@ -6423,6 +6473,12 @@ Input-Output</primary><see>Input-Output Statements</see></indexterm>
 Non-Executable</primary><see>Non-Executable Statements</see></indexterm>
 <indexterm><primary>Subscript, Linear</primary><see>Linear Subscript</see></indexterm>
 <indexterm><primary>Subscript, Negative</primary><see>Negative Subscript</see></indexterm>
+<indexterm><primary>THROUGH Statement</primary><see>Iteration Statement</see></indexterm>
+<indexterm><primary>Transpose of a Matrix</primary><see>Matrix Transpose</see></indexterm>
+<indexterm><primary>Truncation</primary><see>Intrger Division</see></indexterm>
+<indexterm><primary>Variables, Bound</primary><see>Bound Variables</see></indexterm>
+<indexterm><primary>Variables, Dummy</primary><see>Dummy Variables</see></indexterm>
+<indexterm><primary>Vector, Presetting</primary><see>Presetting Vectors</see></indexterm>
 
 <index/>
 </appendix>