%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  help.tex               GAP documentation                    Frank LŸbeck
%%
%A  @(#)$Id: help.tex,v 4.19.2.2 2005/04/21 10:38:03 gap Exp $
%%
%Y  Copyright 1990-2001, Lehrstuhl D fuer Mathematik, RWTH Aachen, Germany
%%
%%  Original version by Martin Schoenert.
%%
\Chapter{The Help System}

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Invoking the Help}

The  basic command  to  read  {\GAP}'s documentation  from  within a  {\GAP}
session is as follows.

\>`?[<book>:][?]<topic>'{getting help}

For an explanation and some examples see~"tut: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.

%%      Throw away? (FL) 
%%  The help command `?' displays the section with the name <section> on the
%%  screen. For example `?Help' will display this section on the screen.
%%  You should not type in the single quotes. They are only used in help
%%  sections to delimit text that you should enter into {\GAP} or that {\GAP}
%%  prints in response. When the whole section has been displayed the normal
%%  {\GAP} prompt `gap>' is shown and normal {\GAP} interaction resumes.

When there are several manual sections  that match the query a numbered list
of topics is displayed. These matches can be accessed with `?<number>'.

%%  Section~"Reading Sections" tells you what actions you can perform
%%  while you are reading a section. You tell {\GAP} to display this
%%  section by entering `?Reading Sections', without quotes.
%%  Section~"Format of Sections" describes the format of sections and the
%%  conventions used,

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

%%  lists the commands you use to flip
%%  through sections, "Redisplaying a Section" describes how to read a
%%  section again, "Abbreviating Section Names" tells you how to avoid typing
%%  the long section names, and "Help Index" describes the index command.

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  Isn't all this practically self-explatory? Throw away? (FL)
%%  \Section{Reading Sections}
%%  
%%  \index{help!scrolling}
%%  If the section is longer than the size of your screen, {\GAP} stops after
%%  displaying a full screen and displays
%%  
%%  \begintt
%%  -- <space> for more, <q> to quit --
%%  \endtt
%%  
%%  If you press <space> {\GAP} displays the next full screen of lines of the
%%  section and then stops again.
%%  This goes on until the whole section has been displayed,
%%  at which point {\GAP} will return immediately to the main {\GAP} loop.
%%  Pressing `f' has the same effect as <space>.
%%  
%%  You can also press `b' which will scroll back to the *previous* full screen
%%  of lines of the section.
%%  If you press `b' when {\GAP} is displaying the top of a section,
%%  {\GAP} will ring the bell.
%%  
%%  You can also press `q' to quit and return immediately back to the main
%%  {\GAP} loop without reading the rest of the section.
%%  
%%  The size of the screen is set using information obtained from the
%%  operating system, if possible, or to $24$ lines if not.
%%  If this does not produce the correct results for your system,
%%  you may wish to set the number of lines with the `-y <rows>' option
%%  (see~"Command Line Options") when you start {\GAP}.
%%  
%%  
%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  This should not be documented as a (compulsory) format of the sections,
%%  to allow other Help formats. Shouldn't a section showed by the help
%%  have a format which doesn't need further long explanations?  (FL)


%%%%%%%%%  Throw this away ??? The essential information  is contained
%%%%%%%%%  in "Ref: Manual Conventions"     (FL)
%%  \Section{Format of Sections}
%%  
%%  \index{help!format}
%%  This section describes the format of sections when they are displayed on
%%  the screen and the special conventions used.
%%  For general conventions about manual sections and the format of sections
%%  in the printed manual, see~"Manual Conventions".
%%  
%%  As you can see, {\GAP} prints a header line
%%  containing the name of the section on the left and the name of the
%%  chapter on the right.
%%  
%%  (If this header line ends in `(not loaded)' the documentation belongs to a
%%  package, which has not yet been loaded. See section~"Loading a GAP Package"
%%  for further information.)
%%  
%%  \begintt
%%  <text>
%%  \endtt
%%  Text enclosed in angle brackets is used for arguments in the descriptions
%%  of functions and for other place holders. It means that you should not
%%  actually enter this text into {\GAP} but replace it by appropriate
%%  text depending on what you want to do. For example when we write that
%%  you should enter `?<section>' to see the section with the name <section>,
%%  <section> serves as a place holder, indicating that you can enter the
%%  name of the section that you want to see at this place.
%%  
%%  \begintt
%%  `text'
%%  \endtt
%%  Text enclosed in single quotes is used for names of variables and
%%  functions and other text that you may actually enter into your computer
%%  and see on your screen. The text enclosed in single quotes may contain
%%  place holders enclosed in angle brackets as described above. For example
%%  when the help text for `IsPrime' says that the form of the call is
%%  `IsPrime( <n> )' this means that you should actually
%%  enter the strings ``IsPrime('' and ``)'', without the quotes,
%%  but replace the `<n>' with the number (or expression)
%%  that you want to test.
%%  
%%  \begintt
%%  "text"
%%  \endtt
%%  Text enclosed in double quotes is used for cross references to other
%%  parts of the manual. So the text inside the double quotes is the name of
%%  another section of the manual. This is used to direct you to other
%%  sections that describe a topic or a function used in this section. So, 
%%  for example, "Browsing through the Sections" is a cross reference to the next
%%  section.
%%  
%%  \begintt
%%  > Oper( <arg1>, <arg2>[, <opt>] ) F
%%  \endtt
%%  starts a subsection on the command `Oper' that takes two arguments <arg1>
%%  and <arg2> and an optional third argument <opt>.
%%  
%%  The letter `F' at the end
%%  indicates that the command is a simple function.
%%  The letters `A', `P', `O', `C', `R', and `V' indicate
%%  ``Attribute'', ``Property'', ``Operation'', ``Category'', ``Representation''
%%  (see Chapter~"Types of Objects"), or ``Variable'', respectively.
%%  
%%  `_' and `^'
%%  
%%  In mathematical formulas the underscore and the caret are used to denote
%%  subscription and superscription. Ordinarily they apply only to the very
%%  next character following, unless a whole expression enclosed in
%%  parentheses follows. So, for example, `x_1^(i+1)' denotes the variable `x'
%%  with subscript 1 raised to the power `i+1'.
%%  
%%  Longer examples are usually paragraphs of their own.
%%  Everything on the lines with the prompts `gap>' and `>', except
%%  the prompts themselves of course, is the input you have to type;
%%  everything else is {\GAP}'s response.
%%  
%%  \begintt
%%  gap> ?Format of Sections
%%  Format of Sections ______________________________________ Environment
%%  
%%  This section describes the format of sections when they are displayed
%%  on the screen and the special conventions used.
%%  ... 
%%  \endtt

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Browsing through the Sections}

