| 1 |
Here we describe the format of the examples. |
| 2 |
|
| 3 |
Firstly, each file *can* be read using `Read', but `PqExample' does a |
| 4 |
little more (by echoing to the screen) and requires the following: |
| 5 |
|
| 6 |
0. Blank lines are ok, but must consist of only a new-line (and no |
| 7 |
other white-space. |
| 8 |
|
| 9 |
1. The file can start with any number of commented out lines followed |
| 10 |
by a line of form: |
| 11 |
|
| 12 |
#Example <example-name> . . . <comment> |
| 13 |
|
| 14 |
where <example-name> is the name of the file in a pair of |
| 15 |
double-quotes and <comment> should say something like `based on ...'. |
| 16 |
This line can be followed by any number of commented out lines |
| 17 |
followed by: |
| 18 |
|
| 19 |
#vars: <list>; |
| 20 |
|
| 21 |
where <list> is a comma (and/or blank) separated list of variables |
| 22 |
used in the example. Missing one will cause the possible over-writing |
| 23 |
of a user variable. This line should be no longer than 72 characters. |
| 24 |
|
| 25 |
A number of examples have a <comment> stating `based on <dir>/...' |
| 26 |
where <dir> is `examples' or `isom' which are sub-directories of the |
| 27 |
`standalone' directory. |
| 28 |
|
| 29 |
2. The next line must be of form: |
| 30 |
|
| 31 |
#options: <list> |
| 32 |
|
| 33 |
(like 1. except <list> should contain a list of the options of the |
| 34 |
example that the user can provide, to change the behaviour of the |
| 35 |
example). |
| 36 |
|
| 37 |
3. Any statement for which GAP does not produce output should |
| 38 |
terminate with a double-;. `PqExample' tries to emulate a user typing |
| 39 |
the commands and when executing a line of input displays all the |
| 40 |
output a user would normally see. A double-; tells `PqExample' not to |
| 41 |
try to get output from the command on executing it. All statements |
| 42 |
terminating with a double-; are displayed with a single ;. |
| 43 |
|
| 44 |
4. Comments that you want the user to see should appear after a |
| 45 |
double-#. On execution/printing of the example the user only sees one |
| 46 |
#. |
| 47 |
|
| 48 |
All other lines beginning with # are special: |
| 49 |
|
| 50 |
5. A line of form: |
| 51 |
|
| 52 |
#comment: set a different ... by supplying <...> |
| 53 |
|
| 54 |
is ignored when the example is executed but Info-ed at `InfoANUPQ' |
| 55 |
level 1 when printed as: |
| 56 |
|
| 57 |
#I In the next command, you may set a different ... by |
| 58 |
#I supplying to `PqExample' the option: `...' |
| 59 |
|
| 60 |
where the ... is anything in each case but every other word should be |
| 61 |
something that makes sense in a similarly substituted sentence. The |
| 62 |
word `supplying' and a pair of angle brackets (<>) enclosing an |
| 63 |
option *must* be present. |
| 64 |
|
| 65 |
6. A line of form: |
| 66 |
|
| 67 |
#sub <<option>> for <<value>> if set and ok |
| 68 |
|
| 69 |
is interpreted only when the example is executed (and ignored when |
| 70 |
printed). It states that if the option <option> has been passed to |
| 71 |
`PqExample' and its value is ok then that value should be substituted |
| 72 |
for <value> on the next line. There should normally be a companion |
| 73 |
`#comment:' line as per 5, to tell the user that the option exists, |
| 74 |
usually on the line previous, but in any case at a sensible place. |
| 75 |
Care should be taken to ensure <value> only occurs once on the line |
| 76 |
(GAP's `ReplacedString' is used). The option <option> should either |
| 77 |
be exactly the option used in the following line (so that the right |
| 78 |
check is used) or the option with a single digit (0..9) appended. |
| 79 |
(The possibility of adding a digit is included to allow the cases |
| 80 |
where the same option occurs in more than one line of the example and |
| 81 |
one wishes to avail the user of changing the option to possibly |
| 82 |
different values in those places. There may be additional argument |
| 83 |
checking required for such options which is the reason 10. is |
| 84 |
provided.) Options passed to `PqExample' with ok values are stored in |
| 85 |
the record `ANUPQData.example.options'. |
| 86 |
|
| 87 |
7. A line of form: |
| 88 |
|
| 89 |
#add <<option>> for <value> if set and ok |
| 90 |
|
| 91 |
is very similar to `#sub' described in 6. It is interpreted only when |
| 92 |
the example is executed (and ignored when printed). It states that if |
| 93 |
the option <option> has been passed to `PqExample' and its value is |
| 94 |
ok then the following line which should be commented out by a single |
| 95 |
#, should be made uncommented (by replacing the initial `#' with a |
| 96 |
blank) and the value of <option> should be substituted for <value> on |
| 97 |
the next line (unlike `#sub', `<value>' should occur literally in the |
| 98 |
`#add' and the line following. All other things mentioned for `#sub' |
| 99 |
(including that there should be a companion `#comment:' line) apply |
| 100 |
to `#add'. |
| 101 |
|
| 102 |
8. A line of form: |
| 103 |
|
| 104 |
#alt: do |
| 105 |
|
| 106 |
says uncomment the following line if `PqExample' is called with |
| 107 |
argument `PqStart'. |
| 108 |
|
| 109 |
9. A line of form: |
| 110 |
|
| 111 |
#alt: sub <var2> for <var1> |
| 112 |
|
| 113 |
says replace <var1> with <var2> if `PqExample' is called with |
| 114 |
argument `PqStart' (the idea being to convert the example form a |
| 115 |
non-interactive example to an interactive one). |
| 116 |
|
| 117 |
10. All other lines starting with a # are lines that should be |
| 118 |
executed in the background (with the # removed) without being |
| 119 |
displayed when `PqExample' is called to execute an example. Such |
| 120 |
lines are ignored when `PqExample' is called to print an example. |
| 121 |
This has been added mainly for doing additional option checking. For |
| 122 |
convenience, `datarec' may be used as an abbreviation for |
| 123 |
`ANUPQData.example.options'. |
| 124 |
|
| 125 |
An example of how one might want to use this is as follows. Suppose |
| 126 |
there are two places where one uses `ClassBound' in the example but |
| 127 |
you wish to make it possible for the user to change the default |
| 128 |
values used. In this case, there will need to be lines something like |
| 129 |
`#sub <ClassBound1> for ...' and `#sub <ClassBound2> for ...' i.e. |
| 130 |
`PqExample' will have options `ClassBound1' and `ClassBound2'. |
| 131 |
Suppose you need to ensure `ClassBound1' > `ClassBound2' then you |
| 132 |
might want to do something like the following: |
| 133 |
|
| 134 |
#if IsBound(datarec.ClassBound1) then |
| 135 |
# if (IsBound(datarec.ClassBound2) and |
| 136 |
# datarec.ClassBound2 <= datarec.ClassBound1) or |
| 137 |
# (not( IsBound(datarec.ClassBound2) ) and 19 <= datarec.ClassBound1) then |
| 138 |
# datarec.ClassBound2 := datarec.ClassBound1 + 1; |
| 139 |
# Info(InfoANUPQ,1, "ClassBound2 must be greater than ",datarec.ClassBound1); |
| 140 |
# Info(InfoANUPQ,1, "ClassBound2 reset to ", datarec.ClassBound2); |
| 141 |
# fi; |
| 142 |
#elif IsBound(datarec.ClassBound2) and datarec.ClassBound2 <= 3 then |
| 143 |
# datarec.ClassBound2 := 4; |
| 144 |
# Info(InfoANUPQ,1, "ClassBound2 must be greater than 3"); |
| 145 |
# Info(InfoANUPQ,1, "ClassBound2 reset to ", datarec.ClassBound2); |
| 146 |
#fi; |
| 147 |
|
| 148 |
Observe that the idea is not to accept values of options that will |
| 149 |
run `PqExample' into error; it's not designed to cope with such a |
| 150 |
possibility. |
| 151 |
|
| 152 |
- Greg Gamble -- 7 August, 2001; 14 February, 2002. |