V10/cmd/spitbol/gpmdoc.gpm

{Set Program,GPMDOC}
{Set Version,Version 6.10}
!
{Setq Macdescr,-
  {Set Macroname,{Caps @1}}-
  {Sec {1}{Cond {Leq @Mode,TEXT},~({2})}}-
  {Tset Toc,{Rpad {Dbl @1}~-~{2}~,50,.~}~A-{Pagenum}}-
  {Nfj}-
  {Macsec Format}-
}
!
{Setq Macsec,-
  {Cond {Leq {Caps @1},FORMAT},{Ls 1}Format:{Ls 1}{Lin 8}{Nfj},-
    {Leq {Caps @1},DESCRIPTION},{Ls 1}{Restore Lmg}{Fj},-
    ,{Hl {+ @Seclevel,2},{Caps @1}}{Fj}-
  }-
}
!
! Define the list items macros
! Bl is used to begin a new list.  It should be on the same physical
! line with the rest of the text.  It does an initial {Li...}
!
{Setq Bl,{Set.Add1 Numlist}-
  {Set LIST${Numlist},0}-
  {Brk}-
  {Lin 4}-
  {Li @1}-
}
!
! Li is called to start a new item in a list.
! (Bl does this automatically for the first item)
!
{Setq Li,{Ls 1}{Set.Add1 LIST${Numlist}}-
  {Outdent {Size {1}{Setv Listlabel,-
    {Dowhile{Set Listi,@Numlist} {Gt @Listi,1},-
      {LIST${Numlist}}.{Set.Sub1 Listi}-
    }-
    {LIST$1}:~}}-
  }{1}{Listlabel}-
}
!
! El is used to return to the previous list level.
!
{Setq El,{Brk}{Restore Lmg}{Set.Sub1 Numlist}}
!
{Exclude HELP}
{Load SYS$LIBRARY:AUXLIB.GPM,ROMAN}
{Setq Endpage,{Ls 2}{Center A-{Roman @Pagenum}}{Eject}}
{Tsetq Newpage,{Ls 3}}
{Ls 1}{Center APPENDIX A}
{Ls 1}{Center - NOTES -}{Ls 2}
This section contains a complete description of the
GPMDOC system macros in alphabetical order for {version}.
 Some abbreviations are used in the Format descriptions which
require explanation:
!**
{Exclude TEXT}
{Sec GPMDOC}
HELP is provided for all intrinsic GPMDOC macros.
 Macros are explained under the subheading corresponding to the
macro's name.
 In addition,
an explanation of the abbreviations used in the "Format"s can be
obtained under the subheading "Formats".
{Newsec}
{Sec Formats}
!**
{Ls 1}{Lin 6}{OUTDENT 6}
<"{MACRO arg1,arg2,...}":>
{Ls 1}This means you can use the MACRO with the
normal GPMDOC evaluation process.
 If MACRO
takes arguments (arg1, arg2) they are shown.
 Optional arguments are noted in the description.
{Ls 1}
Macros place restrictions or interpretations
on the arguments that you can pass to them.
 The required form of an argument is given in the format description