%%  The help sections are organized like a book into chapters. This should
%%  not surprise you, since the same source is used both for the printed
%%  manual and the online help. Just as you can flip through the pages of a
%%  book there are special commands to browse through the help 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 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.

\>`?>>'{browsing forward one chapter}
\>`?\<\<'{browsing backwards one chapter}

`?\<\<' 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.

\>`?-'{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.

\>`?books'{list of available 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 `LoadPackage'
(see "LoadPackage") before you can use the described functions.

\>`?[<book>:]sections'{table of sections for help books}  
\>`?[<book>:][chapters]'{table of chapters for help books}

These commands  show tables of  content for all available,  respectively the
matching books.

\>`?'{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~"SetHelpViewer" below.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Changing the Help Viewer}

\index{document formats (text, dvi, ps, pdf, HTML)}

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

\beginitems

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.

\enditems

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").

\beginitems

`\"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.

`\"firefox\"', `\"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 books the browser must be configured
  to use symbol fonts.

`\"w3m\"', `\"lynx\"' &
  If a book is  available in HTML-format this is shown  using the text based
  `w3m' or `lynx' web-browser inside the terminal  running {\GAP}.  Formulae 
  which use symbol fonts may be unreadable.

`\"mac default browser\"', `\"safari\"' &
  (for Apple Macintosh) 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 `Internet' control panel (System 9  and System X).
  For some browsers (e.g., Internet Explorer), you may have to 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
  \URL{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.

\enditems

Please,     send     ideas     for    further     viewer     commands     to
\Mailto{support@gap-system.org}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{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:
\begintt
  PAGER := "less";
  PAGER_OPTIONS := ["-f", "-r", "-a", "-i", "-M", "-j2"];
\endtt

The argument <lines> can have one of the following forms:

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

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

\beginitems
`.formatted' &
  can 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)

