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   add   a   file   manual.css,  see
  GAPDoc2HTMLPrintHTMLFiles  (5.3-8)  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.
  
  Experimental:  MakeGAPDocDoc  can  be called with additional arguments "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-10) for more details.
  
  
  5.2 Parsing XML Documents
  
  Arbitrary  well-formed  XML  documents  can  be  parsed  and  browsed by the
  following functions.
  
  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.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:  a4wide,  amssymb, inputenc, makeidx, color, fancyvrb, pslatex 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 online 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). There is support for two types of XML processing instructions which
  allow to change the options used for the document class or to add some extra
  lines to the preamble of the LaTeX document. They can be specified as in the
  following examples:
  
  -----------------  in top level of XML document  -----------------
    <?LaTeX Options="12pt"?>
    <?LaTeX ExtraPreamble="\usepackage{blabla}
    \newcommand{\bla}{blabla}
    "?>
  ------------------------------------------------------------------
  
  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).
  
  A  hint  for large documents: In many TeX installations one can easily reach
  some    memory    limitations    with    documents    which   contain   many
  (cross-)references.  In teTeX you can look for a file texmf.cnf which allows
  to enlarge certain memory sizes.
  
  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.
  
  A  few  settings  can  be adjusted by the function SetGapDocLaTeXOptions. It
  takes  strings  as  arguments.  If  the arguments contain one of the strings
  "pdf",  "dvi"  or  "ps"  then  LaTeXs  hyperref  package  is  configured for
  optimized  output  of  the  given  format  (default is "pdf"). If "color" or
  "nocolor"  is  in  the  argument  list  then  colors  are  used or not used,
  respectively. The default is to use colors but "nocolor" can be useful for a
  printable  version  of  a  manual (but who wants to print such manuals?). If
  "utf8" is an argument then the package inputenc is used with UTF-8 encoding,
  instead  of  the  default  latin1.  If  "nopslatex"  is an argument then the
  package pslatex is not used, otherwise it is.
  
  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
  'Extending: 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
  (5.3-1)(tree)  produces  a  file  pnrfile (with extension .pnr). The command
  GAPDoc2Text  (5.3-2)(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( [optrec] ) ___________________________________function
  Returns:  nothing
  
  With  this  function  can readers of the screen version of GAP manuals which
  are generated by the GAPDoc package 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 argument optrec can be a string for the known name of
  a  theme. Currently, there is only "none" which displays just the plain text
  without any markup.
  
  Otherwise,  optrec must be a record. Its entries overwrite the corresponding
  entries  in  the  default.  To  construct  valid markup you can use TextAttr
  (6.1-2). The following components are recognized:
  
  reset
        reset to default, don't change this
  
  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
  
  Emph
        emphasized text
  
  Ref
        reference text
  
  BibReset
        reset for bibliography, don't change
  
  BibAuthor
        author names in bibliography
  
  BibTitle
        titles in bibliography
  
  BibJournal
        journal names in bibliography
  
  BibVolume
        volume number in bibliography
  
  BibLabel
        labels for bibliography entries
  
  ---------------------------  Example  ----------------------------
    gap> # change display of headings to bold green
    gap> SetGAPDocTextTheme(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.
  
  Using a stylesheet file
  
  The  layout  information  for  a  browser should be specified in a cascading
  style  sheet  (CSS)  file.  The GAPDoc package contains an example of such a
  style  sheet,  see the file gapdoc.css in the root directory of the package.
  This    file    conforms   to   the   W3C   specification   CSS   2.0,   see
  http://www.w3.org/TR/REC-CSS2.  You  may  just  copy that file as manual.css
  into  the  directory  which contains the HTML version of your documentation.
  But,  of  course,  you  are free to adjust it for your package, e.g., change
  colors or other layout details, add a background image, ... Each of the HTML
  files  produced  by the converters contains a link to this local style sheet
  file called manual.css.
  
  Output format with mtrans argument
  
  Currently,  there  are two experimental variants of this converter available
  which  handle  mathematical  formulae differently. They are accessed via the
  optional last mtrans argument.
  
  If  this  argument 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.
  
  If  the  mtrans  argument  is  set  to  "MathML" it is assumed that you have
  installed   the   translation   program  ttm,  see  also  the  Tth  homepage
  (http://hutchinson.belmont.ma.us/tth/)).  This  is  used  to  translate  the
  contents  of  the  M,  Math  and  Display elements to MathML 2.0 markup. The
  resulting  files should conform to the "XHTML 1.1 plus MathML 2.0" standard,
  see the W3C information (http://www.w3.org/TR/MathML2/) for more details. It
  is  expected  that the next generation of graphical browsers will be able to
  render  such  files (try for example Mozilla, at least 0.9.9). You must copy
  the  .xsl  and  .css  files  from  GAPDocs mathml directory to the directory
  containing the output files. The translation with ttm is still experimental.
  The  output  of  this  converter variant is garbage for browsers which don't
  support MathML.
  
  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).
  
  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  experimental  versions which are produced with tth or ttm use different
  names  for  the files, namely chap0_sym.html, and so on for files which need
  symbol fonts and chap0_mml.xml for files with MathML translations.
  
  You  may  also  want  to  place  a style sheet file manual.css into the same
  directory as the HTML files. You can copy for example the file gapdoc.css in
  the  root directory of the GAPDoc package (Filename( Directory( PackageInfo(
  "gapdoc" )[1].InstallationPath), "gapdoc.css");).
  
  5.3-9 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-10 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 the information on ExtraPreamble in
  GAPDoc2LaTeX  (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   the   examples   given  in
  <Example>-elements.
  
  5.4-1 ManualExamples
  
  > ManualExamples( path, main, files, units ) _______________________function
  Returns:  a list of strings
  
  > ManualExamplesXMLTree( tree, units ) _____________________________function
  Returns:  a list of strings
  
  The  argument  tree  must  be  a  parse  tree  of  a  GAPDoc  document,  see
  ParseTreeXMLFile  (5.2-1). The function ManualExamplesXMLTree returns a list
  of  strings  containing  the content of <Example> elements. For each example
  there  is a comment line showing the paragraph number and (if available) the
  original  location  of  this example with file and line number. Depending on
  the argument units several examples are colleected in one string. Recognized
  values  for  units  are  "Chapter", "Section", "Subsection" or "Single". The
  latter  means that each example is in a separate string. For all other value
  of units just one string with all examples is returned.
  
  The  arguments  path,  main  and files of ManualExamples are the same as for
  ComposedDocument  (4.2-1).  This  function  first  contructs  and parses the
  GAPDoc document and then applies ManualExamplesXMLTree.
  
  5.4-2 ReadTestExamplesString
  
  > ReadTestExamplesString( str ) ____________________________________function
  Returns:  true or false
  
  > TestExamplesString( str[, print] ) _______________________________function
  Returns:  true or a list of records
  
  > TestManualExamples( [tree, ][path, main, files] ) ________________function
  Returns:  true or a list of records
  
  The argument str must be a string containing lines for the test mode of GAP.
  The function ReadTestExamplesString just runs ReadTest (Reference: ReadTest)
  on this code.
  
  The   function  TestExamplesString  returns  true  if  ReadTest  (Reference:
  ReadTest)  does not find differences. In the other case it returns a list of
  records, where each record describes one difference. The records have fields
  .line  with  the  line number of the relevant input line of str, .input with
  the  input  line  and  .diff  with  the differences as displayed by ReadTest
  (Reference:  ReadTest).  If  the optional argument print is given and set to
  true then the differences are also printed before the function returns.
  
  The arguments of the function TestManualExamples is either a parse tree of a
  GAPDoc  document  or the information to build and parse such a document. The
  function   extracts   all   examples   in   "Single"   units   and   applies
  TestExamplesString to them.
  
  ---------------------------  Example  ----------------------------
    gap> TestExamplesString("gap> 1+1;\n2\n");
    true
    gap> TestExamplesString("gap> 1+1;\n2\ngap> 2+3;\n4\n");
    [ rec( line := 3, input := "gap> 2+3;", diff := "+ 5\n- 4\n" ) ]
    gap> TestExamplesString("gap> 1+1;\n2\ngap> 2+3;\n4\n", true);
    -----------  bad example --------
    line: 3
    input: gap> 2+3;
    differences:
    + 5
    - 4
    [ rec( line := 3, input := "gap> 2+3;", diff := "+ 5\n- 4\n" ) ]
  ------------------------------------------------------------------