Skip to content

Commit 81963ee

Browse files
ThomasBreuerThomasBreuer
authored
better documentation for user preferences (#5248)
* better documentation for user preferences - added a new subsection "User Preferences Defined by ⪆" to the section of the GAP Reference Manual that deals with user preferences, - added the file `doc/ref/user_pref_list.xml` that contains the current list of descriptions of user preferences that are declared for GAP (not for GAP packages); this includes an index entry for each user preference, - added the function `XMLForUserPreferences` that creates the contents of `doc/ref/user_pref_list.xml` from the declarations of the user preferences, - added GAPDoc markup to the description strings in the declarations of GAP's user preferences, - changed `ShowStringUserPreference` such that this markup disappears when the description is shown in the GAP session, - added a remark about `BrowseUserPreferences` in the documentation of `ShowUserPreferences`, - added a test that complains when `doc/ref/user_pref_list.xml` is not up-to-date. * try to find out why the new test fails * move the declaration of some user preferences Up to now, the user preferences `Autocompleter`, `HistoryMaxLines`, and `SaveAndRestoreHistory` got declared only when `readline` was supported. In order to get them documented also in the case of GAP without `readline`, we move their declarations outside the `if` branch that is executed only for GAP with `readline` support. * deal with HPCGAP Up to now, there is a file `hpcgap/lib/userpref.g` which differs from `lib/userpref.g` by some `AtomicRecord` and `AtomicList` calls, plus some `MakeImmutable` calls for the records that define user preferences. Now `lib/userpref.g` gets adjusted to these HPCGAP requirements, and `hpcgap/lib/userpref.g` gets removed. Let us see whether we run into trouble because of the now immutable records. * one more HPCGAP specific file adjusted * moved `hpcgap/lib/integer.gi` to `lib/integer.gi` * document that values of user preferences are immutable The immutability in "plain" GAP is a consequence of commit df9078d; In HPCGAP, the values had been immutable before this commit. Now the documentation states that the values of user preferences are always immutable.
1 parent 27fcd6f commit 81963ee

File tree

14 files changed

+583
-2618
lines changed

14 files changed

+583
-2618
lines changed

‎doc/ref/run.xml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -536,6 +536,19 @@ which GAP will not recognize.
536536

537537
<#Include Label="UserPreferences">
538538

539+
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
540+
<Subsection Label="subsect:User Preferences Defined by GAP">
541+
<Heading>User Preferences Defined by &GAP;</Heading>
542+
543+
Here is the list of those user preferences that are currently declared
544+
via <Ref Func="DeclareUserPreference"/> for &GAP; itself.
545+
The preferences that are declared for &GAP; packages belong to the
546+
documentation of these packages.
547+
548+
<#Include SYSTEM "user_pref_list.xml">
549+
550+
</Subsection>
551+
539552
</Section>
540553

541554

‎doc/ref/user_pref_list.xml

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
<List>
2+
<Mark>
3+
<Index Key='Autocompleter'><C>Autocompleter</C></Index>
4+
<C>Autocompleter</C>
5+
</Mark>
6+
<Item>
7+
Set how names are filtered during tab-autocomplete, this can be:
8+
<C>"default"</C>: case-sensitive matching. <C>"case-insensitive"</C>:
9+
case-insensitive matching, or a record with two components named <C>filter</C>
10+
and <C>completer</C>, which are both functions which take two arguments.
11+
<C>filter</C> takes a list of names and a partial identifier and returns all
12+
the members of <C>names</C> which are a valid extension of the partial
13+
identifier. <C>completer</C> takes a list of names and a partial identifier
14+
and returns the partial identifier as extended as possible (it may also change
15+
the identifier, for example to correct the case, or spelling mistakes), or
16+
returns <K>fail</K> to leave the existing partial identifier.
17+
<P/>
18+
This preference is ignored if &GAP; was not compiled with readline support.
19+
20+
<P/>
21+
22+
Default: <C>"default"</C>.
23+
</Item>
24+
<Mark>
25+
<Index Key='Editor'><C>Editor</C></Index>
26+
<Index Key='EditorOptions'><C>EditorOptions</C></Index>
27+
<C>Editor</C>,
28+
<C>EditorOptions</C>
29+
</Mark>
30+
<Item>
31+
Determines the editor and options (used by &GAP;'s <Ref Func="Edit"/>
32+
command). Under macOS, the value <C>"open"</C> for <C>Editor</C> will work.
33+
For further options, see the &GAP; help for <Ref Func="Edit"/>. If you want to
34+
use the editor defined in your (shell) environment then leave the
35+
<C>Editor</C> and <C>EditorOptions</C> preferences empty.
36+
37+
<P/>
38+
39+
The defaults are computed at runtime.
40+
</Item>
41+
<Mark>
42+
<Index Key='ExcludeFromAutoload'><C>ExcludeFromAutoload</C></Index>
43+
<C>ExcludeFromAutoload</C>
44+
</Mark>
45+
<Item>
46+
These packages are not loaded at &GAP; startup. This doesn't work for packages
47+
which are needed by the &GAP; library, or which are already loaded in a
48+
workspace.
49+
50+
<P/>
51+
52+
Default: <C>""</C>.
53+
</Item>
54+
<Mark>
55+
<Index Key='HelpViewers'><C>HelpViewers</C></Index>
56+
<Index Key='XpdfOptions'><C>XpdfOptions</C></Index>
57+
<Index Key='XdviOptions'><C>XdviOptions</C></Index>
58+
<C>HelpViewers</C>,
59+
<C>XpdfOptions</C>,
60+
<C>XdviOptions</C>
61+
</Mark>
62+
<Item>
63+
Here you can choose your preferred help viewers. See the help for <Ref
64+
Func="SetHelpViewer"/> for further options.
65+
<P/>
66+
Try <C>HelpViewers:= [ "screen", "firefox", "xpdf" ];</C>.
67+
<P/>
68+
(For <C>"screen"</C> we also suggest to set the <C>Pager</C> entry to
69+
<C>"less"</C>.)
70+
71+
<P/>
72+
73+
Defaults: <C>[ [ "screen" ], "", "" ]</C>.
74+
</Item>
75+
<Mark>
76+
<Index Key='HistoryMaxLines'><C>HistoryMaxLines</C></Index>
77+
<Index Key='SaveAndRestoreHistory'><C>SaveAndRestoreHistory</C></Index>
78+
<C>HistoryMaxLines</C>,
79+
<C>SaveAndRestoreHistory</C>
80+
</Mark>
81+
<Item>
82+
<C>HistoryMaxLines</C> is the maximal amount of input lines held in &GAP;'s
83+
command line history.
84+
<P/>
85+
If <C>SaveAndRestoreHistory</C> is <K>true</K> then &GAP; saves its command
86+
line history before terminating a &GAP; session, and prepends the stored
87+
history when &GAP; is started. If this is enabled it is suggested to set
88+
<C>HistoryMaxLines</C> to some finite value. It is also possible to set
89+
<C>HistoryMaxLines</C> to <Ref Var="infinity"/> to keep arbitrarily many
90+
lines.
91+
<P/>
92+
These preferences are ignored if &GAP; was not compiled with readline support.
93+
94+
<P/>
95+
96+
Defaults: <C>[ 10000, true ]</C>.
97+
</Item>
98+
<Mark>
99+
<Index Key='InfoPackageLoadingLevel'><C>InfoPackageLoadingLevel</C></Index>
100+
<C>InfoPackageLoadingLevel</C>
101+
</Mark>
102+
<Item>
103+
Info messages concerning package loading up to this level are printed. The
104+
level can be changed in a running session using <Ref Func="SetInfoLevel"/>.
105+
106+
<P/>
107+
108+
Admissible values:
109+
<C>1</C>,
110+
<C>2</C>,
111+
<C>3</C>,
112+
<C>4</C>.
113+
114+
<P/>
115+
116+
Default: <C>1</C>.
117+
</Item>
118+
<Mark>
119+
<Index Key='MaxBitsIntView'><C>MaxBitsIntView</C></Index>
120+
<C>MaxBitsIntView</C>
121+
</Mark>
122+
<Item>
123+
Maximal bit length of integers to <C>View</C> unabbreviated. Default is about
124+
<M>30</M> lines of a <M>80</M> character wide terminal. Set this to <C>0</C>
125+
to avoid abbreviated ints.
126+
127+
<P/>
128+
129+
Default: <C>8000</C>.
130+
</Item>
131+
<Mark>
132+
<Index Key='PartialPermDisplayLimit'><C>PartialPermDisplayLimit</C></Index>
133+
<Index Key='NotationForPartialPerms'><C>NotationForPartialPerms</C></Index>
134+
<C>PartialPermDisplayLimit</C>,
135+
<C>NotationForPartialPerms</C>
136+
</Mark>
137+
<Item>
138+
options for the display of partial perms
139+
140+
<P/>
141+
142+
Defaults: <C>[ 100, "component" ]</C>.
143+
</Item>
144+
<Mark>
145+
<Index Key='TransformationDisplayLimit'><C>TransformationDisplayLimit</C></Index>
146+
<Index Key='NotationForTransformations'><C>NotationForTransformations</C></Index>
147+
<C>TransformationDisplayLimit</C>,
148+
<C>NotationForTransformations</C>
149+
</Mark>
150+
<Item>
151+
options for the display of transformations
152+
153+
<P/>
154+
155+
Defaults: <C>[ 100, "input" ]</C>.
156+
</Item>
157+
<Mark>
158+
<Index Key='PackagesToIgnore'><C>PackagesToIgnore</C></Index>
159+
<C>PackagesToIgnore</C>
160+
</Mark>
161+
<Item>
162+
These packages are not regarded as available. This doesn't work for packages
163+
which are needed by the &GAP; library, or which are already loaded in a
164+
workspace.
165+
166+
<P/>
167+
168+
Default: <C>""</C>.
169+
</Item>
170+
<Mark>
171+
<Index Key='PackagesToLoad'><C>PackagesToLoad</C></Index>
172+
<C>PackagesToLoad</C>
173+
</Mark>
174+
<Item>
175+
A list of names of packages which should be loaded during startup. For
176+
backwards compatibility, the default lists most of packages that were
177+
autoloaded in &GAP; 4.4 (add or remove packages as you like).
178+
179+
<P/>
180+
181+
Default: <C>[ "autpgrp", "alnuth", "crisp", "ctbllib", "factint", "fga", "irredsol", "laguna", "polenta", "polycyclic", "resclasses", "sophus", "tomlib" ]</C>.
182+
</Item>
183+
<Mark>
184+
<Index Key='Pager'><C>Pager</C></Index>
185+
<Index Key='PagerOptions'><C>PagerOptions</C></Index>
186+
<C>Pager</C>,
187+
<C>PagerOptions</C>
188+
</Mark>
189+
<Item>
190+
For displaying help pages on screen and other things &GAP; has a rudimentary
191+
builtin pager. We recommend using a more sophisticated external program. For
192+
example, when you have the program <C>less</C> on your computer we recommend:
193+
<P/>
194+
<C>Pager := "less";</C>
195+
<P/>
196+
<C>PagerOptions := ["-f", "-r", "-a", "-i", "-M", "-j2"];</C>
197+
<P/>
198+
If you want to use <C>more</C>, we suggest to use the <C>-f</C> option. If you
199+
want to use the pager defined in your environment then leave the <C>Pager</C>
200+
and <C>PagerOptions</C> preferences empty.
201+
202+
<P/>
203+
204+
The defaults are computed at runtime.
205+
</Item>
206+
<Mark>
207+
<Index Key='ReadObsolete'><C>ReadObsolete</C></Index>
208+
<C>ReadObsolete</C>
209+
</Mark>
210+
<Item>
211+
May be useful to say <K>false</K> here to check if you are using commands
212+
which may vanish in a future version of &GAP;
213+
214+
<P/>
215+
216+
Admissible values:
217+
<K>true</K>,
218+
<K>false</K>.
219+
220+
<P/>
221+
222+
Default: <K>true</K>.
223+
</Item>
224+
<Mark>
225+
<Index Key='ReproducibleBehaviour'><C>ReproducibleBehaviour</C></Index>
226+
<C>ReproducibleBehaviour</C>
227+
</Mark>
228+
<Item>
229+
This preference disables code in &GAP; which changes behaviour based on time
230+
spent, and therefore can produce different results depending on how much time
231+
is taken by other programs running on the same computer. This option may lead
232+
to slower or lower-quality results. Note that many algorithms in &GAP; use the
233+
global random number generator, which is NOT affected by this option. This
234+
only tries to ensure the same version of &GAP;, with the same package versions
235+
loaded, on the same machine, running the same code, in a fresh &GAP; session,
236+
will produce the same results.
237+
238+
<P/>
239+
240+
Admissible values:
241+
<K>true</K>,
242+
<K>false</K>.
243+
244+
<P/>
245+
246+
Default: <K>false</K>.
247+
</Item>
248+
<Mark>
249+
<Index Key='UseColorPrompt'><C>UseColorPrompt</C></Index>
250+
<C>UseColorPrompt</C>
251+
</Mark>
252+
<Item>
253+
In a color capable terminal (almost any terminal application) you can run
254+
&GAP; such that the prompts, the input and output are distinguished by colors.
255+
Options are <K>true</K>, <K>false</K> or some record as explained in the help
256+
section for <Ref Func="ColorPrompt"/>.
257+
258+
<P/>
259+
260+
Default: <K>true</K>.
261+
</Item>
262+
<Mark>
263+
<Index Key='UseColorsInTerminal'><C>UseColorsInTerminal</C></Index>
264+
<C>UseColorsInTerminal</C>
265+
</Mark>
266+
<Item>
267+
Almost all current terminal emulations support color display, setting this to
268+
<K>true</K> implies a default display of most manuals with color markup. It
269+
may influence the display of other things in the future.
270+
271+
<P/>
272+
273+
Admissible values:
274+
<K>true</K>,
275+
<K>false</K>.
276+
277+
<P/>
278+
279+
Default: <K>true</K>.
280+
</Item>
281+
<Mark>
282+
<Index Key='ViewLength'><C>ViewLength</C></Index>
283+
<C>ViewLength</C>
284+
</Mark>
285+
<Item>
286+
A bound for the number of lines printed when <C>View</C>ing some large
287+
objects.
288+
289+
<P/>
290+
291+
Default: <C>3</C>.
292+
</Item>
293+
</List>

0 commit comments

Comments
 (0)