Debian Codegraph @

examples/README

raw
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.