  
  [1X5. The Converters and an XML Parser[0X
  
  The  [5XGAPDoc[0X  package  contains a set of programs which allow us to convert a
  [5XGAPDoc[0X book into several output versions and to make them available to [5XGAP[0X's
  online help.
  
  Currently  the  following  output  formats  are  provided: text for browsing
  inside  a  terminal  running  [5XGAP[0X,  LaTeX  with  [10Xhyperref[0X-package  for cross
  references via hyperlinks and HTML for reading with a Web-browser.
  
  
  [1X5.1 Producing Documentation from Source Files[0X
  
  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 [11XMyBook.xml[0X
  of  a  book [10X"MyBook"[0X in the directory [11X/my/book/path[0X. This contains [10X<#Include
  ...>[0X-statements  as explained in Chapter [14X4.[0X. These refer to some other files
  as well as pieces of text which are found in the comments of some [5XGAP[0X source
  files  [11X../lib/a.gd[0X  and  [11X../lib/b.gi[0X  (relative to the path above). A BibTeX
  database  [11XMyBook.bib[0X for the citations is also in the directory given above.
  We  want to produce a text-, [10Xpdf-[0X and HTML-version of the document. (A LaTeX
  version  of  the manual is produced, so it is also easy to compile [10Xdvi[0X-, and
  postscript-versions.)
  
  All  the commands shown in this Section are collected in the single function
  [2XMakeGAPDocDoc[0X ([14X5.1-1[0X).
  
  First   we   construct   the   complete   XML-document   as  a  string  with
  [2XComposedDocument[0X   ([14X4.2-1[0X).   This   interprets  recursively  the  [10X<#Include
  ...>[0X-statements.
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4Xgap> path := Directory("/my/book/path");;[0X
    [4Xgap> main := "MyBook.xml";;[0X
    [4Xgap> files := ["../lib/a.gd", "../lib/b.gi"];;[0X
    [4Xgap> bookname := "MyBook";;[0X
    [4Xgap> doc := ComposedDocument("GAPDoc", path, main, files, true);;[0X
  [4X------------------------------------------------------------------[0X
  
  Now  [10Xdoc[0X  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  [2XParseTreeXMLString[0X  ([14X5.2-1[0X)  and
  [2XCheckAndCleanGapDocTree[0X ([14X5.2-8[0X).
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4Xgap> r := ParseTreeXMLString(doc[1], doc[2]);;[0X
    [4Xgap> CheckAndCleanGapDocTree(r);[0X
    [4Xtrue[0X
  [4X------------------------------------------------------------------[0X
  
  We  start  to  produce  a text version of the manual, which can be read in a
  terminal  (window).  The  command  is  [2XGAPDoc2Text[0X  ([14X5.3-2[0X). This produces a
  record with the actual text and some additional information. The text can be
  written  chapter-wise into files with [2XGAPDoc2TextPrintTextFiles[0X ([14X5.3-3[0X). The
  names  of  these files are [11Xchap0.txt[0X, [11Xchap1.txt[0X and so on. The text contains
  some  markup  using ANSI escape sequences. This markup is substituted by the
  [5XGAP[0X  help  system (user configurable) to show the text with colors and other
  attributes.  For  the  bibliography  we have to tell [2XGAPDoc2Text[0X ([14X5.3-2[0X) the
  location of the BibTeX database by specifying a [10Xpath[0X as second argument.
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4Xgap> t := GAPDoc2Text(r, path);;[0X
    [4Xgap> GAPDoc2TextPrintTextFiles(t, path);[0X
  [4X------------------------------------------------------------------[0X
  
  This  command  constructs  all  parts  of  the  document  including table of
  contents,  bibliography and index. The functions [2XFormatParagraph[0X ([14X6.1-3[0X) for
  formatting  text  paragraphs  and  [2XParseBibFiles[0X  ([14X7.1-1[0X) for reading BibTeX
  files with [5XGAP[0X may be of independent interest.
  
  With  the  text  version we have also produced the information which is used
  for searching with [5XGAP[0X's online help. Also, labels are produced which can be
  used by links in the HTML- and [10Xpdf[0X-versions of the manual.
  
  Next  we  produce  a  LaTeX  version  of  the document. [2XGAPDoc2LaTeX[0X ([14X5.3-1[0X)
  returns   a  string  containing  the  LaTeX  source.  The  utility  function
  [2XFileString[0X  ([14X6.3-5[0X)  writes  the  content  of  a string to a file, we choose
  [11XMyBook.tex[0X.
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4Xgap> l := GAPDoc2LaTeX(r);;[0X
    [4Xgap> FileString(Filename(path, Concatenation(bookname, ".tex")), l);[0X
  [4X------------------------------------------------------------------[0X
  
  Assuming  that  you  have  a sufficiently good installation of TeX available
  (see  [2XGAPDoc2LaTeX[0X  ([14X5.3-1[0X) for details) this can be processed with a series
  of commands like in the following example.
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4Xcd /my/book/path[0X
    [4Xpdflatex MyBook[0X
    [4Xbibtex MyBook[0X
    [4Xpdflatex MyBook[0X
    [4Xmakeindex MyBook[0X
    [4Xpdflatex MyBook[0X
    [4Xmv MyBook.pdf manual.pdf[0X
  [4X------------------------------------------------------------------[0X
  
  After  this we have a [10Xpdf[0X-version of the document in the file [11Xmanual.pdf[0X. It
  contains  hyperlink  information which can be used with appropriate browsers
  for convenient reading of the document on screen (e.g., [10Xxpdf[0X is nice because
  it  allows  remote  calls  to  display  named locations of the document). Of
  course,  we could also use other commands like [10Xlatex[0X or [10Xdvips[0X to process the
  LaTeX  source  file. Furthermore we have produced a file [11XMyBook.pnr[0X which is
  [5XGAP[0X-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 [11Xmanual.six[0X file which is
  read by [5XGAP[0X when the manual is loaded. This is done with [2XAddPageNumbersToSix[0X
  ([14X5.3-4[0X) and [2XPrintSixFile[0X ([14X5.3-5[0X).
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4Xgap> AddPageNumbersToSix(r, Filename(path, "MyBook.pnr"));[0X
    [4Xgap> PrintSixFile(Filename(path, "manual.six"), r, bookname);[0X
  [4X------------------------------------------------------------------[0X
  
  Finally   we   produce   an  HTML-version  of  the  document  and  write  it
  (chapter-wise) into files [11Xchap0.html[0X, [11Xchap1.html[0X and so on. They can be read
  with   any   Web-browser.   The   commands   are   [2XGAPDoc2HTML[0X  ([14X5.3-7[0X)  and
  [2XGAPDoc2HTMLPrintHTMLFiles[0X  ([14X5.3-8[0X).  We  also add a link from [11Xmanual.html[0X to
  [11Xchap0.html[0X.   You   probably   want   to   add   a   file   [11Xmanual.css[0X,  see
  [2XGAPDoc2HTMLPrintHTMLFiles[0X  ([14X5.3-8[0X)  for  more  details. The argument [10Xpath[0X of
  [2XGAPDoc2HTML[0X  ([14X5.3-7[0X)  specifies the directory containing the BibTeX database
  files.
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4Xgap> h := GAPDoc2HTML(r, path);;[0X
    [4Xgap> GAPDoc2HTMLPrintHTMLFiles(h, path);[0X
  [4X------------------------------------------------------------------[0X
  
  [1X5.1-1 MakeGAPDocDoc[0X
  
  [2X> MakeGAPDocDoc( [0X[3Xpath, main, files, bookname[, gaproot][0X[2X ) __________[0Xfunction
  
  This  function  collects  all  the  commands for producing a text-, [10Xpdf[0X- and
  HTML-version of a [5XGAPDoc[0X document as described in Section [14X5.1[0X. It checks the
  [10X.log[0X  file  from  the  call  of  [10Xpdflatex[0X  and  reports if there are errors,
  warnings or overfull boxes.
  
  [13XNote:[0X  If  this  function works for you depends on your operating system and
  installed  software.  It  will  probably  work  on  most [10XUNIX[0X 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  [3Xpath[0X  must be the directory (as string or directory object) containing
  the  main  file  [3Xmain[0X  of  the  document  (given  with  or  without the [10X.xml[0X
  extension.  The  argument  [3Xfiles[0X  is  a list of (probably source code) files
  relative  to  [3Xpath[0X  which  contain  pieces  of  documentation  which must be
  included  in  the  document, see Chapter [14X4.[0X. And [3Xbookname[0X is the name of the
  book  used  by  [5XGAP[0X's  online  help. The optional argument [3Xgaproot[0X must be a
  string  which  gives  the  relative  path  from  [3Xpath[0X  to  the main [5XGAP[0X root
  directory. If this is given, the HTML files are produced with relative paths
  to external books.
  
  Experimental:  [2XMakeGAPDocDoc[0X  can  be called with additional arguments [10X"Tth"[0X
  and/or  [10X"MathML"[0X.  If  these  are  given  additional  variants  of  the HTML
  conversion are called, see [2XGAPDoc2HTML[0X ([14X5.3-7[0X) for details.
  
  
  [1X5.2 Parsing XML Documents[0X
  
  Arbitrary  well-formed  XML  documents  can  be  parsed  and  browsed by the
  following functions.
  
  [1X5.2-1 ParseTreeXMLString[0X
  
  [2X> ParseTreeXMLString( [0X[3Xstr[, srcinfo][, entitydict][0X[2X ) _______________[0Xfunction
  [2X> ParseTreeXMLFile( [0X[3Xfname[, entitydict][0X[2X ) __________________________[0Xfunction
  [6XReturns:[0X  a record which is root of a tree structure
  
  The  first  function parses an XML-document stored in string [3Xstr[0X and returns
  the document in form of a tree.
  
  The   optional   argument   [3Xsrcinfo[0X   must   have  the  same  format  as  in
  [2XOriginalPositionDocument[0X  ([14X4.2-2[0X).  If it is given then error messages refer
  to the original source of the text with the problem.
  
  With  the  optional  argument  [3Xentitydict[0X named entities can be given to the
  parser,  for  example  entities which are defined in the [10X.dtd[0X-file (which is
  not  read  by  this  parser).  The  standard  XML-entities do not need to be
  provided,  and  for  [5XGAPDoc[0X documents the entity definitions from [10Xgapdoc.dtd[0X
  are  automatically provided. Entities in the documents [10X<!DOCTYPE[0X declaration
  are  parsed  and  also need not to be provided here. The argument [3Xentitydict[0X
  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  [10XParseTreeXMLString(
  StringFile([0X[3Xfname[0X[10X), ... )[0X, see [2XStringFile[0X ([14X6.3-5[0X).
  
  After  these  functions  return  the list of named entities which were known
  during the parsing can be found in the record [10XENTITYDICT[0X.
  
  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:
  
  [4X-------------------------  Example Node  -------------------------[0X
    [4Xrec( name := "Book",[0X
    [4X     attributes := rec( Name := "EDIM" ),[0X
    [4X     content := [ ... list of nodes for content ...],[0X
    [4X     start := 312,[0X
    [4X     stop := 15610,[0X
    [4X     next := 15611     )[0X
  [4X------------------------------------------------------------------[0X
  
  This  means that [10X[3Xstr[0X{[312..15610]}[0X looks like [10X<Book Name="EDIM"> ... content
  ... </Book>[0X.
  
  The  leaves  of  the  tree  encode parsed character data as in the following
  example:
  
  [4X-------------------------  Example Node  -------------------------[0X
    [4Xrec( name := "PCDATA", [0X
    [4X     content := "text without markup "     )[0X
  [4X------------------------------------------------------------------[0X
  
  This function checks whether the XML document is [13Xwell formed[0X, see [14X2.1-14[0X 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  [10XShow();[0X  one  can  browse  the original input in the [2XPager[0X ([14XReference:
  Pager[0X),  starting  with  the line where the error occurred. All entities are
  resolved  when  they  are  either entities defined in the [5XGAPDoc[0X package (in
  particular  the standard XML entities) or if their definition is included in
  the [10X<!DOCTYPE ..>[0X tag of the document.
  
  Note  that [2XParseTreeXMLString[0X does not parse and interpret the corresponding
  document  type  definition  (the  [10X.dtd[0X-file given in the [10X<!DOCTYPE ..>[0X tag).
  Hence  it  also  does not check the [13Xvalidity[0X of the document (i.e., it is no
  [13Xvalidating XML parser[0X).
  
  If  you  are  using  this  function  to  parse a [5XGAPDoc[0X document you can use
  [2XCheckAndCleanGapDocTree[0X  ([14X5.2-8[0X) for some validation and additional checking
  of the document structure.
  
  [1X5.2-2 StringXMLElement[0X
  
  [2X> StringXMLElement( [0X[3Xtree[0X[2X ) _________________________________________[0Xfunction
  [6XReturns:[0X  a list [10X[string, positions][0X
  
  The  argument  [3Xtree[0X must have a format of a node in the parse tree of an XML
  document  as returned by [2XParseTreeXMLString[0X ([14X5.2-1[0X) (including the root node
  representing  the  full  document).  This  function computes a pair [10X[string,
  positions][0X  where  [10Xstring[0X  contains XML code which is equivalent to the code
  which  was  parsed  to  get  [3Xtree[0X.  And [10Xpositions[0X is a list of lists of four
  numbers  [10X[eltb,  elte,  contb,  conte][0X.  There is one such list for each XML
  element  occuring  in  [10Xstring[0X,  where  [10Xeltb[0X  and  [10Xelte[0X are the begin and end
  position  of  this element in [10Xstring[0X and where [10Xcontb[0X and [10Xconte[0X are begin and
  end  position  of  the content of this element, or both are [10X0[0X 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 [10Xstring[0X
  again  and  applying  [2XStringXMLElement[0X  again gives the same result. See the
  function  [2XEntitySubstitution[0X  ([14X5.2-3[0X)  for back-substitutions of entities in
  the result.
  
  [1X5.2-3 EntitySubstitution[0X
  
  [2X> EntitySubstitution( [0X[3Xxmlstring, entities[0X[2X ) ________________________[0Xfunction
  [6XReturns:[0X  a string
  
  The  argument  [3Xxmlstring[0X  must  be  a  string  containing XML code or a pair
  [10X[string,  positions][0X  as  returned by [2XStringXMLElement[0X ([14X5.2-2[0X). The argument
  [3Xentities[0X  specifies entity names (without the surrounding [3X&[0X and [10X;[0X) 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 [10Xstring[0X by the
  given entities. If the [10Xpositions[0X 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.
  
  [1X5.2-4 DisplayXMLStructure[0X
  
  [2X> DisplayXMLStructure( [0X[3Xtree[0X[2X ) ______________________________________[0Xfunction
  
  This  utility  displays  the  tree  structure  of  an  XML document as it is
  returned by [2XParseTreeXMLString[0X ([14X5.2-1[0X) (without the [10XPCDATA[0X leaves).
  
  Since  this  is  usually  quite  long  the  result  is shown using the [2XPager[0X
  ([14XReference: Pager[0X).
  
  [1X5.2-5 ApplyToNodesParseTree[0X
  
  [2X> ApplyToNodesParseTree( [0X[3Xtree, fun[0X[2X ) _______________________________[0Xfunction
  [2X> AddRootParseTree( [0X[3Xtree[0X[2X ) _________________________________________[0Xfunction
  [2X> RemoveRootParseTree( [0X[3Xtree[0X[2X ) ______________________________________[0Xfunction
  
  The  function  [2XApplyToNodesParseTree[0X  applies a function [3Xfun[0X to all nodes of
  the  parse  tree  [3Xtree[0X  of  an  XML  document returned by [2XParseTreeXMLString[0X
  ([14X5.2-1[0X).
  
  The  function  [2XAddRootParseTree[0X  is  an  application of this. It adds to all
  nodes  a  component [10X.root[0X to which the top node tree [3Xtree[0X is assigned. These
  components can be removed afterwards with [2XRemoveRootParseTree[0X.
  
  Here are two more utilities which use [2XApplyToNodesParseTree[0X.
  
  [1X5.2-6 GetTextXMLTree[0X
  
  [2X> GetTextXMLTree( [0X[3Xtree[0X[2X ) ___________________________________________[0Xfunction
  [6XReturns:[0X  a string
  
  The  argument  [3Xtree[0X must be a node of a parse tree of some XML document, see
  [2XParseTreeXMLFile[0X ([14X5.2-1[0X). This function collects the content of this and all
  included elements recursively into a string.
  
  [1X5.2-7 XMLElements[0X
  
  [2X> XMLElements( [0X[3Xtree, eltnames[0X[2X ) ____________________________________[0Xfunction
  [6XReturns:[0X  a list of nodes
  
  The  argument  [3Xtree[0X must be a node of a parse tree of some XML document, see
  [2XParseTreeXMLFile[0X  ([14X5.2-1[0X).  This  function returns a list of all subnodes of
  [3Xtree[0X  (possibly  including  [3Xtree[0X) of elements with name given in the list of
  strings  [3Xeltnames[0X.  Use  [10X"PCDATA"[0X  as name for leave nodes which contain the
  actual  text  of  the  document.  As  an abbreviation [3Xeltnames[0X can also be a
  string which is then put in a one element list.
  
  And here are utilities for processing [5XGAPDoc[0X XML documents.
  
  [1X5.2-8 CheckAndCleanGapDocTree[0X
  
  [2X> CheckAndCleanGapDocTree( [0X[3Xtree[0X[2X ) __________________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  The  argument  [3Xtree[0X of this function is a parse tree from [2XParseTreeXMLString[0X
  ([14X5.2-1[0X) of some [5XGAPDoc[0X document. This function does an (incomplete) validity
  check  of  the  document  according  to  the  document  type  declaration in
  [11Xgapdoc.dtd[0X. 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 [10XShow();[0X one can browse the
  original input in the [2XPager[0X ([14XReference: Pager[0X).
  
  [1X5.2-9 AddParagraphNumbersGapDocTree[0X
  
  [2X> AddParagraphNumbersGapDocTree( [0X[3Xtree[0X[2X ) ____________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  The argument [3Xtree[0X must be an XML tree returned by [2XParseTreeXMLString[0X ([14X5.2-1[0X)
  applied  to a [5XGAPDoc[0X document. This function adds to each node of the tree a
  component   [10X.count[0X   which  is  of  form  [10X[Chapter[,  Section[,  Subsection,
  Paragraph]  ] ][0X. 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  [10X0[0X  and  similarly  for  sections and subsections. Some
  elements are always considered to start a new paragraph.
  
  [1X5.2-10 InfoXMLParser[0X
  
  [2X> InfoXMLParser___________________________________________________[0Xinfo class
  
  The default level of this info class is 1. Functions like [2XParseTreeXMLString[0X
  ([14X5.2-1[0X) are then printing some information, in particular in case of errors.
  You can suppress it by setting the level of [2XInfoXMLParser[0X to 0. With level 2
  there may be some more information for debugging purposes.
  
  
  [1X5.3 The Converters[0X
  
  Here  are  more  details  about  the  conversion  programs  for  [5XGAPDoc[0X  XML
  documents.
  
  [1X5.3-1 GAPDoc2LaTeX[0X
  
  [2X> GAPDoc2LaTeX( [0X[3Xtree[0X[2X ) _____________________________________________[0Xfunction
  [6XReturns:[0X  LaTeX document as string
  
  The  argument  [3Xtree[0X  for  this  function  is  a tree describing a [5XGAPDoc[0X XML
  document  as  returned  by [2XParseTreeXMLString[0X ([14X5.2-1[0X) (probably also checked
  with  [2XCheckAndCleanGapDocTree[0X  ([14X5.2-8[0X)). 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 [10Xmakeindex[0X).
  
  The  output  uses  the  [10Xreport[0X  document class and needs the following LaTeX
  packages:  [10Xa4wide[0X, [10Xamssymb[0X, [10Xisolatin1[0X, [10Xmakeidx[0X, [10Xcolor[0X, [10Xfancyvrb[0X, [10Xpslatex[0X and
  [10Xhyperref[0X.  These  are  for example provided by the [5XteTeX-1.0[0X distribution of
  TeX  (which  in  turn  is  used  for  most  TeX  packages  of  current Linux
  distributions); see [7Xhttp://www.tug.org/tetex/[0X.
  
  In  particular, the resulting [10Xpdf[0X-output (and [10Xdvi[0X-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 [10X.pnr[0X which is [5XGAP[0X
  readable  and  contains  the  page  numbers  for  all  (sub)sections  of the
  document.  This  can  be  used by [5XGAP[0X's online help; see [2XAddPageNumbersToSix[0X
  ([14X5.3-4[0X). There is support for two types or 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:
  
  [4X-----------------  in top level of XML document  -----------------[0X
    [4X<?LaTeX Options="12pt"?>[0X
    [4X<?LaTeX ExtraPreamble="\usepackage{blabla}[0X
    [4X\newcommand{\bla}{blabla}[0X
    [4X"?>[0X
  [4X------------------------------------------------------------------[0X
  
  Non-ASCII characters in the [5XGAPDoc[0X document are translated to LaTeX input in
  ASCII-encoding  with  the help of [2XEncode[0X ([14X6.2-2[0X) and the option [10X"LaTeX"[0X. See
  the  documentation  of  [2XEncode[0X  ([14X6.2-2[0X)  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 [5XteTeX[0X you can look for a file [11Xtexmf.cnf[0X which allows
  to enlarge certain memory sizes.
  
  This  function  works  by  running recursively through the document tree and
  calling  a  handler  function  for  each  [5XGAPDoc[0X  XML element. Many of these
  handler  functions  (usually  in  [10XGAPDoc2LaTeXProcs.<ElementName>[0X)  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 a function [10XSetGapDocLaTeXOptions[0X. It takes
  one  or  several  strings  as arguments. If the arguments contain one of the
  strings  [10X"pdf"[0X, [10X"dvi"[0X or [10X"ps"[0X then LaTeXs [10Xhyperref[0X package is configured for
  optimized  output  of  the  given  format  (default is [10X"pdf"[0X). If [10X"color"[0X or
  [10X"nocolor"[0X  is  in  the  argument  list  then  colors  are  used or not used,
  respectively. The default is to use colors but [10X"nocolor"[0X can be useful for a
  printable version of a manual (but who wants to print such manuals?).
  
  [1X5.3-2 GAPDoc2Text[0X
  
  [2X> GAPDoc2Text( [0X[3Xtree[, bibpath][, width][0X[2X ) __________________________[0Xfunction
  [6XReturns:[0X  record containing text files as strings and other information
  
  The  argument  [3Xtree[0X  for  this  function  is  a tree describing a [5XGAPDoc[0X XML
  document  as  returned  by [2XParseTreeXMLString[0X ([14X5.2-1[0X) (probably also checked
  with [2XCheckAndCleanGapDocTree[0X ([14X5.2-8[0X)). This function produces a text version
  of  the document which can be used with [5XGAP[0X's online help (with the [10X"screen"[0X
  viewer,  see  [2XSetHelpViewer[0X  ([14XReference:  SetHelpViewer[0X)). It includes title
  page,  bibliography  and  index.  The bibliography is made from BibXMLext or
  BibTeX  databases,  see  [14X7.[0X.  Their location must be given with the argument
  [3Xbibpath[0X (as string or directory object).
  
  The  output is a record with one component for each chapter (with names [10X"0"[0X,
  [10X"1"[0X,  ...,  [10X"Bib"[0X and [10X"Ind"[0X). Each such component is again a record with the
  following components:
  
  [8X[10Xtext[0X[0X
        the text of the whole chapter as a string
  
  [8X[10Xssnr[0X[0X
        list  of  subsection  numbers  in  this  chapter  (like  [10X[3, 2, 1][0X for
        chapter 3, section 2, subsection 1)
  
  [8X[10Xlinenr[0X[0X
        corresponding list of line numbers where the subsections start
  
  [8X[10Xlen[0X[0X
        number of lines of this chapter
  
  The    result    can    be    written    into   files   with   the   command
  [2XGAPDoc2TextPrintTextFiles[0X ([14X5.3-3[0X).
  
  As  a  side  effect  this  function also produces the [11Xmanual.six[0X information
  which is used for searching in [5XGAP[0X's online help. This is stored in [10X[3Xtree[0X.six[0X
  and  can  be  printed  into  a  [11Xmanual.six[0X  file  with  [2XPrintSixFile[0X ([14X5.3-5[0X)
  (preferably  after  producing  a  LaTeX  version of the document as well and
  adding the page number information to [10X[3Xtree[0X.six[0X, see [2XGAPDoc2LaTeX[0X ([14X5.3-1[0X) and
  [2XAddPageNumbersToSix[0X ([14X5.3-4[0X)).
  
  The  text  produced  by  this  function contains some markup via ANSI escape
  sequences. The sequences used here are usually ignored by terminals. But the
  [5XGAP[0X  help  system  will  substitute  them by interpreted color and attribute
  sequences  (see [2XTextAttr[0X ([14X6.1-2[0X)) before displaying them. There is a default
  markup  used  for  this  but  it  can  also  be  configured by the user, see
  [2XSetGAPDocTextTheme[0X  ([14X5.3-6[0X).  Furthermore,  the  text  produced  is in UTF-8
  encoding.    The    encoding   is   also   translated   on   the   fly,   if
  [10XGAPInfo.TermEncoding[0X  is  set  to some encoding supported by [2XEncode[0X ([14X6.2-2[0X),
  e.g., [10X"ISO-8859-1"[0X or [10X"latin1"[0X.
  
  With the optional argument [3Xwidth[0X 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.
  
  [1X5.3-3 GAPDoc2TextPrintTextFiles[0X
  
  [2X> GAPDoc2TextPrintTextFiles( [0X[3Xt[, path][0X[2X ) ___________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  The  first  argument  must  be a result returned by [2XGAPDoc2Text[0X ([14X5.3-2[0X). 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 [11Xchap0.txt[0X, [11Xchap1.txt[0X, ..., [11XchapBib.txt[0X, and [11XchapInd.txt[0X.
  
  If  you  want  to  make your document accessible via the [5XGAP[0X online help you
  must  put  at  least  these  files  for  the  text version into a directory,
  together  with  the  file [11Xmanual.six[0X, see [2XPrintSixFile[0X ([14X5.3-5[0X). Then specify
  the  path  to  the  [11Xmanual.six[0X  file in the packages [11XPackageInfo.g[0X file, see
  [14X'Extending: The PackageInfo.g File'[0X.
  
  Optionally  you  can add the [10Xdvi[0X- and [10Xpdf[0X-versions of the document which are
  produced  with  [2XGAPDoc2LaTeX[0X  ([14X5.3-1[0X) to this directory. The files must have
  the  names  [11Xmanual.dvi[0X  and  [11Xmanual.pdf[0X,  respectively. Also you can add the
  files  of  the  HTML  version  produced  with  [2XGAPDoc2HTML[0X  ([14X5.3-7[0X)  to this
  directory,  see  [2XGAPDoc2HTMLPrintHTMLFiles[0X ([14X5.3-8[0X). The handler functions in
  [5XGAP[0X  for this help format detect automatically which of the optional formats
  of a book are actually available.
  
  [1X5.3-4 AddPageNumbersToSix[0X
  
  [2X> AddPageNumbersToSix( [0X[3Xtree, pnrfile[0X[2X ) _____________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  Here  [3Xtree[0X  must  be  the  XML  tree  of  a  [5XGAPDoc[0X  document,  returned  by
  [2XParseTreeXMLString[0X  ([14X5.2-1[0X).  Running  [10Xlatex[0X  on  the result of [2XGAPDoc2LaTeX[0X
  ([14X5.3-1[0X)[10X([3Xtree[0X)[0X  produces  a  file  [3Xpnrfile[0X (with extension [10X.pnr[0X). The command
  [2XGAPDoc2Text[0X  ([14X5.3-2[0X)[10X([3Xtree[0X)[0X  creates  a component [10X[3Xtree[0X.six[0X which contains all
  information  about  the  document  for  the [5XGAP[0X online help, except the page
  numbers  in  the [10X.dvi, .ps, .pdf[0X versions of the document. This command adds
  the missing page number information to [10X[3Xtree[0X.six[0X.
  
  [1X5.3-5 PrintSixFile[0X
  
  [2X> PrintSixFile( [0X[3Xtree, bookname, fname[0X[2X ) ____________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  This  function  prints  the  [10X.six[0X file [3Xfname[0X for a [5XGAPDoc[0X document stored in
  [3Xtree[0X with name [3Xbookname[0X. Such a file contains all information about the book
  which  is  needed  by  the  [5XGAP[0X  online help. This information must first be
  created by calls of [2XGAPDoc2Text[0X ([14X5.3-2[0X) and [2XAddPageNumbersToSix[0X ([14X5.3-4[0X).
  
  [1X5.3-6 SetGAPDocTextTheme[0X
  
  [2X> SetGAPDocTextTheme( [0X[3X[optrec][0X[2X ) ___________________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  With  this  function  can readers of the screen version of [5XGAP[0X manuals which
  are generated by the [5XGAPDoc[0X 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 [3Xoptrec[0X can be a string for the known name of
  a  theme. Currently, there is only [10X"none"[0X which displays just the plain text
  without any markup.
  
  Otherwise,  [3Xoptrec[0X must be a record. Its entries overwrite the corresponding
  entries  in  the  default.  To  construct  valid markup you can use [2XTextAttr[0X
  ([14X6.1-2[0X). The following components are recognized:
  
  [8X[10Xreset[0X[0X
        reset to default, don't change this
  
  [8X[10XHeading[0X[0X
        chapter and (sub-)section headings
  
  [8X[10XFunc[0X[0X
        function, operation, ... names
  
  [8X[10XArg[0X[0X
        argument names in descriptions
  
  [8X[10XExample[0X[0X
        example code
  
  [8X[10XPackage[0X[0X
        package names
  
  [8X[10XReturns[0X[0X
        Returns-line in descriptions
  
  [8X[10XURL[0X[0X
        URLs
  
  [8X[10XMark[0X[0X
        Marks in description lists
  
  [8X[10XK[0X[0X
        [5XGAP[0X keywords
  
  [8X[10XC[0X[0X
        code or text to type
  
  [8X[10XF[0X[0X
        file names
  
  [8X[10XB[0X[0X
        buttons
  
  [8X[10XEmph[0X[0X
        emphasized text
  
  [8X[10XRef[0X[0X
        reference text
  
  [8X[10XBibReset[0X[0X
        reset for bibliography, don't change
  
  [8X[10XBibAuthor[0X[0X
        author names in bibliography
  
  [8X[10XBibTitle[0X[0X
        titles in bibliography
  
  [8X[10XBibJournal[0X[0X
        journal names in bibliography
  
  [8X[10XBibVolume[0X[0X
        volume number in bibliography
  
  [8X[10XBibLabel[0X[0X
        labels for bibliography entries
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> # change display of headings to bold green[0X
    [4Xgap> SetGAPDocTextTheme(rec([0X
    [4X>              Heading:=Concatenation(TextAttr.bold, TextAttr.2)));[0X
  [4X------------------------------------------------------------------[0X
  
  [1X5.3-7 GAPDoc2HTML[0X
  
  [2X> GAPDoc2HTML( [0X[3Xtree[, bibpath[, gaproot]][, mtrans][0X[2X ) ______________[0Xfunction
  [6XReturns:[0X  record containing HTML files as strings and other information
  
  The  argument  [3Xtree[0X  for  this  function  is  a tree describing a [5XGAPDoc[0X XML
  document  as  returned  by [2XParseTreeXMLString[0X ([14X5.2-1[0X) (probably also checked
  with  [2XCheckAndCleanGapDocTree[0X  ([14X5.2-8[0X)).  Without  an  [3Xmtrans[0X  argument this
  function produces an HTML version of the document which can be read with any
  Web-browser  and  also  be  used  with  [5XGAP[0X's online help (see [2XSetHelpViewer[0X
  ([14XReference:  SetHelpViewer[0X)).  It  includes  title  page,  bibliography, and
  index.  The  bibliography is made from BibTeX databases. Their location must
  be  given  with  the argument [3Xbibpath[0X (as string or directory object, if not
  given the current directory is used). If the third argument [3Xgaproot[0X is given
  and  is  a  string then this string is interpreted as relative path to [5XGAP[0X's
  main  root directory. Reference-URLs to external HTML-books which begin with
  the  [5XGAP[0X 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 [5XGAP[0X root.
  
  The  output is a record with one component for each chapter (with names [10X"0"[0X,
  [10X"1"[0X,  ..., [10X"Bib"[0X, and [10X"Ind"[0X). Each such component is again a record with the
  following components:
  
  [8X[10Xtext[0X[0X
        the text of an HTML file containing the whole chapter (as a string)
  
  [8X[10Xssnr[0X[0X
        list  of  subsection  numbers  in  this  chapter  (like  [10X[3, 2, 1][0X for
        chapter 3, section 2, subsection 1)
  
  [13XStandard output format without[0X [3Xmtrans[0X [13Xargument[0X
  
  The HTML code produced with this converter conforms to the W3C specification
  "XHTML  1.0 strict", see [7Xhttp://www.w3.org/TR/xhtml1[0X. 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 [2XGAPDoc2Text[0X
  ([14X5.3-2[0X). We don't want to assume that the browser can use symbol fonts. Some
  [5XGAP[0X  users  like  to  browse  the  online  help with [10Xlynx[0X, see [2XSetHelpViewer[0X
  ([14XReference:  SetHelpViewer[0X),  which runs inside the same terminal windows as
  [5XGAP[0X.
  
  [13XUsing a stylesheet file[0X
  
  The  layout  information  for  a  browser should be specified in a cascading
  style  sheet  (CSS)  file.  The [5XGAPDoc[0X package contains an example of such a
  style  sheet,  see the file [11Xgapdoc.css[0X in the root directory of the package.
  This    file    conforms   to   the   W3C   specification   CSS   2.0,   see
  [7Xhttp://www.w3.org/TR/REC-CSS2[0X.  You  may  just  copy that file as [11Xmanual.css[0X
  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 [11Xmanual.css[0X.
  
  [13XOutput format with[0X [3Xmtrans[0X argument
  
  Currently,  there  are two experimental variants of this converter available
  which  handle  mathematical  formulae differently. They are accessed via the
  optional last [3Xmtrans[0X argument.
  
  If  this  argument is set to [10X"Tth"[0X it is assumed that you have installed the
  LaTeX  to  HTML  translation  program  [10Xtth[0X.  This  is  used to translate the
  contents  of  the [10XM[0X, [10XMath[0X and [10XDisplay[0X 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 ([7Xhttp://hutchinson.belmont.ma.us/tth/[0X) for
  more details.
  
  If  the  [3Xmtrans[0X  argument  is  set  to  [10X"MathML"[0X it is assumed that you have
  installed   the   translation   program  [10Xttm[0X,  see  also  the  Tth  homepage
  ([7Xhttp://hutchinson.belmont.ma.us/tth/[0X)).  This  is  used  to  translate  the
  contents  of  the  [10XM[0X,  [10XMath[0X  and  [10XDisplay[0X 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 ([7Xhttp://www.w3.org/TR/MathML2/[0X) for more details. It
  is  expected  that the next generation of graphical browsers will be able to
  render  such  files (try for example [10XMozilla[0X, at least 0.9.9). You must copy
  the  [10X.xsl[0X  and  [10X.css[0X  files  from  [5XGAPDoc[0Xs [11Xmathml[0X directory to the directory
  containing the output files. The translation with [10Xttm[0X 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  [5XGAPDoc[0X  XML element. Many of these
  handler   functions  (usually  in  [10XGAPDoc2TextProcs.<ElementName>[0X)  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
  [2XGAPDoc2HTMLPrintHTMLFiles[0X ([14X5.3-8[0X).
  
  [1X5.3-8 GAPDoc2HTMLPrintHTMLFiles[0X
  
  [2X> GAPDoc2HTMLPrintHTMLFiles( [0X[3Xt[, path][0X[2X ) ___________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  The  first  argument  must  be a result returned by [2XGAPDoc2HTML[0X ([14X5.3-7[0X). 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 [11Xchap0.html[0X, [11Xchap1.html[0X, ..., [11XchapBib.html[0X, and [11XchapInd.html[0X.
  
  The  experimental  versions which are produced with [10Xtth[0X or [10Xttm[0X use different
  names  for  the files, namely [11Xchap0_sym.html[0X, and so on for files which need
  symbol fonts and [11Xchap0_mml.xml[0X for files with MathML translations.
  
  You  may  also  want  to  place  a style sheet file [11Xmanual.css[0X into the same
  directory as the HTML files. You can copy for example the file [11Xgapdoc.css[0X in
  the  root directory of the [5XGAPDoc[0X package ([10XFilename( Directory( PackageInfo(
  "gapdoc" )[1].InstallationPath), "gapdoc.css");[0X).
  
  [1X5.3-9 InfoGAPDoc[0X
  
  [2X> InfoGAPDoc______________________________________________________[0Xinfo class
  
  The  default  level  of  this  info  class is 1. The converter functions for
  [5XGAPDoc[0X  documents  are then printing some information. You can suppress this
  by setting the level of [2XInfoGAPDoc[0X to 0. With level 2 there may be some more
  information for debugging purposes.
  
  
  [1X5.4 Testing Manual Examples[0X
  
  We   also   provide   some   tools   to   check   the   examples   given  in
  [10X<Example>[0X-elements.
  
  [1X5.4-1 ManualExamples[0X
  
  [2X> ManualExamples( [0X[3Xpath, main, files, units[0X[2X ) _______________________[0Xfunction
  [6XReturns:[0X  a list of strings
  
  [2X> ManualExamplesXMLTree( [0X[3Xtree, units[0X[2X ) _____________________________[0Xfunction
  [6XReturns:[0X  a list of strings
  
  The  argument  [3Xtree[0X  must  be  a  parse  tree  of  a  [5XGAPDoc[0X  document,  see
  [2XParseTreeXMLFile[0X  ([14X5.2-1[0X). The function [2XManualExamplesXMLTree[0X returns a list
  of  strings  containing  the content of [10X<Example>[0X 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 [3Xunits[0X several examples are colleected in one string. Recognized
  values  for  [3Xunits[0X  are  [10X"Chapter"[0X, [10X"Section"[0X, [10X"Subsection"[0X or [10X"Single"[0X. The
  latter  means that each example is in a separate string. For all other value
  of [3Xunits[0X just one string with all examples is returned.
  
  The  arguments  [3Xpath[0X,  [3Xmain[0X  and [3Xfiles[0X of [2XManualExamples[0X are the same as for
  [2XComposedDocument[0X  ([14X4.2-1[0X).  This  function  first  contructs  and parses the
  [5XGAPDoc[0X document and then applies [2XManualExamplesXMLTree[0X.
  
  [1X5.4-2 ReadTestExamplesString[0X
  
  [2X> ReadTestExamplesString( [0X[3Xstr[0X[2X ) ____________________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0X or [9Xfalse[0X
  
  [2X> TestExamplesString( [0X[3Xstr[, print][0X[2X ) _______________________________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0X or a list of records
  
  [2X> TestManualExamples( [0X[3X[tree][,][path, main, files][0X[2X ) _______________[0Xfunction
  [6XReturns:[0X  [9Xtrue[0X or a list of records
  
  The argument [3Xstr[0X must be a string containing lines for the test mode of [5XGAP[0X.
  The function [2XReadTestExamplesString[0X just runs [2XReadTest[0X ([14XReference: ReadTest[0X)
  on this code.
  
  The   function  [2XTestExamplesString[0X  returns  [9Xtrue[0X  if  [2XReadTest[0X  ([14XReference:
  ReadTest[0X)  does not find differences. In the other case it returns a list of
  record,  where  each record describes one difference. The record have fields
  [10X.line[0X  with  the  line number of the relevant input line of [3Xstr[0X, [10X.input[0X with
  the  input  line  and  [10X.diff[0X  with  the differences as displayed by [2XReadTest[0X
  ([14XReference:  ReadTest[0X).  If  the optional argument [3Xprint[0X is given and set to
  [9Xtrue[0X then the differences are also printed before the function returns.
  
  The arguments of the function [2XTestManualExamples[0X is either a parse tree of a
  [5XGAPDoc[0X  document  or the information to build and parse such a document. The
  function   extracts   all   examples   in   [10X"Single"[0X   units   and   applies
  [2XTestExamplesString[0X to them.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> TestExamplesString("gap> 1+1;\n2\n");[0X
    [4Xtrue[0X
    [4Xgap> TestExamplesString("gap> 1+1;\n2\ngap> 2+3;\n4\n");[0X
    [4X[ rec( line := 3, input := "gap> 2+3;", diff := "+ 5\n- 4\n" ) ][0X
    [4Xgap> TestExamplesString("gap> 1+1;\n2\ngap> 2+3;\n4\n", true);[0X
    [4X-----------  bad example --------[0X
    [4Xline: 3[0X
    [4Xinput: gap> 2+3;[0X
    [4Xdifferences:[0X
    [4X+ 5[0X
    [4X- 4[0X
    [4X[ rec( line := 3, input := "gap> 2+3;", diff := "+ 5\n- 4\n" ) ][0X
  [4X------------------------------------------------------------------[0X
  
