Dear GAP Forum,

the GAP Team has been asked several times about the status of
undocumented GAP functions,
and a policy to turn them into documented functions.

As an answer to this request,
the following section has been added to the GAP documentation.

Undocumented Variables _____________________________________ Library Files

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 Mailto{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}.

Kind regards,
Thomas Breuer