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