for each macro according to the following convention:
{Ls 1}{Lin 8}{OUTDENT 8}
"mname"~The argument text, after evaluation, is
used as the {ul name} of a macro.
 Any "mname" can optionally be suffixed with a backslash ("\") followed
by a property table name, otherwise, the null property table
is assumed.
{Ls 1}Since any string
of text can serve as a macro name, "mname" can be
anything.
 However, "mname" denotes the fact that
the macro being described will {ul interpret}
this argument to be a macro name.
{ls 1}{outdent 8}
"n"~~~~~The argument text must evaluate to a {ul number}.
 Either integers or fractional real numbers with decimal points
can be used.
 In cases where an integer is required and a
real number is used, the real number is converted to an
integer by disregarding the fractional part.
 The acceptable range of n may be restricted for some macros,
this is noted in accompanying description.
 For the purposes of arithmetic, a null string is interpreted as zero.
{Ls 1}{Outdent 8}"pred"~~The evaluated argument is considered by the
macro to be a {ul predicate}.
 Predicates designate true/false values with a null value
being considered "true," and any string of actual size greater than
zero is thus considered "false."
 The GPMDOC built-in system predicate macros such as LT, EVEN, etc.
return null when they evaluate true, and (by convention) evaluate to
"1" otherwise.
 Users defining their own predicate-valued macros are urged to
follow this convention.
{ls 1}{outdent 8}
"str"~~~The argument text can evaluate to any text {ul string}.
{ls 1}{restore lmg}
In addition, any of these forms may be preceeded by the letter 'q'.
 For example, "qstr", "qpred" and the like.
 This indicates that the argument is {ul not} evaluated by GPMDOC
before it is given to the macro.
 The macro itself may, if it chooses, evaluate the argument on its own.
 This is used primarily by system macros that must {ul conditionally}
evaluate arguments (e.g. COND, DOWHILE, DOPROP).
{Ls 1}{outdent 6}
<"{D MACRO}":>{LS 1}
This says that the textual definition of MACRO can
be retrieved.
 Some system macros are compiled into an internal coded form with no textual
representation.
 D applied to these macros will give the same result as "<{MACRO}>",
and the D form is not shown for them.
{Ls 1}The "@mname" abbreviation form for arguments is, in operation,
entirely equivalent to the <"{D mname}"> macro form,
and these same remarks apply.
{ls 1}{outdent 6}
<"{SET MACRO,argument}":>{brk}
{LS 1}
This format means that MACRO can sensibly be redefined
using any form of set (SET, TSET, SETQ, SETV, etc.).
 Many system macros will have side effects when set,
such as altering
the margins or causing spacing down the page.
{ls 1}{restore lmg}
The examples try to present several different facets
of the uses for the macro being described.
 (The examples are all shown in upper case for emphasis;
but keep in mind that the case of macro names is not significant.)
{Ls 1}To avoid making the examples trivial, most of them are
"real-life", some easy and others a bit more involved.
 An asterisk next to an example indicates that the
example is a particularly advanced one.
 You may wish to skip over these.
 As a final note, this section does not describe the many macros
available in libraries.
{Exclude HELP}
{P}
{Restore Newpage}
{Setq Endpage,{Ls 2}{Center A-{D Pagenum} [{D Macroname}]}{Eject}}
!**
!
! Start the descriptions
!
!
! ADD1
!
{macdescr ADD1,Add One To Numeric}
<{ADD1 n}>
{macsec description}
The value of ADD1 is one added to n.  It is equivalent
to <{+~n,1}>.
{macsec examples}
{bl}Add one to the current page number:
{ls 1}
{Center <{SET.ADD1 PAGENUM}>}
{Ls 1}
{Li *~}Here is a definition for a macro, CASE, that evaluates one
of its arguments depending on the value of a 'control argument':
{Ls 1}{Center <{SETQ CASE,{{ADD1 @1}}}>}{Ls 1}
A macro reference such as <"{CASE~2,SNURF,BLURF,ERFF}"> would
evaluate to "BLURF" because the "2", in effect, 'selects' argument #3.
 It does this by adding one to the 2, and then using the resulting "3"
as the name of a macro to be evaluated.
 If any of the arguments themselves contained macro calls that were to be
conditionally evaluated, they could be placed in quotes to defer the
evaluation.
{Ls 1}This is not a wholly satisfactory definition, since "<{CASE~0,...}>"
will evaluate to "0" (argument #1),
whereas all other values of the first argument that are out of range will
evaluate null.
 The definition of CASE could be revised a bit using a COND macro to be:
{Ls 1}{Center <{SETQ CASE,{COND {NE @1,0},{{ADD1 @1}}}}>}{Ls 1}
{EL}
{P}
!
! APPEND
!
{macdescr APPEND,Join Two Strings}
<{APPEND str1,str2}>
{macsec description}
The value of APPEND is the text value formed by
appending str1 on the right of str2.
{macsec notes}
{bl}A simple left to right juxtaposition of text is
sufficient to perform this function, so APPEND is only
useful in extended sets (see example).
{el}
{macsec examples}
{bl}Print an extra line after the page heading from now on:
{Ls 1}{Center <{SET.APPEND NEWPAGE,<{LS 1}>}>}{Ls 1}
{EL}
{P}
!
! BEGINTEXT
!
{macdescr BEGINTEXT,Starting Input Line}
<{set BEGINTEXT,str}>
<{BEGINTEXT}>
<{D BEGINTEXT}>
{Macsec Description}
The value of BEGINTEXT is used with INPUT to define the starting
line of the new file.
 If BEGINTEXT is non-null when INPUT is set, GPMDOC will skip over
input lines looking for one that matches BEGINTEXT.
 When one is found, input starts with the line that follows.
{Macsec Notes}
{Bl}The input lines that are skipped are physical lines of the designated
input file, not logical lines.
 This means that continuations are not processed, and also that
comment lines (those that begin with an exclamation point) can
are candidates for BEGINTEXT.
 Comment lines are recommended for BEGINTEXT, as they are otherwise
ignored by GPMDOC when processing a file.
{Li}The line for BEGINTEXT must match exactly.
 The case of letters is significant.
{el}
{Macsec examples}
{bl}Read the file MACLIB.GPM starting at the line following
one which reads "!LIST 3", and finishing at the line which reads
"!END 3":
{Ls 1}
{Center <{TSET INPUT,MACLIB.GPM,STARTTEXT=!LIST 3,ENDTEXT=!END 3}>}
{LS 1}
This sort of thing is useful for a 'macro library' which could contain
sets of macro definitions for different purposes.
{el}
{p}
!
! BIAS
!
{Macdescr BIAS,Set Page Bias}
<{set BIAS,n}> (Default: BIAS=0)
<{BIAS}>
{Macsec DESCRIPTION}
BIAS controls the size of the left hand "gutter."
Its effect is similar to that of setting the left margin,
except that the right margin is also moved a corresponding amount,
so the linelength remains unchanged.
 The sum of BIAS and LMG (current left margin) must always be positive.
{Macsec NOTES}
{Bl}BIAS is useful for printing documents on varying devices which
start printing at different locations.
{Li}Setting BIAS has no effect on the values of LMG or RMG.
{El}
{P}
!
! BRK
!
{macdescr BRK,Force Line Break}
<{BRK}>
{MACSEC DESCRIPTION}
This macro is identical to <{LS~0}> or <{LS}>.
 It causes the text line
currently being assembled to be flushed to the output stream.
 This is termed a "line break".
 Right justification is not applied,
regardless of whether or not it is enabled.
{MACSEC NOTES}
{BL}Line break is normally used to force printing to begin on a new
line when line fill is on, or whilst typing in the middle of a line,
or within a macro.
 Note that line fill being off (non-null) forces
an automatic line break after reading each input line.
{EL}
{macsec examples}
{BL}This example shows how to print successive items on
separate lines when line fill is enabled, using BRK:
{ls 1}
A. Two eggs<{brk}>B. Three cups flour<{brk}>C. Two tbsp. butter
{ls 1}
would print as:
{ls 1}
A. Two eggs{brk}B. Three cups flour{brk}C. Two tbsp. butter
{el}
{P}
!
! BSLACK
!
{Macdescr BSLACK,End-of-Page Runout}
<{set BSLACK,n}> (Default: BSLACK=0)
<{BSLACK}>
<{D BSLACK}>
{MACSEC DESCRIPTION}
The value of BSLACK is used by the system to determine when
to run out the rest of a page during line skipping.
Assuming BSLACK has the value "n" and an attempt is made to skip
lines when less than "n" lines remain on the page, the page is
simply run out, and an ENDPAGE condition occurs.
(Line skipping means either an <{LS...}> or
a <{SET~LINENUM,...}>.)
{MACSEC NOTES}
{BL}The value for n cannot be negative.
{LI}BSLACK can be used to avoid such situations as the first line
of a paragraph being printed at the bottom of a page.
{LI}Setting BSLACK to zero effectively nullifies any BSLACK action.
{EL}
{P}
!
! CAB
!
{MACDESCR CAB,Close Angle Bracket}
<{CAB}>
{MACSEC DESCRIPTION}
Evaluates to ">".
{MACSEC NOTES}
{BL}This macro, and its companion <{OAB}>, are used in situations
where the quote symbols are needed without causing the effect
of quoting, or where they appear in an unbalanced way.
{EL}
{MACSEC EXAMPLES}
{BL}Computer programs often use the GPMDOC quote symbols to
signify the operations of comparison (less than and greater than).
For instance:
{LS 1}
{center IF A {OAB} B AND A {CAB} C}
{LS 1}
in GPM would print as:
{LS 1}
{Center IF A  B AND A  C}
{LS 1}
The CAB (and OAB) macros could be used:
{LS 1}
{CENTER IF A <{OAB}> B AND A <{CAB}> C.}
{LS 1}
which evaluates correctly. (It would also be possible to
achieve the same effect in this example by quoting the entire
line, or with the use of INFORMAT.)
{EL}
{P}
!
! CAPS
!
{macdescr CAPS,Capitalize Text}
<{CAPS str}>
{macsec description}
The value of a call to CAPS is str, except all lower
case letters are replaced with their equivalents in
upper case.
 It is the same as:
{ls 1}
     <{REPLACE str,abc...xyz,ABC...XYZ}>
{macsec examples}
{bl}Print the text of the macro TITLE capitalized:
{ls 1}{Center <{CAPS @TITLE}>}
{Li *~}Read "FILE1" if the user responds "No" and "FILE2" if
the user responds "Yes"
{Ls 1}{Nfj}
<{TSET INPUT,->
  <{COND ->
    <{LEQ {CAPS {SUBSTR {QUERY Enter Yes or No: },1,1}},N},->
    <FILE1,,FILE2->
  <}->
<}>
{Fj}
{Ls 1}Note that only the first cahracter of the response
is compared.
 It is capitalized so that regardless of whether the user types
"N" or "n",
it is still perceived as a 'no' response.
{Ls 1}You might want to write a predicate macro that would issue a general
yes/no question (supplied as an argument) to be true if the response
is affirmative,
and false if the response is negative.
 As an enhancement,
the macro will loop until it gets one of the two responses.
{Ls 1}{Nfj}
<{SETQ YNQ,->
  <{SET YNQ$R}->
  <{DOWHILE {LNE @YNQ$R,N}{LNE @YNQ$R,Y},->
    <{SET YNQ$R,{CAPS {SUBSTR {QUERY @1},1,1}}}->
  <}->
  <{COND {LEQ @YNQ$R,N},1}->
<}>
{Ls 1}{Fj}
{el}
{P}
!
! CENTER
!
{macdescr CENTER,Center a Text Line}
<{CENTER str}>
{macsec description}
CENTER prints str padded on the left with hard spaces so as to cause it to
appear centered between the current left and right margins.
 A line break is forced before and after str is printed.
 The value of the CENTER macro is always null,
(the centered text is sent directly to the output stream).
{macsec notes}
{bl}If str is longer than <{LINELENGTH}>, the text will
be printed on multiple, uncentered lines.
{el}
{macsec examples}
{bl}Print the text "SUBMITTED IN PARTIAL FULFILLMENT" centered on line 30:
{Ls 1}{Center <{SET LINENUM,30}{CENTER SUBMITTED IN PARTIAL FULFILLMENT}{BRK}>}
{Ls 1}
{Li}Print the text stored in the macro TITLE, centered at the top of every
page:{Ls 1}{Center <{SETQ NEWPAGE,{CENTER @TITLE}}{BRK}>}{LS 1}
{el}
{P}
!
! CODE
!
{Macdescr CODE,Define Internal Macro Code}
<{CODE mname,str}>
{Macsec Description}
CODE is used to define mname as an internal code sequence in order to
improve efficiency, or to make available functions that cannot be realistically
coded in macro form.
 Str must represent a legitimate internal code string.
 Evaluation of CODE will 'compile' STR and bind the resulting code
to mname as a system macro.
 The value of CODE is null.
{Ls 1}As this is not a systems reference document, no further elaboration
of CODE is given here.
{P}
!
! COND
!
{MACDESCR COND,Conditional Evaluation}
<{COND qpred1,qstr1,qpred2,qstr2, ...}>
{MACSEC DESCRIPTION}
COND will conditionally evaluate one of str1,~str2,~etc. in
the following way.
 First, pred1 is evaluated.
 If it is null (true), then the value of the COND becomes the
evaluation of str1.
 Otherwise, the COND continues by evaluating pred2, and if
it is true, the value of COND becomes the value of str2.
{Ls 1}COND allows an indefinite number of predicate-string
pairs.
 Since any unspecified arguments are taken as null strings,
if none of the predicates evaluates null (true), then an implied
null predicate will be 'seen' past the given arguments and the
following implied null string will be returned as the value.
{macsec notes}
{Bl}While any text may be given for a predicate, generally
one of the system predicate macros is used.
 These predicates are described fully under their own sections.
{Ls 1}For numeric tests, LT, LE, GT, GE, NE, EQ, EVEN and ODD
are the system predicates.
{Ls 1}For comparing strings, LLT, LLE, LGT, LGE, LNE, and LEQ
are the system predicates.
{Li}All system predicates use the string "1" as the standard
'false' value.
 Uses writing their own predicate-valued macros are urged to
adopt this convention.
{EL}
{macsec examples}
{BL}If less than ten lines remain on the page then skip to a new
page:
{LS 1}
{CENTER <{COND {LT {- @LINENUM,@PAGELENGTH},10},{SET LINENUM,1}}>}
{LS 1}
(Note that in this example qpred2 and qstr2 are omitted,
so they are assumed to be null.)
{LI}Define a macro <{IFLINES n}> to do the same thing, allowing any
number n.
{LS 1}
{NFJ}
<{SETQ IFLINES,{COND {LT {- @LINENUM,@PAGELENGTH},@1},->
     <{SET LINENUM,1}}}>
{FJ}
{LI}Move the left margin out 5 spaces, unless it is less than
5 from the edge already, in which case set it to 1.
{LS 1}
{CENTER <{SET LMG,{COND {LE @LMG,5},1,,{- @LMG,5}}}>}
{CENTER or}
{CENTER <{COND {LE @LMG,5},{SET LMG,1},,{SET.- LMG,5}}>}
{EL}
{p}
!
! CREPROP
!
{macdescr CREPROP,Create Property Table}
<{CREPROP str}>
{Macsec Description}
CREPROP generates a property table with the name "str".
 Once such a table has been created, named values can be
set in the table using the property table name suffixed
onto the macro name with a backslash ("\").
{Macsec Notes}
{bl}Only one property table is initially defined - the so-called
null property table.
 The null property table is where all system defined macro values
reside, and the table which, by default, is referred to if a
macro name contains no property table reference.
{li}TSET stacks for the same name in different property tables are
distinct.
{li}DELPROP can be used to eliminate a property table and all
associated values when they are no longer of use.
{li}DOPROP allows examination of all the values of a property
table.
{Li}Numeric names in property tables other than the null table
do {ul not} refer to argument values, numeric names function no
differently from other names in these tables.
{El}
{macsec examples}
{bl}Create a property table "SECNUM" and set name "I" in it
to zero:
{Ls 1}{Center <{CREPROP SECNUM}{SET I\SECNUM,0}>}{Ls 1}
{li}The description of DOPROP contains more examples of
property tables.
{el}
{p}
!
! CS
!
{MACDESCR CS,Create Control Sequence}
<{CS str}>
{Macsec description}
The value of CS is a control sequence for str.
 A control sequence is printed as "str" but has a defined length of
zero, regardless of the length of str.
 Str must not contain any overstrikes or embedded control sequences.
{Macsec notes}
{Bl}CS is primarily useful in creating device-dependent control
sequences that are embedded in the text, but which should not figure
into line length calculations (e.g. centering, justification, etc.).
{el}
{p}
!
! D
!
{MACDESCR D,Retrieve The Definition of a Macro}
<{D mname}>
{macsec description}
The value of D is the string of characters which form the
definition of mname.
{macsec notes}
{Bl}The definition retrieved is not evaluated, so this is quite
different from <{mname ...}> if the definition contains quotes
or macro calls.
{LI}You can also apply D to arguments as in "<{D~3}>" which will
give the string of text passed as argument 3, without evaluating it.
{LI}D applied to system functions will result in the string
"SYSTEM", since these macros are not defined internally
using text, but rather as operational sequences using
a special code.
{Li}There is an abbreviated form of D which can be used when
an argument in a macro call is to evaluate to the definition
of some other macro.
 If an argument begins with the at-sign ("@"), it is considered
to be such an argument.
 The text of the argument following the at-sign is evaluated
in the normal way, and the result is taken as an "mname".
 The value of the argument becomes the definition of that mname.
 There are examples of this abbreviation below.
{Ls 1}Note that to have this effect,
the leading "@" cannot be a product of the evaluation,
it must be the {ul actual first character} of the argument text itself.
{EL}
{macsec examples}
{BL}Print the centered definition of a user-defined macro TITLE
without evaluating it:
{LS 1}
{center <{CENTER {D TITLE}}>}{BRK}{Center or}{Brk}
{Center <{CENTER @TITLE}>}
{LI}Suffix the string <{LS 1}> onto NEWLINE without upsetting
things by evaluating the text already in NEWLINE:
{LS 1}
{CENTER <{SET NEWLINE,{D NEWLINE}<{LS 1}>}>}
{center or}
{CENTER <{SET.APPEND NEWLINE,<{LS 1}>}>}
{LS 1}
Note that a form such as:
{Ls 1}{Center <{SET NEWLINE,@NEWLINE<{LS 1}>}>}{Ls 1}
would {ul not} be satisfactory because the "@" applies to
the resulting text of the {ul entire} argument (including the <"<{LS~1}>">,
not just the initial part of it.
{el}
{P}
!
! DATE
!
{Macdescr DATE,Date Text}
<{DATE}>
{Macsec Description}
The value of DATE is the date-of-year in the form DD-MMM-YYYY.
 For example, 08-SEP-1981.
{p}
!
! DBL
!
{macdescr DBL,Double-Strike (Bold) Text}
<{DBL str}>
{macsec description}
<{DBL~str}> is equivalent to <{OS~str,str}>.
 Its value is str overstruck with itself.
{macsec notes}
{bl}DBL can be a good substitute for italics.
{el}
{macsec examples}
{bl}Print "THE GETTYSBURG ADDRESS", centered and boldface.
{LS 1}
{CENTER <{CENTER {DBL THE GETTYSBURG ADDRESS}}>}
{ls 1}
This will print as:
{ls 1}
{CENTER {DBL THE GETTYSBURG ADDRESS}}
{li}Define a macro REALBOLD that will overstrike an image
with itself sixteen times:
{ls 1}
{center <{SETQ REALBOLD,{DBL {DBL {DBL {DBL @1}}}}}>}
{EL}
{P}
!
! DELPROP
!
{Macdescr DELPROP,Delete a Property Table}
<{DELPROP str}>
{Macsec Description}
DELPROP erases a property table and all values and stacks associated
with it.
 If further use is to be made of the eradicated property table, a
new CREPROP must be performed for it.
{p}
!
! DIAG
!
{macdescr DIAG,Enter Diagnostic Subsystem}
<{DIAG}>
{Macsec Description}
DIAG is used for system testing.
 It enters the system debugger.
 The value of DIAG is null.
{Ls 1}As this is not a systems manual, no further explanation
of DIAG is offered here.
 This function is for debugging and development, and should not
ordinarily be used.
{P}
!
! DISPLAY
!
{macdescr DISPLAY,Print Message on Terminal}
<{DISPLAY str}>
{macsec description}
DISPLAY causes the value of str to be displayed on your
terminal. The value of DISPLAY itself is null.
{macsec notes}
{BL}No formatting is applied to str before it is sent to
the terminal.
{LI}QUERY can be used for messages where a response is
desired.
{EL}
{macsec examples}
{bl}Display an instructional message and begin receiving input from the
terminal:
{ls 1}
{nfj}
<{DISPLAY <Enter your text, use Control-Z to finish>}->
          <{TSET INPUT,TT:}}>
{LS 1}
{FJ}
{LI *~}Process the first 10 chapters of a document which has
been segmented into files: CH1.GPM, CH2.GPM, etc. Precede
each with an informative message to tell you that GPMDOC is
still alive.
{ls 1}
{nfj}
     <{DOWHILE {LT @CHAP,10},{SET.ADD1 CHAP}->
        <{DISPLAY PRINTING CHAPTER {CHAP}}->
        <{TSET INPUT,CH{CHAP}.GPM}}>
{FJ}
{EL}
{P}
!
! DOPROP
!
{macdescr DOPROP,Evaluate Property Table}
<{DOPROP str1,qstr2,str3}>
{Macsec Description}
DOPROP uses str1 (case irrelevant)
as a property table name (the backslash is not specified).
 Qstr2 is repeatedly evaluated for each non-null
value in the indicated property table.
 The context of this evaluation has <{D~1}> (argument one) set to the
macro name in the property table (without the table name suffix), and
<{D~2}> set to its corresponding value.
{Ls 1}If str3 evaluates to the string "UP" (case irrelevant), then
the table names are presented in ascending sorted order.
 Similarly, "DOWN" will cause the names to be sorted in descending
order.
 Otherwise, the names are presented in an unpredictable order.
 In all cases, all the name-value pairs are evaluated exactly once.
{Ls 1}The value of DOPROP is the concatenated result formed by the
successive evaluations of qstr2.
{Macsec Notes}
{bl}For UP and DOWN sorts, names which are numeric will be sorted
as numbers, not as alphanumerics.
 For example, the "2" is, as a number, less than "10", but
considered as a text string, "2" would be greater than "10".
{el}
{macsec examples}
{bl *~}DOPROP can be useful for generating sorted indices.
 First, define a macro at the beginning of the document such as:
{Ls 1}{Center <{SETQ INDEX,{SET.APPEND {1}\INDEX,<,>{PAGENUM}}}>}
{Ls 1}This macro, when invoked in the document with a reference such
as "<{INDEX Pancakes}>" will append a comma and the current page number to
the value for PANCAKES on the INDEX property table.  Before using
the macro, it is also necessary to establish the property table
with a macro call such as: "<{CREPROP INDEX}>".
{Ls 1}At the end of the document, you can 'dump' this property table in
a neat format.
 The following DOPROP macro shows one way to do this:
{Ls 1}{Center <{DOPROP INDEX,{RPAD {SUBSTR @1,2},30,.}{2}{BRK},UP}>}
{Ls 1}This will print successive lines of the form:
{Ls 1}{Center <PANCAKES.....................18,45,104>}{Ls 1}
The SUBSTR is used to eliminate the initial comma which the INDEX macro
puts in front of each page number (including the first).
{el}
{p}
!
! DOWHILE
!
{Macdescr DOWHILE,Repeated Evaluation}
<{DOWHILE pred,qstr}>
{MACSEC DESCRIPTION}
DOWHILE is evaluated by first evaluating the given predicate, and
if it is true, evaluating qstr.
 This cycle is repeated until pred becomes non-null (false).
 The value of the DOWHILE is
the concatenated values of the successive evaluations of qstr.
{macsec notes}
{BL}Be careful that the given predicate will eventually become
false, or an "infinite loop" will result, and you will have
to abort GPMDOC.
{EL}
{macsec examples}
{BL *~}Print the numbers from 1 to 20 on successive lines down
the left margin of the page:
{Ls 1}{Center <{SET NUM,0}{DOWHILE {LT {SETV.ADD1 NUM},20},{NUM}{BRK}}>}
{LS 1}Note that the macro NUM is the 'counter,' and that it is
initialized to zero.
{LI *~}Print ten numbered copies of a document:
{LS 1}
{Center <{SET D#,0}{DOWHILE {LT {SETV.ADD1 D#},10},{TSET INPUT,DOC.GPM}}>}
{ls 1}
DOC.GPM presumably contains references to <{D#}> which will
contain the document number as a result of the DOWHILE.
{EL}
{P}
!
! DSIZE
!
{macdescr DSIZE,Size of Defined Macro}
<{DSIZE mname}>
{Macsec Description}
The value of DSIZE is the number of print columns in the definition
of mname.
 DSIZE is equivalent to <{SIZE~{D~mname}}> or <{SIZE~@mname}>,
but is simpler and more efficient.
{Macsec Notes}
{bl}If the definition of mname contains no overstrikes
then the value of DSIZE is equal to the number of characters in the
definition.
{li}DSIZE applied to coded system macros (those for which <"{D mname}">
is the same as <"{mname}">, will yield the same as <"{SIZE {mname}}">.
{el}
{p}
!
! DUPL
!
{macdescr DUPL,Duplicate a String}
<{DUPL str,n}>
{macsec description}
The value of DUPL is str repeated n times. If n is zero,
the value of DUPL is null.
{macsec notes}
{BL}N must be non-negative.
{el}
{macsec examples}
{bl}Produce 20 periods:
{ls 1}
{nfj}
        <{DUPL .,20}>
{fj}
{ls 1}
{li}Print a line of hyphens across the page:
{ls 1}
{nfj}
        <{BRK}{DUPL -,@LINELENGTH}>
{FJ}
{LI *~}Define a macro CPAD, that will return its argument
text prefixed with the correct number of hard spaces to
cause the argument to be centered on the line (assuming it is printed
from the left margin).
{ls 1}
{nfj}
       <{SETQ CPAD,{DUPL @HS,->
            <{DIV {- @LINELENGTH,{DSIZE 1}},2}}{D 1}}>
{FJ}
{Ls 1}
This macro calculates the number of hard spaces to produce
by subtracting the size of the argument text from the
length of the line, and dividing it by two. The argument text
is appended onto the right of these hard spaces.
{Ls 1}
The advantage that this macro might have over the system
CENTER macro is that CPAD only returns the argument text
padded on the left with hard spaces.
 It does not cause any line breaks as does CENTER.
 This means it would be possible for
you to print text on the same line to the right of the centered
text.
{el}
{p}
!
! EJECT
!
{macdescr EJECT,Form Feed}
<{EJECT},> (Default: See Description)
<{D EJECT},>
<{set EJECT},>
{macsec description}
<{EJECT}> is initialized with the character codes or
sequence needed to cause a "form feed" (page eject)
on the system standard hard copy device.
{macsec notes}
{bl}If you are directing OUTPUT to other than the standard
device, it may be advantageous to set EJECT to a suitable
value first.
{li}<{EJECT}> has no effect on <{PAGENUM}>, and for
that reason is generally only used in ENDPAGE.
{el}
{macsec examples}
{bl}Skip to a new page at the bottom of each page
{ls 1}
{nfj}
        <{SETQ ENDPAGE,{EJECT}}>
{ls 1}
{fj}
{el}
{p}
!
! END
!
{macdescr END,Terminate GPMDOC Session}
<{END}>
{macsec description}
An evaluation of <{END}> will cause GPMDOC to flush its
output stream, close all files, and exit.
 The value of END is irrelevant.
{macsec notes}
{BL}You can exit from GPMDOC by finishing input from the
initial input file (see the description of INPUT).
{LI}END can be used at any point in any file regardless
of present activity.
{Li}The use of END is normally discouraged,
as document files that contain it cannot be included (TSET INPUT)
from other document files.
{EL}
{macsec examples}
{BL}If <{FILENAME}> is null, print an error message and
 terminate the session.
{ls 1}
{nfj}
<{COND {LEQ @FILENAME},{DISPLAY YOU HAVEN'T SPECIFIED><->
     <A FILE!}{END}}>
{FJ}
{EL}
{P}
!
! ENDPAGE
!
{macdescr ENDPAGE,Ending Page Event}
<{set ENDPAGE,str}> (Default: <ENDPAGE={EJECT}>)
<{ENDPAGE}>
<{D ENDPAGE}>
{macsec description}
When the value of LINENUM becomes greater than the
value of PAGELENGTH, an ENDPAGE event occurs, which
causes the following sequence of events:
{bl}The line to be printed and any other text in the
output stream are put aside.
{li}NEWLINE is TSET to null, SPACING is TSET to one,
LMG is TSET to 10 and RMG is TSET to 75.
{li}<"{ENDPAGE}"> is evaluated.
{li}NEWLINE, SPACING, LMG and RMG are all restored.  This
completes the ENDPAGE event.
{el}
{macsec notes}
{bl}If NEWLINE, SPACING, LMG or RMG are changed by
ENDPAGE, changes will only have effect during the ENDPAGE
event, as these macros are TSET and RESTOREd.
 If you desire a permanent change, first do a RESTORE, and
then SET your desired permanent value for the macro.
 (This will become the value restored at the end of the ENDPAGE
condition.)
 Then TSET back the value for the ENDPAGE context.
{li}NEWPAGE and ENDPAGE conditions are inhibited while
the ENDPAGE condition is being processed.
{el}
{macsec examples}
{bl}Print the current page number, centered between hyphens
at the bottom of every page:
{ls 1}
{center <{SETQ ENDPAGE,{CENTER - {PAGENUM} -}}>}
{LI *~}In documents that are to be bound after they
are printed, it is frequently necessary to provide a
"gutter" on each page so that printing does not disappear
down into the binding.  If printing is to be two-sided,
then odd-numbered pages will need to have this gutter
on the left, and even-numbered pages will have it on the
right (or vice-versa).  This, in effect, necessitates
"sliding" the text horizontally back-and-forth on
successive pages.  The place to do such sliding is
ENDPAGE.  (NEWPAGE would be too late, since the margin
for the first line has already been formed when NEWPAGE occurs.)
{ls 1}
<{SETQ ENDPAGE,->{Brk}
<   {SET.+ BIAS,{COND {EVEN @PAGENUM},5,,-5}}}>
{El}
{P}
!
! ENDTEXT
!
{macdescr ENDTEXT,Ending Input Line}
<{set ENDTEXT,str}>
<{ENDTEXT}>
<{D ENDTEXT}>
{Macsec Description}
If ENDTEXT is non-null each physical line read by GPMDOC is compared
to the definition of ENDTEXT.
 If it matches, INPUT is RESTOREd immediately.
 The ENDTEXT line itself is discarded.
{Macsec Notes}
{Bl}The input lines that are examined are physical lines of the designated
input file, not logical lines.
 This means that continuations are not processed, and also that
comment lines (those that begin with an exclamation point)
are candidates for ENDTEXT.
 Comment lines are recommended for ENDTEXT, as they are otherwise
ignored by GPMDOC when processing a file.
{Li}The line for ENDTEXT must match exactly.
 The case of letters is significant.
{Li}The ENDTEXT macro is most useful to terminate the context of a
pseudo-read.
 To conditionally skip over text in the input stream,
the SKIPTEXT macro is more useful.
{el}
{p}
!
! EQ
!
{Macdescr EQ,Predicate Comparison for Equality}
<{EQ n1,n2}>
{Macsec Description}
EQ evaluates to null (true) if "n1" is equal to "n2",
otherwise it evaluates to "1" (false).
{Macsec Examples}
See COND for uses of system predicate macros.
{P}
!
! EVEN
!
{macdescr EVEN,Predicate Test for Numeric Even}
<{EVEN n}>
{Macsec description}
This predicate will evaluate null if the given argument is an even
number (zero and negative even numbers are even).
 Otherwise it evaluates to "1" (false).
!
! FILL
!
{Macdescr FILL,Line Fill Flag}
<{set FILL,pred}> (Default: FILL=1)
<{FILL}>
<{D FILL}>
{Macsec Description}
FILL is a flag that controls line fill mode on input.
 If fill is enabled (FILL null) then no line break is forced after
reading logical lines of input text.
 This allows output to be buffered in the output stream until there
is enough to just about fit on the line.
{Macsec Notes}
{Bl}The FJ and NFJ macros are normally used to control FILL, as
right justification is usually desired in concert with line fill.
{el}
{P}
!
! FJ
!
{macdescr FJ,Enable Fill and Justify Flags}
<{FJ}>
<{D FJ}>
{macsec description}
<{D~FJ}> is the string; <"{SET~FILL}{SET~JUST}">.
It enables both line fill and right justification.
 The value of FJ is, by the above definition, null.
{P}
!
! GE
!
{Macdescr GE,Predicate for Greater or Equal}
<{GE n1,n2}>
{Macsec Description}
GE evaluates to null (true) if "n1" is greater than or equal to "n2",
otherwise it evaluates to "1" (false).
{Macsec Examples}
See COND for uses of system predicate macros.
{P}
!
! GT
!
{Macdescr GT,Predicate Comparison for Greater Than}
<{GT n1,n2}>
{Macsec Description}
GT evaluates to null (true) if "n1" is greater than "n2",
otherwise it evaluates to "1" (false).
{Macsec Examples}
See COND for uses of system predicate macros.
{P}
!
! HS
!
{MACDESCR HS,Hard Space Character}
{TSET HS,%}
<{set HS,str}> (Default: HS=~ (tilde))
<{HS}>,
<{D HS}>
{Restore Hs}
{MACSEC DESCRIPTION}
HS is used to alter or reference the Hard Space Character of the
system. A hard space is a character (other than a space) that
GPMDOC translates to a space just before the text is printed.
The hard space can be used where it is desirable to prevent
line-breaking or right justification.
{MACSEC NOTES}
{BL}Only the first character of str is taken for the new
hardspace.
{LI}Hard spacing can be disabled entirely by setting HS to a blank.
{LI}It is impossible for the current hard space character to be
printed, it must be changed by setting HS first.
{LI}Note that hard space translation is applied just as the
line is being printed. Thus if the hard space character is
changed several times within a line, only the last change will
have effect.
{LI}Certain system macros (e.g. T (Tab), CENTER, LPAD, RPAD) can
emit hard spaces.
{EL}
{MACSEC EXAMPLES}
{BL}Insert ten hard spaces:
{LS 1}
{Tset Hs,%}
{CENTER <{DUPL @HS,10}>}
{CENTER or}
{BRK}
{CENTER <{DUPL ~,10}>}
{Restore Hs}
{LI}
Turn off hard spaces so the tilde can be printed:
{Tset Hs,%}
{Ls 1}{Center <{TSET HS, }> A tilde looks like "~"<{BRK}{RESTORE HS}>}
{El}
{Restore Hs}
!
! INDEX
!
{Macdescr INDEX,Locate Position of Substring}
<{INDEX str1,str2}>
{Macsec Description}
The value of INDEX is the numeric position of the first occurrence
of "str2" within "str1".
 If "str2" is not in "str1", the value of the INDEX macro is zero.
 If "str2" is null, the value of INDEX is one.
{Macsec Notes}
{Bl}The value of INDEX is the position of the substring (str2),
not the offset.
 It is thus useful for use in the SUBSTR macro (see description).
{el}
{Macsec Notes}
{Bl}Display a message if the value of the macro FILE does not
contain the substring ".GPM":
{Ls 1}{Center <{COND {EQ {INDEX @FILE,.GPM}},{DISPLAY WRONG FILE!}}>}{Ls 1}
{El}
!
! INFORMAT
!
{Macdescr INFORMAT,Logical Line Formatting Flag}
<{set INFORMAT,pred}> (Default: INFORMAT=null)
<{INFORMAT}>
<{D INFORMAT}>
{Macsec Description}
The INFORMAT flag controls whether any processing is applied to input.
 If it is false (non-null) then input lines are processed exactly as read.
 Continuation hyphens are taken as ordinary characters,
and comment lines (those that begin
with an exclamation point) are processed as any other line.
 No evaluation of macros takes place.
 Text is sent to the output stream exactly as it is read.
{Macsec Notes}
{Bl}Note that output processing (e.g. FILL, JUST) will still be
applied according to the setting of the flags.
{li}Processing with INFORMAT set false is faster because less computation
is required.
{Li}In general, INFORMAT is used only in an INPUT TSET, where an
ENDTEXT flag can be specified.
 Otherwise, since embedded macros are not evaluated it is impossible
to get INFORMAT set true once it has been set false.
{el}
{p}
!
! INPUT
!
{MACDESCR INPUT,Define the Data Input File}
<{set INPUT,str,mname1=str1,mname2=str2,...}>
{macsec description}
Evaluation of a SET form on the system name INPUT causes GPMDOC
to read succeeding lines from the device/file specified by "str".
 If a TSET form is used on INPUT, the current file is not closed
out, and a subsequent RESTORE (or end-of-file) on the new
file will cause input to resume from the original file at the
line following the one which caused the TSET.
 In general, "<{SET INPUT,...}>" switches input to a different
file, while a TSET suspends the current file temporarily
in order to process a new one.
{Ls 1}Input completes when an end-of-file condition is encountered,
when a <{RESTORE INPUT}> occurs (for a TSET), or when
a previously defined ENDTEXT line is seen.
{ls 1}Arguments out past "str" should evaluate to text of
the form: "mname=str" (e.g. "LMG=40").
 Arguments of this form are termed "keyword" arguments,
and will be TSET by GPMDOC before initiating
the new input stream, and be automatically RESTOREd by GPMDOC when
the input is complete.
 Such keyword arguments are only significant on an INPUT TSET,
they are ignored on INPUT SETs.
{Ls 1}A null "str" is termed a 'pseudo-read.'
 It signifies that input should continue from the current file.
 This is useful for forms which use the keyword arguments
to create a 'nested context'.
{macsec notes}
(INPUT is somewhat implementation dependent, these notes
describe the VAX/VMS version.)
{BL}INPUT TSETs can only be nested to a system-imposed limit
(between 10 and 20).
 Pseudo-reads do not count toward that limit.
 INPUT SETs simply cause the current file to be closed, and
the designated one to be opened.
 There is thus no limit to the number of times this can be done.
{LI}The STARTTEXT and ENDTEXT macros are useful in conjunction
with INPUT TSETs.  Either or both can be specified as keyword
arguments to the INPUT set to cause the input to begin or end
at predetermined points in the file.
 The INFORMAT system macro flag is also useful in the same
way to cause a section of a document to be printed {ul literally}.
{LI}"Str" should be a standard device/file specification. If
your specification includes commas it must be in quotes ("<<>>") to
avoid an incorrect argument scan.
{LI}When GPMDOC is first started, it issues several INPUT sets
automatically.
 First is input for the auxilliary built-in
function definitions contained in a file called GPMBIF.GPM
on a system account.
 It then attempts to read a file called
GPMSTART on your account.
 (If this file doesn't exist, no error is reported.)
 GPMDOC finally evaluates the command line and exits.
If the command line is empty, then INPUT is automatically
TSET to your terminal (the message "READY" is printed to
inform you of this condition).
 A control-Z signals an end-of-file from the terminal, and
can thus be used to exit GPMDOC when in this mode.
 The initial commands you specify, either in the command line
or from your terminal can SET or TSET INPUT for the files
you want to process.
{Ls 1}You may want to put frequently used
"private" macros in your GPMSTART file.
{LI}INPUT TSETs can be useful in breaking up large documents.
 Each part of a document can be put in a separate file.
 These files can then be edited and
run off individually.
 To run off all of them, construct another
file which issues INPUT TSETs to each of the individual files in turn.
 This "master file" might also contain, or read in, the definitions
of any macros that are referenced frequently in the document files.
{Li}A SET on INPUT does not have any effect until the next line is
read in,
that is, not until the current line of input has been processed.
 An INPUT TSET can be issued at any point and has immediate effect.
The remainder of the line (if any) where the TSET occurred will be
processed when input is restored.
{EL}
{MACSEC EXAMPLES}
{BL}Start GPMDOC and read and process the text in WHITEPAP.GPM.
 As no output file is specified, output will be directed at
the standard output stream.
 GPMDOC will exit when the file has been processed.
{LS 1}
{CENTER <GPMDOC6 {SET INPUT,WHITEPAP.GPM}>}
{Ls 1}This shows method of specifying a command line to GPMDOC.
{LI}This macro reference will read and process the text in the
file [1,40]HELP.GPM.
 When the end-of-file is reached, input will be resumed
from the point in the file which issued this TSET.
{LS 1}{CENTER <{TSET INPUT,<[1,40]HELP.GPM>}>}{LS 1}
Note the use of the angle brackets to shield the comma in the
directory string "[1,40]".
{LI}Read and process text from the user's terminal until
an end-of-file (control Z) is entered.
{LS 1}
{CENTER <{TSET INPUT,TT:}>}
{LI}Define a macro that will read and process text from the
user's terminal until *EOF is typed in:
{Ls 1}{CENTER <{SETQ REOF,{TSET INPUT,TT:,ENDTEXT=*EOF}}>}
{LS 1}
{LI}Insert a "boiler-plate" paragraph from a file that the
user specifies when the document is run off:
{Ls 1}{CENTER <{TSET INPUT,BOILER{QUERY WHICH PARAGRAPH?}.GPM}>}
{LS 1}
Note:  This example assumes that the boiler-plate paragraphs
all have the form BOILERXXX.GPM; all the user need do in this
case is enter which XXX is desired.
{LI}Print a form letter using an address from a file of
addresses, "ADDR.GPM".
 This file is assumed to have the form:
{Ls 1}{Nfj}
   !**PAULS PIZZA
   PAUL'S PIZZA EMPORIUM
   140 SAN PEPPERONI DR.
   AUSTIN, TEXAS
   !**
   !**TERRYS TOYS
   TERRY'S TOY SHOP
   #1 NORTH POLE
   ARTIC CIRCLE
   !**
      :
      :
{Ls 1}{Fj}
The user will specify which address to use when the letter is run.
{Ls 1}{Nfj}
   !
   !Print the Sender's Address
   !
   <{LIN 40}>
   Acme Collection Agency
   Hardline Ave.
   Cleveland, Ohio
   <{RESTORE LMG}>
   !
   !Now Print the Address
   !
   <{TSET INPUT,->
   <  ADDR.GPM,STARTTEXT=!**{Query Recipient?},ENDTEXT=!**}>
   !
   !Do the Body
   !
   Dear person:<{Brk}{Fj}>a check of our records
      :
      :
{Ls 1}{Fj}
{LI}Fortran programs contain characters that could cause
them to be erroneously processed (e.g. a minus sign at
the end of a line). This example shows how to insert the
text of such a program in a document using a literal read.
{Ls 1}{Center <{TSET INPUT,PROGRAM.FOR,INFORMAT=1,FILL=1,JUST=1}>}
{Ls 1}
{Li}This example shows how to print a section of a document exactly
as it appears using a pseudo-read.
{Ls 1}{Nfj}
   :
   :
<!> Ordinary text
   :
<{TSET INPUT,,INFORMAT=1,FILL=1,JUST=1,Endtext=!**}>
   :
<!> Text to be printed as it appears
   :
!**
   :
<!> Continue with ordinary text
   :
   :
{Ls 1}{Fj}
Note that here ENDTEXT is used to designate a marker ("!**") that will cause
the pseudo-read to terminate and thus end literal input.
Reading then continues on in the ordinary way after the **.
{Li *~}Set up a file to print the first three chapters of the document
SHIPLOG. Each chapter is in a separate file.
{Nfj}{Ls 1}
    <{TSET INPUT,SHIPLOG1.GPM}>
    <{TSET INPUT,SHIPLOG2.GPM}>
    <{TSET INPUT,SHIPLOG3.GPM}>
              or
    <{DOWHILE {LT @LOG#,3},{SET.ADD1 LOG#}->
       <{TSET INPUT,SHIPLOG{LOG#}.GPM}}>
{Fj}
{El}
{P}
!
! JUST
!
{Macdescr JUST,Right Justification Flag}
<{set JUST,pred}> (Default: JUST=null)
<{JUST}>
<{D JUST}>
{Macsec description}
JUST is the GPMDOC right justification flag.
 If true (null) then all lines that are broken off the output stream
for printing have spaces inserted in them to cause the rightmost
character to line up with the right margin.
 This action will only be applied if the line is broken off as a
consequence of the output stream accumulating as much or more text than will
fit on a single output line.
 Lines printed as a consequence of line breaks are never justified.
{Macsec Notes}
{bl}FJ and NFJ are normally used to manipulate FILL and JUST together.
 Under normal circumstances, FILL should be enabled when JUST is enabled.
{Li}Spaces are inserted only at points in the line where spaces already
exist.
 Spaces in the line are never removed.
 The spaces are distributed throughout the lines in such a way as
to reduce the possibility of white 'rivers' or 'lakes' running down the
page.
{el}
{p}
!
! LE
!
{Macdescr LE,Predicate for Less Than or Equal}
<{LE n1,n2}>
{Macsec Description}
LE evaluates to null (true) if "n1" is less than or equal to "n2",
otherwise it evaluates to "1" (false).
{Macsec Examples}
See COND for uses of system predicate macros.
{P}
!
! LEQ
!
{Macdescr LEQ,Predicate for Lexical Equality}
<{LEQ str1,str2}>
{Macsec Description}
LEQ evaluates to null (true) if "str1" is equal to "str2"
in terms of alphanumeric (lexical) value.
 This means that the two strings must be identical in all respects,
including case.
 Otherwise it evaluates to "1" (false).
{Macsec Examples}
{Bl}If the user responds "No" then skip input up to the next line
of the form "!**":
{Ls 1}{Center <{COND {LEQ NO,{CAPS {QUERY CONTINUE?}}},{SKIPTEXT !**}}>}
{Ls 1}
Note the use of "CAPS" to insure that regardless of the case
of the user's response,
the comparison will be true if the response was "no".
{El}
{Ls 1}
See COND for other uses of system predicate macros.
{P}
!
! LGE
!
{Macdescr LGE,Predicate for Lexical Greater or Equal}
<{LGE str1,str2}>
{Macsec Description}
LGE evaluates to null (true) if "str1" is greater than or equal to "str2"
in terms of alphanumeric (lexical) value.
 Otherwise it evaluates to "1" (false).
{Macsec Examples}
See COND for uses of system predicate macros.
{P}
!
! LGT
!
{Macdescr LGT,Predicate for Lexical Greater Than}
<{LGT str1,str2}>
{Macsec Description}
LGT evaluates to null (true) if "str1" is greater than "str2"
in terms of alphanumeric (lexical) value.
 Otherwise it evaluates to "1" (false).
{Macsec Examples}
See COND for uses of system predicate macros.
{P}
!
! LIN
!
{Macdescr LIN,Indent the left margin}
<{LIN n}>
{Macsec Description}
<{LIN n}> is equivalent to <{TSET.+ LMG,n}>.
 It indents the left margin an additional "n" places.
{Macsec Notes}
{bl}"n" can be negative to outdent the left margin
{li}Keep in mind that LIN does a TSET.
 The left margin prior to the LIN operation is saved on the LMG stack.
 A subsequent <{RESTORE LMG}> will reactivate it.
{li}There is a companion RIN macro to indent the right margin.
{EL}
{P}
!
! LINELENGTH
!
{Macdescr LINELENGTH,Number of Print Positions on a Line}
<{set LINELENGTH,n}> (Default: LINELENGTH=66}
<{LINELENGTH}>
<{D LINELENGTH}>
{macsec description}
The value of LINELENGTH is the number of print columns between
the current left and right margins. Setting LINELENGTH has
the effect of altering the value of RMG (the right margin)
so as to force <{LINELENGTH}> to equal the requested value.
{macsec notes}
{BL}n must be positive and non-zero.
{el}
{macsec examples}
{BL}Set the page to have 40 print columns
{ls 1}
{CENTER <{SET LINELENGTH,40}>}
{LI}If there are less than ten columns on the line, then
set LINELENGTH to 10.
{ls 1}
{CENTER <{COND {LT @LINELENGTH,10},{SET LINELENGTH,10}}>}
{EL}
{P}
!
! LINENUM
!
{MACDESCR LINENUM,Current Line on Page}
<{set LINENUM,n}>
<{LINENUM}>
<{D LINENUM}>
{macsec description}
LINENUM always has the number of the next line to be
printed on the page. It is set to one by the system
at the conclusion of processing a NEWPAGE condition.
Thus lines are numbered consecutively starting at one
with the first line on the page.
 LINENUM can also be set.
 This forces a line break, and lines to be skipped until
the next print line will be at the value specified in the SET.
This is termed "vertical tabulation".
{macsec notes}
{BL}The value for n must be between 1 and <{PAGELENGTH}>.
{LI}You can use <{SET~LINENUM,1}> to force printing to begin
on a new page. This is different from <{LS~10000}> in that
the LS form can cause a blank page to appear if printing
is already positioned at the top of a page.
 The <{SET~LINENUM,1}>
form will cause nothing to happen if the current print line is
already n.
 <{SET~LINENUM,1}> should normally be used to begin a page.
{LI}If the printing has already gone past line n
on a <{SET~LINENUM,n}>,
a new page is forced before skipping occurs.
{EL}
{macsec examples}
{BL}Print text centered on line 40.
{ls 1}
{nfj}
   <{SET LINENUM,40}{CENTER REPORT SUBMITTED BY:}{BRK}>
{FJ}
{LI}Skip to a new page if more than ten lines have
been already printed.
{LS 1}
{Center <{COND {GT @LINENUM,10},{LS 10000}}>}
{EL}
{P}
!
! LITERAL
!
{Macdescr LITERAL,Process Text Literally}
<{Literal str}>
{Macsec Description}
LITERAL causes subsequent text lines to be processed exactly as they
appear in the input file.
 Macros are not evaluated, comment lines are passed, and line fill and
justification are disabled.
{Ls 1}A line identical to 'str' causes termination of the LITERAL,
and a resumption of the previous processing state.
 If str is omitted, it is assumed to be "!**".
{Ls 1}LITERAL is defined to be:
{Ls 1}~~~~~<{BRK}{TSET INPUT,,INFORMAT={COND {LEQ @1},!**,,@1},->
{Brk }~~~~~<~~~~~INFORMAT=1,JUST=1,FILL=1}>
{Ls 1}
!
! LLE
!
{Macdescr LLE,Predicate for Lexical Less Than or Equal}
<{LLE str1,str2}>
{Macsec Description}
LLE evaluates to null (true) if "str1" is less than or equal to "str2"
in terms of alphanumeric (lexical) value.
 Otherwise it evaluates to "1" (false).
{Macsec Examples}
See COND for uses of system predicate macros.
{P}
!
! LLT
!
{Macdescr LLT,Predicate Comparison for Lexical Less Than}
<{LLT str1,str2}>
{Macsec Description}
LLT evaluates to null (true) if "str1" is less than "str2"
in terms of alphanumeric (lexical) value.
 Otherwise it evaluates to "1" (false).
{Macsec Examples}
See COND for uses of system predicate macros.
{P}
!
! LMG
!
{macdescr LMG,Left Margin}
<{set LMG,n}> (Default: LMG=10)
<{LMG}>
<{D LMG}>
{MACSEC DESCRIPTION}
The value of LMG tells GPMDOC how far to space out each print
line from the left BIAS.
 LMG must always be less than or equal to the right margin (RMG).
 In addition, the sum of LMG and BIAS must always be a positive value.
{macsec notes}
{Bl}The value of LMG is only used by GPMDOC when it is ready to
print a new line. So if you change LMG several times in a line,
only the final change will have effect.
{LI}LMG is used prior to evaluating NEWLINE, so if NEWLINE
changes LMG, that change will affect the next print line.
{EL}
{macsec examples}
{BL}Set the left margin to 20:
{ls 1}{nfj}
          <{SET LMG,20}>
{Fj}{Ls 1}
{Li}Set the left margin to 20 to the left of the right
margin:
{Ls 1}{Nfj}
     <{SET LMG,{- @RMG,20}}}>
{Fj}{Ls 1}
Note that <{LINELENGTH}> will now equal 21, not 20 because
both <{LMG}> and <{RMG}> are printing columns.
{El}
{P}
!
! LNE
!
{Macdescr LNE,Predicate Comparison for Lexical Not Equal}
<{LNE str1,str2}>
{Macsec Description}
LNE evaluates to null (true) if "str1" is not equal to "str2"
in terms of alphanumeric (lexical) value.
 Otherwise it evaluates to "1" (false).
{Macsec Examples}
See COND for uses of system predicate macros.
{P}
!
! LOAD
!
{Macdescr LOAD,Load from Library}
<{LOAD str1,str2}>
{Macsec Description}
Load reads from a user 'macro library'.
 "Str1" is taken as the filename of the library.
 "Str2" is the name of the 'module' to be loaded.
 If "str2" is null, then the entire library is processed.
{Macsec Notes}
{Bl}The "SYSLOAD" macro can be used when loading from the
standard system library.
{Li}Normally, library modules should set macro definitions,
and not produce any text on their own.
{Li}The library must be in a particular form in order for
LOAD to work correctly.
 Each module must be preceeded by a single line containing
an exclamation mark in column one,
and the module name starting in column two of the line.
 The remainder of the line must be empty.
{Ls 1}The end of the module must be a single line of the form "!**"
{Ls 1}LOAD is thus defined as:
{Ls 1}{Nfj}
<{COND {LEQ @2},{TSET INPUT,@1},->
  <{TSET INPUT,@1,STARTTEXT=!{1},ENDTEXT=!**}}>
{El}
{P}
!
! LPAD
!
{macdescr LPAD,Pad a String on the Left}
<{LPAD str1,n,str2}>
{macsec description}
The value of LPAD is str1 prefixed with
replications of str2 to produce a result of length n.
 If str1 is already as long or longer than n, the value of LPAD is str1.
 The value of LPAD is also str1 if n is zero or negative.
 If str2 must be replicated a non-integral number of times, the
last replication will be truncated to the appropriate length.
 If str2 is null, then the present hardspace character is used.
{macsec notes}
{BL}LPAD, along with RPAD, is useful for producing
tabular text.
{EL}
{macsec examples}
{BL}Print a line consisting of "PAGE:" and the current
page number at the right margin:
{Ls 1}{Center <{LPAD PAGE:{PAGENUM},@LINELENGTH}{BRK}>}
{Ls 1}
The LPAD causes the first argument string (e.g. "PAGE:32") to
be prefixed with hard spaces until it is as long as one
print line (<{LINELENGTH}>). It will thus appear flush with the
right margin.
{Li}Print the number in macro LISTNUM, left padded with zeros
to 6 digits.
{Ls 1}{Center <{LPAD @LISTNUM,6,0}>}
{Ls 1}
With this macro, if <{LISTNUM}> were defined as "63",
the LPAD would return "000063".
{El}
{P}
!
! LS
!
{macdescr LS,Line Spacing}
<{LS n}>
{macsec description}
The LS macro causes a line break and n blank lines to be
inserted on the page. This spacing will terminate if
it causes an ENDPAGE to occur, regardless of the value of n.
 The value of LS is null.
{macsec notes}
{bl}N may not be negative.
{LI}LS is subject to the effect induced by the value of
BSLACK.
{LI}<{LS~0}> is equivalent to <{BRK}>, a line break.  No blank
lines will be printed.  Note that <{LS}> is the same
as <{LS~0}>, as the implied null argument in the former
will be interpreted as a numeric zero.
{LI}LINENUM is also useful for skipping lines, read the
description of the LINENUM macro, and particularly the
<{SET~LINENUM,n}> form.
{EL}
{macsec examples}
{BL}Skip 10 lines to leave room for a drawing:
{Ls 1}{Center <{LS 10}>}
{Ls 1}
{LI}The example above isn't really very good, since skipping
always stops at the end of a page. If the page is already
almost full, the <{LS 10}> won't leave enough room. One way to solve
this problem would be to run the page out and put the 10 lines
at the top of the next page if less than 10 lines remain. This
can be done with:
{Ls 1}{Center <{COND {GT @LINENUM,{- @PAGELENGTH,10}},{LS 10000}}{LS 10}>}
{Ls 1}
The <{LS 10000}> will most certainly cause the page to run
out (unless you have a {ul very} long page!), but notice
that it will only occur if the value of LINENUM is past
<{PAGELENGTH}> minus 10.
 The LS 10 does the skipping.
{Li *~}The example just given may not seem all that satisfactory
to you either, since it leaves a rather big "white lake"
at the bottom of some of the pages for no seemingly good reason.
What we really want is to either skip the 10 lines if there is
room, or wait and skip the 10 lines when we start the next page.
This is fairly straightforward using NEWPAGE. As before, we
test LINENUM, and either skip the 10 lines, or if it has gone
too far, TSET the <{LS 10}> onto NEWPAGE.
{Ls 1}{Nfj}
<{COND {LE @LINENUM,{- @PAGELENGTH,10}},{LS 10},->
  <{TSET.APPEND NEWPAGE,<{LS 10}{RESTORE NEWPAGE}>}}>
{Ls 1}{Fj}
The flavor of this is similar to that used with OUTDENT,
in that the NEWPAGE "self-destructs" the <{LS 10}>
once it has been carried out, by doing a RESTORE on itself.
{Li}Here is a macro definition FIGURE for this, to which
you can give the number of lines as an argument:
{Ls 1}{Nfj}
<{SETQ FIGURE,->
  <{COND {LE @LINENUM,{- @PAGELENGTH,@1}},{LS @1},->
  <,{TSET.APPEND NEWPAGE,<{LS >{1}<}{RESTORE NEWPAGE}>}}->
<}>
{Ls 1}{Fj}
{EL}
{P}
!
! LT
!
{Macdescr LT,Predicate Comparison for Less Than}
<{LT n1,n2}>
{Macsec Description}
LT evaluates to null (true) if "n1" is less than "n2",
otherwise it evaluates to "1" (false).
{Macsec Examples}
See COND for uses of system predicate macros.
{P}
!
! NEWLINE
!
{macdescr NEWLINE,Define Event For Each New Line}
<{set NEWLINE,str}>
<{NEWLINE}>
<{D NEWLINE}>
{macsec description}
NEWLINE is an evaluated automatically
by GPMDOC each time it is ready to print a new line.
 Any value produced by referencing NEWLINE is discarded.
{macsec notes}
{BL}The <{NEWLINE}> form is not normally used. The system does
this automatically on each newline.
{LI}GPMDOC makes no adjustment to the margins as a result of
any characters affixed to the line as a result of NEWLINE's
evaluation.
{LI}The OUTSTREAM macro can be useful in NEWLINE to alter the
line to be printed.
{LI}The GPMDOC uses NEWLINE for the operation of some of
its macros (e.g. OUTDENT). It is thus not
normally advisable to set NEWLINE directly, since it may
already contain text (your's or GPMDOC's).
 A
{Ls 1}{Center <{SET.APPEND~NEWLINE,text}>}
{Center or}
{Center <{TSET.APPEND~NEWLINE,text}>}
{Ls 1}
which affixes your text to any existing text in NEWLINE is
preferred.
{EL}
{macsec examples}
(Also see OUTSTREAM macro description).
{BL *~}OUTDENT the next line five spaces:
{Ls 1}{Nfj}
<{TSET.- LMG,5}->
  <{TSET.APPEND NEWLINE,<{RESTORE LMG,NEWLINE}}>>
{Ls 1}{Fj}
This operation proceeds by first temporarily setting (TSET)
the left margin out 5 spaces. Then the text
<{RESTORE~LMG,NEWLINE}> is tacked onto the end of
any existing NEWLINE text and temporarily set back into
NEWLINE (TSET.APPEND).
 Thus when the next line is printed
the following actions occur:
{BL}The left margin spacing is computed based on the new
value which is the old value minus 5.
{LI}NEWLINE is evaluated automatically by GPMDOC and this causes
the old left margin to be restored (for succeeding lines),
NEWLINE then restores its own old value so that the text
appended onto it for the outdent effectively "self-destructs".
{LS 1}
{EL}
This is the definition for the system OUTDENT macro.
{el}
{P}
!
! NEWPAGE
!
{MACDESCR NEWPAGE,Define Event For Starting a New Page}
<{set NEWPAGE,str}> (Default: NEWPAGE=<{LS 1}->
                     <{COND {GT @PAGENUM,1},->
                     <{LPAD PAGE {PAGENUM},@LINELENGTH}}->
                     <{LS 2}>
<{NEWPAGE}>
<{D NEWPAGE}>
{macsec description}
The first line to be printed after an ENDPAGE condition has
occurred causes a NEWPAGE event.
 Before the line is actually printed, the following actions take place:
{BL}The line to be printed and any other assembled output text
are put aside.
{LI}NEWLINE is TSET to null, SPACING is TSET to one (single
spacing). LMG is TSET to 10. RMG is TSET to 75.
{LI}The value of LINENUM becomes one.
{LI}"<{NEWPAGE}>" is given to the evaluator for printing.
{LI}NEWLINE, SPACING, LMG and RMG are restored, which completes
the NEWPAGE event.
{EL}
{MACSEC NOTES}
{BL}A NEWPAGE event happens on the first line of a
document, even though no preceeding ENDPAGE has occurred.
{LI}If NEWLINE, SPACING, LMG or RMG are changed in NEWPAGE,
changes will only have effect during the NEWPAGE condition, as
they are TSET and RESTOREd.
 If you desire a permanent effect,
the NEWPAGE can RESTORE and re-TSET new values
that will then be the values ultimately RESTORED at the conclusion
of the NEWPAGE condition.
{li}NEWPAGE and ENDPAGE conditions are inhibited while
the NEWPAGE condition is being processed.
{EL}
{MACSEC EXAMPLES}
{BL}At the top of every page, print two blank lines, the
centered text of the user-defined macro TITLE, the page
number then two more blank lines:
{LS 1}{nfj}
<{SETQ NEWPAGE,->
  <{LS 2}{CENTER @TITLE}{T 60}PAGE:{PAGENUM}{LS 2}}>
{FJ}
{EL}
{P}
!
! NFJ
!
{macdescr NFJ,No Fill or Justify}
<{NFJ}>
{macsec description}
<{D NFJ}> is the string; <"{SET~FILL,FALSE}{SET~JUST,FALSE}">.
It disables both line fill and right justification.
 The value of NFJ is null.
{P}
!
! OAB
!
{MACDESCR OAB,Open Angle Bracket}
<{OAB}>
{MACSEC DESCRIPTION}
Evaluates to "<".
{MACSEC NOTES}
{BL}This macro, and its companion <{CAB}>, are used in situations
where the quote symbols are needed without causing the effect
of quoting, or where they appear in an unbalanced way.
{EL}
{MACSEC EXAMPLES}
See the examples for CAB.
{P}
!
! ODD
!
{Macdescr ODD,Predicate Test for Numeric Odd}
<{ODD n}>
{Macsec Description}
ODD evaluates to null (true) if "n" is an odd integer,
otherwise it evaluates to "1" (false).
{Macsec Examples}
See the description of COND for examples of the use of predicates.
{P}
!
! OS
!
{macdescr OS,Overstrike Two Strings}
<{OS str1,str2}>
{macsec description}
OS returns a string which, when printed, will have str1
overprinted with str2.
 If the two strings are not of the same length,
the shorter is padded on the right with blanks
before the overstrikes are computed.
{macsec notes}
{BL}Overstrikes are computed internally with a special
backspace character that cannot be entered from the keyboard.
Thus overstruck strings can be freely passed about, and joined
with other strings.
 The SIZE macro correctly computes the actual
number of print positions of a string, compensating for the
extra length caused by the presence of the backspaces.
 For output, GPMDOC decomposes the print line containing the
backspaces into a series of non-overstruck lines that it
prints on top of each other.
{LI}Overstrikes may themselves be overstruck (to any
reasonable degree).
 Note however, that use of overstriking
slows down both the processing and actual printing of such text.
{EL}
{macsec examples}
{BL}Overstrike pairs of characters to get interesting new
characters from the ordinary ol' line printer:
{ls 1}
{nfj}
{TSETQ OSC,<{OS >{D 1}<,>{D 2}<}  --  >{OS {1},{2}}<     >({3}){BRK}}
{OSC c,|,cent sign}
{OSC -,|,dagger}
{OSC |,=,double dagger}
{OSC /,=,not equals}
{OSC O,-,theta}
{OSC 0,/,computer zero}
{OSC {oab},-,arrow}
{OSC ),/,gamma}
{OSC ),\,lambda}
{OSC o,_,rising sun}
{OSC =,-,equivalence symbol}
{OSC \,/,X marks the spot}
{OSC <{OS \,/}>,<{OS |,-}>,attention grabber}
{RESTORE OSC}
{FJ}
{LI}Print the text "RIGHT NOW" with the "NOW" underlined:
{ls 1}{Center RIGHT <{OS NOW,___}>}
{Ls 1}{Fj}
{LI *~}Define a macro UNDER that will evaluate to an underlined version
of whatever text is given as an argument:
{ls 1}{Center <{SETQ UNDER,{OS @1,{DUPL _,{DSIZE 1}}}}>}
{ls 1}
This macro has a problem in that it will underscore blanks,
preventing them from being used as line breaks, or as
justification points.
 This problem can be solved by using
REPLACE and IMAGE, which is essentially what is done by the
system underlining macro UL.
{LI *~}Sometimes when revising a document, it is necessary to
show on the new version what changes have been made.
 "Change bars" in the left margin are usually
used to show new or changed lines.
 Deletions, however, pose a formidable problem.
 This example shows a way to use NEWLINE to
overstrike print lines with hyphens to indicate that they are
deleted without actually removing the text:
{ls 1}{nfj}
<{TSET.APPEND NEWLINE,->
  <<{SET OUTSTREAM,{OS @OUTSTREAM,{DUPL -,{DSIZE OUTSTREAM}}}}>}}>
{Ls 1}{Fj}
{EL}
{P}
!
! OUTDENT
!
{Macdescr OUTDENT,Outdent a Line}
<{OUTDENT n}>
{Macsec Description}
OUTDENT will cause the left margin to be 'outdented' n spaces on the
next line printed.
 OUTDENT is defined as:
{Ls 1}{Center <{BRK}{TSET.- LMG,@1}{TSET.APPEND NEWLINE,->}
{Center <<{RESTORE LMG,NEWLINE}>}>}
{Ls 1}
{p}
!
! OUTOS
!
{Macdescr OUTOS,Output Stream Overstrike Flag}
<{set OUTOS,pred}> (Default: OUTOS=null)
<{OUTOS}>
<{D OUTOS}>
{Macsec Description}
OUTOS is a flag which controls the formatting of overstrikes in the
output stream.
 When OUTOS is true (null), output files are accessed for writing
with carriage control properties that will properly display overstruck
text.
 Such files may be difficult to manipulate with other system utilities.
 If OUTOS is set false (non-null), only the primary images of output
lines will be printed (no overstrikes), and output files will be opened
with normal, sequential attributes.
{Macsec Notes}
{Bl}Changing OUTOS will only have effect
for output files opened subsequent to the change.
{el}
{p}
!
! OUTPUT
!
{macdescr OUTPUT,Name of Output File}
<{set OUTPUT,str}> (Default: OUTPUT=user's terminal device)
<{OUTPUT}>
<{D OUTPUT}>
{Macsec Description}
The value you set to OUTPUT instructs GPMDOC as to the name of the
current file for print stream output text.
 Setting a value for OUTPUT causes the present output stream to
be closed out, and a new one whose name is given by "str" is
created and opened.
{Macsec Notes}
The nature of OUTPUT is necessarily somewhat system-dependent.
 These notes and examples pertain to the VAX/VMS version.
{Bl}"Str" should be a valid device/file specification, enclosed in
quote symbols if it contains any commas.
{Li}If TSET is used with OUTPUT, a later RESTORE will not
continue with the old file, but will open a new version of it.
{El}
{Macsec Examples}
{Bl}Set the output stream to the terminal:
{Ls 1}{Center <{SET OUTPUT,TT:}>}{Ls 1}
{Li}Shut off output entirely (direct it to the null device):
{Ls 1}{Center <{SET OUTPUT,NL:}>}{Ls 1}
{Li}Direct further output to FILE.LST~:
{Ls 1}{Center <{SET OUTPUT,FILE.LST}>}{Ls 1}
You should be aware that each time OUTPUT is set, a new stream is
created and opened.
 This means that if you set the output stream to the same file
repeatedly, GPMDOC will not keep appending to one file, but rather
create multiple copies of the same file with successively higher
version numbers.
{el}{p}
!
! OUTSTREAM
!
{MACDESCR OUTSTREAM,The Current Output Stream}
<{set OUTSTREAM,str}> (Default: See Description)
<{OUTSTREAM}>
{macsec description}
The value of OUTSTREAM is the currently assembled output stream
(no evaluation is done).
 With a NEWLINE macro, the value of an OUTSTREAM reference is the
text of the line about to be printed, excluding the left margin bias.
{macsec notes}
{BL}Care should be exercised when performing a SET-type operation on
OUTSTREAM.
 This is especially true in a NEWLINE evaluation,
as the system will not 'recompensate' for margin or spacing
irregularities induced by changing the OUTSTREAM.
{EL}
{macsec examples}
{BL}Print every line with a "*" on the front.
{LS 1}{CENTER <{SET.PREPEND OUTSTREAM,*}>}
{LI *~}Temporarily change NEWLINE to cause every print line to be
underscored until NEWLINE is RESTORED.
{LS 1}{CENTER <{TSET.APPEND NEWLINE,<{SET.UL OUTSTREAM}>}>}
{EL}
{P}
!
! P
!
{macdescr P,Skip to New Page}
<{P}>
<{D P}>
{macsec description}
P is defined as <{SET LINENUM,1}>, which will cause a new
page to be started unless printing is presently at the first
line of a page.
{macsec notes}
{BL}You should read the description of LINENUM for a complete
explanation of the effects of <{P}>.
{el}
{P}
!
! PAGELENGTH
!
{Macdescr PAGELENGTH,Defined Length of Page}
<{set PAGELENGTH,n}> (Default: PAGELENGTH=55)
<{PAGELENGTH}>
<{D PAGELENGTH}>
{Macsec Description}
The value of PAGELENGTH is used by GPMDOC to determine when to signal
an ENDPAGE condition.
 When <{LINENUM}> exceeds <{PAGELENGTH}>, an ENDPAGE (see description)
condition is signalled.
{Macsec Notes}
{Bl}The value of "n" must be positive.
{Li}Paging is inhibited by GPMDOC during NEWPAGE/ENDPAGE conditions,
so even if the number of lines emitted by NEWPAGE is larger than
PAGELENGTH, no endlessly recursive paging is possible.
{Li}Assuming that ENDPAGE causes some sort of 'page eject,'
PAGELENGTH can be thought of as defining the number of lines on a
page.
{Li}Setting PAGELENGTH to a very large value will effectively inhibit
page conditions.
{el}
{p}
!
! PAGENUM
!
{macdescr PAGENUM,Current Page Number}
<{set PAGENUM,n}> (Default: PAGENUM=1)
<{PAGENUM}>
<{D PAGENUM}>
{macsec description}
PAGENUM contains its last defined value, but updated
by one at the conclusion of each ENDPAGE condition.
{macsec notes}
{BL}N must be non-negative.
{li}Setting PAGENUM has no side-effects.
{el}
{macsec examples}
{bl}Print the page number at the top right-hand corner
of every succeeding page.
{LS 1}{CENTER <{SETQ NEWPAGE,{LPAD @PAGENUM,@LINELENGTH}}>}
{LI}Reset page numbering to one.
{ls 1}
{Center <{SET PAGENUM,1}>}
{el}
{p}
!
! PARA
!
{macdescr PARA,Start a New Paragraph}
<{PARA}>
<{D PARA}>
{Macsec Description}
Referencing PARA will cause a line break, a single blank line and five
hard spaces to be sent to the output stream.
 This is what is normally used for a standard paragraph.
{Macsec Notes}
{bl}If you want to insure that {ul exactly} five spaces indent the
first line of the paragraph then the text of the paragraph should
appear immediately following the <{PARA}>.
 If you start the text on a new logical line, then GPMDOC will
(in fill mode) send a single space to the output stream between
the <{PARA}> and the text on the next line.
 This space is subject to justification and could cause thus cause
uneven spacing of paragraph indents.
{el}
{p}
!
! PREPEND
!
{macdescr PREPEND,Prefix onto a String}
<{PREPEND str1,str2}>
{Macsec Description}
The value of PREPEND is str2 prefixed onto str1.
 PREPEND is the complementary macro to APPEND.
{macsec notes}
{Bl}The PREPEND operation is generally only useful in extended sets.
{el}
{macsec examples}
{bl}Print two extra lines at the bottom of every page,
before the page footing:
{Ls 1}{Center <{SET.PREPEND ENDPAGE,<{LS 2}>}>}{Ls 1}
{el}
{p}
!
! QUERY
!
{macdescr QUERY,Get Text From The Terminal}
<{QUERY str}>
{macsec description}
The value of QUERY is whatever text is typed in at the terminal
in response to str, which is displayed first.
{macsec notes}
{BL}The response typed in is not evaluated by GPMDOC.
{EL}
{macsec examples}
{BL}Print text containing a response that is typed in.
{LS 1}
{nfj}
{CENTER <We will ship to {QUERY Country? }>}
{fj}
{ls 1}
Note:  "Country?" will be displayed at your terminal.
Following this, you should enter text (possibly null)
terminated by a carriage return. This response becomes the
value of the QUERY macro, and hence is effectively inserted
in the output stream.
{LI}Ask for an address from the terminal to be used
later, so place it in a macro called ADDRESS.
{ls 1}
{Center <{SET ADDRESS,{QUERY WHAT IS THE ADDRESS? }}>}
{ls 1}
If text such as "#10 Downing St.<{BRK}>London, England"
were entered, it would be placed into ADDRESS in that form,
since GPMDOC does not evaluate QUERY input. When ADDRESS
was used later, the <{BRK}> would be processed by GPMDOC
at that point.
{LI}Print an address and also put it into ADDRESS to be
referenced later:
{ls 1}
{CENTER <Ship To: {SETV ADDRESS,{QUERY WHAT IS THE ADDRESS? }}>}
{LS 1}
Notice the use of SETV to effectively 'pass through' the value
that was SET, in order for it to be printed.
{EL}
{P}
!
! REMDR
!
{Macdescr REMDR,Arithmetic Remainder}
<{REMDR n1,n2}>
{Macsec Description}
The value of REMDR is the integer remainder after dividing integer
n1 by n2.
 The sign of the result is the same as the sign of n1.
{Macsec Examples}
{bl}Print a message on the terminal every 10 pages.
{ls 1}{Center <{COND {EQ 0,{REMDR @PAGENUM,10}},{DISPLAY Working...}}>}
{Ls 1}
{Li *~}Here is a set of macros to compute roman numbers given a number.
in the range from 0..99.
 For example <{Roman~17}> will yield "xvii".
{Ls 1}{Nfj}
<{SETQ ROMAN,{GENROMAN {/ @1,10},x,l,c}->
  <{GENROMAN {REMDR @1,10},i,v,x}}>
{Ls 1}
<{SETQ GENROMAN,{COND ->
  <{LE @1,3},{DUPL @2,@1},->
  <{EQ @1,4},{2}{3},->
  <{LE @1,8},{3}{DUPL @2,{- @1,5}},->
  <,{2}{4}}}>
{Ls 1}{Fj}
"Genroman" is an auxilliary macro used by Roman that will generate
text according to the rules for roman numbers in the range
0..9.
 Roman makes two calls on Genroman, one for the 10s digit and one
for the ones digit.
 REMDR is used to extract the ones digit.
{Ls 1}Genroman takes in the symbols ("x","l","c", etc.)
to be used, since the rules for generating roman numbers are the same
for both the 10s digit and the ones digit.
{Ls 1}Note that if capital roman numbers were needed, <{CAPS~{ROMAN~n}}>
would do the trick.
{el}
{P}
!
! REPLACE
!
{macdescr REPLACE,Substitute for Characters in Text}
<{REPLACE str1,str2,str3}>
{Macsec Description}
The value of REPLACE is the string str1 with each of its characters
appearing in str2 being replaced by the corresponding character from
str3.
{Macsec Notes}
{bl}Str2 and str3 must be the same size, and must not be null.
{li}Any of the argument strings can contains overstrikes, however,
replacement occurs on the individual component characters of
overstrikes, not on the overstruck characters as unique elements.
{el}
{macsec examples}
{bl}Print the text of the macro TITLE, with all punctuation replaced
by blanks:
{Ls 1}{Center <{REPLACE @TITLE,<,.?":;!>,<       >}>}{Ls 1}
{li}Print text that is typed in from the terminal, with all
spaces replaced by hard spaces:
{Tset Hs,<@>}
{Ls 1}{Center <{REPLACE {QUERY Enter Text},< >,~}>}{Brk}
{Restore Hs}{Ls 1}
{el}
{p}
!
! RESTORE
!
{MACDESCR RESTORE,Restore Prior Value of Macros}
<{RESTORE mname1,mname2,...}>
{macsec description}
RESTORE is used to retrieve the last definition of the mnames
that were stacked by TSET (see the description of TSET).
 Each of the given mnames is processed in turn, starting with mname1.
 A null mname (end of arguments) is assumed to terminate the list.
{Ls 1}RESTORE operates exactly like a SET on mname, where the
value to be SET comes from the top of the stack for mname.
 RESTORE also discards this item from the stack, so that
successive RESTORE's on the same mname retrieve successive items
from mname's stack in inverse order from the order they
were stacked by TSET.
{macsec notes}
{BL}TSET and RESTORE are typically used to save (TSET)
and restore (RESTORE) contextual information such as
margins, spacing and the like.
{LI}An attempt to restore a value from a macro's stack
when the stack is empty will result in a "NO VALUE TO RESTORE"
error.
{Li}A macro may issue a RESTORE on itself (see OUTDENT for example).
 The restored definition is used in subsequent evaluations of the macro,
the evaluation causing the restore continues undisturbed with the previous
definition.
{Li}Stacks for macros with the same name in different property tables
are distinct.
{EL}
{macsec examples}
Examples are shown in the description for TSET.
{P}
!
! RIN
!
{Macdescr RIN,Indent the right margin}
<{RIN n}>
{Macsec Description}
<{RIN n}> is equivalent to <{TSET.- RMG,n}>.
 It indents the right margin an additional "n" places.
{Macsec Notes}
{bl}"n" can be negative to move out the right margin
{li}Keep in mind that RIN does a TSET.
 The right margin prior to the RIN operation is saved on the RMG stack.
 A subsequent <{RESTORE RMG}> will reactivate it.
{li}There is a companion LIN macro to indent the left margin.
{EL}
{P}
!
! RMG
!
{macdescr RMG,Right Margin}
<{set RMG,n}> (Default: RMG=75)
<{RMG}>
<{D RMG}>
{macsec description}
The value of RMG tells GPMDOC the absolute position of the
last printing column on the page.
{macsec notes}
{BL}N must be greater than or equal to <{LMG}>.
{LI}<{RMG}> in fill mode causes lines to be assembled until
characters overflow the right margin. Then this assembled
line is broken off at a blank closest to the right margin, and
printed. If no blank exists in the line, the line is broken
at the right margin. If justification is enabled, the part
broken off is justified before printing, such that the last
character is flush with the right margin. The part of the
assembled text not broken off is retained for printing on
the next line. With line fill disabled, an automatic
line break occurs at the end of each input line, so that <{RMG}>
only assumes significance if single input lines exceed the
line length.
{LI}The LINELENGTH macro can also be used to change the right
margin, see the description of LINELENGTH.
{EL}
{macsec examples}
{BL}Set the right margin at column 60:
{ls 1}
{Center <{SET RMG,60}>}
{LI}Set the right margin to 10 past the left margin:
{ls 1}
{Center <{SET RMG,{+ @LMG,10}}>}
{Center or}
{Center <{SET LINELENGTH,11}>}
{ls 1}
You might be tempted to set LINELENGTH to 10, but this is not
the same. For instance, if <{LMG}> is 10 and RMG is 20 as
a result of this example, then columns 10-20 {UL inclusive}
are printing columns. This means there are 11 printing columns.
<{LINELENGTH}> will always be <{RMG}> - <{LMG}> + 1.
{EL}
{P}
!
! RPAD
!
{macdescr RPAD,Pad a String on the Right}
<{RPAD str1,n,str2}>
{macsec description}
The value of RPAD is str1 suffixed with replications of str2 to
produce a result of length n.
 If str1 is already as
long or longer than n, the value of RPAD is str1.
 The value of RPAD is also str if n is zero or negative.
 If an uneven number of replication are necessary to get a result of
length n, the last replication will be truncated appropriately.
 If str2 is null, the present hardspace character is assumed for str2.
{macsec notes}
{BL}RPAD, along with LPAD, is useful for producing
tabular text.
{EL}
{macsec examples}
{Bl}Define a macro, TABULAR, that will print three items in
columns ten wide:
{Ls 1}
{Nfj}
<{SETQ TABULAR,->
  <{RPAD @1,10}{RPAD @2,10}{RPAD @3,10}}>
{FJ}
{EL}
{P}
!
! SET
!
{macdescr SET,Alter The Value of a Macro}
<{SET mname,str}>
{macsec description}
The macro with name mname is given a definition of str.
 Any previous definition is lost.
 Future references to <{mname...}>
will cause this definition to be retrieved.
 The value of SET is always null.
{macsec notes}
{BL}Certain system macros may only be set to a restricted
range of values (e.g. INPUT, LMG, RMG, LINENUM etc.).
 An attempt to set these macros to an improper value results in a
"BAD VALUE" error.
{LI}All macros not explicitly SET are implicitly null when
referenced.
{LI}There is an additional syntax available for use with
SET, termed "extended set".
 It is used when an operation is
to be applied that involves a macro, and the resulting
value is to be SET back into that macro. (See examples below.)
The syntax is:
{ls 1}
{Center <{SET.mname1 mname2,str1,str2...}>}
{Ls 1}
which is equivalent to:
{Ls 1}
{Center <{SET mname2,{mname1 @mname2,str1,str2,...}}>}
{LS 1}
Extended set should not be used with system macros for which
the <{D mname}> form is not valid, since the macro's
{ul definition} is accessed for extended set.
{LI}The argument macros may be used within a macro's
definition.
 They take the form <{n}>. n is a macro whose definition
is the nth argument string passed in a call to the
macro where the <{n}> occurs, as in:
<{mname arg1,arg2,...}>.
 For instance <{1}> refers to
arg1 of this evaluation of mname.
 An argument macro with a
number less than one or greater than the number of arguments
given will evaluate to null, as will an argument macro
appearing directly in the input text (outside of an evaluation).
 Argument macros are, as with other system macros,
defined in the null property table, however,
 no form of SET should ever be issued for argument macros.
{LI}For the above reasons users should avoid defining their
own macros with names:
{ls 1}
{nfj}
    -  Containing periods or backslashes, or
    -  The same as system macros, or
    -  That are numeric (with the null property table).
{fj}
{ls 1}
{LI}SETting definitions uses up memory space inside GPMDOC.
In some implementations on small machines this may be
significant in that GPMDOC will run slower when the user has set
a large number of definitions because its own internal processing
memory is reduced. In extreme cases a "MEMORY OVERFLOW" error
may occur. To avoid thses situations, macros can be set to null
when they are no longer needed, or an entire property table
and its definitions can be eradicated with the DELPROP macro.
{EL}
{macsec examples}
{BL}Set a macro to "University of California" (saves typing):
{LS 1}{Center <{SET UC,University of California}>}
{LI}Move the left margin in five spaces.
{Ls 1}{Center <{SET LMG,{+ 5,@LMG}}>}
{Center or}
{Center <{SET.+ LMG,5}>}
{Center or}
{Center <{LIN 5}>}
{LI}Set the output file to HELP.DOC on account [1,2].
{LS 1}
{Center <{SET OUTPUT,<[1,2]HELP.DOC>}>}
{LS 1}
Note that the quotes are needed as otherwise the comma
within the account specification would be seen as an
argument separator, and OUTPUT would be set to
"[1" - an error.
{LI}Set the hardspace to a backslash:
{LS 1}{Center <{SET HS,\}>}
{LI}Define a macro PAGE that will skip to a new page
when invoked:
{LS 1}{Center <{SET PAGE,<{LS 10000}>}>}
{LS 1}
Note here that the quotes are required to avoid a premature
evaluation of the LS. If the quote brackets were not
present, when the SET was evaluated, the <{LS 10000}> would then
be evaluated as an argument to SET
which would immediately force a new page, and
the value of the LS (null) would be set to PAGE. It is easier
to do this sort of thing with SETQ (see the description of SETQ).
{LI}Turn right justification off (set it to null).
{LS 1}
{Center <{SET JUST}>}
{El}
{P}
!
! SETQ
!
{macdescr SETQ,Quoted SET}
<{SETQ mname,qstr}>
{macsec description}
SETQ functions exactly like SET in that it establishes a connection
between mname and qstr.
 The difference is that SETQ receives the qstr definition in
unevaluated form.
 The definition is thus made with all
embedded macro calls and quotes in qstr intact.
{macsec notes}
{BL}SETQ is included principally to make it easier to define
macros that consist of calls on other macros.
 (See the examples.)
{li}Your qstr should not contain "open" commas, that is, commas
not contained inside quote symbols or macro braces. The reason
is that these commas would be seen as argument separators for the
SETQ, causing an incorrect argument scan for the SETQ.
{EL}
{macsec examples}
{BL}Define a macro INMARGINS that will move the left and
right margins in by five.
{ls 1}{Center <{SETQ INMARGINS,{LIN 5}{RIN 5}}>}
{ls 1}
This example could be done with SET, it would be written as:
{ls 1}
{Center <{SET INMARGINS,<{LIN 5}{RIN 5}>}>}
{LS 1}
The SETQ allows you to eliminate the quote symbols that
have to be used in the SET.
{el}
{P}
!
! SETV
!
{macdescr SETV,SET Value For Macro and Return It}
<{SETV mname,str}>
{macsec description}
SETV functions identically to SET except instead of having a
a null value, the value of SETV is the text that is set
as the definition of mname.
{macsec notes}
{BL}SETV may be used in extended form as with SET.
{EL}
{macsec examples}
{BL}Indent the left margin five and put the resulting value
in the user-defined macro margin.
{LS 1}{Center <{SET MARGIN,{SETV.+ LMG,5}}>}
{LS 1}
{EL}
{P}
!
! SIZE
!
{macdescr SIZE,Number of Print Positions for Text}
<{SIZE str}>
{macsec description}
The value of SIZE is the (non-negative) integer which
gives the number of print columns that would be
occupied by str, if it were printed.
{macsec notes}
{bl}SIZE includes compensation for any overstruck characters
in str.  Thus SIZE is the number of characters in str if and
only if str contains no overstrikes.
{li}DSIZE is useful and more efficient for determining the
size of a defined macro or argument.  (See the description
of DSIZE).
{el}
{p}
!
! SKIPTEXT
!
{MACDESCR SKIPTEXT,Skip Input Text}
<{SKIPTEXT str}>
{Macsec Description}
The SKIPTEXT macro causes succeeding lines on the currently active
input file to be skipped until a physical line is encountered
that exactly matches "str".
 No evaluation or processing of any kind occurs with the skipped text.
 Reading will continue with the line following the one matched.
 The value of SKIPTEXT is always null.
{Macsec Notes}
{Bl}SKIPTEXT, as with BEGINTEXT and ENDTEXT, works with
physical lines, not logical ones.
 This means that comment lines can be used as SKIPTEXT markers.
 The reason that this is usually helpful is if the text that is
skipped is processed without the SKIPTEXT being invoked.
 In this case, if the marker is a comment, it will not become
part of the text processed.
{li}The preferred marker (by convention) is "!**".
{Li}The given termination string can be null.
 In this case, an empty line will terminate the skipping.
{el}
{Macsec Examples}
{bl}Skip some text if the value of MODE is "BRIEF":
{Ls 1}{Center <{COND {LEQ @MODE,BRIEF},{SKIPTEXT !**}}>}{Ls 1}
This will skip over input through the next "!**" line if the
MODE macro has the value "BRIEF".
 Otherwise, evaluation continues on with no effects.
{Ls 1}This shows why the use of "!**" is helpful, since if
MODE is not "BRIEF", then the "!**" that is encountered later
will be 'ignored.'
{el}
!
! SPACING
!
{MACDESCR SPACING,Set Inter-line Spacing}
<{set SPACING,n}> (Default: SPACING=1)
<{SPACING}>
<{D SPACING}>
{macsec description}
The SPACING macro tells GPMDOC how many blank lines to
automatically print after each text line is output. When
SPACING is one, no extra blank lines are output. SPACING
set to 2 means double spacing, and so forth. In general, setting
SPACING to n is equivalent to performing an <{LS~{sub1~n}}>
after each line is printed.
{macsec notes}
{BL}N must be greater than or equal to one.
{LI}If less than n-1 lines remain on the page, the page
is run out, and an endpage condition occurs.
{LI}Blank lines inserted by the effect of SPACING are not subject
to BSLACK (see the description of BSLACK).
{LI}Blank lines emitted by <{LS~...}> will not have additional
spacing applied (see example).
{EL}
{macsec examples}
{BL}Set double spacing:
{LS 1}{Center <{SET SPACING,2}>}
{LI}Temporarily set single spacing for printing a quotation
then go back to the old spacing:
{LS 1}
{Center <{TSET SPACING,1}{LS 2}{LIN 10}{RIN 10}>}
{Center :}{Center Text of Quotation}{Center :}
{Center <{RESTORE RMG,LMG,SPACING}>}
{LI}Define a macro <{LS* n}> that will do the job
of LS, but will take into account the value of SPACING,
so that each blank line emitted will actually be <{SPACING}>
blank lines:
{LS 1}{Center <{SETQ LS*,{LS {* @1,@SPACING}}}>}
{LS 1}
When <{LS*~n}> is called, n is multiplied by
the value of SPACING so that the LS actually performed is n
times the current spacing.
{EL}
{P}
!
! SUB1
!
{macdescr SUB1,Subtract One From Numeric}
<{SUB1 n}>
{macsec description}
The value of SUB1 is one subtracted from n.  It is
equivalent to <{-~n,1}>.
{macsec notes}
{bl}SUB1 is included for convenience, as it is a frequent
operation.
{el}
{macsec examples}
{bl}Subtract one from the current page number:
{ls 1}
{Center <{SET.SUB1 PAGENUM}>}
{EL}
{P}
!
! SUBSTR
!
{macdescr SUBSTR,Compute Substring}
<{SUBSTR str,n1,n2}>
{Macsec Description}
The value of SUBSTR is n2 contiguous characters of text taken from
str, starting at character position n1.
{Macsec Notes}
{Bl}Both n1 and n2 should be positive, and define a region completely
within str.
{Li}If n2 is omitted, then the 'rest' of str is assumed by default.
{el}
{macsec Examples}
{Bl}Define a macro to print text with the first character
capitalized:
{Ls 1}{Center <{SETQ FCC,{CAPS {SUBSTR @1,1,1}}{SUBSTR @2,2}}>}
{El}{P}
!
! T
!
{macdescr T,Horizontal Tab}
<{T n,str}>
{macsec description}
The value of T is sufficient replications of str to cause the next
character to print in column n.
 N is relative to left margin;
 n=1 is the first printing column.
 If str is null, then a hard space is assumed for str.
{macsec notes}
{BL}N should be less than or equal to <{LINELENGTH}>.
 If text has
already been assembled past column n, a line break occurs
before the hard spaces for the tab are emitted.
{LI}T should not be used when justification is enabled.
Justification may insert additional spaces that will cause
the tab to be moved to the right an unpredictable amount.
{Li}T looks at the current output stream to determine the size of
its result.
 It operates under the assumption that the result of its evaluation
is going to the output stream.
 If T is used in some other context, such as an
argument, then it will evaluate to the appropriate text, but obviously
no actual tabbing will occur as a result.
{EL}
{macsec examples}
{BL}Tab over to column 40 and print $1.99:
{ls 1}
{Center <{T 40}>$1.99}
{LI}Print "CONTRACT" in the last 8 columns of the line:
{ls 1}
{Center <{T {- @LINELENGTH,7}}>CONTRACT}
{LS 1}
This would be easier to do with LPAD.
{LI}Define a macro TOC that will format one line of a
table of contents. The format is: the description, then
periods to column 35, and then the page number. The
description and page number will be given as arguments to TOC:
{ls 1}{Center <{SETQ TOC,{1}{T 35,.}{2}}>}
{Ls 1}
This would be used as in:
{Ls 1}
{Center <{TOC Chapter 1,1}>}
{Center <{TOC Chapter 2,15}>}
{Ls 1}
Which would appear as:
{Ls 1}{Nfj}
{TSETQ TOC,{1}{T 35,.}{2}}
{TOC Chapter 1,1}
{Toc Chapter 2,15}
{Restore TOC}
{Ls 1}{Fj}
{EL}
{P}
!
! TSET
!
{macdescr TSET,Temporary Set}
<{TSET mname,str}>
{macsec description}
TSET performs identically to SET (see description), except
that before the SET is performed, the current value of mname
is put on top of a special stack reserved for mname. A
<{RESTORE mname}> performed will cause this stacked value to be
removed from the top of the stack and restored as the definition
of mname. The TSET value (str) will then be lost. Multiple
TSETs may be performed on the mname; the values are "unstacked"
in reverse from the order they were originally stacked. TSETs
performed on different mnames are totally independent. TSET,
like SET always evaluates null.
{macsec notes}
{BL}TSET may be used in extended form. See the description
of extended SET.
{LI}TSET and RESTORE are normally used jointly.
 The description of
RESTORE should be read for a full understanding of TSET.
{LI}The usual use of TSET is as a mechanism for saving, then
changing, some part of the context of a document such as margins,
spacing, titles, section numbers, and the like. This saved
context can then be restored at a later point in the processing.
For instance, GPMDOC uses TSET internally when processing
NEWPAGE and ENDPAGE. The values of LMG, RMG, SPACING and
NEWLINE are TSET to predefined values for processing the page
condition, regardless of what their values might be in the body
of the text.
 At the conclusion of the page condition, a RESTORE
is done on these macros which brings back the values that existed
prior to the occurrence of the page condition.
{Li}The TSET form for INPUT allows other TSETs to be
incorporated.
 See the description for INPUT.
{EL}
{macsec examples}
{BL}Set the left margin to five, temporarily:
{ls 1}{Center <{TSET LMG,5}>}
{LS 1}
{LI}Define a macro QUOTATION that will skip down two lines,
indent the left and right margins 7 spaces and go to single
spacing in order to insert a properly formatted quotation in the
document:
{ls 1}{Nfj}
<{SETQ QUOTATION,{LS 2}->
  <{LIN 7}{RIN 7}{TSET SPACING,1}}>
{LS 1}{Fj}
Note that at the conclusion of the quotation text, the macros
<{RESTORE~SPACING,RMG,LMG}{LS 2}> would
be included.
 This could be packaged in a second macro
ENDQUOTATION defined as:
{ls 1}{Nfj}
<{SETQ ENDQUOTATION,->
  <{RESTORE LMG,RMG,SPACING}{LS 2}}>
{LS 1}{Nfj}
The next example, however, shows a simpler way to do this.
{LI}Do the same thing, only use a pseudo-read.
{ls 1}{nfj}
<{SETQ QUOTATION,->
  <{LS 2}{LIN 7}{RIN 7}{TSET SPACING,1}->
  <{TSET INPUT,,ENDTEXT=!**}->
  <{LS 2}{RESTORE LMG,RMG,SPACING}>
{LS 1}{FJ}
Using the pseudo-read, the way QUOTATION is used is:
{ls 1}{nfj}
     <{QUOTATION}>
           :
           :
     text of quotation
           :
           :
     !**
{ls 1}{Fj}
The last line terminates the pseudo-read and the QUOTATION
macro finishes by evaluating the RESTORE that follows the READ.
{ls 1}
 In the above example, it is important that the <{LS 2}> precede
the TESETs and RESTOREs. This is so that the LS can flush out
any text (line break) before the margins are changed.
{EL}
{P}
!
! TSETQ
!
{macdescr TSETQ,Temporary Quoted Set}
<{TSETQ mname,qstr}>
{macsec description}
TSETQ functions the same as TSET (see description), but
the definition to be set is implicitly quoted.
 TSETQ is thus to TSET what SETQ is to SET.
{macsec notes}
{Bl}TSETQ cannot be used in extended form.
{el}
{macsec examples}
See the descriptions of SETQ and TSET for examples.
{P}
!
! TSETV
!
{Macdescr TSETV,TSET Value for Macro and Return It}
<{TSETV mname,str}>
{macsec description}
TSETV functions identically to TSET (see description)
except instead of having a
a null value, the value of TSETV is the text that is set
as the definition of mname.
{macsec notes}
{BL}TSETV may be used in extended form (as with TSET).
{EL}
{macsec examples}
See the descriptions of TSET and SETV for examples.
{p}
!
! UL
!
{macdescr UL,Underline Text}
<{UL str1,str2}>
{macsec description}
The UL macro uses the overstriking ability of GPMDOC
to produce a new string consisting of the characters of str1
overstruck with underscores. Characters in str2 will not be
underscored in str1. If str2 is not given (null) then all
characters of str1 except blanks will be overstruck with
underscores in the string produced by UL.
{macsec notes}
{BL}Str1 may contain overstruck characters (including
underscores).
{LI}If it is desired to have all characters including blanks
overstruck, str2 can be given as a single character which
could not reasonably appear in str1 (such as a control
character), or the OVER macro can be used to perform the
overstriking directly (see examples for OVER).
{EL}
{macsec examples}
{BL}Print the text "Three Leaf Clover", underlined:
{LS 1}{Center <{UL Three Leaf Clover.}>}
{Ls 1}
This will print as:
{Ls 1}{Center {UL Three Leaf Clover.}}
{Ls 1}{Fj}
{LI}Define a macro ULC that will return its text underscored
except for lower case letters.
{ls 1}
{center <{SETQ ULC,{UL {D 1},abcdefghijklmnopqrstuvwxyz}}>}
{Ls 1}This would be used as in:{Ls 1}
{Center <{ULC Three Leaf Clover.}>}
{Ls 1}which would print as:
{TSETQ ULC,{UL {D 1},abcdefghijklmnopqrstuvwxyz}}
{ULC Three Leaf Clover}
{Restore ULC}
{EL}
{P}
!
! +
!
{macdescr +,Add Numerics}
<{+ n1,n2}>
{macsec description}
The value of + is the sum of the two numeric strings n1 and n2.
{macsec notes}
{BL}For adding or subtracting one,
the ADD1 and SUB1 macros are better.
{LI}+ is very useful in extended SET forms for incrementing
a numeric-valued macro (see examples).
{EL}
{macsec examples}
{Bl}Add the macros PROFIT and NET, print it in column 35:
{Ls 1}{Center <{BRK}{T 35}{+ @PROFIT,@NET}>}
{EL}
{P}
!
! -
!
{MACDESCR -,Subtract Numerics}
<{- n1,n2}>
{macsec description}
The value of - is the difference when n2 is subtracted from n1.
{macsec notes}
{BL}For subtracting one from a number, the SUB1 macro is better.
{LI}- is useful in extended SET form for decrementing a
numeric-valued macro.
{EL}
{macsec examples}
{Bl}Subtract CREDIT from BILLING and print the result in
column 35:
{ls 1}{Center <{BRK}{T 35}{- @BILLING,@CREDIT}>}
{EL}
{P}
!
! *
!
{macdescr *,Multiply Numerics}
<{* n1,n2}>
{Macsec Description}
The value of * is the product of the two numeric strings n1 and n2.
{p}
!
! /
!
{macdescr /,Divide Numerics}
<{/ n1,n2}>
{Macsec Description}
The value of / is the quotient of the two numeric strings n1 and n2.
{Macsec notes}
{Bl}If both n1 and n2 are integers (no decimal point) then the
value of / will also be an integer, formed by discarding any fractional
part from the quotient.
 If either or both of n1 or n2 contain decimals, then the division
will produce a real (floating) result.
{el}
{p}
{Exclude HELP}
!
!	Print the Index
!
{Set pagenum,1}
{Tset input,,Spacing=1,Lmg=10,Rmg=70,Endtext=!**INDEX,Pagelength=55,-
	Newpage=<{Ls 2}{Center Appendix A}{Center Table of Contents}{Ls 2}>,-
	Endpage=<{Ls 1}{Center TOC-{Pagenum}}>-
}
{Dowhile {Lne @Toc},{Tset Toca,@Toc}{Restore Toc}}
{Set Toc_char}
{Dowhile {Lne @Toca},-
  {Cond {Lne @Toc_char,{Setv Toc_char,{Substr @Toca,1,1}}},{Ls 1},,{Brk}}-
  {D Toca}-
  {Restore Toca}-
}
!
!**INDEX
!
{P}
!**
!
{Exclude TEXT}
{Endsec}
!**