<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %W  helpintf.tex              GAP documentation              Frank Lübeck -->
<!-- %% -->
<!-- %% -->
<!-- %Y  Copyright 1997,  Lehrstuhl D für Mathematik,  RWTH Aachen,   Germany -->
<!-- %% -->
<!-- %%  This file describes the interface between the GAP help system and the -->
<!-- %%  actual documents. -->
<!-- %% -->

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="Interface to the GAP Help System">
<Heading>Interface to the GAP Help System</Heading>

In this chapter we describe which  information the help system needs about a
manual book and  how to tell it this information.  The code which implements
this interface can be found in <F>lib/helpbase.gi</F>.
<P/>
If you are intending to use a documentation format that is already  used  by
some other help book you probably don't need  to  know  anything  from  this
chapter. However, if you want to create a new format and make  it  available
to &GAP; then hopefully you will find the necessary information here.
<P/>
The basic idea of the  help  system  is  as  follows:  One  tells  &GAP;  a
directory which contains a file <F>manual.six</F>,
see&nbsp;<Ref Sect="Installing and Removing a Help Book"/>.
When the &GAP; help is asked something about this book  it  reads  in  some
basic information from the file <F>manual.six</F>:
strings like section  headers,
function names, and index  entries  to  be  searched  by  the  online  help;
information about the available formats of this book like text,  html,  dvi,
and pdf;  the  actual  files  containing  the  documentation,  corresponding
section numbers, and page numbers: and so on.
See&nbsp;<Ref Sect="The manual.six File"/>  for
a description of the format of the <F>manual.six</F> file.
<P/>
It  turns  out  that there  is  almost  no  restriction  on  the  format  of
the  <F>manual.six</F>  file,   except  that  it  must  provide   a  string,  say
<C>"myownformat"</C> which  identifies the  format of the  help book.  Then the
basic actions  on a help  book are delegated by  the help system  to handler
functions stored in a  record <C>HELP_BOOK_HANDLER.myownformat</C>.
See&nbsp;<Ref Sect="The Help Book Handler"/> for  information  which  functions must  be  provided by  the
handler and what they  are supposed to do. The main work  to teach &GAP; to
use a new document format is to write these handler functions and to produce
an appropriate <F>manual.six</F> file.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Installing and Removing a Help Book">
<Heading>Installing and Removing a Help Book</Heading>

<ManSection>
<Func Name="HELP_ADD_BOOK" Arg="short, long, dir"/>

<Description>
This command tells &GAP; that in directory <A>dir</A> (given as either a  string
describing   the   path   relative   to   the    &GAP;    root    directory
<C>GAPInfo.RootPaths[1]</C> or as directory object) contains the basic information
about a help book. The string <A>short</A> is used as  an  identifying  name  for
that book  by  the  online  help.  The  string  <A>long</A>  should  be  a  short
explanation of the content of the book. Both strings together should  easily
fit on a line, since they are displayed with <C>?books</C>.
<P/>
It is possible to reinstall a book with different strings  <A>short</A>,  <A>long</A>;
(for example, documentation of a not-loaded &GAP; package indicates this in
the string <A>short</A> and if you later load the package,  &GAP;  quietly
changes the string <A>short</A> as it reinstalls its documentation).
<P/>
The only condition necessary to make the installation of a book  <E>valid</E>  is
that the directory <A>dir</A> must contain a file <F>manual.six</F>. The next  section
explains how this file must look.
</Description>
</ManSection>

<ManSection>
<Func Name="HELP_REMOVE_BOOK" Arg="short"/>

<Description>
This command tells &GAP; not to use the help book with identifying name <A>short</A>
any more. The book can be re-installed using <Ref Func="HELP_ADD_BOOK" />. <P/>

</Description>
</ManSection>
</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="The manual.six File">
<Heading>The manual.six File</Heading>

