Add various explanatory notes.

diff --git a/doc/mad-manual.xml b/doc/mad-manual.xml
index 08cd8985f6c4b8d1d841581d1eea0e3f0ee466f4..82440dbb77a805bd8d872fb427af716de568cfad 100644 (file)
--- a/doc/mad-manual.xml
+++ b/doc/mad-manual.xml
@@ -204,12 +204,14 @@ it could be the real thing.</para>
 
 <para>The Retrocomputing Museum implementation of MAD translates MAD
 code into compileable C.  It has been tested on the examples in the 
-manual, which are included with the distribution.</para>
+manual, which are included with the distribution.  This section is
+a summary of differences: more details are given in notes attached
+to the relevant sections.</para>
 
 <para>Card images are read from standard input and printing is to
-standard output.  Printer control codes +, 1, 2 and 4 are ignored
-(treated as 0 or space). Tape and drum devices are not
-supported.</para>
+standard output. Line printer control codes are partly but not exactly
+simulated (see <xref linkend='lptcodes'/>). Tape and drum devices are
+not supported.</para>
 
 <para>The 704 had 36-bit words; MAD floats are translated to C
 doubles, which on modern machines have 32 or 64 bits.  Precision and
@@ -263,6 +265,9 @@ velo-bound typed manual; Eric Raymond hand-corrected it, and moved the
 result into PIC and XML-DocBook markup so both HTML and PostScript can
 be generated from it.</para>
 
+<note><para>Redactor's comments in the body of the text are
+decorated like this.</para></note>
+
 <para>Typewriter underlining in the original is expressed by 
 DocBook &lt;emphasis&gt; tags in this version, which will probably
 render as italics.</para>
@@ -314,8 +319,13 @@ the original style in DocBook.</para>
 hand-drawn across them).  The original also some contained hand-drawn
 script characters:</para>
 
-<para role='notebox'>Redactor's comments in the body of the text are
-decorated like this.</para>
+<para>The above notes fail to properly convey just how primitive the
+original document looks to a modern eye, and this is worth noting
+because this transcription into DocBook makes it look a lot less so.
+Standards have risen in a world saturated with the Web and cheap page
+printers.  The original manual's monospace fonts on yellowing paper
+with hand-drawn figures and special characters look quaint and
+ugly by contrast.</para>
 
 <informaltable>
 <tgroup cols='2'>
@@ -593,11 +603,11 @@ 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>
 
-<para role='notebox'>The IBM 704 on which MAD was implemented had a
+<note><para>The IBM 704 on which MAD was implemented had a
 very primitive pre-ASCII character set.  It did not even include
 lowercase letters, let alone fancy punctuation like &lt; and &gt;.
 ASCII still lacks &le; and &ge;, but writing these as &lt;= and &gt;=
