Welcome To Our Shell

Mister Spy & Souheyl Bypass Shell

  
  84 Interface to the GAP Help System
  
  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 lib/helpbase.gi.
  
  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.
  
  The  basic  idea of the help system is as follows: One tells GAP a directory
  which  contains  a  file  manual.six,  see 84.1.  When the GAP help is asked
  something  about  this book it reads in some basic information from the file
  manual.six:  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 84.2 for a description of the format of the manual.six file.
  
  It  turns  out  that  there  is  almost  no restriction on the format of the
  manual.six  file,  except  that  it must provide a string, say "myownformat"
  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   HELP_BOOK_HANDLER.myownformat.   See 84.3   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 manual.six file.
  
  
  84.1 Installing and Removing a Help Book
  
  84.1-1 HELP_ADD_BOOK
  
  HELP_ADD_BOOK( short, long, dir )  function
  
  This  command  tells  GAP  that  in  directory dir (given as either a string
  describing  the path relative to the GAP root directory GAPInfo.RootPaths[1]
  or  as  directory  object) contains the basic information about a help book.
  The  string short is used as an identifying name for that book by the online
  help.  The  string  long 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 ?books.
  
  It  is possible to reinstall a book with different strings short, long; (for
  example,  documentation  of  a  not-loaded GAP package indicates this in the
  string  short  and  if  you  later load the package, GAP quietly changes the
  string short as it reinstalls its documentation).
  
  The  only  condition  necessary  to make the installation of a book valid is
  that  the  directory  dir  must  contain a file manual.six. The next section
  explains how this file must look.
  
  84.1-2 HELP_REMOVE_BOOK
  
  HELP_REMOVE_BOOK( short )  function
  
  This  command tells GAP not to use the help book with identifying name short
  any more. The book can be re-installed using HELP_ADD_BOOK (84.1-1).
  
  
  84.2 The manual.six File
  
  The first non-empty line of manual.six should be of the form
  
  #SIXFORMAT myownformat
  
  where  myownformat  is an identifying string for this format. The reading of
  the   (remainder   of   the)   file   is  then  delegated  to  the  function
  HELP_BOOK_HANDLER.myownformat.ReadSix  which  must  exist. Thus there are no
  further  regulations  for the format of the manual.six file, other that what
  you  yourself  impose. If such a line is missing then it is assumed that the
  manual.six  file  complies with the gapmacro.tex documentation format, which
  internally  is  referred to as the default format for historical reasons. In
  that      case      reading      the      file      is      delegated     to
  HELP_BOOK_HANDLER.default.ReadSix.
  
  Section      84.3      explains      how     the     return     value     of
  HELP_BOOK_HANDLER.myownformat.ReadSix  should  look  like  and which further
  function should be contained in HELP_BOOK_HANDLER.myownformat.
  
  
  84.3 The Help Book Handler
  
  For   each   document   format   myownformat   there   must   be   a  record
  HELP_BOOK_HANDLER.myownformat  of  functions  with  the  following names and
  functionality.
  
  An  implementation example of such a set of handler functions is the default
  format,  which  is  the  format name used for the gapmacro.tex documentation
  format, and this is contained in the file lib/helpdef.gi.
  
  The  package  GAPDoc  (see  Chapter 'GAPDoc: Introduction and Example') also
  defines  a  format  (as  it  should) which is called: GapDocGAP (the case is
  significant).
  
  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.
  
   ReadSix( stream )
        For an input text stream stream to a manual.six file, this must return
        a  record  info  which  has  at  least  the  following two components:
        bookname  which  is  the  short identifying name of the help book, and
        entries.  Here  info.entries  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
        match  for the GAP help is a pair (info, i) where i refers to an index
        for  the  list info.entries and this corresponds to a certain position
        in the document. There is one further regulation for the format of the
        entries  of  info.entries. 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 info which are needed by the functions below, but their
        names and formats are not prescribed. The stream argument is typically
        generated using InputTextFile (10.5-1), e.g.
  
          Example  
          gap> dirs := DirectoriesLibrary( "doc/ref" );;
          gap> file := Filename( dirs, "manual.six" );;
          gap> stream := InputTextFile( file );;
        
  
  ShowChapters( info ) 
        This  must  return  a text string or list of text lines which contains
        the chapter headers of the book info.bookname.
  
  ShowSection( info ) 
        This  must  return  a text string or list of text lines which contains
        the section (and chapter) headers of the book info.bookname.
  
  SearchMatches( info, topic, frombegin ) 
        This  function  must  return  a  list  of  indices of info.entries for
        entries which match the search string topic. If frombegin is true then
        those  parts  of  topic  which  are  separated  by  spaces  should  be
        considered  as  the  beginnings  of  words  to decide the matching. It
        frombegin is false, a substring search should be performed. The string
        topic  can  be  assumed to be already normalized (transformed to lower
        case, and whitespace normalized). The function must return a list with
        two  entries  [exact,  match]  where  exact is the list of indices for
        exact matches and match a list of indices of the remaining matches.
  
  MatchPrevChap( info, i ) 
        This  should  return the match [info, j] which points to the beginning
        of  the  chapter  containing  match  [info,  i],  respectively  to the
        beginning  of  the  previous  chapter  if  [info,  i]  is  already the
        beginning of a chapter. (Corresponds to ?<<.)
  
  MatchNextChap( info, i ) 
        Like  the previous function except that it should return the match for
        the beginning of the next chapter. (Corresponds to ?>>.)
  
  MatchPrev( info, i ) 
        This should return the previous section (or appropriate portion of the
        document). (Corresponds to ?<.)
  
  MatchNext( info, i ) 
        Like  the  previous  function  except  that  it should return the next
        section (or appropriate portion of the document). (Corresponds to ?>.)
  
  HelpData( info, i, type ) 
        This returns for match [info, i] some data whose format depends on the
        string  type,  or  fail if these data are not available. The values of
        type  which  currently  must  be  handled and the corresponding result
        format are described in the list below.
  
  SubsectionNumber( info, i ) 
        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.
  
  The   HELP_BOOK_HANDLER.myownformat.HelpData  function  must  recognize  the
  following values of the type argument.
  
   "text" 
        This  must return a corresponding text string in a format which can be
        fed into the Pager, see Pager (2.4-1).
  
  "url" 
        If  the  help book is available in HTML format this must return an URL
        as  a  string (Probably a file:// URL containing a label for the exact
        start position in that file). Otherwise it returns fail.
  
  "dvi" 
        If  the help book is available in dvi-format this must return a record
        of  form  rec(  file  :=  filename, page := pagenumber ). Otherwise it
        returns fail.
  
  "pdf" 
        Same as case "dvi", but for the corresponding pdf-file.
  
  "secnr" 
        This  must  return  a  pair  like  [[3,3,1],  "3.3.1"] which gives the
        section  number  as  chapter number, section number, subsection number
        triple  and  a  corresponding string (a chapter itself is encoded like
        [[4,0,0], "4."]). Useful for cross-referencing between help books.
  
  
  84.4 Introducing new Viewer for the Online Help
  
  To  introduce a new viewer for the online help, one should extend the global
  record HELP_VIEWER_INFO (84.4-1), the structure of which is explained below.
  
  84.4-1 HELP_VIEWER_INFO
  
  HELP_VIEWER_INFO global variable
  
  The  record  HELP_VIEWER_INFO  contains  one component for each help viewer.
  Each such component is a record with two components: .type and .show.
  
  The  component  .type  refers to one of the types recognized by the HelpData
  handler function explained in the previous section (currently one of "text",
  "url", "dvi", or "pdf").
  
  The  component  .show  is  a  function  which  gets as input the result of a
  corresponding  HelpData  handler call, if it was not fail. This function has
  to perform the actual display of the data. (E.g., by calling a function like
  Pager (2.4-1) or by starting up an external viewer program.)