chap2.txt

  
  2 The Help System
  
  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.
  
  ?[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.
  
  
  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 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.
  
  
  2.3 Changing the Help Viewer
  
  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.
  
  2.3-1 SetHelpViewer
  
  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  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 2.4 for more
        details.
  
  Please,     send     ideas     for     further     viewer     commands    to
  mailto:[email protected].
  
  
  2.4 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.
  
  2.4-1 Pager
  
  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 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 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".
  
    Example  
      SetUserPreference( "Pager", "less" );
      SetUserPreference( "PagerOptions", ["-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  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).
  
  exitAtEnd
        can  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.
  
    Example  
    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," ")));;