From 93107250c4523af7ace2e735523d829f424ed0a4 Mon Sep 17 00:00:00 2001 From: "Eric S. Raymond" Date: Thu, 24 Jun 2004 23:05:31 +0000 Subject: [PATCH] Explanation of the transcription style. --- doc/mad-manual.xml | 195 +++++++++++++++++++++++++++++++-------------- 1 file changed, 134 insertions(+), 61 deletions(-) diff --git a/doc/mad-manual.xml b/doc/mad-manual.xml index c4eee65..c65726d 100644 --- a/doc/mad-manual.xml +++ b/doc/mad-manual.xml @@ -323,6 +323,21 @@ 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. +The philosophy of this transcription is that the semantic +content of the manual is what is essential and is what should be +presented by rendering into HTML; the accidents of literal content +have in some cases been changed but should be reconstructable by +looking at the XML source transcription. Thus, typos have been fixed in the +visible text, but the XML source includes a note adjacent to each one +explaining the fix. We have also corrected other minor errors like +off-by-ones in the indexing, but those fixes too are explained in the +XML masters. + +We have been (necessarily) a little more relaxed about changes +in whitespace distribution, as DocBook doesn't give us the ability to +control that exactly. Other notes in the XML source describe the few +places where we were not able to reproduce the original layout. + Redactor's comments in the body of the text are decorated like this. @@ -446,10 +461,10 @@ the original. Notably, "section 1.1" becomes "Section 1.1" The reference structure of the index has been faithfully reproduced; that is, for each index reference a DocBook <indexterm> tag was placed within the span of text defined by -the original page numbering. However, DocBook renders the index -differently from the original. The original lacked the canned section -headings, and references were by page number rather than section -name. +the original page numbering (two off-by-one errors were corrected). +However, DocBook renders the index differently from the original. The +original lacked the canned section headings, and references were by +page number rather than section name. EPSLON and COMPLX and the like are not typos. As pointed out earlier, MAD variable names are limited to the 6 characters in a @@ -775,6 +790,8 @@ interpreted in the sense: Whenever the following condition (in this case Z < aj) is satisfied, do the specified action (Z = aj), otherwise just go on. +Floating Point + It is interesting to ask just how complicated a condition can be used in making decisions. We have seen that such conditions may occur in iterations statements, and "WHENEVER" statements, etc., for the @@ -822,6 +839,7 @@ available for use in any other program, as a pre-packaged "function", in the sense that, given n and a0, ..., an, this function computes as its value the largest of a0, ..., an. +EXTERNAL FUNCTION In this case we shall call our algorithm an EXTERNAL FUNCTION, and 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. @@ -1155,20 +1173,22 @@ of MAD implements the original MAD behavior. Floating Point Constants Constants, Floating Point +Floating Point Floating point constants may be written with or without -exponents. If written without an exponent, the constant contains from -one to eight digits and a decimal point ".", which must be written, -but which may appear anywhere in the number. Thus, 0., 1.5, -0.05, -+100.0, .1 and -4. are all floating-point constants. If the number is -written with an exponent, it must contain from one to eight digits -with or without a decimal point, followed by the letter "E", followed -by the exponent of the power of 10 that multiplies the number. (If -the decimal point is omitted, it is assumed to be immediately to the -left of the letter "E".) The exponent m consists of one or two digits -preceded by a sign (although a "+" sign may be omitted), and must -satisfy the condition -38 ≥ m ≥ 38. Examples of floating-point -constants with exponent are; +exponents. Exponent If +written without an exponent, the constant contains from one to eight +digits and a decimal point ".", which must be written, but which may +appear anywhere in the number. Thus, 0., 1.5, -0.05, +100.0, .1 and +-4. are all floating-point constants. If the number is written with +an exponent, it must contain from one to eight digits with or without +a decimal point, followed by the letter "E", followed by the exponent +of the power of 10 that multiplies the number. (If the decimal point +is omitted, it is assumed to be immediately to the left of the letter +"E".) The exponent m consists of one or two digits preceded by a sign +(although a "+" sign may be omitted), and must satisfy the condition +-38 ≥ m ≥ 38. Examples of floating-point constants with +exponent are; @@ -1291,7 +1311,7 @@ if Z5 = 7, and D = 3, the Z5 = D will have the value 2. Exponentiation, written as ".P.", e.g., Z5.P.D, and meaning (Z5)D, i.e., Z5 raised to the power -D. +D.Exponentiation Negation, written as "-", e.g., -ALOHA, meaning the "negative of ALOHA." Thus -X.P.-.5 @@ -1303,6 +1323,8 @@ means -(X-.5). Arithmetic Expressions +Expression, Arithmetic + Arithmetic expressionsArithmetic Expressions are defined inductively as follows: @@ -1348,7 +1370,8 @@ value 1B and P has the value 0B. M.EQV.P has the value 1B if and only if M and P have -the same values. +the same values. .EQV. + Thus, .NOT., .OR., .AND., .THEN., AND .EQV. correspond to the @@ -1357,6 +1380,8 @@ usual logical operations, ~, ∨, ∧, ⊃, and ≡. Boolean Expressions +Expression, Boolean + Boolean expressions are defined inductively as follows: Boolean Expressions @@ -1439,6 +1464,8 @@ otherwise indicated by parentheses. Examples: +Expression, Compound + A + B - C + D - E means (((A + B) - C) + D) - E. X/Z * Y/R * S means (((X/Z) * Y/R) * S. @@ -1547,7 +1574,8 @@ I3 will be automatically converted to floating point before adding. Likewise, in the next step, the integer T2 will be converted to floating -point before adding to the floating point number. +point before adding to the floating point number. +Floating Point Subscript In other words, although the mode of the expression is floating point because of the presence of the floating point variable Y, some @@ -1598,6 +1626,8 @@ MP(A, B + 6 * J, I * 6/TDX), MA(K(Z + 5) + T(1) + 6). Statements (Executable) +Executable Statements + Substitution Statement @@ -1608,15 +1638,15 @@ ALPHA = Y + Z + F.(X, Y, Z) That is, the left side of the "=" sign -Equals Sign consists -of the name of a variable (either an individual variable or a -subscripted array variable), and the right side consists of any -expression of the same mode. The only exceptions to this mode -requirement are the cases: (1) If the variable on the left is of -integer mode then the value of a floating point expression of the -right will be converted to integer mode. -Conversion, Floating Point to -Integer (2) if the variable on the left is of +Equals Sign consists of the +name of a variable (either an individual variable or a subscripted +array variable), and the right side consists of any expression of the +same mode. The only exceptions to this mode requirement are the +cases: (1) If the variable on the left is of integer mode then the +value of a floating point expression of the right will be converted to +integer mode. Conversion, Floating Point to +Integer Floating Point +Conversion (2) if the variable on the left is of floating point mode then the value of an integer expression on the right will be converted to floating point mode. Conversion, Integer to Floating @@ -2089,6 +2119,8 @@ This would appear as: EXECUTE LSORT.(ARRAY, MAP, N) +EXECUTE Statement + (See for definition of functions). Here ARRAY, MAP, N are the "arguments" of the function (subroutine) LSORT. Arguments and parentheses may be omitted in an EXECUTE @@ -2105,6 +2137,8 @@ statement is simply: ERROR RETURN +ERROR RETURN Statement + (An example of its use is shown near the end of ). @@ -2378,7 +2412,8 @@ made even if at load point. tape check, etc.) occurs during any input-output statement except READ DRUM or WRITE DRUM, the subroutine ERROR. is automatically entered. The subroutine ERROR. sets an error flag and returns control to the -system in which the translated program is imbedded. +system in which the translated program is imbedded. +ERROR Subroutine If an end-of-file is encountered while executed a READ FORMAT, READ BCD TAPE, or READ BINARY TAPE statement the subroutine SYSTEM. (a @@ -2553,16 +2588,36 @@ external medium as follows: -S Skip (or blank information) -I Integer -F Fixed point number (Internally floating point) + + S + S Field (Format) + + Skip (or blank information) + + + I + I Field (Format) + + Integer + + + F + F Field (Format) + + Fixed point number (Internally floating point) + E E Field (Format) Floating point number -K Octal number + + K + K Field (Format) + + Octal number + C C Field (Format) @@ -3341,6 +3396,7 @@ identical in all sections of the program. There are two main types of functions: The internal function and the external function. +EXTERNAL FUNCTION Since these are quite similar in many ways, that part of the description which is specific to external functions will be @@ -3364,6 +3420,8 @@ III. External Function Definitions +EXTERNAL FUNCTION + @@ -3421,12 +3479,11 @@ INTERNAL FUNCTION SUMSQ.(X,Y,Z) = X * X + Y + Z * Z - T * T As indicated above, X, Y, and Z, as they occur here, are dummy - variables, and (X, Y, Z) is the dummy - variableDummy Arguments - list. The current value of T, however, will be obtained and used each - time the value of the function is needed. An example of theuse of - the function so defined would be: +variableDummy Arguments +list. The current value of T, however, will be obtained and used each +time the value of the function is needed. An example of theuse of +the function so defined would be: A = 1.-SUMSQ. (U, V + 3, W) .P..5 @@ -3521,29 +3578,33 @@ END OF FUNCTION The first statement (INTERNAL FUNCTION (X)) is a function declaration (i.e., declares that the following -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 - -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. 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 +statements define a function). + +EXTERNAL 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 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. 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. An example of a definition for procedures is as follows: +EXTERNAL FUNCTION + EXTERNAL FUNCTION (M, N, I, P, Q) STATEMENT LABEL N, I @@ -3633,11 +3694,13 @@ flag set. If is part of a program and Y ≤ 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. +statement is executed ERROR RETURN +Statement 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. END OF FUNCTION Statement + @@ -3666,6 +3729,7 @@ in Chapter 4). TAPEWR. PUNCH. SETERR. COMMNT Subroutine +ERROR Subroutine If a block designation @@ -3715,6 +3779,8 @@ relation is true. Scientific Examples +Examples, Scientific + Example 1<emphasis role='note'>: Compute roots of linear and quadratic equations</emphasis> @@ -4219,6 +4285,7 @@ compile this example. The problem is the array I/O. Business Data Processing Examples Business Data Processing Examples +Examples, Business Data Processing Example 1<emphasis role='note'>: Payroll Processing</emphasis> @@ -4655,6 +4722,9 @@ compile this example. The problem is the array I/O. Symbol Manipulation and Recursive Function Examples <emphasis role='note'>Example 1: Find a word in a string</emphasis> +Exammples, Recursive Functions +Examples, Symbol Manipulation + Problem: Find the first occurrence of an arbitrary word in a given text. @@ -4991,11 +5061,14 @@ routine. END OF PROGRAM Statement ERROR + Entry to this routine also causes a return to the operating system. However, if a dump of storage was requested of the operating system such a print of storage will be produced before the return to the system. The ERROR RETURN statement may produce a call -for this routine. +for this routine.ERROR RETURN +Statement ERROR +Subroutine -- 2.43.0