[ref] 2 The Help System

[Top] [Up] [Previous] [Next] [Index]

# 2 The Help System

### Sections

1. Invoking the Help
2. Browsing through the Sections
3. Changing the Help Viewer
4. The Pager Command

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

## 2.1 Invoking the Help

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.

  ## 2.3 Changing the Help Viewer

  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):

  text
    This is used for display in the terminal window in which GAP is running. Complicated mathematical expressions may not be well readable in this format.

  dvi
    The standard output format of TeX. Only useful if TeX is installed on your system. Can be used for printing a help book and onscreen reading. Some books include hyperlink information in this format which can be useful for onscreen reading.

  ps
    Postscript format. Can be printed on most systems and also be used with an onscreen viewer.

  pdf
    Adobe's `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.

  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 also has the problem that complicated formulae may be not well readable since there is no syntax for formulae in HTML. Some books use special symbol fonts for formulae and need an appropriate Web-browser for correct display.

  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"`
    This is the default setting. The help is shown in text-format using the `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"`
    If a book is available in HTML-format this is shown using the (already running) `netscape` Web-browser. Note, that for some books the browser must be configured to use symbol fonts.

  `"lynx"`
    If a book is available in HTML-format this is shown using the text based `lynx` Web-browser inside the terminal running GAP. Formulae which use symbol fonts may be unreadable.

  `"internet config"`
    (for Apple Macintosh with MacOS) If a book is available in HTML-format this is shown in a Web browser. The web browser used is the program set to handle the `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"`
    (on X-windows systems) If a book is available in dvi-format it is shown with the onscreen viewer program `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"`
    (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. (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"`
    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 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"`
    This is the same as `"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

  ## 2.4 The Pager Command

  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:

  (1)
    a string (i.e., lines are separated by newline characters)
  (2)
    a list of strings (without newline characters) which are interpreted as lines of the text to be shown
  (3)
    a record with component `.lines` as in (1) or (2) and optional further components

  In case (3) currently the following additional components are used:

  `.formatted`
    can be `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`
    must be a positive integer. This is interpreted as the number of the first line shown by the pager (one may see the beginning of the text via back scrolling).

  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