3.4 Undocumented Variables

For several global variables in GAP, no information is available via the help system (see The Help System). There are various reasons for ``hiding'' a variable from the user; namely, the variable may be regarded as of minor importance (for example, it may be a function called by documented GAP functions that first compute many input parameters for the undocumented function), or it belongs to a part of GAP that is still experimental in the sense that the meaning of the variable has not yet been fixed or even that it is not clear whether the variable will vanish in a more developed version.

As a consequence, it is dangerous to use undocumented variables because they are not guaranteed to exist or to behave the same in future versions of GAP.

Conversely, for documented variables, the definitions in the GAP manual can be relied on for future GAP versions (unless they turn out to be erroneous); if the GAP developers find that some piece of minor, but documented functionality is an insurmountable obstacle to important developments, they may make the smallest possible incompatible change to the functionality at the time of a major release. However, in any such case it will be announced clearly in the GAP Forum what has been changed and why.

So on the one hand, the developers of GAP want to keep the freedom of changing undocumented GAP code. On the other hand, users may be interested in using undocumented variables.

In this case, whenever you write GAP code involving undocumented variables, and want to get sure that this code will work in future versions of GAP, you may ask at gap-trouble@dcs.st-and.ac.uk for documentation about the variables in question. The GAP developers then decide whether these variables shall be documented or not, and if yes, what the definitions shall be.

In the former case, the new documentation is added to the GAP manual, this means that from then on, this definition is protected against changes.

In the latter case (which may occur for example if the variables in question are still experimental), you may add the current values of these variables to your private code if you want to be sure that nothing will be broken later due to changes in GAP.

[Top] [Previous] [Up] [Index]

GAP 4 manual
February 2000