`.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).
\enditems

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.

%notest
\beginexample
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," ")));;                
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  \Section{Changing the Way the Help Pages are Displayed}
%%  
%%  \index{HTML}
%%  \index{netscape}\index{lynx}\index{internet config}
%%  \index{less}\index{pager}
%%  
%%  If you have installed an html version of the manual you can
%%  alternatively use an html browser to display the manual sections. The
%%  command
%%  
%%  \>SetHelpViewer(<device>)
%%  
%%  will select a method described by the string <device> to display the help
%%  pages online. Currently <device> can be `"screen"' for the default built-in
%%  text browser, `"less"' (only under UNIX) to use `less' for paging,
%%  `"netscape"' for the netscape HTML browser and `"lynx"' for the
%%  lynx HTML browser. Both HTML browsers will only work under UNIX. 
%%  
%%  On an Apple Macintosh you can use an HTML browser by calling `SetHelpViewer'
%%  with the parameter `"Internet Config"'.
%%  See section~"Features of GAP for MacOS" for details about this.
%%  
%%  If you want the HTML help to be the default, you should call this function
%%  in your `.gaprc' file (see the sections on operating
%%  system dependent features in chapter "Installing GAP").
%%  
%%  Note that you need to set up the `symbol' font properly in your web browser
%%  to get a correct display of mathematical formulae (see section~"HTML Font
%%  Setup").
%%  
%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  \Section{Redisplaying a Section}
%%  
%%  \index{help!redisplaying}
%%  
%%  \>`?'{browsing the same section again}
%%  
%%  The help command `?' followed by no section name redisplays the last help
%%  section again. So if you reach the bottom of a long help section and have
%%  already forgotten what was mentioned at the beginning, or, for example, the
%%  examples do not seem to agree with your interpretation of the
%%  explanations, use `?' to read the whole section again from the beginning.
%%  
%%  When `?' is used before any section has been read, {\GAP} displays a
%%  `Welcome to GAP'.
%%  
%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  \Section{Abbreviating Section Names}
%%  
%%  \index{help!abbreviating}
%%  Upper and lower case in <section> are not distinguished, so typing either
%%  `?Abbreviating Section Names' or `?abbreviating section names' will show
%%  the section you are currently reading.
%%  
%%  Each word in <section> may be abbreviated. So instead of typing
%%  `?abbreviating section names' you may also type `?abb sec nam', or even `?a
%%  s n'. You must not omit the spaces separating the words. For each word in
%%  the section name you must give at least the first character. As another
%%  example you may type `?el oper for int' instead of `?elementary operations
%%  for integers', which is especially handy when you can not remember whether
%%  it was `operations' or `operators'.
%%  
%%  If an abbreviation matches multiple section names a list of all these
%%  section names is displayed.
%%  
%%  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  \Section{Help Index}
%%  
%%  \>`??<topic>'{list help topics}
%%  
%%  The operator `??' looks up <topic> in {\GAP}'s index and prints all the
%%  index entries that contain the substring <topic>.
%%  Then you can decide which section is the one you are actually interested
%%  in and request this one.
%%  
%%  \begintt
%%  gap> ??read
%%  Help: several entries match this topic
%%  [1] reference:read
%%  [2] reference:reading sections
%%  [3] reference:readlib
%%  [4] reference:isreadablefile
%%  [5] reference:read
%%  ...
%%  \endtt
%%  
%%  The first part of each line is a reference number.  Then follows the
%%  part of the manual which contains the section and finally the actual
%%  name of the (sub)section. All names are converted to lower case.
%%  
%%  The order of the sections corresponds to their order in the
%%  {\GAP} manual, so that related sections should be adjacent.
%%  
%%  You can then either refer to the desired subsection by its name or simply
%%  use `?<nr>' to look at the topic with the reference number <nr>. So in the
%%  above example `?3' would display the section on `ReadLib'.
%%  
%%  When referring to sections by their name you can usually omit the part
%%  of the manual unless several parts contain the same section names.
%%  
%%  If there are several subsections which have exactly the same name, a number
%%  in parentheses is added to the name to distinguish these.
%%  

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E
%%