Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve manual section about Info classes #2834

Merged
merged 1 commit into from
Sep 19, 2018
Merged

Improve manual section about Info classes #2834

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 34 additions & 15 deletions doc/ref/debug.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,18 +94,34 @@ afterwards.
<Section Label="Info Functions">
<Heading>Info Functions</Heading>

The <Ref Func="Info"/> mechanism permits operations to display intermediate results or
The <Index>verbosity of GAP output</Index><Ref Func="Info"/> mechanism
permits operations to display intermediate results or
information about the progress of the algorithms.
Information is always given according to one or more <E>info classes</E>. Each of the
info classes defined in the &GAP; library usually covers a certain range
of algorithms, so for example <C>InfoLattice</C> covers all the cyclic extension
algorithms for the computation of a subgroup lattice.
<P/>
The amount of information to be displayed can be specified by the user for
each info class separately by a <E>level</E>, the higher the level the more
information will be displayed.
Ab initio all info classes have level zero except
<Ref Func="InfoWarning"/> which initially has level 1.

Note that not all info classes defined in the &GAP; library are currently
documented. Many &GAP; packages define additional info classes, which are
typically documented in the corresponding package documentation.
<P/>
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
<E>level</E> 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:
<List>
<Item><Ref Func="InfoWarning"/>,</Item>
<Item><Ref Func="InfoPackageLoading"/>,</Item>
<Item><C>InfoDebug</C>,</Item>
<Item><C>InfoPerformance</C>,</Item>
<Item><C>InfoTempDirectories</C>,</Item>
<Item><C>InfoPrimeInt</C>, and</Item>
<Item><C>InfoSLP</C>.</Item>
</List>
<P/>
<ManSection>
<Oper Name="NewInfoClass" Arg='name'/>
Expand All @@ -129,7 +145,8 @@ readonly by this function.
<Oper Name="SetInfoLevel" Arg='infoclass, level'/>

<Description>
Sets the info level for <A>infoclass</A> to <A>level</A>.
Sets the info level for <A>infoclass</A> to the non-negative integer
<A>level</A>.
</Description>
</ManSection>
<P/>
Expand All @@ -145,13 +162,15 @@ returns the info level of <A>infoclass</A>.
<Func Name="Info" Arg='infoclass, level, info[, moreinfo ...]'/>

<Description>
If the info level of <A>infoclass</A> is at least <A>level</A> the remaining
arguments, <A>info</A> and possibly <A>moreinfo</A> and so on, are evaluated.
If the info level of <A>infoclass</A> is at least <A>level</A>, then the remaining
arguments, <A>info</A>, and possibly <A>moreinfo</A> and so on, are evaluated.
(Technically, <Ref Func="Info"/> is a keyword and not a function.)
<P/>
By default, they are
By default, the results of these evaluations are
viewed, preceded by the string <C>"#I "</C> and followed by a newline.
Otherwise the third and subsequent arguments are not evaluated.
<P/>
If the info level of <A>infoclass</A> is strictly less than <A>level</A>, then
the third and subsequent arguments are not evaluated.
(The latter can save substantial time when displaying difficult results.)
<P/>
The behaviour can be customized with <Ref Func="SetInfoHandler"/>.
Expand Down Expand Up @@ -208,12 +227,12 @@ gap> InfoLevel(InfoWarning);
<Func Arg="out" Name="SetDefaultInfoOutput" />
<Returns>nothing</Returns>
<Description>
This allows to customize what happens in an
This allows one to customize what happens in an
<C>Info(<A>infoclass</A>, <A>level</A>, ...)</C> statement.<P/>
In the first function <A>handler</A>
In the first function, <A>handler</A>
must be a function with three arguments <A>infoclass</A>, <A>level</A>,
<A>list</A>. Here <A>list</A> is the list containing the third to last
argument of the <Ref Func="Info"/> call.
<A>list</A>. Here <A>list</A> is the list containing the third argument and
any subsequent optional arguments of the <Ref Func="Info"/> call.
<P/>
The default handler is the function <C>DefaultInfoHandler</C>.
<Index Key="DefaultInfoHandler"><C>DefaultInfoHandler</C></Index>
Expand Down