-became universal in later ASCII-based languages.</para>
+became universal in later ASCII-based languages.</para></note>
 
 <para>The flow diagram for our previous example, then, may be
 rewritten as follows: (In order to keep the notation familiar when
@@ -984,7 +994,7 @@ F. -->
 
 <para>The first statement, labelled GAMMA, would cause the program to
 read from the data card the numbers a, b, c, x<subscript>0</subscript>,
-&epsi;<subscript>=1</subscript>, &epsi;<subscript>2</subscript>, and
+&epsi;<subscript>1</subscript>, &epsi;<subscript>2</subscript>, and
 n<subscript>0</subscript>.  The format of the input information is to
 be found in a block of storage labelled "CARD" whose values are set
 later in the program by a VECTOR VALUES statement.  The vector CARD
@@ -1039,6 +1049,12 @@ the "-" sign must be present if the number is negative (e.g., 2, -2, 0,
 +0, -0. 100 are all integers).  Leading (but not following) zeros may
 be omitted (e.g., 5 and 005 represent the same integer, but 3 and 300
 do not.</para>
+
+<note><para>There is a subtle difference from modern practice here.
+In 2004, major contemporary languages (perhaps unfortunately) follow
+C's lead and interpret leading 0 as a directive to evaluate the 
+following digits in octal.  The Retrocomputing Museum implementation
+of MAD implements the original MAD behavior.</para></note> 
 </sect3>
 
 <sect3><title>Floating Point Constants</title>
@@ -1083,6 +1099,11 @@ constant containing fewer than six characters will be extended to six
 characters by adding blanks on the right; thus $ABCD$ will appear
 internally as $ABCD&squ;&squ;$
 </para>
+
+<note><para>The Retrocomputing Museum implementation neither enforces
+the six-character limit nor blank-pads constants. These features were
+an artifact of packing six-bit characters into the IBM 704's 36-bit
+machine word.</para></note>
 </sect3>
 
 <sect3><title>Boolean Constants</title>
@@ -1355,9 +1376,9 @@ GCD.(I, J)/I
 may be necessary before some of the operations can be performed.
 Thus, in the expression</para>
 
-<literallayout>
+<para role='centered'>
 Y + 3
-</literallayout>
+</para>
 
 <para>if Y is in the floating point mode it cannot be added directly
 to the integer 3. But for one precaution the user need not be
@@ -1371,9 +1392,9 @@ improper conversion will take place.</para>
 <para>In some cases, however, the user must understand the sequence in
 which the conversions will be made.  Consider the expression</para>
 
-<literallayout>
+<para role='centered'>
 ( Y + 7/3) + (I * J/K)
-</literallayout>
+</para>
 
 <para>where Y is in the floating point mode, and I, J, and K are in the
 integer mode.  According to the parenthesizing conventions, the
@@ -1414,9 +1435,9 @@ different from the value one might expect from a different analysis.</para>
 <para>In the example above, the divisions would be performed in the
 floating point mode if the expression were written:</para>
 
-<literallayout>
+<para role='centered'>
 (Y + 7./3) + (I * J)/(K + 0.)
-</literallayout>
+</para>
 
 <para>Of course, many times the expression will be written as
 originally stated just to achieve the "truncation" effect.</para>
@@ -1458,9 +1479,9 @@ MP(A, B + 6 * J, I * 6/TDX), MA(K(Z + 5) + T(1) + 6).</para>
 <!-- beginpage -->
 <para>This statement has the form illustrated by</para>
 
-<programlisting>
+<para role='centered'>
 ALPHA = Y + Z + F.(X, Y, Z)
-</programlisting>
+</para>
 
 <para>That is, the left side of the "=" sign consists of the name of a
 variable (either an individual variable or a subscripted array
@@ -1480,17 +1501,17 @@ variable on the left the value which results from steps (1) and (2)."
 
 <para>Thus, if Y is a floating point variable, then the statement</para>
 
-<programlisting>
+<para role='centered'>
 Y = 1
-</programlisting>
+</para>
 
 <para>will cause the integer 1 to be converted to floating point and then
 stored in the location called "Y"; i.e., Y will now have the value 1.
 (as a floating point number).  If the statement were written</para>
 
-<programlisting>
+<para role='centered'>
 Y = 1.
-</programlisting>
+</para>
 
 <para>then the floating point number 1. would be stored in the
 location "Y"; i.e., Y would again have the floating point value 1.,
@@ -1502,15 +1523,15 @@ it is first expressed as a number with both an integer part and a
 fractional part, and then the fractional part is truncated.  Thus, the
 following floating point numbers:</para>
 
-<programlisting>
+<para role='centered'>
 3E5, .3E0, .34568127E2, - .345681E10
-</programlisting>
+</para>
 
 <para>would convert to the following integers, respectively:</para>
 
-<programlisting>
+<para role='centered'>
 300000, 0, 34, -3456810000.
-</programlisting>
+</para>
 </sect2>
 
 <sect2><title>Transfer Statement</title>
@@ -1533,9 +1554,9 @@ is SWTCH(6)).</para>
 
 <para>(a) Simple Conditional</para>
 
-<programlisting>
+<para role='centered'>
 WHENEVER B,Q
-</programlisting>
+</para>
 
 <para>Here B is a Boolean expression and Q any executable statement
 except the following: end of program, another conditional, iteration,
@@ -1547,10 +1568,10 @@ statements containing punctuation, must be written.</para>
 
 <para>Examples:</para>
 
-<programlisting>
+<para role='centered'>
 WHENEVER XM.LE.1, TRANSFER TO END
 WHENEVER I.GE.N.AND.J.NE.I-1, I=0
-</programlisting>
+</para>
 
 
 <para>(b) Compound Conditional</para>
@@ -1903,6 +1924,10 @@ program.  The number n is an octal integer containing up to 5 digits,
 which will be displayed on the computer console for the operator to
 note when the computer stops, thus indicating the point in the program
 at which the stop occurred.</para>
+
+<note><para>The Retrocomputing Museum implementation handles this by
+generating code that prints the octal number to standard output, then
+waits for the user to press Enter.</para></note>
 </sect2>
 
 <sect2><title>Function Statement</title>
@@ -1946,6 +1971,10 @@ or a variable in statement label mode, whose value is the label of a
 statement to which a transfer is made in case the ERROR RETURN
 statement is executed.</para>
 
+<note><para>This language is confusing, and doesn't seem to match the
+actual uses of ERROR RETURN in the examples.  The Retrocomputing
+Museum implementation ignores it.</para></note>
+
 <para>Even though an error return has been provided in the definition
 of a function, in the use of the function the last argument may be
 omitted.  If it is omitted, execution of the ERROR RETURN statement
@@ -1953,6 +1982,9 @@ will cause control <!-- beginpage --> to be transferred to the
 operating system in which the translated program is imbedded, with an
 error indication.</para>
 
+<note><para>The Retrocomputing Museum implementation generates code
+that prints ERROR RETURN and terminates the program.</para></note>
+
 </sect2>
 <sect2><title>End of program Statement</title>
 
@@ -1990,6 +2022,11 @@ ENTRY TO &scriptN;
 </programlisting>
 
 <para>where &scriptN; is the name of this entry (see section 3.8).</para>
+
+<note><para>The Retrocomputing Museum implementation supports only
+one entry point per function.  Attempting to specify more than one
+will raise a compile-time error.</para></note>
+
 </sect2>
 <sect2><title>List Manipulation Statements</title>
 
@@ -2292,6 +2329,27 @@ effective before the rest of the specification is carried out.</para>
 </tgroup>
 </informaltable>
 
+<note id='lptcodes'>
+<para>These were the standard control codes for line printers, which
+assumed they were printing to 132x66 fanfold paper.  There isn't a lot
+of point in simulating them on a modern page printer.  The
+Retrocomputing Museum implementation implements them by prefixing the
+output string:</para>
+
+<informaltable frame='none' colsep='0' rowsep='0' role='centered'>
+<tgroup cols='2'>
+<tbody>
+<row><entry>Blank  </entry> <entry>No prefix</entry></row>
+<row><entry>0      </entry> <entry>\n</entry></row>
+<row><entry>+      </entry> <entry>Not supported, no prefix.</entry></row>
+<row><entry>1      </entry> <entry>Form feed</entry></row>
+<row><entry>2      </entry> <entry>Two vertical tabs</entry></row> 
+<row><entry>4      </entry> <entry>One vertical tab</entry></row>
+</tbody>
+</tgroup>
+</informaltable>
+</note>
+
 <para>As another example, the specification</para>
 
 <para role='centered'>