diff --git a/doc/ref/debug.xml b/doc/ref/debug.xml index 2cd2686806..d604b5567c 100644 --- a/doc/ref/debug.xml +++ b/doc/ref/debug.xml @@ -94,18 +94,34 @@ afterwards.
Info Functions -The mechanism permits operations to display intermediate results or +The verbosity of GAP output mechanism +permits operations to display intermediate results or information about the progress of the algorithms. Information is always given according to one or more info classes. Each of the info classes defined in the ⪆ library usually covers a certain range of algorithms, so for example InfoLattice covers all the cyclic extension algorithms for the computation of a subgroup lattice.

-The amount of information to be displayed can be specified by the user for -each info class separately by a level, the higher the level the more -information will be displayed. -Ab initio all info classes have level zero except - which initially has level 1. + +Note that not all info classes defined in the ⪆ library are currently +documented. Many ⪆ packages define additional info classes, which are +typically documented in the corresponding package documentation. +

+The amount of information to be displayed by each info class can be separately +specified by the user. This is done by selecting a non-negative integer +level for the info class: no information will be displayed at level 0, +and the higher the level, the more information that will be displayed. At +creation, an info class has level 0. By default, all built-in GAP info classes +have level 0, except for the following info classes, which have level 1: + + , + , + InfoDebug, + InfoPerformance, + InfoTempDirectories, + InfoPrimeInt, and + InfoSLP. +

@@ -129,7 +145,8 @@ readonly by this function. -Sets the info level for infoclass to level. + Sets the info level for infoclass to the non-negative integer + level.

@@ -145,13 +162,15 @@ returns the info level of infoclass. -If the info level of infoclass is at least level the remaining -arguments, info and possibly moreinfo and so on, are evaluated. +If the info level of infoclass is at least level, then the remaining +arguments, info, and possibly moreinfo and so on, are evaluated. (Technically, is a keyword and not a function.)

-By default, they are +By default, the results of these evaluations are viewed, preceded by the string "#I " and followed by a newline. -Otherwise the third and subsequent arguments are not evaluated. +

+If the info level of infoclass is strictly less than level, then +the third and subsequent arguments are not evaluated. (The latter can save substantial time when displaying difficult results.)

The behaviour can be customized with . @@ -208,12 +227,12 @@ gap> InfoLevel(InfoWarning); nothing -This allows to customize what happens in an +This allows one to customize what happens in an Info(infoclass, level, ...) statement.

-In the first function handler +In the first function, handler must be a function with three arguments infoclass, level, -list. Here list is the list containing the third to last -argument of the call. +list. Here list is the list containing the third argument and +any subsequent optional arguments of the call.

The default handler is the function DefaultInfoHandler. DefaultInfoHandler