This chapter describes the GAP help system. The help system lets you read the documentation interactively.
The basic command to read GAP's documentation from within a GAP session is as follows.
?[?]topic [book:]
For an explanation and some examples see Help.
Note that the first question mark must appear in the first position after
the gap> prompt. The search strings book and topic are normalized in
a certain way (see the end of this section for details)
before the search starts. This makes the search case
insensitive and there can be arbitrary white space after the first question
mark.
When there are several manual sections that match the query a numbered list
of topics is displayed. These matches can be accessed with ?number.
There are some further specially handled commands which start with a question mark. They are explained in section Browsing through the Sections.
As default GAP shows the help sections as text in the terminal (window),
page by page if the shown text does not fit on the screen. But there are
several other choices to read (other formats of) the documents: via a viewer
for dvi-files (produced by TeX) or files in Acrobat's pdf-format or
via a Web-browser. This is explained in section Changing the Help Viewer.
Details of the string normalization process
Here now is precisely how the search strings book and topic are normalized before a search starts: backslashes and double or single quotes are removed, parentheses and braces are substituted by blanks, non-ASCII characters are considered as ISO-latin1 characters and the accented letters are substituted by their non-accented counterpart. Finally white space is normalized.
2.2 Browsing through the Sections
Help books for GAP are organized in chapters, sections and subsections.
There are a few special commands starting with a question mark (in the first
position after the gap> prompt) which allow browsing a book section or
chapter wise.
?>
?<
The two help commands ?< and ?> allow to browse through a whole help
book. ?< displays the section preceding the previously shown section, and
?> takes you to the section following the previously shown one.
?>>
?<<
?<< takes you back to the first section of the current chapter, which
gives an overview of the sections described in this chapter. If you are
already in this section ?<< takes you to the first section of the
previous chapter. ?>> takes you to the first section of the next chapter.
?-
?+
GAP remembers the last few sections that you have read. ?- takes you to
the one that you have read before the current one, and displays it again.
Further applications of ?- take you further back in this history. ?+
reverses this process, i.e., it takes you back to the section that you have
read after the current one. It is important to note that ?- and ?+ do
not alter the history like the other help commands.
?books
This command shows a list of books which are currently known to the help system. For each book there is a short name which is used with the book part of the basic help query and there is a long name which hopefully tells you what this book is about.
A short name which ends in (not loaded) refers to a GAP package
whose documentation is loaded but which needs a call of RequirePackage
(see RequirePackage) before you can use the described functions.
?sections [book:]
?[chapters] [book:]
These commands show tables of content for all available, respectively the matching books.
?
?&
These commands redisplay the last shown help section. In the form ?& the
next preferred help viewer is used for the display (provided one has chosen
several viewers), see SetHelpViewer below.
Books of the GAP help system can be available in several formats. Currently the following formats occur (not all of them may be available for all books):
pdf-format. Can also be used for printing and onscreen reading
on most current systems (with freely available software). Some books have
hyperlink information included in this format.
Depending on your operating system and available additional software you can use several of these formats with GAP's online help. This is configured with the following command.
SetHelpViewer( viewer1, viewer2, ... )
This command takes an arbitrary number of arguments which must be strings describing a viewer. The recognized viewer are explained below. A call with no arguments shows the current setting.
The first given arguments are those with higher priority. So, if a help
section is available in the format needed by viewer1, this viewer is used.
If not, availability of the format for viewer2 is checked and so on.
Recall that the command ?& displays the last seen section again but with
the next possible viewer in your list, see redisplay with next help viewer.
The viewer "screen" (see below) is always silently appended since we
assume that each help book is available in text format.
If you want to change the default setting you will probably put a call of
SetHelpViewer into your .gaprc file (see The .gaprc File).
"screen" Pager command explained in the next section Pager. (Hint: Some
formatting procedures assume that your terminal displays at least 80
characters per line, if this is not the case some sections may look very
bad. Furthermore the terminal (window) should use a fixed width font and
we suggest to take one with ISO-8859-1 (also called latin1) encoding.
"netscape" netscape Web-browser. Note, that for some books the browser
must be configured to use symbol fonts.
"lynx" lynx Web-browser inside the terminal running GAP. Formulae which use
symbol fonts may be unreadable.
"internet config" file protocol in the program Internet Config (System
7 and 8) resp. the Internet control panel (System 9 and System X).
For some browsers (e.g., Internet Explorer), you may have enter the
GAP command
HELP_MAC_PROTOCOL := "file:/";
for this to work correctly. If you wish to use the online html version of
the manual, you may use
HELP_EXTERNAL_URL := "http://www.gap-system.org/";. Note that
HELP_EXTERNAL_URL := ""; switches back to the local html files.
It may be a good idea to put the relevant line in the gap.rc
file (see The .gaprc file).
"xdvi" xdvi. (Of course, xdvi and TeX
must be installed on your system.) This program doesn't allow remote
commands, so usually for each shown topic a new xdvi is launched. You
can try to compile the program GAPPATH/etc/xrmtcmd.c and to put the
executable xrmtcmd into your PATH. Then this viewer tries to reuse one
running xdvi for each help book.
"xpdf" xpdf (which must be installed on your
system). This is a nice program, once it is running it is reused by
GAP for the next displays of help sections. (Hint: On many systems
xpdf shows a very bad display quality, this is due to a wrong or
missing font configuration. One needs to set certain X-resources; for
more details follow the Problems link at
http://www.foolabs.com/xpdf/
"acroread" acroread (which must be available on your system). This program
doesn't allow remote commands or startup with a given page. Therefore the
page numbers you have to visit are just printed on the screen. When you
are looking at several sections of the same book, this viewer assumes that
the acroread window still exists. When you go to another book a new
acroread window is launched.
"less" or "more" "screen" but additionally the PAGER and
PAGER_OPTIONS variables are set, see the next section The Pager Command for more details.
Please, send ideas for further viewer commands to Gap-Trouble@dcs.st-and.ac.uk
GAP contains a builtin pager which shows a text string which doesn't fit on the screen page by page. Its functionality is very rudimentary and self-explaining. This is because (at least under UNIX) there are powerful external standard programs which do this job.
Pager( lines )
This function can be used to display a text on screen using a pager, i.e., the text is shown page by page.
There is a default builtin pager in GAP which has very limited capabilities but should work on any system.
At least on a UNIX system one should use an external pager program like
less or more. GAP assumes that this program has a command line option
+nr which starts the display of the text with line number nr.
Which pager is used can be controlled by setting the variable PAGER. The
default setting is PAGER := "builtin"; which means that the internal
pager is used.
On UNIX systems you probably want to set PAGER := "less"; or PAGER :=
"more";, you can do this for example in your .gaprc file. In that case
you can also tell GAP a list of standard options for the external pager.
These are specified as list of strings in the variable PAGER_OPTIONS.
Example:
PAGER := "less"; PAGER_OPTIONS := ["-f", "-r", "-a", "-i", "-M", "-j2"];
The argument lines can have one of the following forms:
.lines as in (1) or (2) and
optional further components
In case (3) currently the following additional components are used:
.formatted false or true. If set to true the builtin pager tries to show
the text exactly as it is given (avoiding GAPs automatic line breaking)
.start
The Pager command is used by GAP's help system for displaying help
sections in text-format. But, of course, it may be used for other purposes
as well.
gap> s6 := SymmetricGroup(6);; gap> words := ["This", "is", "a", "very", "stupid", "example"];; gap> l := List(s6, p-> Permuted(words, p));; gap> Pager(List(l, a-> JoinStringsWithSeparator(a," ")));;
[Top] [Up] [Previous] [Next] [Index]
GAP 4 manual
May 2002