The Help System

This chapter describes the &GAP; help system. The help system lets you read the documentation interactively.

Invoking the Help

The basic command to read &GAP;'s documentation from within a &GAP; session is as follows.

getting help
?[book:][?]topic

For an explanation and some examples see .

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 .

By 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 pdf files or via a web browser. This is explained below in Section .

Details of the string normalization process

Here is a precise description 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.

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.

browsing forward
?>

browsing backwards
?<

The two help commands ?< and ?> allow one to browse through a whole help book. ?< displays the section or subsection preceding the previously shown (sub)section, and ?> takes you to the section or subsection following the previously shown one.

browsing forward one chapter
?>>

browsing backwards one chapter
?<<

?<<
takes you back to the beginning of the current chapter. If you are already at the start of a chapter ?<< takes you to the beginning of the previous chapter. ?>> takes you to the beginning of the next chapter.

browsing the previous section browsed
?-

browsing the next section browsed
?+

&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.

list of available books
?books

This command shows a list of the 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 before you can use the described functions.

table of sections for help books
?[book:]sections

table of chapters for help books
?[book:][chapters]

These commands show tables of contents for all available, respectively the matching books. For some books these commands show the same, namely the whole table of contents.

redisplay a help section
?

redisplay with next help viewer
?&

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 below.

Changing the Help Viewer
document formats (text, dvi, ps, pdf, HTML)

Books of the &GAP; help system or package manuals can be available in several formats. Currently the following formats occur (not all of them may be available for all books):

text
This is used for display in the terminal window in which &GAP; is running. Complicated mathematical expressions may not be easy to read in this format.
pdf
Adobe's pdf format. Can be used for printing and onscreen reading on most current systems (with freely available software). Some manual books contain hyperlinks in this format.
HTML
The format of web pages. Can be used with any web browser. There may be hyperlink information available which allows a convenient browsing through the book via cross-references. This format has the problem that complicated formulae may be not be easy to read since there is no syntax for formulae in HTML. (Some older manual books use special symbol fonts for formulae and need a particular configuration of the web browser for correct display. Some manuals may use technology for quite sophisticated formula display.)

Depending on your operating system and available additional software you can use several of these formats with &GAP;'s help system. This is configured with the following command.

This command takes an arbitrary number of arguments which must be strings describing a viewer. The recognized viewers 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 .

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 can use a call of SetUserPreference( "HelpViewers", [ ... ] ); (the list in the second argument containing the viewers you want) in your gap.ini file (see ).

"screen"
This is the default setting. The help is shown in text format using the command. Hint: Text versions of manuals are formatted assuming that your terminal displays at least 80 characters per line, if this is not the case some sections may look very bad. We suggest to use a terminal in UTF-8 encoding with a fixed width font (this is the default on most modern Linux/Windows/Mac systems anyway). Terminals in ISO-8859-X encoding will also work reasonably well (so far, since we do not yet use many special characters which such terminals could not display).
"firefox"
, chrome, "mozilla", "netscape", "konqueror"
If a book is available in HTML format this is shown using the corresponding web browser. How well this works, for example by using a running instance of this browser, depends on your particular start script of this browser. (Note, that for some old books the browser must be configured to use symbol fonts.)
"browser"
(for MS Windows) If a book is available in HTML format, it will be opened using the Windows default application (typically, a web browser).
"links2"
, "w3m", "lynx"
If a book is available in HTML format this is shown using the text based "links2" (in graphics mode), w3m or lynx web browser, respectively, inside the terminal running &GAP;. (Formulae in some older books which use symbol fonts may be unreadable.)
"mac default browser"
, "browser", "safari", "firefox"
(for Mac OS X) If a book is available in HTML format this is shown in a web browser. The options "safari" and "firefox" use the corresponding browsers. The other two options use the program default browser (which can be set in Safari's preferences, in the "General" tab).
"xpdf"
(on X-windows systems) If a book is available in pdf format it is shown with the onscreen viewer program 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.
"acroread"
If a book is available in pdf format it is shown with the onscreen viewer program acroread (which must be available on your system). This program does not 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.
"pdf viewer"
, "skim", "preview", "adobe reader"
(for Mac OS X) If a book is available in pdf format this is shown in a pdf viewer. The options "skim", "preview" and "adobe reader" use the corresponding viewers. The other two options use the pdf viewer which you have chosen to open pdf files from the Finder. Note that only "Skim" seems to be capable to open a pdf file on a given page. For the other help viewers, the page numbers where the information can be found will just be printed on the screen. None of the help viewers seems to be capable of opening a pdf at a given named destination (i. e., jump to precisely the place where the information can be found). The pdf viewer "Skim" is open source software, it can be downloaded from http://skim-app.sourceforge.net/.
"less"
or "more"
This is the same as "screen" but additionally the user preferences "Pager" and ""PagerOptions" are set, see the section for more details.

Please, send ideas for further viewer commands to support@gap-system.org.
The Pager Command

&GAP; contains a builtin pager which shows a text string which does not 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.

<#Include Label="Pager">