The first non-empty line of <F>manual.six</F> should be of the form
<P/>
<C>#SIXFORMAT</C> <A>myownformat</A>
<P/>
where <A>myownformat</A> is an identifying string for this format. The reading
of the (remainder of the) file is then delegated to the function
<C>HELP_BOOK_HANDLER.<A>myownformat</A>.ReadSix</C> which must exist. Thus
there are no further regulations for the format of the <F>manual.six</F> file,
other that what you yourself impose. If such a line is missing then it is
assumed that the <F>manual.six</F> file complies with the <F>gapmacro.tex</F>
documentation format, which internally is referred to as the <C>default</C>
format for historical reasons. In that case reading the file is delegated to
<C>HELP_BOOK_HANDLER.default.ReadSix</C>.
<P/>
Section <Ref Sect="The Help Book Handler"/> explains how the return value of
<C>HELP_BOOK_HANDLER.<A>myownformat</A>.ReadSix</C> should look like and which further
function should be contained in <C>HELP_BOOK_HANDLER.<A>myownformat</A></C>.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="The Help Book Handler">
<Heading>The Help Book Handler</Heading>

<Index>document formats!for help books</Index>
For  each  document  format   <A>myownformat</A>   there   must   be   a   record
<C>HELP_BOOK_HANDLER.<A>myownformat</A></C> of functions with the following names  and
functionality.
<P/>
An implementation example  of  such  a  set  of  handler  functions  is  the
<C>default</C> format, which is the  format  name  used  for  the  <F>gapmacro.tex</F>
documentation format, and this is contained in the file <F>lib/helpdef.gi</F>.
<P/>
The package &GAPDoc; (see Chapter&nbsp;<Ref Chap="Introduction and Example" BookName="gapdoc"/>)
also defines a format (as it should) which is called: <C>GapDocGAP</C> (the  case
<E>is</E> significant).
<P/>
As you can see by the above two examples, the name for a document format can
be anything, but it should be in some way meaningful.
<P/>
<List>
<Mark>
<C>ReadSix( <A>stream</A> )</C></Mark>
<Item>
  For an input text stream <A>stream</A> to a <F>manual.six</F> file,
  this must return a record <A>info</A> which has at least the following two
  components:
  <C>bookname</C> which is the short identifying  name  of  the  help  book,  and
  <C>entries</C>. Here <A>info</A><C>.entries</C> must be a list with one entry per  search
  string (which can be a section header,  function  name,  index  entry,  or
  whatever seems sensible to be searched  for  matching  a  help  query).  A
  <E>match</E> for the &GAP; help is a pair (<A>info</A>, <A>i</A>) where <A>i</A> refers to an
  index for the list <A>info</A><C>.entries</C> and  this  corresponds  to  a  certain
  position in the document. There is one further regulation for  the  format
  of the entries of <A>info</A><C>.entries</C>. They  must  be  lists  and  the  first
  element of such a list must be a string which is  printed  by  &GAP;  for
  example when  several  matches  are  found  for  a  query  (so  it  should
  essentially be the string which is searched for the match, except that  it
  may contain upper and lower case letters or some  markup).  There  may  be
  other components in <A>info</A> which are needed by the  functions  below,  but
  their names and formats are  not  prescribed.  The  <A>stream</A>  argument  is
  typically generated using <Ref Oper="InputTextFile"/>, e.g.
<P/>
<Log><![CDATA[
gap> dirs := DirectoriesLibrary( "doc/ref" );;
gap> file := Filename( dirs, "manual.six" );;
gap> stream := InputTextFile( file );;
]]></Log>
</Item>
<Mark><C>ShowChapters( <A>info</A> )</C> </Mark>
<Item>
  This must return a text string or list of text lines  which  contains  the
  chapter headers of the book <A>info</A><C>.bookname</C>.
</Item>
<Mark><C>ShowSection( <A>info</A> )</C> </Mark>
<Item>
  This must return  a text string or  list of text lines  which contains the
  section (and chapter) headers of the book <A>info</A><C>.bookname</C>.
</Item>
<Mark><C>SearchMatches( <A>info</A>, <A>topic</A>, <A>frombegin</A> )</C> </Mark>
<Item>
  This  function must  return  a  list of  indices  of <A>info</A><C>.entries</C>  for
  entries which  match the search  string <A>topic</A>. If <A>frombegin</A>  is <K>true</K>
  then  those parts  of  <A>topic</A> which  are separated  by  spaces should  be
  considered  as  the  beginnings  of  words  to  decide  the  matching.  It
  <A>frombegin</A> is <K>false</K>, a substring search should be performed. The string
  <A>topic</A>  can be  assumed to  be already  normalized (transformed  to lower
  case, and whitespace normalized). The function must return a list with two
  entries <C>[exact,  match]</C> where <C>exact</C> is  the list of indices  for exact
  matches and <C>match</C> a list of indices of the remaining matches.
