<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %A  help.tex               GAP documentation                    Frank Lbeck -->
<!-- %% -->
<!-- %% -->
<!-- %Y  Copyright 1990-2001, Lehrstuhl D für Mathematik, RWTH Aachen, Germany -->
<!-- %% -->
<!-- %%  Original version by Martin Schönert. -->
<!-- %% -->
<Chapter Label="The Help System">
<Heading>The Help System</Heading>

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


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Invoking the Help">
<Heading>Invoking the Help</Heading>

The  basic command  to  read  &GAP;'s documentation  from  within a  &GAP;
session is as follows.
<P/>
<Index>getting help</Index>
<C>?[<A>book</A>:][?]<A>topic</A></C>
<P/>
For an explanation and some examples
see&nbsp;<Ref Sect="Help" BookName="tut"/>.
<P/>
Note that the first question mark must appear in the <E>first position</E>
after the <C>gap> </C> prompt.
The search strings <A>book</A> and <A>topic</A> 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.
<P/>
When there are several manual sections  that match the query a numbered list
of topics is displayed.
These matches can be accessed with <C>?<A>number</A></C>.
<P/>
There  are  some  further  specially   handled  commands  which  start  with
a  question  mark.
They are explained in
Section&nbsp;<Ref Sect="Browsing through the Sections"/>.
<P/>
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 <C>pdf</C> files or via a web browser.
This is explained below in Section&nbsp;<Ref Sect="Changing the Help Viewer"/>.
<P/>
<E>Details of the string normalization process</E>
<P/>
Here is a precise description how the search strings <A>book</A> and
<A>topic</A> 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.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Browsing through the Sections">
<Heading>Browsing through the Sections</Heading>

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 <C>gap> </C> prompt) which allow browsing a book section
or chapter wise.
<P/>

<Index>browsing forward</Index>
<C>?></C>
<P/>
<Index>browsing backwards</Index>
<C>?&lt;</C>
<P/>
The two help commands <C>?&lt;</C> and <C>?></C> allow one to browse through
a whole help book.
<C>?&lt;</C> displays the section or subsection preceding the
previously shown (sub)section,
and <C>?></C> takes you to the section or subsection following the
previously shown one.
<P/>
<Index>browsing forward one chapter</Index>
<C>?>></C>
<P/>
<Index>browsing backwards one chapter</Index>
<C>?&lt;&lt;</C>
<P/>
<C>?&lt;&lt;</C> takes you back to the beginning of the current chapter.
If you are already at the start of a chapter <C>?&lt;&lt;</C> takes you to
the beginning of the previous chapter.
<C>?>></C> takes you to the beginning of the next chapter.
<P/>
<Index>browsing the previous section browsed</Index>
<C>?-</C>
<P/>
<Index>browsing the next section browsed</Index>
<C>?+</C>
<P/>
&GAP; remembers the last few sections that you have read.
<C>?-</C> takes you to the one that you have read before the current one,
and displays it again.
Further applications of <C>?-</C> take you further back in this history.
<C>?+</C> 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 <C>?-</C>  and <C>?+</C> do not alter the
history like the other help commands.
<P/>
<Index>list of available books</Index>
<C>?books</C>
<P/>
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
<A>book</A> part of the basic help query
and there is a long name which hopefully tells you what this book is about.
<P/>
A short name which ends in <C>(not loaded)</C> refers to a &GAP; package
whose documentation is loaded but which needs a call of
<Ref Func="LoadPackage"/> before you can use the described functions.
<P/>
<Index>table of sections for help books</Index>
<C>?[<A>book</A>:]sections</C>
<P/>
<Index>table of chapters for help books</Index>
<C>?[<A>book</A>:][chapters]</C>
<P/>
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.
<P/>
<Index>redisplay a help section</Index>
<C>?</C>
<P/>
<Index>redisplay with next help viewer</Index>
<C>?&amp;</C>
<P/>
These commands redisplay the last shown help section.
In the form <C>?&amp;</C> the next preferred help viewer is used for the
display (provided one has chosen several viewers),
see&nbsp;<Ref Func="SetHelpViewer"/> below.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Changing the Help Viewer">
<Heading>Changing the Help Viewer</Heading>

<Index>document formats (text, dvi, ps, pdf, HTML)</Index>

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):
<P/>
<List>
<Mark>text</Mark>
<Item>
  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.
