Return to gpmdoc.gpm CVS log

Up to [Research Unix] / researchv10no / cmd / spitbol

Annotation of researchv10no/cmd/spitbol/gpmdoc.gpm, revision 1.1

1.1     ! root        1: {Set Program,GPMDOC}
        !             2: {Set Version,Version 6.10}
        !             3: !
        !             4: {Setq Macdescr,-
        !             5:   {Set Macroname,{Caps @1}}-
        !             6:   {Sec {1}{Cond {Leq @Mode,TEXT},~({2})}}-
        !             7:   {Tset Toc,{Rpad {Dbl @1}~-~{2}~,50,.~}~A-{Pagenum}}-
        !             8:   {Nfj}-
        !             9:   {Macsec Format}-
        !            10: }
        !            11: !
        !            12: {Setq Macsec,-
        !            13:   {Cond {Leq {Caps @1},FORMAT},{Ls 1}Format:{Ls 1}{Lin 8}{Nfj},-
        !            14:     {Leq {Caps @1},DESCRIPTION},{Ls 1}{Restore Lmg}{Fj},-
        !            15:     ,{Hl {+ @Seclevel,2},{Caps @1}}{Fj}-
        !            16:   }-
        !            17: }
        !            18: !
        !            19: ! Define the list items macros
        !            20: ! Bl is used to begin a new list.  It should be on the same physical
        !            21: ! line with the rest of the text.  It does an initial {Li...}
        !            22: !
        !            23: {Setq Bl,{Set.Add1 Numlist}-
        !            24:   {Set LIST${Numlist},0}-
        !            25:   {Brk}-
        !            26:   {Lin 4}-
        !            27:   {Li @1}-
        !            28: }
        !            29: !
        !            30: ! Li is called to start a new item in a list.
        !            31: ! (Bl does this automatically for the first item)
        !            32: !
        !            33: {Setq Li,{Ls 1}{Set.Add1 LIST${Numlist}}-
        !            34:   {Outdent {Size {1}{Setv Listlabel,-
        !            35:     {Dowhile{Set Listi,@Numlist} {Gt @Listi,1},-
        !            36:       {LIST${Numlist}}.{Set.Sub1 Listi}-
        !            37:     }-
        !            38:     {LIST$1}:~}}-
        !            39:   }{1}{Listlabel}-
        !            40: }
        !            41: !
        !            42: ! El is used to return to the previous list level.
        !            43: !
        !            44: {Setq El,{Brk}{Restore Lmg}{Set.Sub1 Numlist}}
        !            45: !
        !            46: {Exclude HELP}
        !            47: {Load SYS$LIBRARY:AUXLIB.GPM,ROMAN}
        !            48: {Setq Endpage,{Ls 2}{Center A-{Roman @Pagenum}}{Eject}}
        !            49: {Tsetq Newpage,{Ls 3}}
        !            50: {Ls 1}{Center APPENDIX A}
        !            51: {Ls 1}{Center - NOTES -}{Ls 2}
        !            52: This section contains a complete description of the
        !            53: GPMDOC system macros in alphabetical order for {version}.
        !            54:  Some abbreviations are used in the Format descriptions which
        !            55: require explanation:
        !            56: !**
        !            57: {Exclude TEXT}
        !            58: {Sec GPMDOC}
        !            59: HELP is provided for all intrinsic GPMDOC macros.
        !            60:  Macros are explained under the subheading corresponding to the
        !            61: macro's name.
        !            62:  In addition,
        !            63: an explanation of the abbreviations used in the "Format"s can be
        !            64: obtained under the subheading "Formats".
        !            65: {Newsec}
        !            66: {Sec Formats}
        !            67: !**
        !            68: {Ls 1}{Lin 6}{OUTDENT 6}
        !            69: <"{MACRO arg1,arg2,...}":>
        !            70: {Ls 1}This means you can use the MACRO with the
        !            71: normal GPMDOC evaluation process.
        !            72:  If MACRO
        !            73: takes arguments (arg1, arg2) they are shown.
        !            74:  Optional arguments are noted in the description.
        !            75: {Ls 1}
        !            76: Macros place restrictions or interpretations
        !            77: on the arguments that you can pass to them.
        !            78:  The required form of an argument is given in the format description
        !            79: for each macro according to the following convention:
        !            80: {Ls 1}{Lin 8}{OUTDENT 8}
        !            81: "mname"~The argument text, after evaluation, is
        !            82: used as the {ul name} of a macro.
        !            83:  Any "mname" can optionally be suffixed with a backslash ("\") followed
        !            84: by a property table name, otherwise, the null property table
        !            85: is assumed.
        !            86: {Ls 1}Since any string
        !            87: of text can serve as a macro name, "mname" can be
        !            88: anything.
        !            89:  However, "mname" denotes the fact that
        !            90: the macro being described will {ul interpret}
        !            91: this argument to be a macro name.
        !            92: {ls 1}{outdent 8}
        !            93: "n"~~~~~The argument text must evaluate to a {ul number}.
        !            94:  Either integers or fractional real numbers with decimal points
        !            95: can be used.
        !            96:  In cases where an integer is required and a
        !            97: real number is used, the real number is converted to an
        !            98: integer by disregarding the fractional part.
        !            99:  The acceptable range of n may be restricted for some macros,
        !           100: this is noted in accompanying description.
        !           101:  For the purposes of arithmetic, a null string is interpreted as zero.
        !           102: {Ls 1}{Outdent 8}"pred"~~The evaluated argument is considered by the
        !           103: macro to be a {ul predicate}.
        !           104:  Predicates designate true/false values with a null value
        !           105: being considered "true," and any string of actual size greater than
        !           106: zero is thus considered "false."
        !           107:  The GPMDOC built-in system predicate macros such as LT, EVEN, etc.
        !           108: return null when they evaluate true, and (by convention) evaluate to
        !           109: "1" otherwise.
        !           110:  Users defining their own predicate-valued macros are urged to
        !           111: follow this convention.
        !           112: {ls 1}{outdent 8}
        !           113: "str"~~~The argument text can evaluate to any text {ul string}.
        !           114: {ls 1}{restore lmg}
        !           115: In addition, any of these forms may be preceeded by the letter 'q'.
        !           116:  For example, "qstr", "qpred" and the like.
        !           117:  This indicates that the argument is {ul not} evaluated by GPMDOC
        !           118: before it is given to the macro.
        !           119:  The macro itself may, if it chooses, evaluate the argument on its own.
        !           120:  This is used primarily by system macros that must {ul conditionally}
        !           121: evaluate arguments (e.g. COND, DOWHILE, DOPROP).
        !           122: {Ls 1}{outdent 6}
        !           123: <"{D MACRO}":>{LS 1}
        !           124: This says that the textual definition of MACRO can
        !           125: be retrieved.
        !           126:  Some system macros are compiled into an internal coded form with no textual
        !           127: representation.
        !           128:  D applied to these macros will give the same result as "<{MACRO}>",
        !           129: and the D form is not shown for them.
        !           130: {Ls 1}The "@mname" abbreviation form for arguments is, in operation,
        !           131: entirely equivalent to the <"{D mname}"> macro form,
        !           132: and these same remarks apply.
        !           133: {ls 1}{outdent 6}
        !           134: <"{SET MACRO,argument}":>{brk}
        !           135: {LS 1}
        !           136: This format means that MACRO can sensibly be redefined
        !           137: using any form of set (SET, TSET, SETQ, SETV, etc.).
        !           138:  Many system macros will have side effects when set,
        !           139: such as altering
        !           140: the margins or causing spacing down the page.
        !           141: {ls 1}{restore lmg}
        !           142: The examples try to present several different facets
        !           143: of the uses for the macro being described.
        !           144:  (The examples are all shown in upper case for emphasis;
        !           145: but keep in mind that the case of macro names is not significant.)
        !           146: {Ls 1}To avoid making the examples trivial, most of them are
        !           147: "real-life", some easy and others a bit more involved.
        !           148:  An asterisk next to an example indicates that the
        !           149: example is a particularly advanced one.
        !           150:  You may wish to skip over these.
        !           151:  As a final note, this section does not describe the many macros
        !           152: available in libraries.
        !           153: {Exclude HELP}
        !           154: {P}
        !           155: {Restore Newpage}
        !           156: {Setq Endpage,{Ls 2}{Center A-{D Pagenum} [{D Macroname}]}{Eject}}
        !           157: !**
        !           158: !
        !           159: ! Start the descriptions
        !           160: !
        !           161: !
        !           162: ! ADD1
        !           163: !
        !           164: {macdescr ADD1,Add One To Numeric}
        !           165: <{ADD1 n}>
        !           166: {macsec description}
        !           167: The value of ADD1 is one added to n.  It is equivalent
        !           168: to <{+~n,1}>.
        !           169: {macsec examples}
        !           170: {bl}Add one to the current page number:
        !           171: {ls 1}
        !           172: {Center <{SET.ADD1 PAGENUM}>}
        !           173: {Ls 1}
        !           174: {Li *~}Here is a definition for a macro, CASE, that evaluates one
        !           175: of its arguments depending on the value of a 'control argument':
        !           176: {Ls 1}{Center <{SETQ CASE,{{ADD1 @1}}}>}{Ls 1}
        !           177: A macro reference such as <"{CASE~2,SNURF,BLURF,ERFF}"> would
        !           178: evaluate to "BLURF" because the "2", in effect, 'selects' argument #3.
        !           179:  It does this by adding one to the 2, and then using the resulting "3"
        !           180: as the name of a macro to be evaluated.
        !           181:  If any of the arguments themselves contained macro calls that were to be
        !           182: conditionally evaluated, they could be placed in quotes to defer the
        !           183: evaluation.
        !           184: {Ls 1}This is not a wholly satisfactory definition, since "<{CASE~0,...}>"
        !           185: will evaluate to "0" (argument #1),
        !           186: whereas all other values of the first argument that are out of range will
        !           187: evaluate null.
        !           188:  The definition of CASE could be revised a bit using a COND macro to be:
        !           189: {Ls 1}{Center <{SETQ CASE,{COND {NE @1,0},{{ADD1 @1}}}}>}{Ls 1}
        !           190: {EL}
        !           191: {P}
        !           192: !
        !           193: ! APPEND
        !           194: !
        !           195: {macdescr APPEND,Join Two Strings}
        !           196: <{APPEND str1,str2}>
        !           197: {macsec description}
        !           198: The value of APPEND is the text value formed by
        !           199: appending str1 on the right of str2.
        !           200: {macsec notes}
        !           201: {bl}A simple left to right juxtaposition of text is
        !           202: sufficient to perform this function, so APPEND is only
        !           203: useful in extended sets (see example).
        !           204: {el}
        !           205: {macsec examples}
        !           206: {bl}Print an extra line after the page heading from now on:
        !           207: {Ls 1}{Center <{SET.APPEND NEWPAGE,<{LS 1}>}>}{Ls 1}
        !           208: {EL}
        !           209: {P}
        !           210: !
        !           211: ! BEGINTEXT
        !           212: !
        !           213: {macdescr BEGINTEXT,Starting Input Line}
        !           214: <{set BEGINTEXT,str}>
        !           215: <{BEGINTEXT}>
        !           216: <{D BEGINTEXT}>
        !           217: {Macsec Description}
        !           218: The value of BEGINTEXT is used with INPUT to define the starting
        !           219: line of the new file.
        !           220:  If BEGINTEXT is non-null when INPUT is set, GPMDOC will skip over
        !           221: input lines looking for one that matches BEGINTEXT.
        !           222:  When one is found, input starts with the line that follows.
        !           223: {Macsec Notes}
        !           224: {Bl}The input lines that are skipped are physical lines of the designated
        !           225: input file, not logical lines.
        !           226:  This means that continuations are not processed, and also that
        !           227: comment lines (those that begin with an exclamation point) can
        !           228: are candidates for BEGINTEXT.
        !           229:  Comment lines are recommended for BEGINTEXT, as they are otherwise
        !           230: ignored by GPMDOC when processing a file.
        !           231: {Li}The line for BEGINTEXT must match exactly.
        !           232:  The case of letters is significant.
        !           233: {el}
        !           234: {Macsec examples}
        !           235: {bl}Read the file MACLIB.GPM starting at the line following
        !           236: one which reads "!LIST 3", and finishing at the line which reads
        !           237: "!END 3":
        !           238: {Ls 1}
        !           239: {Center <{TSET INPUT,MACLIB.GPM,STARTTEXT=!LIST 3,ENDTEXT=!END 3}>}
        !           240: {LS 1}
        !           241: This sort of thing is useful for a 'macro library' which could contain
        !           242: sets of macro definitions for different purposes.
        !           243: {el}
        !           244: {p}
        !           245: !
        !           246: ! BIAS
        !           247: !
        !           248: {Macdescr BIAS,Set Page Bias}
        !           249: <{set BIAS,n}> (Default: BIAS=0)
        !           250: <{BIAS}>
        !           251: {Macsec DESCRIPTION}
        !           252: BIAS controls the size of the left hand "gutter."
        !           253: Its effect is similar to that of setting the left margin,
        !           254: except that the right margin is also moved a corresponding amount,
        !           255: so the linelength remains unchanged.
        !           256:  The sum of BIAS and LMG (current left margin) must always be positive.
        !           257: {Macsec NOTES}
        !           258: {Bl}BIAS is useful for printing documents on varying devices which
        !           259: start printing at different locations.
        !           260: {Li}Setting BIAS has no effect on the values of LMG or RMG.
        !           261: {El}
        !           262: {P}
        !           263: !
        !           264: ! BRK
        !           265: !
        !           266: {macdescr BRK,Force Line Break}
        !           267: <{BRK}>
        !           268: {MACSEC DESCRIPTION}
        !           269: This macro is identical to <{LS~0}> or <{LS}>.
        !           270:  It causes the text line
        !           271: currently being assembled to be flushed to the output stream.
        !           272:  This is termed a "line break".
        !           273:  Right justification is not applied,
        !           274: regardless of whether or not it is enabled.
        !           275: {MACSEC NOTES}
        !           276: {BL}Line break is normally used to force printing to begin on a new
        !           277: line when line fill is on, or whilst typing in the middle of a line,
        !           278: or within a macro.
        !           279:  Note that line fill being off (non-null) forces
        !           280: an automatic line break after reading each input line.
        !           281: {EL}
        !           282: {macsec examples}
        !           283: {BL}This example shows how to print successive items on
        !           284: separate lines when line fill is enabled, using BRK:
        !           285: {ls 1}
        !           286: A. Two eggs<{brk}>B. Three cups flour<{brk}>C. Two tbsp. butter
        !           287: {ls 1}
        !           288: would print as:
        !           289: {ls 1}
        !           290: A. Two eggs{brk}B. Three cups flour{brk}C. Two tbsp. butter
        !           291: {el}
        !           292: {P}
        !           293: !
        !           294: ! BSLACK
        !           295: !
        !           296: {Macdescr BSLACK,End-of-Page Runout}
        !           297: <{set BSLACK,n}> (Default: BSLACK=0)
        !           298: <{BSLACK}>
        !           299: <{D BSLACK}>
        !           300: {MACSEC DESCRIPTION}
        !           301: The value of BSLACK is used by the system to determine when
        !           302: to run out the rest of a page during line skipping.
        !           303: Assuming BSLACK has the value "n" and an attempt is made to skip
        !           304: lines when less than "n" lines remain on the page, the page is
        !           305: simply run out, and an ENDPAGE condition occurs.
        !           306: (Line skipping means either an <{LS...}> or
        !           307: a <{SET~LINENUM,...}>.)
        !           308: {MACSEC NOTES}
        !           309: {BL}The value for n cannot be negative.
        !           310: {LI}BSLACK can be used to avoid such situations as the first line
        !           311: of a paragraph being printed at the bottom of a page.
        !           312: {LI}Setting BSLACK to zero effectively nullifies any BSLACK action.
        !           313: {EL}
        !           314: {P}
        !           315: !
        !           316: ! CAB
        !           317: !
        !           318: {MACDESCR CAB,Close Angle Bracket}
        !           319: <{CAB}>
        !           320: {MACSEC DESCRIPTION}
        !           321: Evaluates to ">".
        !           322: {MACSEC NOTES}
        !           323: {BL}This macro, and its companion <{OAB}>, are used in situations
        !           324: where the quote symbols are needed without causing the effect
        !           325: of quoting, or where they appear in an unbalanced way.
        !           326: {EL}
        !           327: {MACSEC EXAMPLES}
        !           328: {BL}Computer programs often use the GPMDOC quote symbols to
        !           329: signify the operations of comparison (less than and greater than).
        !           330: For instance:
        !           331: {LS 1}
        !           332: {center IF A {OAB} B AND A {CAB} C}
        !           333: {LS 1}
        !           334: in GPM would print as:
        !           335: {LS 1}
        !           336: {Center IF A  B AND A  C}
        !           337: {LS 1}
        !           338: The CAB (and OAB) macros could be used:
        !           339: {LS 1}
        !           340: {CENTER IF A <{OAB}> B AND A <{CAB}> C.}
        !           341: {LS 1}
        !           342: which evaluates correctly. (It would also be possible to
        !           343: achieve the same effect in this example by quoting the entire
        !           344: line, or with the use of INFORMAT.)
        !           345: {EL}
        !           346: {P}
        !           347: !
        !           348: ! CAPS
        !           349: !
        !           350: {macdescr CAPS,Capitalize Text}
        !           351: <{CAPS str}>
        !           352: {macsec description}
        !           353: The value of a call to CAPS is str, except all lower
        !           354: case letters are replaced with their equivalents in
        !           355: upper case.
        !           356:  It is the same as:
        !           357: {ls 1}
        !           358:      <{REPLACE str,abc...xyz,ABC...XYZ}>
        !           359: {macsec examples}
        !           360: {bl}Print the text of the macro TITLE capitalized:
        !           361: {ls 1}{Center <{CAPS @TITLE}>}
        !           362: {Li *~}Read "FILE1" if the user responds "No" and "FILE2" if
        !           363: the user responds "Yes"
        !           364: {Ls 1}{Nfj}
        !           365: <{TSET INPUT,->
        !           366:   <{COND ->
        !           367:     <{LEQ {CAPS {SUBSTR {QUERY Enter Yes or No: },1,1}},N},->
        !           368:     <FILE1,,FILE2->
        !           369:   <}->
        !           370: <}>
        !           371: {Fj}
        !           372: {Ls 1}Note that only the first cahracter of the response
        !           373: is compared.
        !           374:  It is capitalized so that regardless of whether the user types
        !           375: "N" or "n",
        !           376: it is still perceived as a 'no' response.
        !           377: {Ls 1}You might want to write a predicate macro that would issue a general
        !           378: yes/no question (supplied as an argument) to be true if the response
        !           379: is affirmative,
        !           380: and false if the response is negative.
        !           381:  As an enhancement,
        !           382: the macro will loop until it gets one of the two responses.
        !           383: {Ls 1}{Nfj}
        !           384: <{SETQ YNQ,->
        !           385:   <{SET YNQ$R}->
        !           386:   <{DOWHILE {LNE @YNQ$R,N}{LNE @YNQ$R,Y},->
        !           387:     <{SET YNQ$R,{CAPS {SUBSTR {QUERY @1},1,1}}}->
        !           388:   <}->
        !           389:   <{COND {LEQ @YNQ$R,N},1}->
        !           390: <}>
        !           391: {Ls 1}{Fj}
        !           392: {el}
        !           393: {P}
        !           394: !
        !           395: ! CENTER
        !           396: !
        !           397: {macdescr CENTER,Center a Text Line}
        !           398: <{CENTER str}>
        !           399: {macsec description}
        !           400: CENTER prints str padded on the left with hard spaces so as to cause it to
        !           401: appear centered between the current left and right margins.
        !           402:  A line break is forced before and after str is printed.
        !           403:  The value of the CENTER macro is always null,
        !           404: (the centered text is sent directly to the output stream).
        !           405: {macsec notes}
        !           406: {bl}If str is longer than <{LINELENGTH}>, the text will
        !           407: be printed on multiple, uncentered lines.
        !           408: {el}
        !           409: {macsec examples}
        !           410: {bl}Print the text "SUBMITTED IN PARTIAL FULFILLMENT" centered on line 30:
        !           411: {Ls 1}{Center <{SET LINENUM,30}{CENTER SUBMITTED IN PARTIAL FULFILLMENT}{BRK}>}
        !           412: {Ls 1}
        !           413: {Li}Print the text stored in the macro TITLE, centered at the top of every
        !           414: page:{Ls 1}{Center <{SETQ NEWPAGE,{CENTER @TITLE}}{BRK}>}{LS 1}
        !           415: {el}
        !           416: {P}
        !           417: !
        !           418: ! CODE
        !           419: !
        !           420: {Macdescr CODE,Define Internal Macro Code}
        !           421: <{CODE mname,str}>
        !           422: {Macsec Description}
        !           423: CODE is used to define mname as an internal code sequence in order to
        !           424: improve efficiency, or to make available functions that cannot be realistically
        !           425: coded in macro form.
        !           426:  Str must represent a legitimate internal code string.
        !           427:  Evaluation of CODE will 'compile' STR and bind the resulting code
        !           428: to mname as a system macro.
        !           429:  The value of CODE is null.
        !           430: {Ls 1}As this is not a systems reference document, no further elaboration
        !           431: of CODE is given here.
        !           432: {P}
        !           433: !
        !           434: ! COND
        !           435: !
        !           436: {MACDESCR COND,Conditional Evaluation}
        !           437: <{COND qpred1,qstr1,qpred2,qstr2, ...}>
        !           438: {MACSEC DESCRIPTION}
        !           439: COND will conditionally evaluate one of str1,~str2,~etc. in
        !           440: the following way.
        !           441:  First, pred1 is evaluated.
        !           442:  If it is null (true), then the value of the COND becomes the
        !           443: evaluation of str1.
        !           444:  Otherwise, the COND continues by evaluating pred2, and if
        !           445: it is true, the value of COND becomes the value of str2.
        !           446: {Ls 1}COND allows an indefinite number of predicate-string
        !           447: pairs.
        !           448:  Since any unspecified arguments are taken as null strings,
        !           449: if none of the predicates evaluates null (true), then an implied
        !           450: null predicate will be 'seen' past the given arguments and the
        !           451: following implied null string will be returned as the value.
        !           452: {macsec notes}
        !           453: {Bl}While any text may be given for a predicate, generally
        !           454: one of the system predicate macros is used.
        !           455:  These predicates are described fully under their own sections.
        !           456: {Ls 1}For numeric tests, LT, LE, GT, GE, NE, EQ, EVEN and ODD
        !           457: are the system predicates.
        !           458: {Ls 1}For comparing strings, LLT, LLE, LGT, LGE, LNE, and LEQ
        !           459: are the system predicates.
        !           460: {Li}All system predicates use the string "1" as the standard
        !           461: 'false' value.
        !           462:  Uses writing their own predicate-valued macros are urged to
        !           463: adopt this convention.
        !           464: {EL}
        !           465: {macsec examples}
        !           466: {BL}If less than ten lines remain on the page then skip to a new
        !           467: page:
        !           468: {LS 1}
        !           469: {CENTER <{COND {LT {- @LINENUM,@PAGELENGTH},10},{SET LINENUM,1}}>}
        !           470: {LS 1}
        !           471: (Note that in this example qpred2 and qstr2 are omitted,
        !           472: so they are assumed to be null.)
        !           473: {LI}Define a macro <{IFLINES n}> to do the same thing, allowing any
        !           474: number n.
        !           475: {LS 1}
        !           476: {NFJ}
        !           477: <{SETQ IFLINES,{COND {LT {- @LINENUM,@PAGELENGTH},@1},->
        !           478:      <{SET LINENUM,1}}}>
        !           479: {FJ}
        !           480: {LI}Move the left margin out 5 spaces, unless it is less than
        !           481: 5 from the edge already, in which case set it to 1.
        !           482: {LS 1}
        !           483: {CENTER <{SET LMG,{COND {LE @LMG,5},1,,{- @LMG,5}}}>}
        !           484: {CENTER or}
        !           485: {CENTER <{COND {LE @LMG,5},{SET LMG,1},,{SET.- LMG,5}}>}
        !           486: {EL}
        !           487: {p}
        !           488: !
        !           489: ! CREPROP
        !           490: !
        !           491: {macdescr CREPROP,Create Property Table}
        !           492: <{CREPROP str}>
        !           493: {Macsec Description}
        !           494: CREPROP generates a property table with the name "str".
        !           495:  Once such a table has been created, named values can be
        !           496: set in the table using the property table name suffixed
        !           497: onto the macro name with a backslash ("\").
        !           498: {Macsec Notes}
        !           499: {bl}Only one property table is initially defined - the so-called
        !           500: null property table.
        !           501:  The null property table is where all system defined macro values
        !           502: reside, and the table which, by default, is referred to if a
        !           503: macro name contains no property table reference.
        !           504: {li}TSET stacks for the same name in different property tables are
        !           505: distinct.
        !           506: {li}DELPROP can be used to eliminate a property table and all
        !           507: associated values when they are no longer of use.
        !           508: {li}DOPROP allows examination of all the values of a property
        !           509: table.
        !           510: {Li}Numeric names in property tables other than the null table
        !           511: do {ul not} refer to argument values, numeric names function no
        !           512: differently from other names in these tables.
        !           513: {El}
        !           514: {macsec examples}
        !           515: {bl}Create a property table "SECNUM" and set name "I" in it
        !           516: to zero:
        !           517: {Ls 1}{Center <{CREPROP SECNUM}{SET I\SECNUM,0}>}{Ls 1}
        !           518: {li}The description of DOPROP contains more examples of
        !           519: property tables.
        !           520: {el}
        !           521: {p}
        !           522: !
        !           523: ! CS
        !           524: !
        !           525: {MACDESCR CS,Create Control Sequence}
        !           526: <{CS str}>
        !           527: {Macsec description}
        !           528: The value of CS is a control sequence for str.
        !           529:  A control sequence is printed as "str" but has a defined length of
        !           530: zero, regardless of the length of str.
        !           531:  Str must not contain any overstrikes or embedded control sequences.
        !           532: {Macsec notes}
        !           533: {Bl}CS is primarily useful in creating device-dependent control
        !           534: sequences that are embedded in the text, but which should not figure
        !           535: into line length calculations (e.g. centering, justification, etc.).
        !           536: {el}
        !           537: {p}
        !           538: !
        !           539: ! D
        !           540: !
        !           541: {MACDESCR D,Retrieve The Definition of a Macro}
        !           542: <{D mname}>
        !           543: {macsec description}
        !           544: The value of D is the string of characters which form the
        !           545: definition of mname.
        !           546: {macsec notes}
        !           547: {Bl}The definition retrieved is not evaluated, so this is quite
        !           548: different from <{mname ...}> if the definition contains quotes
        !           549: or macro calls.
        !           550: {LI}You can also apply D to arguments as in "<{D~3}>" which will
        !           551: give the string of text passed as argument 3, without evaluating it.
        !           552: {LI}D applied to system functions will result in the string
        !           553: "SYSTEM", since these macros are not defined internally
        !           554: using text, but rather as operational sequences using
        !           555: a special code.
        !           556: {Li}There is an abbreviated form of D which can be used when
        !           557: an argument in a macro call is to evaluate to the definition
        !           558: of some other macro.
        !           559:  If an argument begins with the at-sign ("@"), it is considered
        !           560: to be such an argument.
        !           561:  The text of the argument following the at-sign is evaluated
        !           562: in the normal way, and the result is taken as an "mname".
        !           563:  The value of the argument becomes the definition of that mname.
        !           564:  There are examples of this abbreviation below.
        !           565: {Ls 1}Note that to have this effect,
        !           566: the leading "@" cannot be a product of the evaluation,
        !           567: it must be the {ul actual first character} of the argument text itself.
        !           568: {EL}
        !           569: {macsec examples}
        !           570: {BL}Print the centered definition of a user-defined macro TITLE
        !           571: without evaluating it:
        !           572: {LS 1}
        !           573: {center <{CENTER {D TITLE}}>}{BRK}{Center or}{Brk}
        !           574: {Center <{CENTER @TITLE}>}
        !           575: {LI}Suffix the string <{LS 1}> onto NEWLINE without upsetting
        !           576: things by evaluating the text already in NEWLINE:
        !           577: {LS 1}
        !           578: {CENTER <{SET NEWLINE,{D NEWLINE}<{LS 1}>}>}
        !           579: {center or}
        !           580: {CENTER <{SET.APPEND NEWLINE,<{LS 1}>}>}
        !           581: {LS 1}
        !           582: Note that a form such as:
        !           583: {Ls 1}{Center <{SET NEWLINE,@NEWLINE<{LS 1}>}>}{Ls 1}
        !           584: would {ul not} be satisfactory because the "@" applies to
        !           585: the resulting text of the {ul entire} argument (including the <"<{LS~1}>">,
        !           586: not just the initial part of it.
        !           587: {el}
        !           588: {P}
        !           589: !
        !           590: ! DATE
        !           591: !
        !           592: {Macdescr DATE,Date Text}
        !           593: <{DATE}>
        !           594: {Macsec Description}
        !           595: The value of DATE is the date-of-year in the form DD-MMM-YYYY.
        !           596:  For example, 08-SEP-1981.
        !           597: {p}
        !           598: !
        !           599: ! DBL
        !           600: !
        !           601: {macdescr DBL,Double-Strike (Bold) Text}
        !           602: <{DBL str}>
        !           603: {macsec description}
        !           604: <{DBL~str}> is equivalent to <{OS~str,str}>.
        !           605:  Its value is str overstruck with itself.
        !           606: {macsec notes}
        !           607: {bl}DBL can be a good substitute for italics.
        !           608: {el}
        !           609: {macsec examples}
        !           610: {bl}Print "THE GETTYSBURG ADDRESS", centered and boldface.
        !           611: {LS 1}
        !           612: {CENTER <{CENTER {DBL THE GETTYSBURG ADDRESS}}>}
        !           613: {ls 1}
        !           614: This will print as:
        !           615: {ls 1}
        !           616: {CENTER {DBL THE GETTYSBURG ADDRESS}}
        !           617: {li}Define a macro REALBOLD that will overstrike an image
        !           618: with itself sixteen times:
        !           619: {ls 1}
        !           620: {center <{SETQ REALBOLD,{DBL {DBL {DBL {DBL @1}}}}}>}
        !           621: {EL}
        !           622: {P}
        !           623: !
        !           624: ! DELPROP
        !           625: !
        !           626: {Macdescr DELPROP,Delete a Property Table}
        !           627: <{DELPROP str}>
        !           628: {Macsec Description}
        !           629: DELPROP erases a property table and all values and stacks associated
        !           630: with it.
        !           631:  If further use is to be made of the eradicated property table, a
        !           632: new CREPROP must be performed for it.
        !           633: {p}
        !           634: !
        !           635: ! DIAG
        !           636: !
        !           637: {macdescr DIAG,Enter Diagnostic Subsystem}
        !           638: <{DIAG}>
        !           639: {Macsec Description}
        !           640: DIAG is used for system testing.
        !           641:  It enters the system debugger.
        !           642:  The value of DIAG is null.
        !           643: {Ls 1}As this is not a systems manual, no further explanation
        !           644: of DIAG is offered here.
        !           645:  This function is for debugging and development, and should not
        !           646: ordinarily be used.
        !           647: {P}
        !           648: !
        !           649: ! DISPLAY
        !           650: !
        !           651: {macdescr DISPLAY,Print Message on Terminal}
        !           652: <{DISPLAY str}>
        !           653: {macsec description}
        !           654: DISPLAY causes the value of str to be displayed on your
        !           655: terminal. The value of DISPLAY itself is null.
        !           656: {macsec notes}
        !           657: {BL}No formatting is applied to str before it is sent to
        !           658: the terminal.
        !           659: {LI}QUERY can be used for messages where a response is
        !           660: desired.
        !           661: {EL}
        !           662: {macsec examples}
        !           663: {bl}Display an instructional message and begin receiving input from the
        !           664: terminal:
        !           665: {ls 1}
        !           666: {nfj}
        !           667: <{DISPLAY <Enter your text, use Control-Z to finish>}->
        !           668:           <{TSET INPUT,TT:}}>
        !           669: {LS 1}
        !           670: {FJ}
        !           671: {LI *~}Process the first 10 chapters of a document which has
        !           672: been segmented into files: CH1.GPM, CH2.GPM, etc. Precede
        !           673: each with an informative message to tell you that GPMDOC is
        !           674: still alive.
        !           675: {ls 1}
        !           676: {nfj}
        !           677:      <{DOWHILE {LT @CHAP,10},{SET.ADD1 CHAP}->
        !           678:         <{DISPLAY PRINTING CHAPTER {CHAP}}->
        !           679:         <{TSET INPUT,CH{CHAP}.GPM}}>
        !           680: {FJ}
        !           681: {EL}
        !           682: {P}
        !           683: !
        !           684: ! DOPROP
        !           685: !
        !           686: {macdescr DOPROP,Evaluate Property Table}
        !           687: <{DOPROP str1,qstr2,str3}>
        !           688: {Macsec Description}
        !           689: DOPROP uses str1 (case irrelevant)
        !           690: as a property table name (the backslash is not specified).
        !           691:  Qstr2 is repeatedly evaluated for each non-null
        !           692: value in the indicated property table.
        !           693:  The context of this evaluation has <{D~1}> (argument one) set to the
        !           694: macro name in the property table (without the table name suffix), and
        !           695: <{D~2}> set to its corresponding value.
        !           696: {Ls 1}If str3 evaluates to the string "UP" (case irrelevant), then
        !           697: the table names are presented in ascending sorted order.
        !           698:  Similarly, "DOWN" will cause the names to be sorted in descending
        !           699: order.
        !           700:  Otherwise, the names are presented in an unpredictable order.
        !           701:  In all cases, all the name-value pairs are evaluated exactly once.
        !           702: {Ls 1}The value of DOPROP is the concatenated result formed by the
        !           703: successive evaluations of qstr2.
        !           704: {Macsec Notes}
        !           705: {bl}For UP and DOWN sorts, names which are numeric will be sorted
        !           706: as numbers, not as alphanumerics.
        !           707:  For example, the "2" is, as a number, less than "10", but
        !           708: considered as a text string, "2" would be greater than "10".
        !           709: {el}
        !           710: {macsec examples}
        !           711: {bl *~}DOPROP can be useful for generating sorted indices.
        !           712:  First, define a macro at the beginning of the document such as:
        !           713: {Ls 1}{Center <{SETQ INDEX,{SET.APPEND {1}\INDEX,<,>{PAGENUM}}}>}
        !           714: {Ls 1}This macro, when invoked in the document with a reference such
        !           715: as "<{INDEX Pancakes}>" will append a comma and the current page number to
        !           716: the value for PANCAKES on the INDEX property table.  Before using
        !           717: the macro, it is also necessary to establish the property table
        !           718: with a macro call such as: "<{CREPROP INDEX}>".
        !           719: {Ls 1}At the end of the document, you can 'dump' this property table in
        !           720: a neat format.
        !           721:  The following DOPROP macro shows one way to do this:
        !           722: {Ls 1}{Center <{DOPROP INDEX,{RPAD {SUBSTR @1,2},30,.}{2}{BRK},UP}>}
        !           723: {Ls 1}This will print successive lines of the form:
        !           724: {Ls 1}{Center <PANCAKES.....................18,45,104>}{Ls 1}
        !           725: The SUBSTR is used to eliminate the initial comma which the INDEX macro
        !           726: puts in front of each page number (including the first).
        !           727: {el}
        !           728: {p}
        !           729: !
        !           730: ! DOWHILE
        !           731: !
        !           732: {Macdescr DOWHILE,Repeated Evaluation}
        !           733: <{DOWHILE pred,qstr}>
        !           734: {MACSEC DESCRIPTION}
        !           735: DOWHILE is evaluated by first evaluating the given predicate, and
        !           736: if it is true, evaluating qstr.
        !           737:  This cycle is repeated until pred becomes non-null (false).
        !           738:  The value of the DOWHILE is
        !           739: the concatenated values of the successive evaluations of qstr.
        !           740: {macsec notes}
        !           741: {BL}Be careful that the given predicate will eventually become
        !           742: false, or an "infinite loop" will result, and you will have
        !           743: to abort GPMDOC.
        !           744: {EL}
        !           745: {macsec examples}
        !           746: {BL *~}Print the numbers from 1 to 20 on successive lines down
        !           747: the left margin of the page:
        !           748: {Ls 1}{Center <{SET NUM,0}{DOWHILE {LT {SETV.ADD1 NUM},20},{NUM}{BRK}}>}
        !           749: {LS 1}Note that the macro NUM is the 'counter,' and that it is
        !           750: initialized to zero.
        !           751: {LI *~}Print ten numbered copies of a document:
        !           752: {LS 1}
        !           753: {Center <{SET D#,0}{DOWHILE {LT {SETV.ADD1 D#},10},{TSET INPUT,DOC.GPM}}>}
        !           754: {ls 1}
        !           755: DOC.GPM presumably contains references to <{D#}> which will
        !           756: contain the document number as a result of the DOWHILE.
        !           757: {EL}
        !           758: {P}
        !           759: !
        !           760: ! DSIZE
        !           761: !
        !           762: {macdescr DSIZE,Size of Defined Macro}
        !           763: <{DSIZE mname}>
        !           764: {Macsec Description}
        !           765: The value of DSIZE is the number of print columns in the definition
        !           766: of mname.
        !           767:  DSIZE is equivalent to <{SIZE~{D~mname}}> or <{SIZE~@mname}>,
        !           768: but is simpler and more efficient.
        !           769: {Macsec Notes}
        !           770: {bl}If the definition of mname contains no overstrikes
        !           771: then the value of DSIZE is equal to the number of characters in the
        !           772: definition.
        !           773: {li}DSIZE applied to coded system macros (those for which <"{D mname}">
        !           774: is the same as <"{mname}">, will yield the same as <"{SIZE {mname}}">.
        !           775: {el}
        !           776: {p}
        !           777: !
        !           778: ! DUPL
        !           779: !
        !           780: {macdescr DUPL,Duplicate a String}
        !           781: <{DUPL str,n}>
        !           782: {macsec description}
        !           783: The value of DUPL is str repeated n times. If n is zero,
        !           784: the value of DUPL is null.
        !           785: {macsec notes}
        !           786: {BL}N must be non-negative.
        !           787: {el}
        !           788: {macsec examples}
        !           789: {bl}Produce 20 periods:
        !           790: {ls 1}
        !           791: {nfj}
        !           792:         <{DUPL .,20}>
        !           793: {fj}
        !           794: {ls 1}
        !           795: {li}Print a line of hyphens across the page:
        !           796: {ls 1}
        !           797: {nfj}
        !           798:         <{BRK}{DUPL -,@LINELENGTH}>
        !           799: {FJ}
        !           800: {LI *~}Define a macro CPAD, that will return its argument
        !           801: text prefixed with the correct number of hard spaces to
        !           802: cause the argument to be centered on the line (assuming it is printed
        !           803: from the left margin).
        !           804: {ls 1}
        !           805: {nfj}
        !           806:        <{SETQ CPAD,{DUPL @HS,->
        !           807:             <{DIV {- @LINELENGTH,{DSIZE 1}},2}}{D 1}}>
        !           808: {FJ}
        !           809: {Ls 1}
        !           810: This macro calculates the number of hard spaces to produce
        !           811: by subtracting the size of the argument text from the
        !           812: length of the line, and dividing it by two. The argument text
        !           813: is appended onto the right of these hard spaces.
        !           814: {Ls 1}
        !           815: The advantage that this macro might have over the system
        !           816: CENTER macro is that CPAD only returns the argument text
        !           817: padded on the left with hard spaces.
        !           818:  It does not cause any line breaks as does CENTER.
        !           819:  This means it would be possible for
        !           820: you to print text on the same line to the right of the centered
        !           821: text.
        !           822: {el}
        !           823: {p}
        !           824: !
        !           825: ! EJECT
        !           826: !
        !           827: {macdescr EJECT,Form Feed}
        !           828: <{EJECT},> (Default: See Description)
        !           829: <{D EJECT},>
        !           830: <{set EJECT},>
        !           831: {macsec description}
        !           832: <{EJECT}> is initialized with the character codes or
        !           833: sequence needed to cause a "form feed" (page eject)
        !           834: on the system standard hard copy device.
        !           835: {macsec notes}
        !           836: {bl}If you are directing OUTPUT to other than the standard
        !           837: device, it may be advantageous to set EJECT to a suitable
        !           838: value first.
        !           839: {li}<{EJECT}> has no effect on <{PAGENUM}>, and for
        !           840: that reason is generally only used in ENDPAGE.
        !           841: {el}
        !           842: {macsec examples}
        !           843: {bl}Skip to a new page at the bottom of each page
        !           844: {ls 1}
        !           845: {nfj}
        !           846:         <{SETQ ENDPAGE,{EJECT}}>
        !           847: {ls 1}
        !           848: {fj}
        !           849: {el}
        !           850: {p}
        !           851: !
        !           852: ! END
        !           853: !
        !           854: {macdescr END,Terminate GPMDOC Session}
        !           855: <{END}>
        !           856: {macsec description}
        !           857: An evaluation of <{END}> will cause GPMDOC to flush its
        !           858: output stream, close all files, and exit.
        !           859:  The value of END is irrelevant.
        !           860: {macsec notes}
        !           861: {BL}You can exit from GPMDOC by finishing input from the
        !           862: initial input file (see the description of INPUT).
        !           863: {LI}END can be used at any point in any file regardless
        !           864: of present activity.
        !           865: {Li}The use of END is normally discouraged,
        !           866: as document files that contain it cannot be included (TSET INPUT)
        !           867: from other document files.
        !           868: {EL}
        !           869: {macsec examples}
        !           870: {BL}If <{FILENAME}> is null, print an error message and
        !           871:  terminate the session.
        !           872: {ls 1}
        !           873: {nfj}
        !           874: <{COND {LEQ @FILENAME},{DISPLAY YOU HAVEN'T SPECIFIED><->
        !           875:      <A FILE!}{END}}>
        !           876: {FJ}
        !           877: {EL}
        !           878: {P}
        !           879: !
        !           880: ! ENDPAGE
        !           881: !
        !           882: {macdescr ENDPAGE,Ending Page Event}
        !           883: <{set ENDPAGE,str}> (Default: <ENDPAGE={EJECT}>)
        !           884: <{ENDPAGE}>
        !           885: <{D ENDPAGE}>
        !           886: {macsec description}
        !           887: When the value of LINENUM becomes greater than the
        !           888: value of PAGELENGTH, an ENDPAGE event occurs, which
        !           889: causes the following sequence of events:
        !           890: {bl}The line to be printed and any other text in the
        !           891: output stream are put aside.
        !           892: {li}NEWLINE is TSET to null, SPACING is TSET to one,
        !           893: LMG is TSET to 10 and RMG is TSET to 75.
        !           894: {li}<"{ENDPAGE}"> is evaluated.
        !           895: {li}NEWLINE, SPACING, LMG and RMG are all restored.  This
        !           896: completes the ENDPAGE event.
        !           897: {el}
        !           898: {macsec notes}
        !           899: {bl}If NEWLINE, SPACING, LMG or RMG are changed by
        !           900: ENDPAGE, changes will only have effect during the ENDPAGE
        !           901: event, as these macros are TSET and RESTOREd.
        !           902:  If you desire a permanent change, first do a RESTORE, and
        !           903: then SET your desired permanent value for the macro.
        !           904:  (This will become the value restored at the end of the ENDPAGE
        !           905: condition.)
        !           906:  Then TSET back the value for the ENDPAGE context.
        !           907: {li}NEWPAGE and ENDPAGE conditions are inhibited while
        !           908: the ENDPAGE condition is being processed.
        !           909: {el}
        !           910: {macsec examples}
        !           911: {bl}Print the current page number, centered between hyphens
        !           912: at the bottom of every page:
        !           913: {ls 1}
        !           914: {center <{SETQ ENDPAGE,{CENTER - {PAGENUM} -}}>}
        !           915: {LI *~}In documents that are to be bound after they
        !           916: are printed, it is frequently necessary to provide a
        !           917: "gutter" on each page so that printing does not disappear
        !           918: down into the binding.  If printing is to be two-sided,
        !           919: then odd-numbered pages will need to have this gutter
        !           920: on the left, and even-numbered pages will have it on the
        !           921: right (or vice-versa).  This, in effect, necessitates
        !           922: "sliding" the text horizontally back-and-forth on
        !           923: successive pages.  The place to do such sliding is
        !           924: ENDPAGE.  (NEWPAGE would be too late, since the margin
        !           925: for the first line has already been formed when NEWPAGE occurs.)
        !           926: {ls 1}
        !           927: <{SETQ ENDPAGE,->{Brk}
        !           928: <   {SET.+ BIAS,{COND {EVEN @PAGENUM},5,,-5}}}>
        !           929: {El}
        !           930: {P}
        !           931: !
        !           932: ! ENDTEXT
        !           933: !
        !           934: {macdescr ENDTEXT,Ending Input Line}
        !           935: <{set ENDTEXT,str}>
        !           936: <{ENDTEXT}>
        !           937: <{D ENDTEXT}>
        !           938: {Macsec Description}
        !           939: If ENDTEXT is non-null each physical line read by GPMDOC is compared
        !           940: to the definition of ENDTEXT.
        !           941:  If it matches, INPUT is RESTOREd immediately.
        !           942:  The ENDTEXT line itself is discarded.
        !           943: {Macsec Notes}
        !           944: {Bl}The input lines that are examined are physical lines of the designated
        !           945: input file, not logical lines.
        !           946:  This means that continuations are not processed, and also that
        !           947: comment lines (those that begin with an exclamation point)
        !           948: are candidates for ENDTEXT.
        !           949:  Comment lines are recommended for ENDTEXT, as they are otherwise
        !           950: ignored by GPMDOC when processing a file.
        !           951: {Li}The line for ENDTEXT must match exactly.
        !           952:  The case of letters is significant.
        !           953: {Li}The ENDTEXT macro is most useful to terminate the context of a
        !           954: pseudo-read.
        !           955:  To conditionally skip over text in the input stream,
        !           956: the SKIPTEXT macro is more useful.
        !           957: {el}
        !           958: {p}
        !           959: !
        !           960: ! EQ
        !           961: !
        !           962: {Macdescr EQ,Predicate Comparison for Equality}
        !           963: <{EQ n1,n2}>
        !           964: {Macsec Description}
        !           965: EQ evaluates to null (true) if "n1" is equal to "n2",
        !           966: otherwise it evaluates to "1" (false).
        !           967: {Macsec Examples}
        !           968: See COND for uses of system predicate macros.
        !           969: {P}
        !           970: !
        !           971: ! EVEN
        !           972: !
        !           973: {macdescr EVEN,Predicate Test for Numeric Even}
        !           974: <{EVEN n}>
        !           975: {Macsec description}
        !           976: This predicate will evaluate null if the given argument is an even
        !           977: number (zero and negative even numbers are even).
        !           978:  Otherwise it evaluates to "1" (false).
        !           979: !
        !           980: ! FILL
        !           981: !
        !           982: {Macdescr FILL,Line Fill Flag}
        !           983: <{set FILL,pred}> (Default: FILL=1)
        !           984: <{FILL}>
        !           985: <{D FILL}>
        !           986: {Macsec Description}
        !           987: FILL is a flag that controls line fill mode on input.
        !           988:  If fill is enabled (FILL null) then no line break is forced after
        !           989: reading logical lines of input text.
        !           990:  This allows output to be buffered in the output stream until there
        !           991: is enough to just about fit on the line.
        !           992: {Macsec Notes}
        !           993: {Bl}The FJ and NFJ macros are normally used to control FILL, as
        !           994: right justification is usually desired in concert with line fill.
        !           995: {el}
        !           996: {P}
        !           997: !
        !           998: ! FJ
        !           999: !
        !          1000: {macdescr FJ,Enable Fill and Justify Flags}
        !          1001: <{FJ}>
        !          1002: <{D FJ}>
        !          1003: {macsec description}
        !          1004: <{D~FJ}> is the string; <"{SET~FILL}{SET~JUST}">.
        !          1005: It enables both line fill and right justification.
        !          1006:  The value of FJ is, by the above definition, null.
        !          1007: {P}
        !          1008: !
        !          1009: ! GE
        !          1010: !
        !          1011: {Macdescr GE,Predicate for Greater or Equal}
        !          1012: <{GE n1,n2}>
        !          1013: {Macsec Description}
        !          1014: GE evaluates to null (true) if "n1" is greater than or equal to "n2",
        !          1015: otherwise it evaluates to "1" (false).
        !          1016: {Macsec Examples}
        !          1017: See COND for uses of system predicate macros.
        !          1018: {P}
        !          1019: !
        !          1020: ! GT
        !          1021: !
        !          1022: {Macdescr GT,Predicate Comparison for Greater Than}
        !          1023: <{GT n1,n2}>
        !          1024: {Macsec Description}
        !          1025: GT evaluates to null (true) if "n1" is greater than "n2",
        !          1026: otherwise it evaluates to "1" (false).
        !          1027: {Macsec Examples}
        !          1028: See COND for uses of system predicate macros.
        !          1029: {P}
        !          1030: !
        !          1031: ! HS
        !          1032: !
        !          1033: {MACDESCR HS,Hard Space Character}
        !          1034: {TSET HS,%}
        !          1035: <{set HS,str}> (Default: HS=~ (tilde))
        !          1036: <{HS}>,
        !          1037: <{D HS}>
        !          1038: {Restore Hs}
        !          1039: {MACSEC DESCRIPTION}
        !          1040: HS is used to alter or reference the Hard Space Character of the
        !          1041: system. A hard space is a character (other than a space) that
        !          1042: GPMDOC translates to a space just before the text is printed.
        !          1043: The hard space can be used where it is desirable to prevent
        !          1044: line-breaking or right justification.
        !          1045: {MACSEC NOTES}
        !          1046: {BL}Only the first character of str is taken for the new
        !          1047: hardspace.
        !          1048: {LI}Hard spacing can be disabled entirely by setting HS to a blank.
        !          1049: {LI}It is impossible for the current hard space character to be
        !          1050: printed, it must be changed by setting HS first.
        !          1051: {LI}Note that hard space translation is applied just as the
        !          1052: line is being printed. Thus if the hard space character is
        !          1053: changed several times within a line, only the last change will
        !          1054: have effect.
        !          1055: {LI}Certain system macros (e.g. T (Tab), CENTER, LPAD, RPAD) can
        !          1056: emit hard spaces.
        !          1057: {EL}
        !          1058: {MACSEC EXAMPLES}
        !          1059: {BL}Insert ten hard spaces:
        !          1060: {LS 1}
        !          1061: {Tset Hs,%}
        !          1062: {CENTER <{DUPL @HS,10}>}
        !          1063: {CENTER or}
        !          1064: {BRK}
        !          1065: {CENTER <{DUPL ~,10}>}
        !          1066: {Restore Hs}
        !          1067: {LI}
        !          1068: Turn off hard spaces so the tilde can be printed:
        !          1069: {Tset Hs,%}
        !          1070: {Ls 1}{Center <{TSET HS, }> A tilde looks like "~"<{BRK}{RESTORE HS}>}
        !          1071: {El}
        !          1072: {Restore Hs}
        !          1073: !
        !          1074: ! INDEX
        !          1075: !
        !          1076: {Macdescr INDEX,Locate Position of Substring}
        !          1077: <{INDEX str1,str2}>
        !          1078: {Macsec Description}
        !          1079: The value of INDEX is the numeric position of the first occurrence
        !          1080: of "str2" within "str1".
        !          1081:  If "str2" is not in "str1", the value of the INDEX macro is zero.
        !          1082:  If "str2" is null, the value of INDEX is one.
        !          1083: {Macsec Notes}
        !          1084: {Bl}The value of INDEX is the position of the substring (str2),
        !          1085: not the offset.
        !          1086:  It is thus useful for use in the SUBSTR macro (see description).
        !          1087: {el}
        !          1088: {Macsec Notes}
        !          1089: {Bl}Display a message if the value of the macro FILE does not
        !          1090: contain the substring ".GPM":
        !          1091: {Ls 1}{Center <{COND {EQ {INDEX @FILE,.GPM}},{DISPLAY WRONG FILE!}}>}{Ls 1}
        !          1092: {El}
        !          1093: !
        !          1094: ! INFORMAT
        !          1095: !
        !          1096: {Macdescr INFORMAT,Logical Line Formatting Flag}
        !          1097: <{set INFORMAT,pred}> (Default: INFORMAT=null)
        !          1098: <{INFORMAT}>
        !          1099: <{D INFORMAT}>
        !          1100: {Macsec Description}
        !          1101: The INFORMAT flag controls whether any processing is applied to input.
        !          1102:  If it is false (non-null) then input lines are processed exactly as read.
        !          1103:  Continuation hyphens are taken as ordinary characters,
        !          1104: and comment lines (those that begin
        !          1105: with an exclamation point) are processed as any other line.
        !          1106:  No evaluation of macros takes place.
        !          1107:  Text is sent to the output stream exactly as it is read.
        !          1108: {Macsec Notes}
        !          1109: {Bl}Note that output processing (e.g. FILL, JUST) will still be
        !          1110: applied according to the setting of the flags.
        !          1111: {li}Processing with INFORMAT set false is faster because less computation
        !          1112: is required.
        !          1113: {Li}In general, INFORMAT is used only in an INPUT TSET, where an
        !          1114: ENDTEXT flag can be specified.
        !          1115:  Otherwise, since embedded macros are not evaluated it is impossible
        !          1116: to get INFORMAT set true once it has been set false.
        !          1117: {el}
        !          1118: {p}
        !          1119: !
        !          1120: ! INPUT
        !          1121: !
        !          1122: {MACDESCR INPUT,Define the Data Input File}
        !          1123: <{set INPUT,str,mname1=str1,mname2=str2,...}>
        !          1124: {macsec description}
        !          1125: Evaluation of a SET form on the system name INPUT causes GPMDOC
        !          1126: to read succeeding lines from the device/file specified by "str".
        !          1127:  If a TSET form is used on INPUT, the current file is not closed
        !          1128: out, and a subsequent RESTORE (or end-of-file) on the new
        !          1129: file will cause input to resume from the original file at the
        !          1130: line following the one which caused the TSET.
        !          1131:  In general, "<{SET INPUT,...}>" switches input to a different
        !          1132: file, while a TSET suspends the current file temporarily
        !          1133: in order to process a new one.
        !          1134: {Ls 1}Input completes when an end-of-file condition is encountered,
        !          1135: when a <{RESTORE INPUT}> occurs (for a TSET), or when
        !          1136: a previously defined ENDTEXT line is seen.
        !          1137: {ls 1}Arguments out past "str" should evaluate to text of
        !          1138: the form: "mname=str" (e.g. "LMG=40").
        !          1139:  Arguments of this form are termed "keyword" arguments,
        !          1140: and will be TSET by GPMDOC before initiating
        !          1141: the new input stream, and be automatically RESTOREd by GPMDOC when
        !          1142: the input is complete.
        !          1143:  Such keyword arguments are only significant on an INPUT TSET,
        !          1144: they are ignored on INPUT SETs.
        !          1145: {Ls 1}A null "str" is termed a 'pseudo-read.'
        !          1146:  It signifies that input should continue from the current file.
        !          1147:  This is useful for forms which use the keyword arguments
        !          1148: to create a 'nested context'.
        !          1149: {macsec notes}
        !          1150: (INPUT is somewhat implementation dependent, these notes
        !          1151: describe the VAX/VMS version.)
        !          1152: {BL}INPUT TSETs can only be nested to a system-imposed limit
        !          1153: (between 10 and 20).
        !          1154:  Pseudo-reads do not count toward that limit.
        !          1155:  INPUT SETs simply cause the current file to be closed, and
        !          1156: the designated one to be opened.
        !          1157:  There is thus no limit to the number of times this can be done.
        !          1158: {LI}The STARTTEXT and ENDTEXT macros are useful in conjunction
        !          1159: with INPUT TSETs.  Either or both can be specified as keyword
        !          1160: arguments to the INPUT set to cause the input to begin or end
        !          1161: at predetermined points in the file.
        !          1162:  The INFORMAT system macro flag is also useful in the same
        !          1163: way to cause a section of a document to be printed {ul literally}.
        !          1164: {LI}"Str" should be a standard device/file specification. If
        !          1165: your specification includes commas it must be in quotes ("<<>>") to
        !          1166: avoid an incorrect argument scan.
        !          1167: {LI}When GPMDOC is first started, it issues several INPUT sets
        !          1168: automatically.
        !          1169:  First is input for the auxilliary built-in
        !          1170: function definitions contained in a file called GPMBIF.GPM
        !          1171: on a system account.
        !          1172:  It then attempts to read a file called
        !          1173: GPMSTART on your account.
        !          1174:  (If this file doesn't exist, no error is reported.)
        !          1175:  GPMDOC finally evaluates the command line and exits.
        !          1176: If the command line is empty, then INPUT is automatically
        !          1177: TSET to your terminal (the message "READY" is printed to
        !          1178: inform you of this condition).
        !          1179:  A control-Z signals an end-of-file from the terminal, and
        !          1180: can thus be used to exit GPMDOC when in this mode.
        !          1181:  The initial commands you specify, either in the command line
        !          1182: or from your terminal can SET or TSET INPUT for the files
        !          1183: you want to process.
        !          1184: {Ls 1}You may want to put frequently used
        !          1185: "private" macros in your GPMSTART file.
        !          1186: {LI}INPUT TSETs can be useful in breaking up large documents.
        !          1187:  Each part of a document can be put in a separate file.
        !          1188:  These files can then be edited and
        !          1189: run off individually.
        !          1190:  To run off all of them, construct another
        !          1191: file which issues INPUT TSETs to each of the individual files in turn.
        !          1192:  This "master file" might also contain, or read in, the definitions
        !          1193: of any macros that are referenced frequently in the document files.
        !          1194: {Li}A SET on INPUT does not have any effect until the next line is
        !          1195: read in,
        !          1196: that is, not until the current line of input has been processed.
        !          1197:  An INPUT TSET can be issued at any point and has immediate effect.
        !          1198: The remainder of the line (if any) where the TSET occurred will be
        !          1199: processed when input is restored.
        !          1200: {EL}
        !          1201: {MACSEC EXAMPLES}
        !          1202: {BL}Start GPMDOC and read and process the text in WHITEPAP.GPM.
        !          1203:  As no output file is specified, output will be directed at
        !          1204: the standard output stream.
        !          1205:  GPMDOC will exit when the file has been processed.
        !          1206: {LS 1}
        !          1207: {CENTER <GPMDOC6 {SET INPUT,WHITEPAP.GPM}>}
        !          1208: {Ls 1}This shows method of specifying a command line to GPMDOC.
        !          1209: {LI}This macro reference will read and process the text in the
        !          1210: file [1,40]HELP.GPM.
        !          1211:  When the end-of-file is reached, input will be resumed
        !          1212: from the point in the file which issued this TSET.
        !          1213: {LS 1}{CENTER <{TSET INPUT,<[1,40]HELP.GPM>}>}{LS 1}
        !          1214: Note the use of the angle brackets to shield the comma in the
        !          1215: directory string "[1,40]".
        !          1216: {LI}Read and process text from the user's terminal until
        !          1217: an end-of-file (control Z) is entered.
        !          1218: {LS 1}
        !          1219: {CENTER <{TSET INPUT,TT:}>}
        !          1220: {LI}Define a macro that will read and process text from the
        !          1221: user's terminal until *EOF is typed in:
        !          1222: {Ls 1}{CENTER <{SETQ REOF,{TSET INPUT,TT:,ENDTEXT=*EOF}}>}
        !          1223: {LS 1}
        !          1224: {LI}Insert a "boiler-plate" paragraph from a file that the
        !          1225: user specifies when the document is run off:
        !          1226: {Ls 1}{CENTER <{TSET INPUT,BOILER{QUERY WHICH PARAGRAPH?}.GPM}>}
        !          1227: {LS 1}
        !          1228: Note:  This example assumes that the boiler-plate paragraphs
        !          1229: all have the form BOILERXXX.GPM; all the user need do in this
        !          1230: case is enter which XXX is desired.
        !          1231: {LI}Print a form letter using an address from a file of
        !          1232: addresses, "ADDR.GPM".
        !          1233:  This file is assumed to have the form:
        !          1234: {Ls 1}{Nfj}
        !          1235:    !**PAULS PIZZA
        !          1236:    PAUL'S PIZZA EMPORIUM
        !          1237:    140 SAN PEPPERONI DR.
        !          1238:    AUSTIN, TEXAS
        !          1239:    !**
        !          1240:    !**TERRYS TOYS
        !          1241:    TERRY'S TOY SHOP
        !          1242:    #1 NORTH POLE
        !          1243:    ARTIC CIRCLE
        !          1244:    !**
        !          1245:       :
        !          1246:       :
        !          1247: {Ls 1}{Fj}
        !          1248: The user will specify which address to use when the letter is run.
        !          1249: {Ls 1}{Nfj}
        !          1250:    !
        !          1251:    !Print the Sender's Address
        !          1252:    !
        !          1253:    <{LIN 40}>
        !          1254:    Acme Collection Agency
        !          1255:    Hardline Ave.
        !          1256:    Cleveland, Ohio
        !          1257:    <{RESTORE LMG}>
        !          1258:    !
        !          1259:    !Now Print the Address
        !          1260:    !
        !          1261:    <{TSET INPUT,->
        !          1262:    <  ADDR.GPM,STARTTEXT=!**{Query Recipient?},ENDTEXT=!**}>
        !          1263:    !
        !          1264:    !Do the Body
        !          1265:    !
        !          1266:    Dear person:<{Brk}{Fj}>a check of our records
        !          1267:       :
        !          1268:       :
        !          1269: {Ls 1}{Fj}
        !          1270: {LI}Fortran programs contain characters that could cause
        !          1271: them to be erroneously processed (e.g. a minus sign at
        !          1272: the end of a line). This example shows how to insert the
        !          1273: text of such a program in a document using a literal read.
        !          1274: {Ls 1}{Center <{TSET INPUT,PROGRAM.FOR,INFORMAT=1,FILL=1,JUST=1}>}
        !          1275: {Ls 1}
        !          1276: {Li}This example shows how to print a section of a document exactly
        !          1277: as it appears using a pseudo-read.
        !          1278: {Ls 1}{Nfj}
        !          1279:    :
        !          1280:    :
        !          1281: <!> Ordinary text
        !          1282:    :
        !          1283: <{TSET INPUT,,INFORMAT=1,FILL=1,JUST=1,Endtext=!**}>
        !          1284:    :
        !          1285: <!> Text to be printed as it appears
        !          1286:    :
        !          1287: !**
        !          1288:    :
        !          1289: <!> Continue with ordinary text
        !          1290:    :
        !          1291:    :
        !          1292: {Ls 1}{Fj}
        !          1293: Note that here ENDTEXT is used to designate a marker ("!**") that will cause
        !          1294: the pseudo-read to terminate and thus end literal input.
        !          1295: Reading then continues on in the ordinary way after the **.
        !          1296: {Li *~}Set up a file to print the first three chapters of the document
        !          1297: SHIPLOG. Each chapter is in a separate file.
        !          1298: {Nfj}{Ls 1}
        !          1299:     <{TSET INPUT,SHIPLOG1.GPM}>
        !          1300:     <{TSET INPUT,SHIPLOG2.GPM}>
        !          1301:     <{TSET INPUT,SHIPLOG3.GPM}>
        !          1302:               or
        !          1303:     <{DOWHILE {LT @LOG#,3},{SET.ADD1 LOG#}->
        !          1304:        <{TSET INPUT,SHIPLOG{LOG#}.GPM}}>
        !          1305: {Fj}
        !          1306: {El}
        !          1307: {P}
        !          1308: !
        !          1309: ! JUST
        !          1310: !
        !          1311: {Macdescr JUST,Right Justification Flag}
        !          1312: <{set JUST,pred}> (Default: JUST=null)
        !          1313: <{JUST}>
        !          1314: <{D JUST}>
        !          1315: {Macsec description}
        !          1316: JUST is the GPMDOC right justification flag.
        !          1317:  If true (null) then all lines that are broken off the output stream
        !          1318: for printing have spaces inserted in them to cause the rightmost
        !          1319: character to line up with the right margin.
        !          1320:  This action will only be applied if the line is broken off as a
        !          1321: consequence of the output stream accumulating as much or more text than will
        !          1322: fit on a single output line.
        !          1323:  Lines printed as a consequence of line breaks are never justified.
        !          1324: {Macsec Notes}
        !          1325: {bl}FJ and NFJ are normally used to manipulate FILL and JUST together.
        !          1326:  Under normal circumstances, FILL should be enabled when JUST is enabled.
        !          1327: {Li}Spaces are inserted only at points in the line where spaces already
        !          1328: exist.
        !          1329:  Spaces in the line are never removed.
        !          1330:  The spaces are distributed throughout the lines in such a way as
        !          1331: to reduce the possibility of white 'rivers' or 'lakes' running down the
        !          1332: page.
        !          1333: {el}
        !          1334: {p}
        !          1335: !
        !          1336: ! LE
        !          1337: !
        !          1338: {Macdescr LE,Predicate for Less Than or Equal}
        !          1339: <{LE n1,n2}>
        !          1340: {Macsec Description}
        !          1341: LE evaluates to null (true) if "n1" is less than or equal to "n2",
        !          1342: otherwise it evaluates to "1" (false).
        !          1343: {Macsec Examples}
        !          1344: See COND for uses of system predicate macros.
        !          1345: {P}
        !          1346: !
        !          1347: ! LEQ
        !          1348: !
        !          1349: {Macdescr LEQ,Predicate for Lexical Equality}
        !          1350: <{LEQ str1,str2}>
        !          1351: {Macsec Description}
        !          1352: LEQ evaluates to null (true) if "str1" is equal to "str2"
        !          1353: in terms of alphanumeric (lexical) value.
        !          1354:  This means that the two strings must be identical in all respects,
        !          1355: including case.
        !          1356:  Otherwise it evaluates to "1" (false).
        !          1357: {Macsec Examples}
        !          1358: {Bl}If the user responds "No" then skip input up to the next line
        !          1359: of the form "!**":
        !          1360: {Ls 1}{Center <{COND {LEQ NO,{CAPS {QUERY CONTINUE?}}},{SKIPTEXT !**}}>}
        !          1361: {Ls 1}
        !          1362: Note the use of "CAPS" to insure that regardless of the case
        !          1363: of the user's response,
        !          1364: the comparison will be true if the response was "no".
        !          1365: {El}
        !          1366: {Ls 1}
        !          1367: See COND for other uses of system predicate macros.
        !          1368: {P}
        !          1369: !
        !          1370: ! LGE
        !          1371: !
        !          1372: {Macdescr LGE,Predicate for Lexical Greater or Equal}
        !          1373: <{LGE str1,str2}>
        !          1374: {Macsec Description}
        !          1375: LGE evaluates to null (true) if "str1" is greater than or equal to "str2"
        !          1376: in terms of alphanumeric (lexical) value.
        !          1377:  Otherwise it evaluates to "1" (false).
        !          1378: {Macsec Examples}
        !          1379: See COND for uses of system predicate macros.
        !          1380: {P}
        !          1381: !
        !          1382: ! LGT
        !          1383: !
        !          1384: {Macdescr LGT,Predicate for Lexical Greater Than}
        !          1385: <{LGT str1,str2}>
        !          1386: {Macsec Description}
        !          1387: LGT evaluates to null (true) if "str1" is greater than "str2"
        !          1388: in terms of alphanumeric (lexical) value.
        !          1389:  Otherwise it evaluates to "1" (false).
        !          1390: {Macsec Examples}
        !          1391: See COND for uses of system predicate macros.
        !          1392: {P}
        !          1393: !
        !          1394: ! LIN
        !          1395: !
        !          1396: {Macdescr LIN,Indent the left margin}
        !          1397: <{LIN n}>
        !          1398: {Macsec Description}
        !          1399: <{LIN n}> is equivalent to <{TSET.+ LMG,n}>.
        !          1400:  It indents the left margin an additional "n" places.
        !          1401: {Macsec Notes}
        !          1402: {bl}"n" can be negative to outdent the left margin
        !          1403: {li}Keep in mind that LIN does a TSET.
        !          1404:  The left margin prior to the LIN operation is saved on the LMG stack.
        !          1405:  A subsequent <{RESTORE LMG}> will reactivate it.
        !          1406: {li}There is a companion RIN macro to indent the right margin.
        !          1407: {EL}
        !          1408: {P}
        !          1409: !
        !          1410: ! LINELENGTH
        !          1411: !
        !          1412: {Macdescr LINELENGTH,Number of Print Positions on a Line}
        !          1413: <{set LINELENGTH,n}> (Default: LINELENGTH=66}
        !          1414: <{LINELENGTH}>
        !          1415: <{D LINELENGTH}>
        !          1416: {macsec description}
        !          1417: The value of LINELENGTH is the number of print columns between
        !          1418: the current left and right margins. Setting LINELENGTH has
        !          1419: the effect of altering the value of RMG (the right margin)
        !          1420: so as to force <{LINELENGTH}> to equal the requested value.
        !          1421: {macsec notes}
        !          1422: {BL}n must be positive and non-zero.
        !          1423: {el}
        !          1424: {macsec examples}
        !          1425: {BL}Set the page to have 40 print columns
        !          1426: {ls 1}
        !          1427: {CENTER <{SET LINELENGTH,40}>}
        !          1428: {LI}If there are less than ten columns on the line, then
        !          1429: set LINELENGTH to 10.
        !          1430: {ls 1}
        !          1431: {CENTER <{COND {LT @LINELENGTH,10},{SET LINELENGTH,10}}>}
        !          1432: {EL}
        !          1433: {P}
        !          1434: !
        !          1435: ! LINENUM
        !          1436: !
        !          1437: {MACDESCR LINENUM,Current Line on Page}
        !          1438: <{set LINENUM,n}>
        !          1439: <{LINENUM}>
        !          1440: <{D LINENUM}>
        !          1441: {macsec description}
        !          1442: LINENUM always has the number of the next line to be
        !          1443: printed on the page. It is set to one by the system
        !          1444: at the conclusion of processing a NEWPAGE condition.
        !          1445: Thus lines are numbered consecutively starting at one
        !          1446: with the first line on the page.
        !          1447:  LINENUM can also be set.
        !          1448:  This forces a line break, and lines to be skipped until
        !          1449: the next print line will be at the value specified in the SET.
        !          1450: This is termed "vertical tabulation".
        !          1451: {macsec notes}
        !          1452: {BL}The value for n must be between 1 and <{PAGELENGTH}>.
        !          1453: {LI}You can use <{SET~LINENUM,1}> to force printing to begin
        !          1454: on a new page. This is different from <{LS~10000}> in that
        !          1455: the LS form can cause a blank page to appear if printing
        !          1456: is already positioned at the top of a page.
        !          1457:  The <{SET~LINENUM,1}>
        !          1458: form will cause nothing to happen if the current print line is
        !          1459: already n.
        !          1460:  <{SET~LINENUM,1}> should normally be used to begin a page.
        !          1461: {LI}If the printing has already gone past line n
        !          1462: on a <{SET~LINENUM,n}>,
        !          1463: a new page is forced before skipping occurs.
        !          1464: {EL}
        !          1465: {macsec examples}
        !          1466: {BL}Print text centered on line 40.
        !          1467: {ls 1}
        !          1468: {nfj}
        !          1469:    <{SET LINENUM,40}{CENTER REPORT SUBMITTED BY:}{BRK}>
        !          1470: {FJ}
        !          1471: {LI}Skip to a new page if more than ten lines have
        !          1472: been already printed.
        !          1473: {LS 1}
        !          1474: {Center <{COND {GT @LINENUM,10},{LS 10000}}>}
        !          1475: {EL}
        !          1476: {P}
        !          1477: !
        !          1478: ! LITERAL
        !          1479: !
        !          1480: {Macdescr LITERAL,Process Text Literally}
        !          1481: <{Literal str}>
        !          1482: {Macsec Description}
        !          1483: LITERAL causes subsequent text lines to be processed exactly as they
        !          1484: appear in the input file.
        !          1485:  Macros are not evaluated, comment lines are passed, and line fill and
        !          1486: justification are disabled.
        !          1487: {Ls 1}A line identical to 'str' causes termination of the LITERAL,
        !          1488: and a resumption of the previous processing state.
        !          1489:  If str is omitted, it is assumed to be "!**".
        !          1490: {Ls 1}LITERAL is defined to be:
        !          1491: {Ls 1}~~~~~<{BRK}{TSET INPUT,,INFORMAT={COND {LEQ @1},!**,,@1},->
        !          1492: {Brk }~~~~~<~~~~~INFORMAT=1,JUST=1,FILL=1}>
        !          1493: {Ls 1}
        !          1494: !
        !          1495: ! LLE
        !          1496: !
        !          1497: {Macdescr LLE,Predicate for Lexical Less Than or Equal}
        !          1498: <{LLE str1,str2}>
        !          1499: {Macsec Description}
        !          1500: LLE evaluates to null (true) if "str1" is less than or equal to "str2"
        !          1501: in terms of alphanumeric (lexical) value.
        !          1502:  Otherwise it evaluates to "1" (false).
        !          1503: {Macsec Examples}
        !          1504: See COND for uses of system predicate macros.
        !          1505: {P}
        !          1506: !
        !          1507: ! LLT
        !          1508: !
        !          1509: {Macdescr LLT,Predicate Comparison for Lexical Less Than}
        !          1510: <{LLT str1,str2}>
        !          1511: {Macsec Description}
        !          1512: LLT evaluates to null (true) if "str1" is less than "str2"
        !          1513: in terms of alphanumeric (lexical) value.
        !          1514:  Otherwise it evaluates to "1" (false).
        !          1515: {Macsec Examples}
        !          1516: See COND for uses of system predicate macros.
        !          1517: {P}
        !          1518: !
        !          1519: ! LMG
        !          1520: !
        !          1521: {macdescr LMG,Left Margin}
        !          1522: <{set LMG,n}> (Default: LMG=10)
        !          1523: <{LMG}>
        !          1524: <{D LMG}>
        !          1525: {MACSEC DESCRIPTION}
        !          1526: The value of LMG tells GPMDOC how far to space out each print
        !          1527: line from the left BIAS.
        !          1528:  LMG must always be less than or equal to the right margin (RMG).
        !          1529:  In addition, the sum of LMG and BIAS must always be a positive value.
        !          1530: {macsec notes}
        !          1531: {Bl}The value of LMG is only used by GPMDOC when it is ready to
        !          1532: print a new line. So if you change LMG several times in a line,
        !          1533: only the final change will have effect.
        !          1534: {LI}LMG is used prior to evaluating NEWLINE, so if NEWLINE
        !          1535: changes LMG, that change will affect the next print line.
        !          1536: {EL}
        !          1537: {macsec examples}
        !          1538: {BL}Set the left margin to 20:
        !          1539: {ls 1}{nfj}
        !          1540:           <{SET LMG,20}>
        !          1541: {Fj}{Ls 1}
        !          1542: {Li}Set the left margin to 20 to the left of the right
        !          1543: margin:
        !          1544: {Ls 1}{Nfj}
        !          1545:      <{SET LMG,{- @RMG,20}}}>
        !          1546: {Fj}{Ls 1}
        !          1547: Note that <{LINELENGTH}> will now equal 21, not 20 because
        !          1548: both <{LMG}> and <{RMG}> are printing columns.
        !          1549: {El}
        !          1550: {P}
        !          1551: !
        !          1552: ! LNE
        !          1553: !
        !          1554: {Macdescr LNE,Predicate Comparison for Lexical Not Equal}
        !          1555: <{LNE str1,str2}>
        !          1556: {Macsec Description}
        !          1557: LNE evaluates to null (true) if "str1" is not equal to "str2"
        !          1558: in terms of alphanumeric (lexical) value.
        !          1559:  Otherwise it evaluates to "1" (false).
        !          1560: {Macsec Examples}
        !          1561: See COND for uses of system predicate macros.
        !          1562: {P}
        !          1563: !
        !          1564: ! LOAD
        !          1565: !
        !          1566: {Macdescr LOAD,Load from Library}
        !          1567: <{LOAD str1,str2}>
        !          1568: {Macsec Description}
        !          1569: Load reads from a user 'macro library'.
        !          1570:  "Str1" is taken as the filename of the library.
        !          1571:  "Str2" is the name of the 'module' to be loaded.
        !          1572:  If "str2" is null, then the entire library is processed.
        !          1573: {Macsec Notes}
        !          1574: {Bl}The "SYSLOAD" macro can be used when loading from the
        !          1575: standard system library.
        !          1576: {Li}Normally, library modules should set macro definitions,
        !          1577: and not produce any text on their own.
        !          1578: {Li}The library must be in a particular form in order for
        !          1579: LOAD to work correctly.
        !          1580:  Each module must be preceeded by a single line containing
        !          1581: an exclamation mark in column one,
        !          1582: and the module name starting in column two of the line.
        !          1583:  The remainder of the line must be empty.
        !          1584: {Ls 1}The end of the module must be a single line of the form "!**"
        !          1585: {Ls 1}LOAD is thus defined as:
        !          1586: {Ls 1}{Nfj}
        !          1587: <{COND {LEQ @2},{TSET INPUT,@1},->
        !          1588:   <{TSET INPUT,@1,STARTTEXT=!{1},ENDTEXT=!**}}>
        !          1589: {El}
        !          1590: {P}
        !          1591: !
        !          1592: ! LPAD
        !          1593: !
        !          1594: {macdescr LPAD,Pad a String on the Left}
        !          1595: <{LPAD str1,n,str2}>
        !          1596: {macsec description}
        !          1597: The value of LPAD is str1 prefixed with
        !          1598: replications of str2 to produce a result of length n.
        !          1599:  If str1 is already as long or longer than n, the value of LPAD is str1.
        !          1600:  The value of LPAD is also str1 if n is zero or negative.
        !          1601:  If str2 must be replicated a non-integral number of times, the
        !          1602: last replication will be truncated to the appropriate length.
        !          1603:  If str2 is null, then the present hardspace character is used.
        !          1604: {macsec notes}
        !          1605: {BL}LPAD, along with RPAD, is useful for producing
        !          1606: tabular text.
        !          1607: {EL}
        !          1608: {macsec examples}
        !          1609: {BL}Print a line consisting of "PAGE:" and the current
        !          1610: page number at the right margin:
        !          1611: {Ls 1}{Center <{LPAD PAGE:{PAGENUM},@LINELENGTH}{BRK}>}
        !          1612: {Ls 1}
        !          1613: The LPAD causes the first argument string (e.g. "PAGE:32") to
        !          1614: be prefixed with hard spaces until it is as long as one
        !          1615: print line (<{LINELENGTH}>). It will thus appear flush with the
        !          1616: right margin.
        !          1617: {Li}Print the number in macro LISTNUM, left padded with zeros
        !          1618: to 6 digits.
        !          1619: {Ls 1}{Center <{LPAD @LISTNUM,6,0}>}
        !          1620: {Ls 1}
        !          1621: With this macro, if <{LISTNUM}> were defined as "63",
        !          1622: the LPAD would return "000063".
        !          1623: {El}
        !          1624: {P}
        !          1625: !
        !          1626: ! LS
        !          1627: !
        !          1628: {macdescr LS,Line Spacing}
        !          1629: <{LS n}>
        !          1630: {macsec description}
        !          1631: The LS macro causes a line break and n blank lines to be
        !          1632: inserted on the page. This spacing will terminate if
        !          1633: it causes an ENDPAGE to occur, regardless of the value of n.
        !          1634:  The value of LS is null.
        !          1635: {macsec notes}
        !          1636: {bl}N may not be negative.
        !          1637: {LI}LS is subject to the effect induced by the value of
        !          1638: BSLACK.
        !          1639: {LI}<{LS~0}> is equivalent to <{BRK}>, a line break.  No blank
        !          1640: lines will be printed.  Note that <{LS}> is the same
        !          1641: as <{LS~0}>, as the implied null argument in the former
        !          1642: will be interpreted as a numeric zero.
        !          1643: {LI}LINENUM is also useful for skipping lines, read the
        !          1644: description of the LINENUM macro, and particularly the
        !          1645: <{SET~LINENUM,n}> form.
        !          1646: {EL}
        !          1647: {macsec examples}
        !          1648: {BL}Skip 10 lines to leave room for a drawing:
        !          1649: {Ls 1}{Center <{LS 10}>}
        !          1650: {Ls 1}
        !          1651: {LI}The example above isn't really very good, since skipping
        !          1652: always stops at the end of a page. If the page is already
        !          1653: almost full, the <{LS 10}> won't leave enough room. One way to solve
        !          1654: this problem would be to run the page out and put the 10 lines
        !          1655: at the top of the next page if less than 10 lines remain. This
        !          1656: can be done with:
        !          1657: {Ls 1}{Center <{COND {GT @LINENUM,{- @PAGELENGTH,10}},{LS 10000}}{LS 10}>}
        !          1658: {Ls 1}
        !          1659: The <{LS 10000}> will most certainly cause the page to run
        !          1660: out (unless you have a {ul very} long page!), but notice
        !          1661: that it will only occur if the value of LINENUM is past
        !          1662: <{PAGELENGTH}> minus 10.
        !          1663:  The LS 10 does the skipping.
        !          1664: {Li *~}The example just given may not seem all that satisfactory
        !          1665: to you either, since it leaves a rather big "white lake"
        !          1666: at the bottom of some of the pages for no seemingly good reason.
        !          1667: What we really want is to either skip the 10 lines if there is
        !          1668: room, or wait and skip the 10 lines when we start the next page.
        !          1669: This is fairly straightforward using NEWPAGE. As before, we
        !          1670: test LINENUM, and either skip the 10 lines, or if it has gone
        !          1671: too far, TSET the <{LS 10}> onto NEWPAGE.
        !          1672: {Ls 1}{Nfj}
        !          1673: <{COND {LE @LINENUM,{- @PAGELENGTH,10}},{LS 10},->
        !          1674:   <{TSET.APPEND NEWPAGE,<{LS 10}{RESTORE NEWPAGE}>}}>
        !          1675: {Ls 1}{Fj}
        !          1676: The flavor of this is similar to that used with OUTDENT,
        !          1677: in that the NEWPAGE "self-destructs" the <{LS 10}>
        !          1678: once it has been carried out, by doing a RESTORE on itself.
        !          1679: {Li}Here is a macro definition FIGURE for this, to which
        !          1680: you can give the number of lines as an argument:
        !          1681: {Ls 1}{Nfj}
        !          1682: <{SETQ FIGURE,->
        !          1683:   <{COND {LE @LINENUM,{- @PAGELENGTH,@1}},{LS @1},->
        !          1684:   <,{TSET.APPEND NEWPAGE,<{LS >{1}<}{RESTORE NEWPAGE}>}}->
        !          1685: <}>
        !          1686: {Ls 1}{Fj}
        !          1687: {EL}
        !          1688: {P}
        !          1689: !
        !          1690: ! LT
        !          1691: !
        !          1692: {Macdescr LT,Predicate Comparison for Less Than}
        !          1693: <{LT n1,n2}>
        !          1694: {Macsec Description}
        !          1695: LT evaluates to null (true) if "n1" is less than "n2",
        !          1696: otherwise it evaluates to "1" (false).
        !          1697: {Macsec Examples}
        !          1698: See COND for uses of system predicate macros.
        !          1699: {P}
        !          1700: !
        !          1701: ! NEWLINE
        !          1702: !
        !          1703: {macdescr NEWLINE,Define Event For Each New Line}
        !          1704: <{set NEWLINE,str}>
        !          1705: <{NEWLINE}>
        !          1706: <{D NEWLINE}>
        !          1707: {macsec description}
        !          1708: NEWLINE is an evaluated automatically
        !          1709: by GPMDOC each time it is ready to print a new line.
        !          1710:  Any value produced by referencing NEWLINE is discarded.
        !          1711: {macsec notes}
        !          1712: {BL}The <{NEWLINE}> form is not normally used. The system does
        !          1713: this automatically on each newline.
        !          1714: {LI}GPMDOC makes no adjustment to the margins as a result of
        !          1715: any characters affixed to the line as a result of NEWLINE's
        !          1716: evaluation.
        !          1717: {LI}The OUTSTREAM macro can be useful in NEWLINE to alter the
        !          1718: line to be printed.
        !          1719: {LI}The GPMDOC uses NEWLINE for the operation of some of
        !          1720: its macros (e.g. OUTDENT). It is thus not
        !          1721: normally advisable to set NEWLINE directly, since it may
        !          1722: already contain text (your's or GPMDOC's).
        !          1723:  A
        !          1724: {Ls 1}{Center <{SET.APPEND~NEWLINE,text}>}
        !          1725: {Center or}
        !          1726: {Center <{TSET.APPEND~NEWLINE,text}>}
        !          1727: {Ls 1}
        !          1728: which affixes your text to any existing text in NEWLINE is
        !          1729: preferred.
        !          1730: {EL}
        !          1731: {macsec examples}
        !          1732: (Also see OUTSTREAM macro description).
        !          1733: {BL *~}OUTDENT the next line five spaces:
        !          1734: {Ls 1}{Nfj}
        !          1735: <{TSET.- LMG,5}->
        !          1736:   <{TSET.APPEND NEWLINE,<{RESTORE LMG,NEWLINE}}>>
        !          1737: {Ls 1}{Fj}
        !          1738: This operation proceeds by first temporarily setting (TSET)
        !          1739: the left margin out 5 spaces. Then the text
        !          1740: <{RESTORE~LMG,NEWLINE}> is tacked onto the end of
        !          1741: any existing NEWLINE text and temporarily set back into
        !          1742: NEWLINE (TSET.APPEND).
        !          1743:  Thus when the next line is printed
        !          1744: the following actions occur:
        !          1745: {BL}The left margin spacing is computed based on the new
        !          1746: value which is the old value minus 5.
        !          1747: {LI}NEWLINE is evaluated automatically by GPMDOC and this causes
        !          1748: the old left margin to be restored (for succeeding lines),
        !          1749: NEWLINE then restores its own old value so that the text
        !          1750: appended onto it for the outdent effectively "self-destructs".
        !          1751: {LS 1}
        !          1752: {EL}
        !          1753: This is the definition for the system OUTDENT macro.
        !          1754: {el}
        !          1755: {P}
        !          1756: !
        !          1757: ! NEWPAGE
        !          1758: !
        !          1759: {MACDESCR NEWPAGE,Define Event For Starting a New Page}
        !          1760: <{set NEWPAGE,str}> (Default: NEWPAGE=<{LS 1}->
        !          1761:                      <{COND {GT @PAGENUM,1},->
        !          1762:                      <{LPAD PAGE {PAGENUM},@LINELENGTH}}->
        !          1763:                      <{LS 2}>
        !          1764: <{NEWPAGE}>
        !          1765: <{D NEWPAGE}>
        !          1766: {macsec description}
        !          1767: The first line to be printed after an ENDPAGE condition has
        !          1768: occurred causes a NEWPAGE event.
        !          1769:  Before the line is actually printed, the following actions take place:
        !          1770: {BL}The line to be printed and any other assembled output text
        !          1771: are put aside.
        !          1772: {LI}NEWLINE is TSET to null, SPACING is TSET to one (single
        !          1773: spacing). LMG is TSET to 10. RMG is TSET to 75.
        !          1774: {LI}The value of LINENUM becomes one.
        !          1775: {LI}"<{NEWPAGE}>" is given to the evaluator for printing.
        !          1776: {LI}NEWLINE, SPACING, LMG and RMG are restored, which completes
        !          1777: the NEWPAGE event.
        !          1778: {EL}
        !          1779: {MACSEC NOTES}
        !          1780: {BL}A NEWPAGE event happens on the first line of a
        !          1781: document, even though no preceeding ENDPAGE has occurred.
        !          1782: {LI}If NEWLINE, SPACING, LMG or RMG are changed in NEWPAGE,
        !          1783: changes will only have effect during the NEWPAGE condition, as
        !          1784: they are TSET and RESTOREd.
        !          1785:  If you desire a permanent effect,
        !          1786: the NEWPAGE can RESTORE and re-TSET new values
        !          1787: that will then be the values ultimately RESTORED at the conclusion
        !          1788: of the NEWPAGE condition.
        !          1789: {li}NEWPAGE and ENDPAGE conditions are inhibited while
        !          1790: the NEWPAGE condition is being processed.
        !          1791: {EL}
        !          1792: {MACSEC EXAMPLES}
        !          1793: {BL}At the top of every page, print two blank lines, the
        !          1794: centered text of the user-defined macro TITLE, the page
        !          1795: number then two more blank lines:
        !          1796: {LS 1}{nfj}
        !          1797: <{SETQ NEWPAGE,->
        !          1798:   <{LS 2}{CENTER @TITLE}{T 60}PAGE:{PAGENUM}{LS 2}}>
        !          1799: {FJ}
        !          1800: {EL}
        !          1801: {P}
        !          1802: !
        !          1803: ! NFJ
        !          1804: !
        !          1805: {macdescr NFJ,No Fill or Justify}
        !          1806: <{NFJ}>
        !          1807: {macsec description}
        !          1808: <{D NFJ}> is the string; <"{SET~FILL,FALSE}{SET~JUST,FALSE}">.
        !          1809: It disables both line fill and right justification.
        !          1810:  The value of NFJ is null.
        !          1811: {P}
        !          1812: !
        !          1813: ! OAB
        !          1814: !
        !          1815: {MACDESCR OAB,Open Angle Bracket}
        !          1816: <{OAB}>
        !          1817: {MACSEC DESCRIPTION}
        !          1818: Evaluates to "<".
        !          1819: {MACSEC NOTES}
        !          1820: {BL}This macro, and its companion <{CAB}>, are used in situations
        !          1821: where the quote symbols are needed without causing the effect
        !          1822: of quoting, or where they appear in an unbalanced way.
        !          1823: {EL}
        !          1824: {MACSEC EXAMPLES}
        !          1825: See the examples for CAB.
        !          1826: {P}
        !          1827: !
        !          1828: ! ODD
        !          1829: !
        !          1830: {Macdescr ODD,Predicate Test for Numeric Odd}
        !          1831: <{ODD n}>
        !          1832: {Macsec Description}
        !          1833: ODD evaluates to null (true) if "n" is an odd integer,
        !          1834: otherwise it evaluates to "1" (false).
        !          1835: {Macsec Examples}
        !          1836: See the description of COND for examples of the use of predicates.
        !          1837: {P}
        !          1838: !
        !          1839: ! OS
        !          1840: !
        !          1841: {macdescr OS,Overstrike Two Strings}
        !          1842: <{OS str1,str2}>
        !          1843: {macsec description}
        !          1844: OS returns a string which, when printed, will have str1
        !          1845: overprinted with str2.
        !          1846:  If the two strings are not of the same length,
        !          1847: the shorter is padded on the right with blanks
        !          1848: before the overstrikes are computed.
        !          1849: {macsec notes}
        !          1850: {BL}Overstrikes are computed internally with a special
        !          1851: backspace character that cannot be entered from the keyboard.
        !          1852: Thus overstruck strings can be freely passed about, and joined
        !          1853: with other strings.
        !          1854:  The SIZE macro correctly computes the actual
        !          1855: number of print positions of a string, compensating for the
        !          1856: extra length caused by the presence of the backspaces.
        !          1857:  For output, GPMDOC decomposes the print line containing the
        !          1858: backspaces into a series of non-overstruck lines that it
        !          1859: prints on top of each other.
        !          1860: {LI}Overstrikes may themselves be overstruck (to any
        !          1861: reasonable degree).
        !          1862:  Note however, that use of overstriking
        !          1863: slows down both the processing and actual printing of such text.
        !          1864: {EL}
        !          1865: {macsec examples}
        !          1866: {BL}Overstrike pairs of characters to get interesting new
        !          1867: characters from the ordinary ol' line printer:
        !          1868: {ls 1}
        !          1869: {nfj}
        !          1870: {TSETQ OSC,<{OS >{D 1}<,>{D 2}<}  --  >{OS {1},{2}}<     >({3}){BRK}}
        !          1871: {OSC c,|,cent sign}
        !          1872: {OSC -,|,dagger}
        !          1873: {OSC |,=,double dagger}
        !          1874: {OSC /,=,not equals}
        !          1875: {OSC O,-,theta}
        !          1876: {OSC 0,/,computer zero}
        !          1877: {OSC {oab},-,arrow}
        !          1878: {OSC ),/,gamma}
        !          1879: {OSC ),\,lambda}
        !          1880: {OSC o,_,rising sun}
        !          1881: {OSC =,-,equivalence symbol}
        !          1882: {OSC \,/,X marks the spot}
        !          1883: {OSC <{OS \,/}>,<{OS |,-}>,attention grabber}
        !          1884: {RESTORE OSC}
        !          1885: {FJ}
        !          1886: {LI}Print the text "RIGHT NOW" with the "NOW" underlined:
        !          1887: {ls 1}{Center RIGHT <{OS NOW,___}>}
        !          1888: {Ls 1}{Fj}
        !          1889: {LI *~}Define a macro UNDER that will evaluate to an underlined version
        !          1890: of whatever text is given as an argument:
        !          1891: {ls 1}{Center <{SETQ UNDER,{OS @1,{DUPL _,{DSIZE 1}}}}>}
        !          1892: {ls 1}
        !          1893: This macro has a problem in that it will underscore blanks,
        !          1894: preventing them from being used as line breaks, or as
        !          1895: justification points.
        !          1896:  This problem can be solved by using
        !          1897: REPLACE and IMAGE, which is essentially what is done by the
        !          1898: system underlining macro UL.
        !          1899: {LI *~}Sometimes when revising a document, it is necessary to
        !          1900: show on the new version what changes have been made.
        !          1901:  "Change bars" in the left margin are usually
        !          1902: used to show new or changed lines.
        !          1903:  Deletions, however, pose a formidable problem.
        !          1904:  This example shows a way to use NEWLINE to
        !          1905: overstrike print lines with hyphens to indicate that they are
        !          1906: deleted without actually removing the text:
        !          1907: {ls 1}{nfj}
        !          1908: <{TSET.APPEND NEWLINE,->
        !          1909:   <<{SET OUTSTREAM,{OS @OUTSTREAM,{DUPL -,{DSIZE OUTSTREAM}}}}>}}>
        !          1910: {Ls 1}{Fj}
        !          1911: {EL}
        !          1912: {P}
        !          1913: !
        !          1914: ! OUTDENT
        !          1915: !
        !          1916: {Macdescr OUTDENT,Outdent a Line}
        !          1917: <{OUTDENT n}>
        !          1918: {Macsec Description}
        !          1919: OUTDENT will cause the left margin to be 'outdented' n spaces on the
        !          1920: next line printed.
        !          1921:  OUTDENT is defined as:
        !          1922: {Ls 1}{Center <{BRK}{TSET.- LMG,@1}{TSET.APPEND NEWLINE,->}
        !          1923: {Center <<{RESTORE LMG,NEWLINE}>}>}
        !          1924: {Ls 1}
        !          1925: {p}
        !          1926: !
        !          1927: ! OUTOS
        !          1928: !
        !          1929: {Macdescr OUTOS,Output Stream Overstrike Flag}
        !          1930: <{set OUTOS,pred}> (Default: OUTOS=null)
        !          1931: <{OUTOS}>
        !          1932: <{D OUTOS}>
        !          1933: {Macsec Description}
        !          1934: OUTOS is a flag which controls the formatting of overstrikes in the
        !          1935: output stream.
        !          1936:  When OUTOS is true (null), output files are accessed for writing
        !          1937: with carriage control properties that will properly display overstruck
        !          1938: text.
        !          1939:  Such files may be difficult to manipulate with other system utilities.
        !          1940:  If OUTOS is set false (non-null), only the primary images of output
        !          1941: lines will be printed (no overstrikes), and output files will be opened
        !          1942: with normal, sequential attributes.
        !          1943: {Macsec Notes}
        !          1944: {Bl}Changing OUTOS will only have effect
        !          1945: for output files opened subsequent to the change.
        !          1946: {el}
        !          1947: {p}
        !          1948: !
        !          1949: ! OUTPUT
        !          1950: !
        !          1951: {macdescr OUTPUT,Name of Output File}
        !          1952: <{set OUTPUT,str}> (Default: OUTPUT=user's terminal device)
        !          1953: <{OUTPUT}>
        !          1954: <{D OUTPUT}>
        !          1955: {Macsec Description}
        !          1956: The value you set to OUTPUT instructs GPMDOC as to the name of the
        !          1957: current file for print stream output text.
        !          1958:  Setting a value for OUTPUT causes the present output stream to
        !          1959: be closed out, and a new one whose name is given by "str" is
        !          1960: created and opened.
        !          1961: {Macsec Notes}
        !          1962: The nature of OUTPUT is necessarily somewhat system-dependent.
        !          1963:  These notes and examples pertain to the VAX/VMS version.
        !          1964: {Bl}"Str" should be a valid device/file specification, enclosed in
        !          1965: quote symbols if it contains any commas.
        !          1966: {Li}If TSET is used with OUTPUT, a later RESTORE will not
        !          1967: continue with the old file, but will open a new version of it.
        !          1968: {El}
        !          1969: {Macsec Examples}
        !          1970: {Bl}Set the output stream to the terminal:
        !          1971: {Ls 1}{Center <{SET OUTPUT,TT:}>}{Ls 1}
        !          1972: {Li}Shut off output entirely (direct it to the null device):
        !          1973: {Ls 1}{Center <{SET OUTPUT,NL:}>}{Ls 1}
        !          1974: {Li}Direct further output to FILE.LST~:
        !          1975: {Ls 1}{Center <{SET OUTPUT,FILE.LST}>}{Ls 1}
        !          1976: You should be aware that each time OUTPUT is set, a new stream is
        !          1977: created and opened.
        !          1978:  This means that if you set the output stream to the same file
        !          1979: repeatedly, GPMDOC will not keep appending to one file, but rather
        !          1980: create multiple copies of the same file with successively higher
        !          1981: version numbers.
        !          1982: {el}{p}
        !          1983: !
        !          1984: ! OUTSTREAM
        !          1985: !
        !          1986: {MACDESCR OUTSTREAM,The Current Output Stream}
        !          1987: <{set OUTSTREAM,str}> (Default: See Description)
        !          1988: <{OUTSTREAM}>
        !          1989: {macsec description}
        !          1990: The value of OUTSTREAM is the currently assembled output stream
        !          1991: (no evaluation is done).
        !          1992:  With a NEWLINE macro, the value of an OUTSTREAM reference is the
        !          1993: text of the line about to be printed, excluding the left margin bias.
        !          1994: {macsec notes}
        !          1995: {BL}Care should be exercised when performing a SET-type operation on
        !          1996: OUTSTREAM.
        !          1997:  This is especially true in a NEWLINE evaluation,
        !          1998: as the system will not 'recompensate' for margin or spacing
        !          1999: irregularities induced by changing the OUTSTREAM.
        !          2000: {EL}
        !          2001: {macsec examples}
        !          2002: {BL}Print every line with a "*" on the front.
        !          2003: {LS 1}{CENTER <{SET.PREPEND OUTSTREAM,*}>}
        !          2004: {LI *~}Temporarily change NEWLINE to cause every print line to be
        !          2005: underscored until NEWLINE is RESTORED.
        !          2006: {LS 1}{CENTER <{TSET.APPEND NEWLINE,<{SET.UL OUTSTREAM}>}>}
        !          2007: {EL}
        !          2008: {P}
        !          2009: !
        !          2010: ! P
        !          2011: !
        !          2012: {macdescr P,Skip to New Page}
        !          2013: <{P}>
        !          2014: <{D P}>
        !          2015: {macsec description}
        !          2016: P is defined as <{SET LINENUM,1}>, which will cause a new
        !          2017: page to be started unless printing is presently at the first
        !          2018: line of a page.
        !          2019: {macsec notes}
        !          2020: {BL}You should read the description of LINENUM for a complete
        !          2021: explanation of the effects of <{P}>.
        !          2022: {el}
        !          2023: {P}
        !          2024: !
        !          2025: ! PAGELENGTH
        !          2026: !
        !          2027: {Macdescr PAGELENGTH,Defined Length of Page}
        !          2028: <{set PAGELENGTH,n}> (Default: PAGELENGTH=55)
        !          2029: <{PAGELENGTH}>
        !          2030: <{D PAGELENGTH}>
        !          2031: {Macsec Description}
        !          2032: The value of PAGELENGTH is used by GPMDOC to determine when to signal
        !          2033: an ENDPAGE condition.
        !          2034:  When <{LINENUM}> exceeds <{PAGELENGTH}>, an ENDPAGE (see description)
        !          2035: condition is signalled.
        !          2036: {Macsec Notes}
        !          2037: {Bl}The value of "n" must be positive.
        !          2038: {Li}Paging is inhibited by GPMDOC during NEWPAGE/ENDPAGE conditions,
        !          2039: so even if the number of lines emitted by NEWPAGE is larger than
        !          2040: PAGELENGTH, no endlessly recursive paging is possible.
        !          2041: {Li}Assuming that ENDPAGE causes some sort of 'page eject,'
        !          2042: PAGELENGTH can be thought of as defining the number of lines on a
        !          2043: page.
        !          2044: {Li}Setting PAGELENGTH to a very large value will effectively inhibit
        !          2045: page conditions.
        !          2046: {el}
        !          2047: {p}
        !          2048: !
        !          2049: ! PAGENUM
        !          2050: !
        !          2051: {macdescr PAGENUM,Current Page Number}
        !          2052: <{set PAGENUM,n}> (Default: PAGENUM=1)
        !          2053: <{PAGENUM}>
        !          2054: <{D PAGENUM}>
        !          2055: {macsec description}
        !          2056: PAGENUM contains its last defined value, but updated
        !          2057: by one at the conclusion of each ENDPAGE condition.
        !          2058: {macsec notes}
        !          2059: {BL}N must be non-negative.
        !          2060: {li}Setting PAGENUM has no side-effects.
        !          2061: {el}
        !          2062: {macsec examples}
        !          2063: {bl}Print the page number at the top right-hand corner
        !          2064: of every succeeding page.
        !          2065: {LS 1}{CENTER <{SETQ NEWPAGE,{LPAD @PAGENUM,@LINELENGTH}}>}
        !          2066: {LI}Reset page numbering to one.
        !          2067: {ls 1}
        !          2068: {Center <{SET PAGENUM,1}>}
        !          2069: {el}
        !          2070: {p}
        !          2071: !
        !          2072: ! PARA
        !          2073: !
        !          2074: {macdescr PARA,Start a New Paragraph}
        !          2075: <{PARA}>
        !          2076: <{D PARA}>
        !          2077: {Macsec Description}
        !          2078: Referencing PARA will cause a line break, a single blank line and five
        !          2079: hard spaces to be sent to the output stream.
        !          2080:  This is what is normally used for a standard paragraph.
        !          2081: {Macsec Notes}
        !          2082: {bl}If you want to insure that {ul exactly} five spaces indent the
        !          2083: first line of the paragraph then the text of the paragraph should
        !          2084: appear immediately following the <{PARA}>.
        !          2085:  If you start the text on a new logical line, then GPMDOC will
        !          2086: (in fill mode) send a single space to the output stream between
        !          2087: the <{PARA}> and the text on the next line.
        !          2088:  This space is subject to justification and could cause thus cause
        !          2089: uneven spacing of paragraph indents.
        !          2090: {el}
        !          2091: {p}
        !          2092: !
        !          2093: ! PREPEND
        !          2094: !
        !          2095: {macdescr PREPEND,Prefix onto a String}
        !          2096: <{PREPEND str1,str2}>
        !          2097: {Macsec Description}
        !          2098: The value of PREPEND is str2 prefixed onto str1.
        !          2099:  PREPEND is the complementary macro to APPEND.
        !          2100: {macsec notes}
        !          2101: {Bl}The PREPEND operation is generally only useful in extended sets.
        !          2102: {el}
        !          2103: {macsec examples}
        !          2104: {bl}Print two extra lines at the bottom of every page,
        !          2105: before the page footing:
        !          2106: {Ls 1}{Center <{SET.PREPEND ENDPAGE,<{LS 2}>}>}{Ls 1}
        !          2107: {el}
        !          2108: {p}
        !          2109: !
        !          2110: ! QUERY
        !          2111: !
        !          2112: {macdescr QUERY,Get Text From The Terminal}
        !          2113: <{QUERY str}>
        !          2114: {macsec description}
        !          2115: The value of QUERY is whatever text is typed in at the terminal
        !          2116: in response to str, which is displayed first.
        !          2117: {macsec notes}
        !          2118: {BL}The response typed in is not evaluated by GPMDOC.
        !          2119: {EL}
        !          2120: {macsec examples}
        !          2121: {BL}Print text containing a response that is typed in.
        !          2122: {LS 1}
        !          2123: {nfj}
        !          2124: {CENTER <We will ship to {QUERY Country? }>}
        !          2125: {fj}
        !          2126: {ls 1}
        !          2127: Note:  "Country?" will be displayed at your terminal.
        !          2128: Following this, you should enter text (possibly null)
        !          2129: terminated by a carriage return. This response becomes the
        !          2130: value of the QUERY macro, and hence is effectively inserted
        !          2131: in the output stream.
        !          2132: {LI}Ask for an address from the terminal to be used
        !          2133: later, so place it in a macro called ADDRESS.
        !          2134: {ls 1}
        !          2135: {Center <{SET ADDRESS,{QUERY WHAT IS THE ADDRESS? }}>}
        !          2136: {ls 1}
        !          2137: If text such as "#10 Downing St.<{BRK}>London, England"
        !          2138: were entered, it would be placed into ADDRESS in that form,
        !          2139: since GPMDOC does not evaluate QUERY input. When ADDRESS
        !          2140: was used later, the <{BRK}> would be processed by GPMDOC
        !          2141: at that point.
        !          2142: {LI}Print an address and also put it into ADDRESS to be
        !          2143: referenced later:
        !          2144: {ls 1}
        !          2145: {CENTER <Ship To: {SETV ADDRESS,{QUERY WHAT IS THE ADDRESS? }}>}
        !          2146: {LS 1}
        !          2147: Notice the use of SETV to effectively 'pass through' the value
        !          2148: that was SET, in order for it to be printed.
        !          2149: {EL}
        !          2150: {P}
        !          2151: !
        !          2152: ! REMDR
        !          2153: !
        !          2154: {Macdescr REMDR,Arithmetic Remainder}
        !          2155: <{REMDR n1,n2}>
        !          2156: {Macsec Description}
        !          2157: The value of REMDR is the integer remainder after dividing integer
        !          2158: n1 by n2.
        !          2159:  The sign of the result is the same as the sign of n1.
        !          2160: {Macsec Examples}
        !          2161: {bl}Print a message on the terminal every 10 pages.
        !          2162: {ls 1}{Center <{COND {EQ 0,{REMDR @PAGENUM,10}},{DISPLAY Working...}}>}
        !          2163: {Ls 1}
        !          2164: {Li *~}Here is a set of macros to compute roman numbers given a number.
        !          2165: in the range from 0..99.
        !          2166:  For example <{Roman~17}> will yield "xvii".
        !          2167: {Ls 1}{Nfj}
        !          2168: <{SETQ ROMAN,{GENROMAN {/ @1,10},x,l,c}->
        !          2169:   <{GENROMAN {REMDR @1,10},i,v,x}}>
        !          2170: {Ls 1}
        !          2171: <{SETQ GENROMAN,{COND ->
        !          2172:   <{LE @1,3},{DUPL @2,@1},->
        !          2173:   <{EQ @1,4},{2}{3},->
        !          2174:   <{LE @1,8},{3}{DUPL @2,{- @1,5}},->
        !          2175:   <,{2}{4}}}>
        !          2176: {Ls 1}{Fj}
        !          2177: "Genroman" is an auxilliary macro used by Roman that will generate
        !          2178: text according to the rules for roman numbers in the range
        !          2179: 0..9.
        !          2180:  Roman makes two calls on Genroman, one for the 10s digit and one
        !          2181: for the ones digit.
        !          2182:  REMDR is used to extract the ones digit.
        !          2183: {Ls 1}Genroman takes in the symbols ("x","l","c", etc.)
        !          2184: to be used, since the rules for generating roman numbers are the same
        !          2185: for both the 10s digit and the ones digit.
        !          2186: {Ls 1}Note that if capital roman numbers were needed, <{CAPS~{ROMAN~n}}>
        !          2187: would do the trick.
        !          2188: {el}
        !          2189: {P}
        !          2190: !
        !          2191: ! REPLACE
        !          2192: !
        !          2193: {macdescr REPLACE,Substitute for Characters in Text}
        !          2194: <{REPLACE str1,str2,str3}>
        !          2195: {Macsec Description}
        !          2196: The value of REPLACE is the string str1 with each of its characters
        !          2197: appearing in str2 being replaced by the corresponding character from
        !          2198: str3.
        !          2199: {Macsec Notes}
        !          2200: {bl}Str2 and str3 must be the same size, and must not be null.
        !          2201: {li}Any of the argument strings can contains overstrikes, however,
        !          2202: replacement occurs on the individual component characters of
        !          2203: overstrikes, not on the overstruck characters as unique elements.
        !          2204: {el}
        !          2205: {macsec examples}
        !          2206: {bl}Print the text of the macro TITLE, with all punctuation replaced
        !          2207: by blanks:
        !          2208: {Ls 1}{Center <{REPLACE @TITLE,<,.?":;!>,<       >}>}{Ls 1}
        !          2209: {li}Print text that is typed in from the terminal, with all
        !          2210: spaces replaced by hard spaces:
        !          2211: {Tset Hs,<@>}
        !          2212: {Ls 1}{Center <{REPLACE {QUERY Enter Text},< >,~}>}{Brk}
        !          2213: {Restore Hs}{Ls 1}
        !          2214: {el}
        !          2215: {p}
        !          2216: !
        !          2217: ! RESTORE
        !          2218: !
        !          2219: {MACDESCR RESTORE,Restore Prior Value of Macros}
        !          2220: <{RESTORE mname1,mname2,...}>
        !          2221: {macsec description}
        !          2222: RESTORE is used to retrieve the last definition of the mnames
        !          2223: that were stacked by TSET (see the description of TSET).
        !          2224:  Each of the given mnames is processed in turn, starting with mname1.
        !          2225:  A null mname (end of arguments) is assumed to terminate the list.
        !          2226: {Ls 1}RESTORE operates exactly like a SET on mname, where the
        !          2227: value to be SET comes from the top of the stack for mname.
        !          2228:  RESTORE also discards this item from the stack, so that
        !          2229: successive RESTORE's on the same mname retrieve successive items
        !          2230: from mname's stack in inverse order from the order they
        !          2231: were stacked by TSET.
        !          2232: {macsec notes}
        !          2233: {BL}TSET and RESTORE are typically used to save (TSET)
        !          2234: and restore (RESTORE) contextual information such as
        !          2235: margins, spacing and the like.
        !          2236: {LI}An attempt to restore a value from a macro's stack
        !          2237: when the stack is empty will result in a "NO VALUE TO RESTORE"
        !          2238: error.
        !          2239: {Li}A macro may issue a RESTORE on itself (see OUTDENT for example).
        !          2240:  The restored definition is used in subsequent evaluations of the macro,
        !          2241: the evaluation causing the restore continues undisturbed with the previous
        !          2242: definition.
        !          2243: {Li}Stacks for macros with the same name in different property tables
        !          2244: are distinct.
        !          2245: {EL}
        !          2246: {macsec examples}
        !          2247: Examples are shown in the description for TSET.
        !          2248: {P}
        !          2249: !
        !          2250: ! RIN
        !          2251: !
        !          2252: {Macdescr RIN,Indent the right margin}
        !          2253: <{RIN n}>
        !          2254: {Macsec Description}
        !          2255: <{RIN n}> is equivalent to <{TSET.- RMG,n}>.
        !          2256:  It indents the right margin an additional "n" places.
        !          2257: {Macsec Notes}
        !          2258: {bl}"n" can be negative to move out the right margin
        !          2259: {li}Keep in mind that RIN does a TSET.
        !          2260:  The right margin prior to the RIN operation is saved on the RMG stack.
        !          2261:  A subsequent <{RESTORE RMG}> will reactivate it.
        !          2262: {li}There is a companion LIN macro to indent the left margin.
        !          2263: {EL}
        !          2264: {P}
        !          2265: !
        !          2266: ! RMG
        !          2267: !
        !          2268: {macdescr RMG,Right Margin}
        !          2269: <{set RMG,n}> (Default: RMG=75)
        !          2270: <{RMG}>
        !          2271: <{D RMG}>
        !          2272: {macsec description}
        !          2273: The value of RMG tells GPMDOC the absolute position of the
        !          2274: last printing column on the page.
        !          2275: {macsec notes}
        !          2276: {BL}N must be greater than or equal to <{LMG}>.
        !          2277: {LI}<{RMG}> in fill mode causes lines to be assembled until
        !          2278: characters overflow the right margin. Then this assembled
        !          2279: line is broken off at a blank closest to the right margin, and
        !          2280: printed. If no blank exists in the line, the line is broken
        !          2281: at the right margin. If justification is enabled, the part
        !          2282: broken off is justified before printing, such that the last
        !          2283: character is flush with the right margin. The part of the
        !          2284: assembled text not broken off is retained for printing on
        !          2285: the next line. With line fill disabled, an automatic
        !          2286: line break occurs at the end of each input line, so that <{RMG}>
        !          2287: only assumes significance if single input lines exceed the
        !          2288: line length.
        !          2289: {LI}The LINELENGTH macro can also be used to change the right
        !          2290: margin, see the description of LINELENGTH.
        !          2291: {EL}
        !          2292: {macsec examples}
        !          2293: {BL}Set the right margin at column 60:
        !          2294: {ls 1}
        !          2295: {Center <{SET RMG,60}>}
        !          2296: {LI}Set the right margin to 10 past the left margin:
        !          2297: {ls 1}
        !          2298: {Center <{SET RMG,{+ @LMG,10}}>}
        !          2299: {Center or}
        !          2300: {Center <{SET LINELENGTH,11}>}
        !          2301: {ls 1}
        !          2302: You might be tempted to set LINELENGTH to 10, but this is not
        !          2303: the same. For instance, if <{LMG}> is 10 and RMG is 20 as
        !          2304: a result of this example, then columns 10-20 {UL inclusive}
        !          2305: are printing columns. This means there are 11 printing columns.
        !          2306: <{LINELENGTH}> will always be <{RMG}> - <{LMG}> + 1.
        !          2307: {EL}
        !          2308: {P}
        !          2309: !
        !          2310: ! RPAD
        !          2311: !
        !          2312: {macdescr RPAD,Pad a String on the Right}
        !          2313: <{RPAD str1,n,str2}>
        !          2314: {macsec description}
        !          2315: The value of RPAD is str1 suffixed with replications of str2 to
        !          2316: produce a result of length n.
        !          2317:  If str1 is already as
        !          2318: long or longer than n, the value of RPAD is str1.
        !          2319:  The value of RPAD is also str if n is zero or negative.
        !          2320:  If an uneven number of replication are necessary to get a result of
        !          2321: length n, the last replication will be truncated appropriately.
        !          2322:  If str2 is null, the present hardspace character is assumed for str2.
        !          2323: {macsec notes}
        !          2324: {BL}RPAD, along with LPAD, is useful for producing
        !          2325: tabular text.
        !          2326: {EL}
        !          2327: {macsec examples}
        !          2328: {Bl}Define a macro, TABULAR, that will print three items in
        !          2329: columns ten wide:
        !          2330: {Ls 1}
        !          2331: {Nfj}
        !          2332: <{SETQ TABULAR,->
        !          2333:   <{RPAD @1,10}{RPAD @2,10}{RPAD @3,10}}>
        !          2334: {FJ}
        !          2335: {EL}
        !          2336: {P}
        !          2337: !
        !          2338: ! SET
        !          2339: !
        !          2340: {macdescr SET,Alter The Value of a Macro}
        !          2341: <{SET mname,str}>
        !          2342: {macsec description}
        !          2343: The macro with name mname is given a definition of str.
        !          2344:  Any previous definition is lost.
        !          2345:  Future references to <{mname...}>
        !          2346: will cause this definition to be retrieved.
        !          2347:  The value of SET is always null.
        !          2348: {macsec notes}
        !          2349: {BL}Certain system macros may only be set to a restricted
        !          2350: range of values (e.g. INPUT, LMG, RMG, LINENUM etc.).
        !          2351:  An attempt to set these macros to an improper value results in a
        !          2352: "BAD VALUE" error.
        !          2353: {LI}All macros not explicitly SET are implicitly null when
        !          2354: referenced.
        !          2355: {LI}There is an additional syntax available for use with
        !          2356: SET, termed "extended set".
        !          2357:  It is used when an operation is
        !          2358: to be applied that involves a macro, and the resulting
        !          2359: value is to be SET back into that macro. (See examples below.)
        !          2360: The syntax is:
        !          2361: {ls 1}
        !          2362: {Center <{SET.mname1 mname2,str1,str2...}>}
        !          2363: {Ls 1}
        !          2364: which is equivalent to:
        !          2365: {Ls 1}
        !          2366: {Center <{SET mname2,{mname1 @mname2,str1,str2,...}}>}
        !          2367: {LS 1}
        !          2368: Extended set should not be used with system macros for which
        !          2369: the <{D mname}> form is not valid, since the macro's
        !          2370: {ul definition} is accessed for extended set.
        !          2371: {LI}The argument macros may be used within a macro's
        !          2372: definition.
        !          2373:  They take the form <{n}>. n is a macro whose definition
        !          2374: is the nth argument string passed in a call to the
        !          2375: macro where the <{n}> occurs, as in:
        !          2376: <{mname arg1,arg2,...}>.
        !          2377:  For instance <{1}> refers to
        !          2378: arg1 of this evaluation of mname.
        !          2379:  An argument macro with a
        !          2380: number less than one or greater than the number of arguments
        !          2381: given will evaluate to null, as will an argument macro
        !          2382: appearing directly in the input text (outside of an evaluation).
        !          2383:  Argument macros are, as with other system macros,
        !          2384: defined in the null property table, however,
        !          2385:  no form of SET should ever be issued for argument macros.
        !          2386: {LI}For the above reasons users should avoid defining their
        !          2387: own macros with names:
        !          2388: {ls 1}
        !          2389: {nfj}
        !          2390:     -  Containing periods or backslashes, or
        !          2391:     -  The same as system macros, or
        !          2392:     -  That are numeric (with the null property table).
        !          2393: {fj}
        !          2394: {ls 1}
        !          2395: {LI}SETting definitions uses up memory space inside GPMDOC.
        !          2396: In some implementations on small machines this may be
        !          2397: significant in that GPMDOC will run slower when the user has set
        !          2398: a large number of definitions because its own internal processing
        !          2399: memory is reduced. In extreme cases a "MEMORY OVERFLOW" error
        !          2400: may occur. To avoid thses situations, macros can be set to null
        !          2401: when they are no longer needed, or an entire property table
        !          2402: and its definitions can be eradicated with the DELPROP macro.
        !          2403: {EL}
        !          2404: {macsec examples}
        !          2405: {BL}Set a macro to "University of California" (saves typing):
        !          2406: {LS 1}{Center <{SET UC,University of California}>}
        !          2407: {LI}Move the left margin in five spaces.
        !          2408: {Ls 1}{Center <{SET LMG,{+ 5,@LMG}}>}
        !          2409: {Center or}
        !          2410: {Center <{SET.+ LMG,5}>}
        !          2411: {Center or}
        !          2412: {Center <{LIN 5}>}
        !          2413: {LI}Set the output file to HELP.DOC on account [1,2].
        !          2414: {LS 1}
        !          2415: {Center <{SET OUTPUT,<[1,2]HELP.DOC>}>}
        !          2416: {LS 1}
        !          2417: Note that the quotes are needed as otherwise the comma
        !          2418: within the account specification would be seen as an
        !          2419: argument separator, and OUTPUT would be set to
        !          2420: "[1" - an error.
        !          2421: {LI}Set the hardspace to a backslash:
        !          2422: {LS 1}{Center <{SET HS,\}>}
        !          2423: {LI}Define a macro PAGE that will skip to a new page
        !          2424: when invoked:
        !          2425: {LS 1}{Center <{SET PAGE,<{LS 10000}>}>}
        !          2426: {LS 1}
        !          2427: Note here that the quotes are required to avoid a premature
        !          2428: evaluation of the LS. If the quote brackets were not
        !          2429: present, when the SET was evaluated, the <{LS 10000}> would then
        !          2430: be evaluated as an argument to SET
        !          2431: which would immediately force a new page, and
        !          2432: the value of the LS (null) would be set to PAGE. It is easier
        !          2433: to do this sort of thing with SETQ (see the description of SETQ).
        !          2434: {LI}Turn right justification off (set it to null).
        !          2435: {LS 1}
        !          2436: {Center <{SET JUST}>}
        !          2437: {El}
        !          2438: {P}
        !          2439: !
        !          2440: ! SETQ
        !          2441: !
        !          2442: {macdescr SETQ,Quoted SET}
        !          2443: <{SETQ mname,qstr}>
        !          2444: {macsec description}
        !          2445: SETQ functions exactly like SET in that it establishes a connection
        !          2446: between mname and qstr.
        !          2447:  The difference is that SETQ receives the qstr definition in
        !          2448: unevaluated form.
        !          2449:  The definition is thus made with all
        !          2450: embedded macro calls and quotes in qstr intact.
        !          2451: {macsec notes}
        !          2452: {BL}SETQ is included principally to make it easier to define
        !          2453: macros that consist of calls on other macros.
        !          2454:  (See the examples.)
        !          2455: {li}Your qstr should not contain "open" commas, that is, commas
        !          2456: not contained inside quote symbols or macro braces. The reason
        !          2457: is that these commas would be seen as argument separators for the
        !          2458: SETQ, causing an incorrect argument scan for the SETQ.
        !          2459: {EL}
        !          2460: {macsec examples}
        !          2461: {BL}Define a macro INMARGINS that will move the left and
        !          2462: right margins in by five.
        !          2463: {ls 1}{Center <{SETQ INMARGINS,{LIN 5}{RIN 5}}>}
        !          2464: {ls 1}
        !          2465: This example could be done with SET, it would be written as:
        !          2466: {ls 1}
        !          2467: {Center <{SET INMARGINS,<{LIN 5}{RIN 5}>}>}
        !          2468: {LS 1}
        !          2469: The SETQ allows you to eliminate the quote symbols that
        !          2470: have to be used in the SET.
        !          2471: {el}
        !          2472: {P}
        !          2473: !
        !          2474: ! SETV
        !          2475: !
        !          2476: {macdescr SETV,SET Value For Macro and Return It}
        !          2477: <{SETV mname,str}>
        !          2478: {macsec description}
        !          2479: SETV functions identically to SET except instead of having a
        !          2480: a null value, the value of SETV is the text that is set
        !          2481: as the definition of mname.
        !          2482: {macsec notes}
        !          2483: {BL}SETV may be used in extended form as with SET.
        !          2484: {EL}
        !          2485: {macsec examples}
        !          2486: {BL}Indent the left margin five and put the resulting value
        !          2487: in the user-defined macro margin.
        !          2488: {LS 1}{Center <{SET MARGIN,{SETV.+ LMG,5}}>}
        !          2489: {LS 1}
        !          2490: {EL}
        !          2491: {P}
        !          2492: !
        !          2493: ! SIZE
        !          2494: !
        !          2495: {macdescr SIZE,Number of Print Positions for Text}
        !          2496: <{SIZE str}>
        !          2497: {macsec description}
        !          2498: The value of SIZE is the (non-negative) integer which
        !          2499: gives the number of print columns that would be
        !          2500: occupied by str, if it were printed.
        !          2501: {macsec notes}
        !          2502: {bl}SIZE includes compensation for any overstruck characters
        !          2503: in str.  Thus SIZE is the number of characters in str if and
        !          2504: only if str contains no overstrikes.
        !          2505: {li}DSIZE is useful and more efficient for determining the
        !          2506: size of a defined macro or argument.  (See the description
        !          2507: of DSIZE).
        !          2508: {el}
        !          2509: {p}
        !          2510: !
        !          2511: ! SKIPTEXT
        !          2512: !
        !          2513: {MACDESCR SKIPTEXT,Skip Input Text}
        !          2514: <{SKIPTEXT str}>
        !          2515: {Macsec Description}
        !          2516: The SKIPTEXT macro causes succeeding lines on the currently active
        !          2517: input file to be skipped until a physical line is encountered
        !          2518: that exactly matches "str".
        !          2519:  No evaluation or processing of any kind occurs with the skipped text.
        !          2520:  Reading will continue with the line following the one matched.
        !          2521:  The value of SKIPTEXT is always null.
        !          2522: {Macsec Notes}
        !          2523: {Bl}SKIPTEXT, as with BEGINTEXT and ENDTEXT, works with
        !          2524: physical lines, not logical ones.
        !          2525:  This means that comment lines can be used as SKIPTEXT markers.
        !          2526:  The reason that this is usually helpful is if the text that is
        !          2527: skipped is processed without the SKIPTEXT being invoked.
        !          2528:  In this case, if the marker is a comment, it will not become
        !          2529: part of the text processed.
        !          2530: {li}The preferred marker (by convention) is "!**".
        !          2531: {Li}The given termination string can be null.
        !          2532:  In this case, an empty line will terminate the skipping.
        !          2533: {el}
        !          2534: {Macsec Examples}
        !          2535: {bl}Skip some text if the value of MODE is "BRIEF":
        !          2536: {Ls 1}{Center <{COND {LEQ @MODE,BRIEF},{SKIPTEXT !**}}>}{Ls 1}
        !          2537: This will skip over input through the next "!**" line if the
        !          2538: MODE macro has the value "BRIEF".
        !          2539:  Otherwise, evaluation continues on with no effects.
        !          2540: {Ls 1}This shows why the use of "!**" is helpful, since if
        !          2541: MODE is not "BRIEF", then the "!**" that is encountered later
        !          2542: will be 'ignored.'
        !          2543: {el}
        !          2544: !
        !          2545: ! SPACING
        !          2546: !
        !          2547: {MACDESCR SPACING,Set Inter-line Spacing}
        !          2548: <{set SPACING,n}> (Default: SPACING=1)
        !          2549: <{SPACING}>
        !          2550: <{D SPACING}>
        !          2551: {macsec description}
        !          2552: The SPACING macro tells GPMDOC how many blank lines to
        !          2553: automatically print after each text line is output. When
        !          2554: SPACING is one, no extra blank lines are output. SPACING
        !          2555: set to 2 means double spacing, and so forth. In general, setting
        !          2556: SPACING to n is equivalent to performing an <{LS~{sub1~n}}>
        !          2557: after each line is printed.
        !          2558: {macsec notes}
        !          2559: {BL}N must be greater than or equal to one.
        !          2560: {LI}If less than n-1 lines remain on the page, the page
        !          2561: is run out, and an endpage condition occurs.
        !          2562: {LI}Blank lines inserted by the effect of SPACING are not subject
        !          2563: to BSLACK (see the description of BSLACK).
        !          2564: {LI}Blank lines emitted by <{LS~...}> will not have additional
        !          2565: spacing applied (see example).
        !          2566: {EL}
        !          2567: {macsec examples}
        !          2568: {BL}Set double spacing:
        !          2569: {LS 1}{Center <{SET SPACING,2}>}
        !          2570: {LI}Temporarily set single spacing for printing a quotation
        !          2571: then go back to the old spacing:
        !          2572: {LS 1}
        !          2573: {Center <{TSET SPACING,1}{LS 2}{LIN 10}{RIN 10}>}
        !          2574: {Center :}{Center Text of Quotation}{Center :}
        !          2575: {Center <{RESTORE RMG,LMG,SPACING}>}
        !          2576: {LI}Define a macro <{LS* n}> that will do the job
        !          2577: of LS, but will take into account the value of SPACING,
        !          2578: so that each blank line emitted will actually be <{SPACING}>
        !          2579: blank lines:
        !          2580: {LS 1}{Center <{SETQ LS*,{LS {* @1,@SPACING}}}>}
        !          2581: {LS 1}
        !          2582: When <{LS*~n}> is called, n is multiplied by
        !          2583: the value of SPACING so that the LS actually performed is n
        !          2584: times the current spacing.
        !          2585: {EL}
        !          2586: {P}
        !          2587: !
        !          2588: ! SUB1
        !          2589: !
        !          2590: {macdescr SUB1,Subtract One From Numeric}
        !          2591: <{SUB1 n}>
        !          2592: {macsec description}
        !          2593: The value of SUB1 is one subtracted from n.  It is
        !          2594: equivalent to <{-~n,1}>.
        !          2595: {macsec notes}
        !          2596: {bl}SUB1 is included for convenience, as it is a frequent
        !          2597: operation.
        !          2598: {el}
        !          2599: {macsec examples}
        !          2600: {bl}Subtract one from the current page number:
        !          2601: {ls 1}
        !          2602: {Center <{SET.SUB1 PAGENUM}>}
        !          2603: {EL}
        !          2604: {P}
        !          2605: !
        !          2606: ! SUBSTR
        !          2607: !
        !          2608: {macdescr SUBSTR,Compute Substring}
        !          2609: <{SUBSTR str,n1,n2}>
        !          2610: {Macsec Description}
        !          2611: The value of SUBSTR is n2 contiguous characters of text taken from
        !          2612: str, starting at character position n1.
        !          2613: {Macsec Notes}
        !          2614: {Bl}Both n1 and n2 should be positive, and define a region completely
        !          2615: within str.
        !          2616: {Li}If n2 is omitted, then the 'rest' of str is assumed by default.
        !          2617: {el}
        !          2618: {macsec Examples}
        !          2619: {Bl}Define a macro to print text with the first character
        !          2620: capitalized:
        !          2621: {Ls 1}{Center <{SETQ FCC,{CAPS {SUBSTR @1,1,1}}{SUBSTR @2,2}}>}
        !          2622: {El}{P}
        !          2623: !
        !          2624: ! T
        !          2625: !
        !          2626: {macdescr T,Horizontal Tab}
        !          2627: <{T n,str}>
        !          2628: {macsec description}
        !          2629: The value of T is sufficient replications of str to cause the next
        !          2630: character to print in column n.
        !          2631:  N is relative to left margin;
        !          2632:  n=1 is the first printing column.
        !          2633:  If str is null, then a hard space is assumed for str.
        !          2634: {macsec notes}
        !          2635: {BL}N should be less than or equal to <{LINELENGTH}>.
        !          2636:  If text has
        !          2637: already been assembled past column n, a line break occurs
        !          2638: before the hard spaces for the tab are emitted.
        !          2639: {LI}T should not be used when justification is enabled.
        !          2640: Justification may insert additional spaces that will cause
        !          2641: the tab to be moved to the right an unpredictable amount.
        !          2642: {Li}T looks at the current output stream to determine the size of
        !          2643: its result.
        !          2644:  It operates under the assumption that the result of its evaluation
        !          2645: is going to the output stream.
        !          2646:  If T is used in some other context, such as an
        !          2647: argument, then it will evaluate to the appropriate text, but obviously
        !          2648: no actual tabbing will occur as a result.
        !          2649: {EL}
        !          2650: {macsec examples}
        !          2651: {BL}Tab over to column 40 and print $1.99:
        !          2652: {ls 1}
        !          2653: {Center <{T 40}>$1.99}
        !          2654: {LI}Print "CONTRACT" in the last 8 columns of the line:
        !          2655: {ls 1}
        !          2656: {Center <{T {- @LINELENGTH,7}}>CONTRACT}
        !          2657: {LS 1}
        !          2658: This would be easier to do with LPAD.
        !          2659: {LI}Define a macro TOC that will format one line of a
        !          2660: table of contents. The format is: the description, then
        !          2661: periods to column 35, and then the page number. The
        !          2662: description and page number will be given as arguments to TOC:
        !          2663: {ls 1}{Center <{SETQ TOC,{1}{T 35,.}{2}}>}
        !          2664: {Ls 1}
        !          2665: This would be used as in:
        !          2666: {Ls 1}
        !          2667: {Center <{TOC Chapter 1,1}>}
        !          2668: {Center <{TOC Chapter 2,15}>}
        !          2669: {Ls 1}
        !          2670: Which would appear as:
        !          2671: {Ls 1}{Nfj}
        !          2672: {TSETQ TOC,{1}{T 35,.}{2}}
        !          2673: {TOC Chapter 1,1}
        !          2674: {Toc Chapter 2,15}
        !          2675: {Restore TOC}
        !          2676: {Ls 1}{Fj}
        !          2677: {EL}
        !          2678: {P}
        !          2679: !
        !          2680: ! TSET
        !          2681: !
        !          2682: {macdescr TSET,Temporary Set}
        !          2683: <{TSET mname,str}>
        !          2684: {macsec description}
        !          2685: TSET performs identically to SET (see description), except
        !          2686: that before the SET is performed, the current value of mname
        !          2687: is put on top of a special stack reserved for mname. A
        !          2688: <{RESTORE mname}> performed will cause this stacked value to be
        !          2689: removed from the top of the stack and restored as the definition
        !          2690: of mname. The TSET value (str) will then be lost. Multiple
        !          2691: TSETs may be performed on the mname; the values are "unstacked"
        !          2692: in reverse from the order they were originally stacked. TSETs
        !          2693: performed on different mnames are totally independent. TSET,
        !          2694: like SET always evaluates null.
        !          2695: {macsec notes}
        !          2696: {BL}TSET may be used in extended form. See the description
        !          2697: of extended SET.
        !          2698: {LI}TSET and RESTORE are normally used jointly.
        !          2699:  The description of
        !          2700: RESTORE should be read for a full understanding of TSET.
        !          2701: {LI}The usual use of TSET is as a mechanism for saving, then
        !          2702: changing, some part of the context of a document such as margins,
        !          2703: spacing, titles, section numbers, and the like. This saved
        !          2704: context can then be restored at a later point in the processing.
        !          2705: For instance, GPMDOC uses TSET internally when processing
        !          2706: NEWPAGE and ENDPAGE. The values of LMG, RMG, SPACING and
        !          2707: NEWLINE are TSET to predefined values for processing the page
        !          2708: condition, regardless of what their values might be in the body
        !          2709: of the text.
        !          2710:  At the conclusion of the page condition, a RESTORE
        !          2711: is done on these macros which brings back the values that existed
        !          2712: prior to the occurrence of the page condition.
        !          2713: {Li}The TSET form for INPUT allows other TSETs to be
        !          2714: incorporated.
        !          2715:  See the description for INPUT.
        !          2716: {EL}
        !          2717: {macsec examples}
        !          2718: {BL}Set the left margin to five, temporarily:
        !          2719: {ls 1}{Center <{TSET LMG,5}>}
        !          2720: {LS 1}
        !          2721: {LI}Define a macro QUOTATION that will skip down two lines,
        !          2722: indent the left and right margins 7 spaces and go to single
        !          2723: spacing in order to insert a properly formatted quotation in the
        !          2724: document:
        !          2725: {ls 1}{Nfj}
        !          2726: <{SETQ QUOTATION,{LS 2}->
        !          2727:   <{LIN 7}{RIN 7}{TSET SPACING,1}}>
        !          2728: {LS 1}{Fj}
        !          2729: Note that at the conclusion of the quotation text, the macros
        !          2730: <{RESTORE~SPACING,RMG,LMG}{LS 2}> would
        !          2731: be included.
        !          2732:  This could be packaged in a second macro
        !          2733: ENDQUOTATION defined as:
        !          2734: {ls 1}{Nfj}
        !          2735: <{SETQ ENDQUOTATION,->
        !          2736:   <{RESTORE LMG,RMG,SPACING}{LS 2}}>
        !          2737: {LS 1}{Nfj}
        !          2738: The next example, however, shows a simpler way to do this.
        !          2739: {LI}Do the same thing, only use a pseudo-read.
        !          2740: {ls 1}{nfj}
        !          2741: <{SETQ QUOTATION,->
        !          2742:   <{LS 2}{LIN 7}{RIN 7}{TSET SPACING,1}->
        !          2743:   <{TSET INPUT,,ENDTEXT=!**}->
        !          2744:   <{LS 2}{RESTORE LMG,RMG,SPACING}>
        !          2745: {LS 1}{FJ}
        !          2746: Using the pseudo-read, the way QUOTATION is used is:
        !          2747: {ls 1}{nfj}
        !          2748:      <{QUOTATION}>
        !          2749:            :
        !          2750:            :
        !          2751:      text of quotation
        !          2752:            :
        !          2753:            :
        !          2754:      !**
        !          2755: {ls 1}{Fj}
        !          2756: The last line terminates the pseudo-read and the QUOTATION
        !          2757: macro finishes by evaluating the RESTORE that follows the READ.
        !          2758: {ls 1}
        !          2759:  In the above example, it is important that the <{LS 2}> precede
        !          2760: the TESETs and RESTOREs. This is so that the LS can flush out
        !          2761: any text (line break) before the margins are changed.
        !          2762: {EL}
        !          2763: {P}
        !          2764: !
        !          2765: ! TSETQ
        !          2766: !
        !          2767: {macdescr TSETQ,Temporary Quoted Set}
        !          2768: <{TSETQ mname,qstr}>
        !          2769: {macsec description}
        !          2770: TSETQ functions the same as TSET (see description), but
        !          2771: the definition to be set is implicitly quoted.
        !          2772:  TSETQ is thus to TSET what SETQ is to SET.
        !          2773: {macsec notes}
        !          2774: {Bl}TSETQ cannot be used in extended form.
        !          2775: {el}
        !          2776: {macsec examples}
        !          2777: See the descriptions of SETQ and TSET for examples.
        !          2778: {P}
        !          2779: !
        !          2780: ! TSETV
        !          2781: !
        !          2782: {Macdescr TSETV,TSET Value for Macro and Return It}
        !          2783: <{TSETV mname,str}>
        !          2784: {macsec description}
        !          2785: TSETV functions identically to TSET (see description)
        !          2786: except instead of having a
        !          2787: a null value, the value of TSETV is the text that is set
        !          2788: as the definition of mname.
        !          2789: {macsec notes}
        !          2790: {BL}TSETV may be used in extended form (as with TSET).
        !          2791: {EL}
        !          2792: {macsec examples}
        !          2793: See the descriptions of TSET and SETV for examples.
        !          2794: {p}
        !          2795: !
        !          2796: ! UL
        !          2797: !
        !          2798: {macdescr UL,Underline Text}
        !          2799: <{UL str1,str2}>
        !          2800: {macsec description}
        !          2801: The UL macro uses the overstriking ability of GPMDOC
        !          2802: to produce a new string consisting of the characters of str1
        !          2803: overstruck with underscores. Characters in str2 will not be
        !          2804: underscored in str1. If str2 is not given (null) then all
        !          2805: characters of str1 except blanks will be overstruck with
        !          2806: underscores in the string produced by UL.
        !          2807: {macsec notes}
        !          2808: {BL}Str1 may contain overstruck characters (including
        !          2809: underscores).
        !          2810: {LI}If it is desired to have all characters including blanks
        !          2811: overstruck, str2 can be given as a single character which
        !          2812: could not reasonably appear in str1 (such as a control
        !          2813: character), or the OVER macro can be used to perform the
        !          2814: overstriking directly (see examples for OVER).
        !          2815: {EL}
        !          2816: {macsec examples}
        !          2817: {BL}Print the text "Three Leaf Clover", underlined:
        !          2818: {LS 1}{Center <{UL Three Leaf Clover.}>}
        !          2819: {Ls 1}
        !          2820: This will print as:
        !          2821: {Ls 1}{Center {UL Three Leaf Clover.}}
        !          2822: {Ls 1}{Fj}
        !          2823: {LI}Define a macro ULC that will return its text underscored
        !          2824: except for lower case letters.
        !          2825: {ls 1}
        !          2826: {center <{SETQ ULC,{UL {D 1},abcdefghijklmnopqrstuvwxyz}}>}
        !          2827: {Ls 1}This would be used as in:{Ls 1}
        !          2828: {Center <{ULC Three Leaf Clover.}>}
        !          2829: {Ls 1}which would print as:
        !          2830: {TSETQ ULC,{UL {D 1},abcdefghijklmnopqrstuvwxyz}}
        !          2831: {ULC Three Leaf Clover}
        !          2832: {Restore ULC}
        !          2833: {EL}
        !          2834: {P}
        !          2835: !
        !          2836: ! +
        !          2837: !
        !          2838: {macdescr +,Add Numerics}
        !          2839: <{+ n1,n2}>
        !          2840: {macsec description}
        !          2841: The value of + is the sum of the two numeric strings n1 and n2.
        !          2842: {macsec notes}
        !          2843: {BL}For adding or subtracting one,
        !          2844: the ADD1 and SUB1 macros are better.
        !          2845: {LI}+ is very useful in extended SET forms for incrementing
        !          2846: a numeric-valued macro (see examples).
        !          2847: {EL}
        !          2848: {macsec examples}
        !          2849: {Bl}Add the macros PROFIT and NET, print it in column 35:
        !          2850: {Ls 1}{Center <{BRK}{T 35}{+ @PROFIT,@NET}>}
        !          2851: {EL}
        !          2852: {P}
        !          2853: !
        !          2854: ! -
        !          2855: !
        !          2856: {MACDESCR -,Subtract Numerics}
        !          2857: <{- n1,n2}>
        !          2858: {macsec description}
        !          2859: The value of - is the difference when n2 is subtracted from n1.
        !          2860: {macsec notes}
        !          2861: {BL}For subtracting one from a number, the SUB1 macro is better.
        !          2862: {LI}- is useful in extended SET form for decrementing a
        !          2863: numeric-valued macro.
        !          2864: {EL}
        !          2865: {macsec examples}
        !          2866: {Bl}Subtract CREDIT from BILLING and print the result in
        !          2867: column 35:
        !          2868: {ls 1}{Center <{BRK}{T 35}{- @BILLING,@CREDIT}>}
        !          2869: {EL}
        !          2870: {P}
        !          2871: !
        !          2872: ! *
        !          2873: !
        !          2874: {macdescr *,Multiply Numerics}
        !          2875: <{* n1,n2}>
        !          2876: {Macsec Description}
        !          2877: The value of * is the product of the two numeric strings n1 and n2.
        !          2878: {p}
        !          2879: !
        !          2880: ! /
        !          2881: !
        !          2882: {macdescr /,Divide Numerics}
        !          2883: <{/ n1,n2}>
        !          2884: {Macsec Description}
        !          2885: The value of / is the quotient of the two numeric strings n1 and n2.
        !          2886: {Macsec notes}
        !          2887: {Bl}If both n1 and n2 are integers (no decimal point) then the
        !          2888: value of / will also be an integer, formed by discarding any fractional
        !          2889: part from the quotient.
        !          2890:  If either or both of n1 or n2 contain decimals, then the division
        !          2891: will produce a real (floating) result.
        !          2892: {el}
        !          2893: {p}
        !          2894: {Exclude HELP}
        !          2895: !
        !          2896: !      Print the Index
        !          2897: !
        !          2898: {Set pagenum,1}
        !          2899: {Tset input,,Spacing=1,Lmg=10,Rmg=70,Endtext=!**INDEX,Pagelength=55,-
        !          2900:        Newpage=<{Ls 2}{Center Appendix A}{Center Table of Contents}{Ls 2}>,-
        !          2901:        Endpage=<{Ls 1}{Center TOC-{Pagenum}}>-
        !          2902: }
        !          2903: {Dowhile {Lne @Toc},{Tset Toca,@Toc}{Restore Toc}}
        !          2904: {Set Toc_char}
        !          2905: {Dowhile {Lne @Toca},-
        !          2906:   {Cond {Lne @Toc_char,{Setv Toc_char,{Substr @Toca,1,1}}},{Ls 1},,{Brk}}-
        !          2907:   {D Toca}-
        !          2908:   {Restore Toca}-
        !          2909: }
        !          2910: !
        !          2911: !**INDEX
        !          2912: !
        !          2913: {P}
        !          2914: !**
        !          2915: !
        !          2916: {Exclude TEXT}
        !          2917: {Endsec}
        !          2918: !**
        !          2919: 
        !          2920: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.