</Item>
<Mark><C>MatchPrevChap( <A>info</A>, <A>i</A> )</C> </Mark>
<Item>
  This should return  the match [<A>info</A>, <C>j</C>] which points  to the beginning
  of  the  chapter  containing  match [<A>info</A>,  <A>i</A>],  respectively  to  the
  beginning  of  the  previous  chapter  if [<A>info</A>,  <A>i</A>]  is  already  the
  beginning of a chapter. (Corresponds to <C>?&lt;&lt;</C>.)
</Item>
<Mark><C>MatchNextChap( <A>info</A>, <A>i</A> )</C> </Mark>
<Item>
  Like the previous function except that it should return the match for  the
  beginning of the next chapter. (Corresponds to <C>?>></C>.)
</Item>
<Mark><C>MatchPrev( <A>info</A>, <A>i</A> )</C> </Mark>
<Item>
  This should return the previous section (or  appropriate  portion  of  the
  document). (Corresponds to <C>?&lt;</C>.)
</Item>
<Mark><C>MatchNext( <A>info</A>, <A>i</A> )</C> </Mark>
<Item>
  Like the previous function except that it should return the  next  section
  (or appropriate portion of the document). (Corresponds to <C>?></C>.)
</Item>
<Mark><C>HelpData( <A>info</A>, <A>i</A>, <A>type</A> )</C> </Mark>
<Item>
  This returns for match [<A>info</A>, <A>i</A>] some data whose format depends on the
  string <A>type</A>,  or <K>fail</K> if these  data are not available.  The values of
  <A>type</A> which currently must be handled and the corresponding result format
  are described in the list below.
</Item>
<Mark><C>SubsectionNumber( <A>info</A>, <A>i</A> )</C> </Mark>
<Item>
  This returns some &GAP; object that identifies the position in the book
  where the display of this entry is started. This can be useful to detect
  if several help book entries actually point to the same place.
</Item>
</List>
<P/>
The <C>HELP_BOOK_HANDLER.<A>myownformat</A>.HelpData</C> function must recognize the
following values of the <A>type</A> argument.
<P/>
<List>
<Mark>
<C>"text"</C> </Mark>
<Item>
  This must return a corresponding text string in a format which can be fed
  into the <C>Pager</C>, see&nbsp;<Ref Func="Pager"/>.
</Item>
<Mark><C>"url"</C> </Mark>
<Item>
  If the help book is available in HTML  format this must return an URL as a
  string (Probably a <C>file://</C> URL containing  a label for the  exact start
  position in that file). Otherwise it returns <K>fail</K>.
</Item>
<Mark><C>"dvi"</C> </Mark>
<Item>
  If the help book  is available in dvi-format this must  return a record of
  form  <C>rec( file := <A>filename</A>, page := <A>pagenumber</A> )</C>.
  Otherwise it returns <K>fail</K>.
</Item>
<Mark><C>"pdf"</C> </Mark>
<Item>
  Same as case <C>"dvi"</C>, but for the corresponding pdf-file.
</Item>
<Mark><C>"secnr"</C> </Mark>
<Item>
  This  must return  a  pair  like <C>[[3,3,1], "3.3.1"]</C>  which gives  the
  section  number  as  chapter  number, section  number,  subsection  number
  triple  and a  corresponding  string  (a chapter  itself  is encoded  like
  <C>[[4,0,0], "4."]</C>). Useful for cross-referencing between help books.
</Item>
</List>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Introducing new Viewer for the Online Help">
<Heading>Introducing new Viewer for the Online Help</Heading>

To introduce a new viewer for the online help,
one should extend the global record <Ref Var="HELP_VIEWER_INFO"/>,
the structure of which is explained below.

<#Include Label="HELP_VIEWER_INFO">

</Section>
</Chapter>


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