</Item>
<Mark>pdf</Mark>
<Item>
  Adobe's <C>pdf</C> 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.
</Item>
<Mark>HTML</Mark>
<Item>
  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.)
</Item>
</List>
<P/>
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.


<ManSection>
<Func Name="SetHelpViewer" Arg='viewer1, viewer2, ...'/>

<Description>
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.
<P/>
The first  given arguments  are those  with higher priority.  So, if  a help
section is available in the format needed by <A>viewer1</A>,
this viewer is used.
If not, availability of the format for <A>viewer2</A> is checked and so on.
Recall that the command <C>?&amp;</C> displays the last seen section again
but with the next possible viewer in your list,
see&nbsp;<Ref Sect="Browsing through the Sections"/>.
<P/>
The viewer <C>"screen"</C> (see below) is always silently appended since we
assume that each help book is available in text format.
<P/>
If you want to change the default setting you can use a call of
<C>SetUserPreference( "HelpViewers", [ ... ] );</C>  (the list in
the second argument containing the viewers you want)
in your <F>gap.ini</F> file (see&nbsp;<Ref Sect="sect:gap.ini"/>).
<P/>
<List>
<Mark><C>"screen"</C></Mark>
<Item>
  This is the default setting. The help is shown in text format using the
  <Ref Func="Pager"/> 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 <C>UTF-8</C> encoding with a fixed
  width font (this is the default on most modern Linux/Windows/Mac systems
  anyway). Terminals in <C>ISO-8859-X</C> encoding will also work reasonably
  well (so far, since we do not yet use many special characters which
  such terminals could not display).
</Item>
<Mark><C>"firefox"</C>, <C>"chrome"</C>, <C>"mozilla"</C>, <C>"netscape"</C>, <C>"konqueror"</C></Mark>
<Item>
  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.)
</Item>
<Mark><C>"browser"</C></Mark>
<Item>
  (for MS Windows) If a book is available in HTML format, it will be
  opened using the Windows default application (typically, a web browser).
</Item>
<Mark><C>"links2"</C>, <C>"w3m"</C>, <C>"lynx"</C></Mark>
<Item>
  If a book is available in HTML format this is shown using the text based
  <C>"links2"</C> (in graphics mode), <C>w3m</C> or <C>lynx</C> web browser,
  respectively, inside the terminal running &GAP;.
  (Formulae in some older books which use symbol fonts may be unreadable.)
</Item>
<Mark><C>"mac default browser"</C>, <C>"browser"</C>, <C>"safari"</C>, <C>"firefox"</C></Mark>
<Item>
  (for macOS) If a book is available in HTML format this is shown
  in a web browser. The options <C>"safari"</C> and <C>"firefox"</C> 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).
</Item>
<Mark><C>"xpdf"</C></Mark>
<Item>
  (on X window systems) If a book is available in pdf format it is shown
  with the onscreen viewer program <C>xpdf</C>
  (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.
</Item>
<Mark><C>"acroread"</C></Mark>
<Item>
  If a book is available in pdf format it is shown with the onscreen viewer
  program <C>acroread</C> (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 <C>acroread</C> window still exists.
  When you go to another book a new acroread window is launched.
</Item>
<Mark><C>"pdf viewer"</C>, <C>"skim"</C>, <C>"preview"</C>, <C>"adobe reader"</C></Mark>
<Item>
  (for macOS) If a book is available in pdf format this is shown
  in a pdf viewer. The options <C>"skim"</C>, <C>"preview"</C> and <C>"adobe reader"</C> 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 <C>"Skim"</C> 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 <C>"Skim"</C> is open source software, it can be downloaded from <F>https://skim-app.sourceforge.io/</F>.
</Item>
<Mark><C>"less"</C> or <C>"more"</C></Mark>
<Item>
  This is the same as <C>"screen"</C> but additionally the user preferences
  <C>"Pager"</C> and <C>"PagerOptions"</C> are set,
  see the section&nbsp;<Ref Sect="The Pager Command"/> for more details.
</Item>
</List>
<P/>
Please, send ideas for further viewer commands to
<Email>support@gap-system.org</Email>.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="The Pager Command">
<Heading>The Pager Command</Heading>

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

</Section>
</Chapter>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %E -->