5 The Converters and an XML Parser
  
  The  GAPDoc  package  contains a set of programs which allow us to convert a
  GAPDoc book into several output versions and to make them available to GAP's
  online help.
  
  Currently  the  following  output  formats  are  provided: text for browsing
  inside  a  terminal  running  GAP,  LaTeX  with  hyperref-package  for cross
  references via hyperlinks and HTML for reading with a Web-browser.
  
  
  5.1 Producing Documentation from Source Files
  
  Here  we explain how to use the functions which are described in more detail
  in  the  following sections. We assume that we have the main file MyBook.xml
  of  a  book "MyBook" in the directory /my/book/path. This contains <#Include
  ...>-statements  as  explained in Chapter 4. These refer to some other files
  as well as pieces of text which are found in the comments of some GAP source
  files  ../lib/a.gd  and  ../lib/b.gi  (relative to the path above). A BibTeX
  database  MyBook.bib for the citations is also in the directory given above.
  We  want to produce a text-, pdf- and HTML-version of the document. (A LaTeX
  version  of  the manual is produced, so it is also easy to compile dvi-, and
  postscript-versions.)
  
  All  the commands shown in this Section are collected in the single function
  MakeGAPDocDoc (5.1-1).
  
  First   we   construct   the   complete   XML-document   as  a  string  with
  ComposedDocument   (4.2-1).   This   interprets  recursively  the  <#Include
  ...>-statements.
  
    Example  
    gap> path := Directory("/my/book/path");;
    gap> main := "MyBook.xml";;
    gap> files := ["../lib/a.gd", "../lib/b.gi"];;
    gap> bookname := "MyBook";;
    gap> doc := ComposedDocument("GAPDoc", path, main, files, true);;
  
  
  Now  doc  is  a  list with two entries, the first is a string containing the
  XML-document,  the  second  gives information from which files and locations
  which  part  of the document was collected. This is useful in the next step,
  if there are any errors in the document.
  
  Next  we  parse  the  document  and  store its structure in a tree-like data
  structure.   The  commands  for  this  are  ParseTreeXMLString  (5.2-1)  and
  CheckAndCleanGapDocTree (5.2-8).
  
    Example  
    gap> r := ParseTreeXMLString(doc[1], doc[2]);;
    gap> CheckAndCleanGapDocTree(r);
    true
  
  
  We  start  to  produce  a text version of the manual, which can be read in a
  terminal  (window).  The  command  is  GAPDoc2Text  (5.3-2). This produces a
  record with the actual text and some additional information. The text can be
  written  chapter-wise into files with GAPDoc2TextPrintTextFiles (5.3-3). The
  names  of  these files are chap0.txt, chap1.txt and so on. The text contains
  some  markup  using ANSI escape sequences. This markup is substituted by the
  GAP  help  system (user configurable) to show the text with colors and other
  attributes.  For  the  bibliography  we have to tell GAPDoc2Text (5.3-2) the
  location of the BibTeX database by specifying a path as second argument.
  
    Example  
    gap> t := GAPDoc2Text(r, path);;
    gap> GAPDoc2TextPrintTextFiles(t, path);
  
  
  This  command  constructs  all  parts  of  the  document  including table of
  contents,  bibliography and index. The functions FormatParagraph (6.1-4) for
  formatting  text  paragraphs  and  ParseBibFiles  (7.1-1) for reading BibTeX
  files with GAP may be of independent interest.
  
  With  the  text  version we have also produced the information which is used
  for searching with GAP's online help. Also, labels are produced which can be
  used by links in the HTML- and pdf-versions of the manual.
  
  Next  we  produce  a  LaTeX  version  of  the document. GAPDoc2LaTeX (5.3-1)
  returns   a  string  containing  the  LaTeX  source.  The  utility  function
  FileString  (6.3-5)  writes  the  content  of  a string to a file, we choose
  MyBook.tex.
  
    Example  
    gap> l := GAPDoc2LaTeX(r);;
    gap> FileString(Filename(path, Concatenation(bookname, ".tex")), l);
  
  
  Assuming  that  you  have  a sufficiently good installation of TeX available
  (see  GAPDoc2LaTeX  (5.3-1) for details) this can be processed with a series
  of commands like in the following example.
  
    Example  
    cd /my/book/path
    pdflatex MyBook
    bibtex MyBook
    pdflatex MyBook
    makeindex MyBook
    pdflatex MyBook
    mv MyBook.pdf manual.pdf
  
  
  After  this we have a pdf-version of the document in the file manual.pdf. It
  contains  hyperlink  information which can be used with appropriate browsers
  for convenient reading of the document on screen (e.g., xpdf is nice because
  it  allows  remote  calls  to  display  named locations of the document). Of
  course,  we could also use other commands like latex or dvips to process the
  LaTeX  source  file. Furthermore we have produced a file MyBook.pnr which is
  GAP-readable and contains the page number information for each (sub-)section
  of the document.
  
  We  can  add  this  page  number  information  to  the  indexing information
  collected  by  the  text converter and then print a manual.six file which is
  read by GAP when the manual is loaded. This is done with AddPageNumbersToSix
  (5.3-4) and PrintSixFile (5.3-5).
  
    Example  
    gap> AddPageNumbersToSix(r, Filename(path, "MyBook.pnr"));
    gap> PrintSixFile(Filename(path, "manual.six"), r, bookname);
  
  
  Finally   we   produce   an  HTML-version  of  the  document  and  write  it
  (chapter-wise) into files chap0.html, chap1.html and so on. They can be read
  with   any   Web-browser.   The   commands   are   GAPDoc2HTML  (5.3-7)  and
  GAPDoc2HTMLPrintHTMLFiles  (5.3-8).  We  also add a link from manual.html to
  chap0.html.  You  probably  want  to  copy  stylesheet  files  into the same
  directory,  see  5.3-9  for  more  details. The argument path of GAPDoc2HTML
  (5.3-7) specifies the directory containing the BibTeX database files.
  
    Example  
    gap> h := GAPDoc2HTML(r, path);;
    gap> GAPDoc2HTMLPrintHTMLFiles(h, path);
  
  
  5.1-1 MakeGAPDocDoc
  
  MakeGAPDocDoc( path, main, files, bookname[, gaproot][, ...] )  function
  
  This  function  collects  all  the  commands for producing a text-, pdf- and
  HTML-version of a GAPDoc document as described in Section 5.1. It checks the
  .log  file  from  the  call  of  pdflatex  and  reports if there are errors,
  warnings or overfull boxes.
  
  Note:  If  this  function works for you depends on your operating system and
  installed  software.  It  will  probably  work  on  most UNIX systems with a
  standard  LaTeX  installation.  If the function doesn't work for you look at
  the source code and adjust it to your system.
  
  Here  path  must be the directory (as string or directory object) containing
  the  main  file  main  of  the  document  (given  with  or  without the .xml
  extension.  The  argument  files  is  a list of (probably source code) files
  relative  to  path  which  contain  pieces  of  documentation  which must be
  included  in  the  document,  see Chapter 4. And bookname is the name of the
  book  used  by  GAP's  online  help. The optional argument gaproot must be a
  string  which  gives  the  relative  path  from  path  to  the main GAP root
  directory. If this is given, the HTML files are produced with relative paths
  to external books.
  
  If  the string "nopdf" is given as optional argument then MakeGAPDocDoc will
  not  produce  a  pdf-version  of  the  help  book  (the  source .tex-file is
  generated).  Consequently,  the  index  for the help system will not contain
  page  numbers for the pdf-version. This variant of MakeGAPDocDoc should work
  independently  of  the  operating  system  because  no external programs are
  called. It is recommended that distributed manuals contain the pdf-version.
  
  MakeGAPDocDoc  can  be  called  with  additional  arguments "MathJax", "Tth"
  and/or  "MathML".  If  these  are  given  additional  variants  of  the HTML
  conversion are called, see GAPDoc2HTML (5.3-7) for details.
  
  It  is  possible  to  use  GAPDoc  with  other  languages  than English, see
  SetGapDocLanguage (5.3-13) for more details.
  
  
  5.2 Parsing XML Documents
  
  Arbitrary  well-formed  XML  documents  can  be  parsed  and  browsed by the
  following  functions.  A  proper  validation  can  be  done with an external
  program, see XMLValidate (5.2-11) below.
  
  5.2-1 ParseTreeXMLString
  
  ParseTreeXMLString( str[, srcinfo][, entitydict] )  function
  ParseTreeXMLFile( fname[, entitydict] )  function
  Returns:  a record which is root of a tree structure
  
  The  first  function parses an XML-document stored in string str and returns
  the document in form of a tree.
  
  The   optional   argument   srcinfo   must   have  the  same  format  as  in
  OriginalPositionDocument  (4.2-2).  If it is given then error messages refer
  to the original source of the text with the problem.
  
  With  the  optional  argument  entitydict named entities can be given to the
  parser,  for  example  entities which are defined in the .dtd-file (which is
  not  read  by  this  parser).  The  standard  XML-entities do not need to be
  provided,  and  for  GAPDoc documents the entity definitions from gapdoc.dtd
  are automatically provided. Entities in the document's <!DOCTYPE declaration
  are  parsed  and  also need not to be provided here. The argument entitydict
  must  be  a  record where each component name is an entity name (without the
  surrounding & and ;) to which is assigned its substitution string.
  
  The   second   function   is   just   a   shortcut  for  ParseTreeXMLString(
  StringFile(fname), ... ), see StringFile (6.3-5).
  
  After  these  functions  return  the list of named entities which were known
  during the parsing can be found in the record ENTITYDICT.
  
  A  node  in the result tree corresponds to an XML element, or to some parsed
  character data. In the first case it looks as follows:
  
    Example Node  
    rec( name := "Book",
         attributes := rec( Name := "EDIM" ),
         content := [ ... list of nodes for content ...],
         start := 312,
         stop := 15610,
         next := 15611     )
  
  
  This  means that str{[312..15610]} looks like <Book Name="EDIM"> ... content
  ... </Book>.
  
  The  leaves  of  the  tree  encode parsed character data as in the following
  example:
  
    Example Node  
    rec( name := "PCDATA", 
         content := "text without markup "     )
  
  
  This function checks whether the XML document is well formed, see 2.1-14 for
  an  explanation.  If an error in the XML structure is found, a break loop is
  entered  and the text around the position where the problem starts is shown.
  With  Show();  one  can  browse  the original input in the Pager (Reference:
  Pager),  starting  with  the line where the error occurred. All entities are
  resolved  when  they  are  either entities defined in the GAPDoc package (in
  particular  the standard XML entities) or if their definition is included in
  the <!DOCTYPE ..> tag of the document.
  
  Note  that ParseTreeXMLString does not parse and interpret the corresponding
  document  type  definition  (the  .dtd-file given in the <!DOCTYPE ..> tag).
  Hence  it  also  does not check the validity of the document (i.e., it is no
  validating XML parser).
  
  If  you  are  using  this  function  to  parse a GAPDoc document you can use
  CheckAndCleanGapDocTree  (5.2-8) for some validation and additional checking
  of the document structure.
  
  5.2-2 StringXMLElement
  
  StringXMLElement( tree )  function
  Returns:  a list [string, positions]
  
  The  argument  tree must have a format of a node in the parse tree of an XML
  document  as returned by ParseTreeXMLString (5.2-1) (including the root node
  representing  the  full  document).  This  function computes a pair [string,
  positions]  where  string  contains XML code which is equivalent to the code
  which  was  parsed  to  get  tree.  And positions is a list of lists of four
  numbers  [eltb,  elte,  contb,  conte].  There is one such list for each XML
  element  occuring  in  string,  where  eltb  and  elte are the begin and end
  position  of  this element in string and where contb and conte are begin and
  end  position  of  the content of this element, or both are 0 if there is no
  content.
  
  Note  that  parsing  XML code is an irreversible task, we can only expect to
  get equivalent XML code from this function. But parsing the resulting string
  again  and  applying  StringXMLElement  again gives the same result. See the
  function  EntitySubstitution  (5.2-3)  for back-substitutions of entities in
  the result.
  
  5.2-3 EntitySubstitution
  
  EntitySubstitution( xmlstring, entities )  function
  Returns:  a string
  
  The  argument  xmlstring  must  be  a  string  containing XML code or a pair
  [string,  positions]  as  returned by StringXMLElement (5.2-2). The argument
  entities  specifies entity names (without the surrounding & and ;) and their
  substitution  strings, either a list of pairs of strings or as a record with
  the names as components and the substitutions as values.
  
  This  function  tries  to substitute non-intersecting parts of string by the
  given entities. If the positions information is given then only parts of the
  document  which  allow  a  valid  substitution  by an entity are considered.
  Otherwise a simple text substitution without further check is done.
  
  Note that in general the entity resolution in XML documents is a complicated
  and  non-reversible task. But nevertheless this utility may be useful in not
  too complicated situations.
  
  5.2-4 DisplayXMLStructure
  
  DisplayXMLStructure( tree )  function
  
  This  utility  displays  the  tree  structure  of  an  XML document as it is
  returned by ParseTreeXMLString (5.2-1) (without the PCDATA leaves).
  
  Since  this  is  usually  quite  long  the  result  is shown using the Pager
  (Reference: Pager).
  
  5.2-5 ApplyToNodesParseTree
  
  ApplyToNodesParseTree( tree, fun )  function
  AddRootParseTree( tree )  function
  RemoveRootParseTree( tree )  function
  
  The  function  ApplyToNodesParseTree  applies a function fun to all nodes of
  the  parse  tree  tree  of  an  XML  document returned by ParseTreeXMLString
  (5.2-1).
  
  The  function  AddRootParseTree  is  an  application of this. It adds to all
  nodes  a  component .root to which the top node tree tree is assigned. These
  components can be removed afterwards with RemoveRootParseTree.
  
  Here are two more utilities which use ApplyToNodesParseTree.
  
  5.2-6 GetTextXMLTree
  
  GetTextXMLTree( tree )  function
  Returns:  a string
  
  The  argument  tree must be a node of a parse tree of some XML document, see
  ParseTreeXMLFile (5.2-1). This function collects the content of this and all
  included elements recursively into a string.
  
  5.2-7 XMLElements
  
  XMLElements( tree, eltnames )  function
  Returns:  a list of nodes
  
  The  argument  tree must be a node of a parse tree of some XML document, see
  ParseTreeXMLFile  (5.2-1).  This  function returns a list of all subnodes of
  tree  (possibly  including  tree) of elements with name given in the list of
  strings  eltnames.  Use  "PCDATA"  as name for leave nodes which contain the
  actual  text  of  the  document.  As  an abbreviation eltnames can also be a
  string which is then put in a one element list.
  
  And here are utilities for processing GAPDoc XML documents.
  
  5.2-8 CheckAndCleanGapDocTree
  
  CheckAndCleanGapDocTree( tree )  function
  Returns:  nothing
  
  The  argument  tree of this function is a parse tree from ParseTreeXMLString
  (5.2-1) of some GAPDoc document. This function does an (incomplete) validity
  check  of  the  document  according  to  the  document  type  declaration in
  gapdoc.dtd. It also does some additional checks which cannot be described in
  the  DTD  (like  checking whether chapters and sections have a heading). For
  elements  with  element  content  the  whitespace  between these elements is
  removed.
  
  In  case of an error the break loop is entered and the position of the error
  in  the  original  XML  document is printed. With Show(); one can browse the
  original input in the Pager (Reference: Pager).
  
  5.2-9 AddParagraphNumbersGapDocTree
  
  AddParagraphNumbersGapDocTree( tree )  function
  Returns:  nothing
  
  The argument tree must be an XML tree returned by ParseTreeXMLString (5.2-1)
  applied  to a GAPDoc document. This function adds to each node of the tree a
  component   .count   which  is  of  form  [Chapter[,  Section[,  Subsection,
  Paragraph]  ] ]. Here the first three numbers should be the same as produced
  by  the  LaTeX  version  of  the  document. Text before the first chapter is
  counted  as  chapter  0  and  similarly  for  sections and subsections. Some
  elements are always considered to start a new paragraph.
  
  5.2-10 InfoXMLParser
  
  InfoXMLParser  info class
  
  The default level of this info class is 1. Functions like ParseTreeXMLString
  (5.2-1) are then printing some information, in particular in case of errors.
  You can suppress it by setting the level of InfoXMLParser to 0. With level 2
  there may be some more information for debugging purposes.
  
  5.2-11 XMLValidate
  
  XMLValidate( doc, dtdpath )  function
  Returns:  fail or a record
  
  The argument doc must be a string which is an XML document, and dtdpath is a
  path containing the corresponding DTD file.
  
  The function returns fail if the program xmllint cannot be called.
  
  Otherwise the document is validated via the external program xmllint via the
  function   IO_PipeThroughWithError   (IO_PipeThroughWithError???),  and  its
  resulting record is returned.
  
  5.2-12 ValidateGAPDoc
  
  ValidateGAPDoc( doc )  function
  Returns:  fail, true or a record
  
  The  argument  doc must be a string which is a GAPDoc XML document or a pair
  of  a  string and list as returned by ComposedDocument (4.2-1) with argument
  info set to true.
  
  The function returns fail in case of a problem.
  
  Otherwise  the  document  is  validated  using  XMLValidate (5.2-11). If the
  validation  was  successful  this  function  returns  true.  In  the case of
  validation  errors some information is printed and the result of XMLValidate
  (5.2-11) is returned.
  
    Example  
    gap> fn := Filename(DirectoriesPackageLibrary("gapdoc", ""), 
    >                                             "3k+1/3k+1.xml");;
    gap> doc := ComposedDocument("GAPDoc", "", fn, [], true);;
    gap> doc[1][220] := 't';;
    gap> check := ValidateGAPDoc(doc);;
    ValidateGAPDoc found problems:
    Line 11:  parser error : Opening and ending tag mismatch
       source position: /opt/gap/pkg/GAPDoc-1.6.4/3k+1/3k+1.xml, line 11
  
  
  
  5.3 The Converters
  
  Here  are  more  details  about  the  conversion  programs  for  GAPDoc  XML
  documents.
  
  5.3-1 GAPDoc2LaTeX
  
  GAPDoc2LaTeX( tree )  function
  Returns:  LaTeX document as string
  
  SetGapDocLaTeXOptions( [...] )  function
  Returns:  Nothing
  
  The  argument  tree  for  this  function  is  a tree describing a GAPDoc XML
  document  as  returned  by ParseTreeXMLString (5.2-1) (probably also checked
  with  CheckAndCleanGapDocTree  (5.2-8)). The output is a string containing a
  version  of  the  document which can be written to a file and processed with
  LaTeX or pdfLaTeX (and probably BibTeX and makeindex).
  
  The  output  uses  the  report  document class and needs the following LaTeX
  packages:  amssymb,  inputenc,  makeidx,  color,  fancyvrb, psnfss, pslatex,
  enumitem  and  hyperref.  These are for example provided by the teTeX-1.0 or
  texlive  distributions  of TeX (which in turn are used for most TeX packages
  of current Linux distributions); see http://www.tug.org/tetex/.
  
  In  particular, the resulting pdf-output (and dvi-output) contains (internal
  and  external)  hyperlinks which can be very useful for onscreen browsing of
  the document.
  
  The  LaTeX  processing also produces a file with extension .pnr which is GAP
  readable  and  contains  the  page  numbers  for  all  (sub)sections  of the
  document.  This  can  be  used by GAP's online help; see AddPageNumbersToSix
  (5.3-4). Non-ASCII characters in the GAPDoc document are translated to LaTeX
  input  in  ASCII-encoding  with  the  help  of Encode (6.2-2) and the option
  "LaTeX".  See  the documentation of Encode (6.2-2) for how to proceed if you
  have a character which is not handled (yet).
  
  This  function  works  by  running recursively through the document tree and
  calling  a  handler  function  for  each  GAPDoc  XML element. Many of these
  handler  functions  (usually  in  GAPDoc2LaTeXProcs.<ElementName>)  are  not
  difficult  to  understand  (the greatest complications are some commands for
  index  entries,  labels  or  the  output  of page number information). So it
  should  be  easy  to  adjust  layout  details  to  your  own taste by slight
  modifications of the program.
  
  Former  versions of GAPDoc supported some XML processing instructions to add
  some  extra  lines  to  the  preamble  of the LaTeX document. Its use is now
  deprecated,  use  the  much more flexible SetGapDocLaTeXOptions instead: The
  default   layout   of   the   resulting   documents   can  be  changed  with
  SetGapDocLaTeXOptions.  This  changes  parts of the header of the LaTeX file
  produced  by  GAPDoc.  You  can  see  the  header  with some placeholders by
  Page(GAPDoc2LaTeXProcs.Head);.  The  placeholders are filled with components
  from   the   record   GAPDoc2LaTeXProcs.DefaultOptions.   The  arguments  of
  SetGapDocLaTeXOptions  can  be  records with the same structure (or parts of
  it)  with  different  values.  As abbreviations there are also three strings
  supported  as  arguments.  These  are  "nocolor" for switching all colors to
  black;  then  "nopslatex"  to use standard LaTeX fonts instead of postscript
  fonts;  and  finally  "utf8" to choose UTF-8 as input encoding for the LaTeX
  document.
  
  5.3-2 GAPDoc2Text
  
  GAPDoc2Text( tree[, bibpath][, width] )  function
  Returns:  record containing text files as strings and other information
  
  The  argument  tree  for  this  function  is  a tree describing a GAPDoc XML
  document  as  returned  by ParseTreeXMLString (5.2-1) (probably also checked
  with CheckAndCleanGapDocTree (5.2-8)). This function produces a text version
  of  the document which can be used with GAP's online help (with the "screen"
  viewer,  see  SetHelpViewer  (Reference:  SetHelpViewer)). It includes title
  page,  bibliography  and  index.  The bibliography is made from BibXMLext or
  BibTeX  databases,  see  7.  Their  location must be given with the argument
  bibpath (as string or directory object).
  
  The  output is a record with one component for each chapter (with names "0",
  "1",  ...,  "Bib" and "Ind"). Each such component is again a record with the
  following components:
  
  text
        the text of the whole chapter as a string
  
  ssnr
        list  of  subsection  numbers  in  this  chapter  (like  [3, 2, 1] for
        chapter 3, section 2, subsection 1)
  
  linenr
        corresponding list of line numbers where the subsections start
  
  len
        number of lines of this chapter
  
  The    result    can    be    written    into   files   with   the   command
  GAPDoc2TextPrintTextFiles (5.3-3).
  
  As  a  side  effect  this  function also produces the manual.six information
  which is used for searching in GAP's online help. This is stored in tree.six
  and  can  be  printed  into  a  manual.six  file  with  PrintSixFile (5.3-5)
  (preferably  after  producing  a  LaTeX  version of the document as well and
  adding the page number information to tree.six, see GAPDoc2LaTeX (5.3-1) and
  AddPageNumbersToSix (5.3-4)).
  
  The  text  produced  by  this  function contains some markup via ANSI escape
  sequences. The sequences used here are usually ignored by terminals. But the
  GAP  help  system  will  substitute  them by interpreted color and attribute
  sequences  (see TextAttr (6.1-2)) before displaying them. There is a default
  markup  used  for  this  but  it  can  also  be  configured by the user, see
  SetGAPDocTextTheme  (5.3-6).  Furthermore,  the  text  produced  is in UTF-8
  encoding.    The    encoding   is   also   translated   on   the   fly,   if
  GAPInfo.TermEncoding  is  set  to some encoding supported by Encode (6.2-2),
  e.g., "ISO-8859-1" or "latin1".
  
  With the optional argument width a different length of the output text lines
  can  be  chosen. The default is 76 and all lines in the resulting text start
  with  two  spaces. This looks good on a terminal with a standard width of 80
  characters and you probably don't want to use this argument.
  
  5.3-3 GAPDoc2TextPrintTextFiles
  
  GAPDoc2TextPrintTextFiles( t[, path] )  function
  Returns:  nothing
  
  The  first  argument  must  be a result returned by GAPDoc2Text (5.3-2). The
  second  argument is a path for the files to write, it can be given as string
  or  directory  object.  The  text of each chapter is written into a separate
  file with name chap0.txt, chap1.txt, ..., chapBib.txt, and chapInd.txt.
  
  If  you  want  to  make your document accessible via the GAP online help you
  must  put  at  least  these  files  for  the  text version into a directory,
  together  with  the  file manual.six, see PrintSixFile (5.3-5). Then specify
  the  path  to  the  manual.six  file in the packages PackageInfo.g file, see
  'Reference: The PackageInfo.g File'.
  
  Optionally  you  can add the dvi- and pdf-versions of the document which are
  produced  with  GAPDoc2LaTeX  (5.3-1) to this directory. The files must have
  the  names  manual.dvi  and  manual.pdf,  respectively. Also you can add the
  files  of  the  HTML  version  produced  with  GAPDoc2HTML  (5.3-7)  to this
  directory,  see  GAPDoc2HTMLPrintHTMLFiles (5.3-8). The handler functions in
  GAP  for this help format detect automatically which of the optional formats
  of a book are actually available.
  
  5.3-4 AddPageNumbersToSix
  
  AddPageNumbersToSix( tree, pnrfile )  function
  Returns:  nothing
  
  Here  tree  must  be  the  XML  tree  of  a  GAPDoc  document,  returned  by
  ParseTreeXMLString    (5.2-1).    Running    latex    on   the   result   of
  GAPDoc2LaTeX(tree)  produces  a  file  pnrfile  (with  extension  .pnr). The
  command  GAPDoc2Text(tree)  creates  a component tree.six which contains all
  information  about  the  document  for  the GAP online help, except the page
  numbers  in  the .dvi, .ps, .pdf versions of the document. This command adds
  the missing page number information to tree.six.
  
  5.3-5 PrintSixFile
  
  PrintSixFile( tree, bookname, fname )  function
  Returns:  nothing
  
  This  function  prints  the  .six file fname for a GAPDoc document stored in
  tree with name bookname. Such a file contains all information about the book
  which  is  needed  by  the  GAP  online help. This information must first be
  created by calls of GAPDoc2Text (5.3-2) and AddPageNumbersToSix (5.3-4).
  
  5.3-6 SetGAPDocTextTheme
  
  SetGAPDocTextTheme( [optrec1[, optrec2], ...] )  function
  Returns:  nothing
  
  This  utility  function  is for readers of the screen version of GAP manuals
  which  are generated by the GAPDoc package. It allows to configure the color
  and  attribute layout of the displayed text. There is a default which can be
  reset by calling this function without argument.
  
  As  an  abbreviation  the arguments optrec1 and so on can be strings for the
  known  name  of  a  theme.  Information  about  valid  names  is  shown with
  SetGAPDocTextTheme("");.
  
  Otherwise,  optrec1  and  so  on must be a record. Its entries overwrite the
  corresponding entries in the default and in previous arguments. To construct
  valid  markup  you can use TextAttr (6.1-2). Entries must be either pairs of
  strings,  which  are  put  before and after the corresponding text, or as an
  abbreviation  it  can  be  a  single  string. In the latter case, the second
  string  is  implied;  if  the  string contains an escape sequence the second
  string  is TextAttr.reset, otherwise the given string is used. The following
  components are recognized:
  
  flush
        "both"  for  left-right  justified  paragraphs,  and "left" for ragged
        right ones
  
  Heading
        chapter and (sub-)section headings
  
  Func
        function, operation, ... names
  
  Arg
        argument names in descriptions
  
  Example
        example code
  
  Package
        package names
  
  Returns
        Returns-line in descriptions
  
  URL
        URLs
  
  Mark
        Marks in description lists
  
  K
        GAP keywords
  
  C
        code or text to type
  
  F
        file names
  
  B
        buttons
  
  M
        simplified math elements
  
  Math
        normal math elements
  
  Display
        displayed math elements
  
  Emph
        emphasized text
  
  Q
        quoted text
  
  Ref
        reference text
  
  Prompt
        GAP prompt in examples
  
  BrkPrompt
        GAP break prompt in examples
  
  GAPInput
        GAP input in examples
  
  reset
        reset to default, don't change this
  
  BibAuthor
        author names in bibliography
  
  BibTitle
        titles in bibliography
  
  BibJournal
        journal names in bibliography
  
  BibVolume
        volume number in bibliography
  
  BibLabel
        labels for bibliography entries
  
  BibReset
        reset for bibliography, don't change
  
  ListBullet
        bullet for simple lists (2 visible characters long)
  
  EnumMarks
        one visible character before and after the number in enumerated lists
  
  DefLineMarker
        marker  before function and variable definitions (2 visible characters
        long)
  
  FillString
        for filling in definitions and example separator lines
  
    Example  
    gap> # use no colors for GAP examples and 
    gap> # change display of headings to bold green
    gap> SetGAPDocTextTheme("noColorPrompt", 
    >            rec(Heading:=Concatenation(TextAttr.bold, TextAttr.2)));
  
  
  5.3-7 GAPDoc2HTML
  
  GAPDoc2HTML( tree[, bibpath[, gaproot]][, mtrans] )  function
  Returns:  record containing HTML files as strings and other information
  
  The  argument  tree  for  this  function  is  a tree describing a GAPDoc XML
  document  as  returned  by ParseTreeXMLString (5.2-1) (probably also checked
  with  CheckAndCleanGapDocTree  (5.2-8)).  Without  an  mtrans  argument this
  function produces an HTML version of the document which can be read with any
  Web-browser  and  also  be  used  with  GAP's online help (see SetHelpViewer
  (Reference:  SetHelpViewer)).  It  includes  title  page,  bibliography, and
  index.  The  bibliography is made from BibTeX databases. Their location must
  be  given  with  the argument bibpath (as string or directory object, if not
  given the current directory is used). If the third argument gaproot is given
  and  is  a  string then this string is interpreted as relative path to GAP's
  main  root directory. Reference-URLs to external HTML-books which begin with
  the  GAP root path are then rewritten to start with the given relative path.
  This  makes  the HTML-documentation portable provided a package is installed
  in some standard location below the GAP root.
  
  The  output is a record with one component for each chapter (with names "0",
  "1",  ..., "Bib", and "Ind"). Each such component is again a record with the
  following components:
  
  text
        the text of an HTML file containing the whole chapter (as a string)
  
  ssnr
        list  of  subsection  numbers  in  this  chapter  (like  [3, 2, 1] for
        chapter 3, section 2, subsection 1)
  
  Standard output format without mtrans argument
  
  The HTML code produced with this converter conforms to the W3C specification
  XHTML  1.0  strict,  see http://www.w3.org/TR/xhtml1. First, this means that
  the  HTML  files are valid XML files. Secondly, the extension strict says in
  particular  that  the  code  doesn't  contain  any  explicit  font  or color
  information.
  
  Mathematical  formulae  are  handled  as  in  the text converter GAPDoc2Text
  (5.3-2). We don't want to assume that the browser can use symbol fonts. Some
  GAP  users  like  to  browse  the  online  help with lynx, see SetHelpViewer
  (Reference:  SetHelpViewer),  which runs inside the same terminal windows as
  GAP.
  
  To  view  the  generated  files in graphical browsers, stylesheet files with
  layout  configuration should be copied into the directory with the generated
  HTML files, see 5.3-9.
  
  Output format with mtrans argument
  
  Currently, there are three variants of this converter available which handle
  mathematical  formulae  differently. They are accessed via the optional last
  mtrans argument.
  
  If mtrans is set to "MathJax" the formulae are essentially translated as for
  LaTeX  documents  (there  is  no  processing  of <M> elements as decribed in
  3.8-2). Inline formulae are delimited by \( and \) and displayed formulae by
  \[  and  \]. With MathJax webpages can contain nicely formatted scalable and
  searchable    formulae.   The   resulting   files   link   by   default   to
  http://cdn.mathjax.org  to get the MathJax script and fonts. This means that
  they  can only be used on computers with internet access. An alternative URL
  can  be  set  by overwriting GAPDoc2HTMLProcs.MathJaxURL before building the
  HTML  version of a manual. This way a local installation of MathJax could be
  used. See http://www.mathjax.org/ for more details.
  
  The  following  possibilities  for mtrans are still supported, but since the
  MathJax approach seems much better, their use is deprecated.
  
  If the argument mtrans is set to "Tth" it is assumed that you have installed
  the  LaTeX  to  HTML  translation program tth. This is used to translate the
  contents  of  the M, Math and Display elements into HTML code. Note that the
  resulting  code is not compliant with any standard. Formally it is XHTML 1.0
  Transitional, it contains explicit font specifications and the characters of
  mathematical  symbols are included via their position in a Symbol font. Some
  graphical  browsers  can  be  configured to display this in a useful manner,
  check  the  Tth  homepage  (http://hutchinson.belmont.ma.us/tth/)  for  more
  details.
  
  This  function  works  by  running recursively through the document tree and
  calling  a  handler  function  for  each  GAPDoc  XML element. Many of these
  handler   functions  (usually  in  GAPDoc2TextProcs.<ElementName>)  are  not
  difficult  to  understand  (the greatest complications are some commands for
  index  entries,  labels  or  the  output  of page number information). So it
  should  be  easy  to  adjust  certain  details  to  your own taste by slight
  modifications of the program.
  
  The  result  of  this  converter  can  be  written to files with the command
  GAPDoc2HTMLPrintHTMLFiles (5.3-8).
  
  There  are  two  user  preferences  for reading the HTML manuals produced by
  GAPDoc.  A  user  can  choose  among several style files which determine the
  appearance of the manual pages with SetUserPreference("GAPDoc", "HTMLStyle",
  [...]);   where   the   list   in  the  third  argument  are  arguments  for
  SetGAPDocHTMLStyle    (5.3-11).    The   second   preference   is   set   by
  SetUserPreference("GAPDoc",  "UseMathJax", ...); where the third argument is
  true  or  false  (default).  If  this  is  set  to true, the GAP help system
  displays the MathJax version of the HTML manuals.
  
  5.3-8 GAPDoc2HTMLPrintHTMLFiles
  
  GAPDoc2HTMLPrintHTMLFiles( t[, path] )  function
  Returns:  nothing
  
  The  first  argument  must  be a result returned by GAPDoc2HTML (5.3-7). The
  second  argument is a path for the files to write, it can be given as string
  or  directory  object.  The  text of each chapter is written into a separate
  file with name chap0.html, chap1.html, ..., chapBib.html, and chapInd.html.
  
  The   MathJax   versions   are   written   to   files   chap0_mj.html,  ...,
  chapInd_mj.html.
  
  The experimental version which is produced with tth uses different names for
  the  files,  namely  chap0_sym.html,  and  so on for files which need symbol
  fonts.
  
  You  should  also add stylesheet files to the directory with the HTML files,
  see 5.3-9.
  
  
  5.3-9 Stylesheet files
  
  For  graphical  browsers  the  layout  of  the generated HTML manuals can be
  highly  configured  by cascading stylesheet (CSS) and javascript files. Such
  files are provided in the styles directory of the GAPDoc package.
  
  We  recommend  that  these files are copied into each manual directory (such
  that   each   of  them  is  selfcontained).  There  is  a  utility  function
  CopyHTMLStyleFiles  (5.3-10)  which does this. Of course, these files may be
  changed  or  new  styles  may  be  added. New styles may also be sent to the
  GAPDoc authors for possible inclusion in future versions.
  
  The  generated HTML files refer to the file manual.css which conforms to the
  W3C  specification  CSS  2.0,  see  http://www.w3.org/TR/REC-CSS2,  and  the
  javascript file manual.js (only in browsers which support CSS or javascript,
  respectively;  but the HTML files are also readable without any of them). To
  add  a  style  mystyle  one  or  both  of mystyle.css and mystyle.js must be
  provided;  these  can  overwrite  default  settings  and  add new javascript
  functions. For more details see the comments in manual.js.
  
  5.3-10 CopyHTMLStyleFiles
  
  CopyHTMLStyleFiles( dir )  function
  Returns:  nothing
  
  This  utility  function  copies  the  *.css  and  *.js files from the styles
  directory of the GAPDoc package into the directory dir.
  
  5.3-11 SetGAPDocHTMLStyle
  
  SetGAPDocHTMLStyle( [style1[, style2], ...] )  function
  Returns:  nothing
  
  This  utility  function  is  for  readers of the HTML version of GAP manuals
  which  are  generated  by  the  GAPDoc  package.  It allows to configure the
  display style of the manuals. This will only have an effect if you are using
  a browser that supports javascript. There is a default which can be reset by
  calling this function without argument.
  
  The  arguments  style1 and so on must be strings. You can find out about the
  valid  strings  by  following  the  [Style]  link on top of any manual page.
  (Going  back to the original page, its address has a setting for GAPDocStyle
  which is the list of strings, separated by commas, you want to use here.)
  
    Example  
    gap> # show/hide subsections in tables on contents only after click,
    gap> # and don't use colors in GAP examples
    gap> SetGAPDocHTMLStyle("toggless", "nocolorprompt");
  
  
  5.3-12 InfoGAPDoc
  
  InfoGAPDoc  info class
  
  The  default  level  of  this  info  class is 1. The converter functions for
  GAPDoc  documents  are then printing some information. You can suppress this
  by setting the level of InfoGAPDoc to 0. With level 2 there may be some more
  information for debugging purposes.
  
  5.3-13 SetGapDocLanguage
  
  SetGapDocLanguage( [lang] )  function
  Returns:  nothing
  
  The  GAPDoc  converter programs sometimes produce text which is not explicit
  in  the  document,  e.g.,  headers  like  Abstract,  Appendix, links to Next
  Chapter, variable types function and so on.
  
  With  SetGapDocLanguage  the  language  for  these texts can be changed. The
  argument  lang must be a string. Calling without argument or with a language
  name  for  which  no  translations  are  available  is the same as using the
  default "english".
  
  If   your   language   lang  is  not  yet  available,  look  at  the  record
  GAPDocTexts.english  and translate all the strings to lang. Then assign this
  record to GAPDocTexts.(lang) and send it to the GAPDoc authors for inclusion
  in  future  versions  of  GAPDoc.  (Currently,  there  are  translations for
  english, german, russian and ukrainian.)
  
  Further  hints: To get strings produced by LaTeX right you will probably use
  the  babel  package  with option lang, see SetGapDocLaTeXOptions (5.3-1). If
  lang cannot be encoded in latin1 encoding you can consider the use of "utf8"
  with SetGapDocLaTeXOptions (5.3-1).
  
  
  5.4 Testing Manual Examples
  
  We  also  provide  some  tools  to  check  and  adjust the examples given in
  <Example>-elements.
  
  Former   versions   of   GAPDoc   provided   functions   ManualExamples  and
  TestManualExamples.  These  functions  are  still  available,  but no longer
  documented. Their use is deprecated.
  
  5.4-1 ExtractExamples
  
  ExtractExamples( path, main, files, units[, withLog] )  function
  Returns:  a list of lists
  
  ExtractExamplesXMLTree( tree, units[, withLog] )  function
  Returns:  a list of lists
  
  The  argument  tree  must  be  a  parse  tree  of  a  GAPDoc  document,  see
  ParseTreeXMLFile (5.2-1). The function ExtractExamplesXMLTree returns a data
  structure  representing  the  <Example> elements of the document. The return
  value  can  be  used with RunExamples (5.4-2) to check and optionally update
  the examples of the document.
  
  Depending  on the argument units several examples are collected in one list.
  Recognized  values  for  units  are  "Chapter",  "Section",  "Subsection" or
  "Single".  The latter means that each example is in a separate list. For all
  other value of units just one list with all examples is returned.
  
  The  arguments  path,  main and files of ExtractExamples are the same as for
  ComposedDocument  (4.2-1).  This  function  first  contructs  and parses the
  GAPDoc document and then applies ExtractExamplesXMLTree.
  
  If  the  optional argument withLog is given and true then <Log> elements are
  handled  like <Example> elements. This allows to put examples which can only
  run  under  certain  conditions,  e.g.,  when  certain external programs are
  available,  into  <Log> elements. (Put example code which should also not be
  included by this variant into <Listing> elements.)
  
  5.4-2 RunExamples
  
  RunExamples( exmpls[, optrec] )  function
  Returns:  true or false
  
  The  argument exmpls must be the output of a call to ExtractExamples (5.4-1)
  or  ExtractExamplesXMLTree  (5.4-1).  The optional argument optrec must be a
  record, its components can change the default behaviour of this function.
  
  By default this function runs the GAP input of all examples and compares the
  actual  output  with  the output given in the examples. If differences occur
  these  are displayed together with information on the location of the source
  code  of  that  example.  Before running the examples in each unit (entry of
  exmpls)  the  function  START_TEST (Reference: START_TEST) is called and the
  screen width is set to 72 characters.
  
  This function returns true if no differences are found and false otherwise.
  
  If the argument optrec is given, the following components are recognized:
  
  showDiffs
        The  default value is true, if set to something else found differences
        in the examples are not displayed.
  
  width
        The  value  must  be  a positive integer which is used as screen width
        when running the examples. As mentioned above, the default is 72 which
        is  a  sensible value for the text version of the GAPDoc document used
        in a 80 character wide terminal.
  
  ignoreComments
        The default is false.
        If  set  to  true  comments  in  the  input will be ignored (as in the
        default behaviour of the Test (Reference: Test) function).
  
  changeSources
        If  this  is  set  to true then the source code of all manual examples
        which show differences is adjusted to the current outputs. The default
        is false.
        Use  this  feature  with  care.  Note  that  sometimes differences can
        indicate  a  bug, and in such a case it is more appropriate to fix the
        bug instead of changing the example output.
  
  compareFunction
        The  function  used to compare the output shown in the example and the
        current output. See Test (Reference: Test) for more details.
  
  checkWidth
        If this option is a positive integer n the function prints warnings if
        an  example  contains  any line with more than n characters (input and
        output lines are considered). By default this option is set to false.