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.
?[book:][?]topic
For an explanation and some examples see Tutorial: 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 2.2.
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 2.3.
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.
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 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.
?>>
?<<
?<< 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.
?-
?+
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 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 LoadPackage (76.2-1) before you can use the described functions.
?[book:]sections
?[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.
?
?&
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 (2.3-1) below.
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):
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.
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.
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.
‣ SetHelpViewer( viewer1, viewer2, ... ) | ( function ) |
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 2.2.
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 3.2).
"screen"This is the default setting. The help is shown in text format using the Pager (2.4-1) 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 macOS) 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 window 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 macOS) 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 https://skim-app.sourceforge.io/.
"less" or "more"This is the same as "screen" but additionally the user preferences "Pager" and "PagerOptions" are set, see the section 2.4 for more details.
Please, send ideas for further viewer commands to support@gap-system.org.
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.
‣ Pager( lines ) | ( function ) |
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 command line options +nr and +/str which start the display of the text with line number nr or at the line with the first occurrence of the string str.
Which pager is used can be controlled by setting the user preference "Pager". The default value is "builtin" which means that the internal pager is used.
On UNIX systems you probably want to set the user preference "Pager" to the value "less" or "more", you can do this for example in your gap.ini file (see 3.2). In that case you can also tell GAP a list of standard options for the external pager, via the user preference "PagerOptions".
SetUserPreference( "Pager", "less" ); SetUserPreference( "PagerOptions", ["-f","-r","-a","-i","-M","-j2"] );
The argument lines can have one of the following forms:
a string (i.e., lines are separated by newline characters)
a list of strings (without newline characters) which are interpreted as lines of the text to be shown
a record with component lines as in 1. or 2. and optional further components
In case 3. currently the following additional components are used:
formattedcan be false or true. If set to true the builtin pager tries to show the text exactly as it is given (avoiding GAP's automatic line breaking),
startmust be a positive integer or a string. An integer is interpreted as the number of the first line shown by the pager, a string is interpreted as a search string such that the first line containing this string is the first line shown by the pager (in both cases, one may see the beginning of the text via back scrolling),
exitAtEndcan be false or true. If set to true (the default), the builtin pager is terminated as soon as the end of the list is shown; otherwise entering the q key is necessary in order to return from the pager.
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," ")));;
generated by GAPDoc2HTML