  
  [1m[4m[31m5. The Converters[0m
  
  The  [1mGAPDoc[0m  package  contains a set of programs which allow us to convert a
  [1mGAPDoc[0m book into several output versions and to make them available to [1mGAP[0m's
  online help.
  
  Currently  the  following  output  formats  are  provided: text for browsing
  inside  a  terminal  running  [1mGAP[0m,  LaTeX  with  [22m[32mhyperref[0m-package  for cross
  references via hyperlinks and HTML for reading with a Web-browser.
  
  
  [1m[4m[31m5.1 Producing Documentation from Source Files[0m
  
  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 [1mMyBook.xml[0m
  of  a  book [22m[32m"MyBook"[0m in the directory [1m/my/book/path[0m. This contains [22m[32m<#Include
  ...>[0m-statements  as explained in Chapter [1m4.[0m. These refer to some other files
  as well as pieces of text which are found in the comments of some [1mGAP[0m source
  files  [1m../lib/a.gd[0m  and  [1m../lib/b.gi[0m  (relative to the path above). A BibTeX
  database  [1mMyBook.bib[0m for the citations is also in the directory given above.
  We  want to produce a text-, [22m[32mdvi[0m-, [22m[32mpdf-[0m, postscript- and HTML-version of the
  document.
  
  All  the commands shown in this Section are collected in the single function
  [1m[34mMakeGAPDocDoc[0m ([1m5.1-1[0m).
  
  First   we   construct   the   complete   XML-document   as  a  string  with
  [1m[34mComposedXMLString[0m   ([1m4.2-1[0m).   This  interprets  recursively  the  [22m[32m<#Include
  ...>[0m-statements.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> path := Directory("/my/book/path");;[0m
    [22m[35mgap> main := "MyBook.xml";;[0m
    [22m[35mgap> files := ["../lib/a.gd", "../lib/b.gi"];;[0m
    [22m[35mgap> bookname := "MyBook";;[0m
    [22m[35mgap> str := ComposedXMLString(path, main, files);;[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Then  we  parse  the  document  and  store its structure in a tree-like data
  structure.   The  commands  for  this  are  [1m[34mParseTreeXMLString[0m  ([1m5.2-1[0m)  and
  [1m[34mCheckAndCleanGapDocTree[0m ([1m5.2-4[0m).
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> r := ParseTreeXMLString(str);;[0m
    [22m[35mgap> CheckAndCleanGapDocTree(r);[0m
    [22m[35mtrue[0m
  [22m[35m------------------------------------------------------------------[0m
  
  We  first  produce  a  LaTeX  version  of the document. [1m[34mGAPDoc2LaTeX[0m ([1m5.3-1[0m)
  returns   a  string  containing  the  LaTeX  source.  The  utility  function
  [1m[34mFileString[0m  ([1m5.6-5[0m)  writes  the  content  of  a string to a file, we choose
  [1mMyBook.tex[0m.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> l := GAPDoc2LaTeX(r);;[0m
    [22m[35mgap> FileString(Filename(path, Concatenation(bookname, ".tex")), l);[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Assuming  that  you  have  a sufficiently good installation of TeX available
  (see  [1m[34mGAPDoc2LaTeX[0m  ([1m5.3-1[0m) for details) this can be processed with a series
  of commands like in the following example.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mcd /my/book/path[0m
    [22m[35mlatex MyBook[0m
    [22m[35mbibtex MyBook[0m
    [22m[35mlatex MyBook[0m
    [22m[35mmakeindex MyBook[0m
    [22m[35mlatex MyBook[0m
    [22m[35mmv MyBook.dvi manual.dvi[0m
    [22m[35mdvips -o manual.ps manual.dvi[0m
    [22m[35mrm MyBook.aux[0m
    [22m[35mpdflatex MyBook[0m
    [22m[35mpdflatex MyBook[0m
    [22m[35mmv MyBook.pdf manual.pdf[0m
  [22m[35m------------------------------------------------------------------[0m
  
  After  this  we  have a [22m[32mdvi[0m-, [22m[32mpdf[0m- and postscript version of the document in
  the  files  [1mmanual.dvi[0m,  [1mmanual.pdf[0m  and  [1mmanual.ps[0m.  The first two versions
  contain  hyperlink  information  which can be used with appropriate browsers
  for  convenient reading of the document on screen (e.g., current versions of
  [22m[32mxdvi[0m, respectively [22m[32mxpdf[0m or [22m[32macroread[0m.
  
  Furthermore  we  have  produced  a file [1mMyBook.pnr[0m which is [1mGAP[0m-readable and
  contains the page number information for each (sub-)section of the document.
  We will use this later.
  
  Next we produce a text version which can be read in a terminal (window). The
  command  is [1m[34mGAPDoc2Text[0m ([1m5.3-2[0m). This produces a record with the actual text
  and  some  additional information. The text can be written chapter wise into
  files  with  [1m[34mGAPDoc2TextPrintTextFiles[0m ([1m5.3-3[0m). The names of these files are
  [1mchap0.txt[0m,  [1mchap1.txt[0m  and  so on. The text contains some color markup using
  ANSI  escape  sequences.  One  can use this with a terminal which interprets
  these  sequences appropriately after setting the [1mGAP[0m variable [22m[32mANSI_COLORS[0m to
  [22m[32mtrue[0m.  For the bibliography we have to tell [1m[34mGAPDoc2Text[0m ([1m5.3-2[0m) the location
  of the BibTeX database by specifying a [22m[32mpath[0m as second argument.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> t := GAPDoc2Text(r, path);;[0m
    [22m[35mgap> GAPDoc2TextPrintTextFiles(t, path);[0m
  [22m[35m------------------------------------------------------------------[0m
  
  This  command  constructs  all  parts  of  the  document  including table of
  contents,  bibliography and index. The functions [1m[34mFormatParagraph[0m ([1m5.5-3[0m) for
  formatting  text  paragraphs  and  [1m[34mParseBibFiles[0m  ([1m5.4-1[0m) for reading BibTeX
  files with [1mGAP[0m may be of independent interest.
  
  With  the  text  version we have also produced the information which is used
  for searching with [1mGAP[0m's online help. We can add the page number information
  from  the  LaTeX  version  of  the document and then print a [1mmanual.six[0m file
  which  is  read  by  [1mGAP[0m  when  the  document  is  loaded. This is done with
  [1m[34mAddPageNumbersToSix[0m ([1m5.3-4[0m) and [1m[34mPrintSixFile[0m ([1m5.3-5[0m).
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> AddPageNumbersToSix(r, Filename(path, "MyBook.pnr"));[0m
    [22m[35mgap> PrintSixFile(Filename(path, "manual.six"), r, bookname);[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Finally   we   produce  an  HTML  version  of  the  document  and  write  it
  (chapter-wise) into files [1mchap0.html[0m, [1mchap1.html[0m and so on. They can be read
  with   any   Web-browser.   The   commands   are   [1m[34mGAPDoc2HTML[0m  ([1m5.3-6[0m)  and
  [1m[34mGAPDoc2HTMLPrintHTMLFiles[0m  ([1m5.3-7[0m).  We  also add a link from [1mmanual.html[0m to
  [1mchap0.html[0m.     You    may    also    add    a    file    [1mmanual.css[0m,    see
  [1m[34mGAPDoc2HTMLPrintHTMLFiles[0m  ([1m5.3-7[0m)  for  more  details. The argument [22m[32mpath[0m of
  [1m[34mGAPDoc2HTML[0m  ([1m5.3-6[0m)  specifies the directory containing the BibTeX database
  files.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> h := GAPDoc2HTML(r, path);;[0m
    [22m[35mgap> GAPDoc2HTMLPrintHTMLFiles(h, path);[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.1-1 MakeGAPDocDoc[0m
  
  [1m[34m> MakeGAPDocDoc( [0m[22m[34mpath, main, files, bookname[, gaproot][0m[1m[34m ) __________[0mfunction
  
  This  function  collects  all  the  commands  for  producing  a  [22m[32mdvi[0m-, [22m[32mpdf[0m-,
  postscript-,  text-  and  HTML-version  of a [1mGAPDoc[0m document as described in
  Section [1m5.1[0m.
  
  [22m[36mNote:[0m  If  this  function works for you depends on your operating system and
  installed  software.  It  will  probably  work  on  most [22m[32mUNIX[0m 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  [22m[34mpath[0m  must be the directory (as string or directory object) containing
  the  main  file  [22m[34mmain[0m  of  the  document  (given  with  or  without the [22m[32m.xml[0m
  extension.  The  argument  [22m[34mfiles[0m  is  a list of (probably source code) files
  relative  to  [22m[34mpath[0m  which  contain  pieces  of  documentation  which must be
  included  in  the  document, see Chapter [1m4.[0m. And [22m[34mbookname[0m is the name of the
  book  used  by  [1mGAP[0m's  online  help. The optional argument [22m[34mgaproot[0m must be a
  string which gives the relative path from [22m[34mpath[0m to the [1mGAP[0m root directory. If
  this  is  given, the HTML files are produced with relative paths to external
  books.
  
  Experimental:  [1m[34mMakeGAPDocDoc[0m  can  be called with additional arguments [22m[32m"Tth"[0m
  and/or  [22m[32m"MathML"[0m.  If  these  are  given  additional  variants  of  the HTML
  conversion are called, see [1m[34mGAPDoc2HTML[0m ([1m5.3-6[0m) for details.
  
  
  [1m[4m[31m5.2 Parsing XML Documents[0m
  
  Arbitrary  well-formed  XML  documents  can  be  parsed  and  browsed by the
  following functions.
  
  [1m[4m[31m5.2-1 ParseTreeXMLString[0m
  
  [1m[34m> ParseTreeXMLString( [0m[22m[34mstr[0m[1m[34m ) ________________________________________[0mfunction
  [1mReturns:[0m  a record which is root of a tree structure
  
  This  function  parses  an XML-document stored in string [22m[34mstr[0m and returns the
  document in form of a tree.
  
  A  node  in  this  tree  corresponds  to  an  XML element, or to some parsed
  character data. In the first case it looks as follows:
  
  [22m[35m-------------------------  Example Node  -------------------------[0m
    [22m[35mrec( name := "Book",[0m
    [22m[35m     attributes := rec( Name := "EDIM" ),[0m
    [22m[35m     content := [ ... list of nodes for content ...],[0m
    [22m[35m     start := 312,[0m
    [22m[35m     stop := 15610,[0m
    [22m[35m     next := 15611     )[0m
  [22m[35m------------------------------------------------------------------[0m
  
  This  means that [22m[32m[22m[34mstr[0m{[312..15610]}[0m looks like [22m[32m<Book Name="EDIM"> ... content
  ... </Book>[0m.
  
  The  leaves  of  the  tree  encode parsed character data as in the following
  example:
  
  [22m[35m-------------------------  Example Node  -------------------------[0m
    [22m[35mrec( name := "PCDATA", [0m
    [22m[35m     content := "text without markup "     )[0m
  [22m[35m------------------------------------------------------------------[0m
  
  This function checks whether the XML document is [22m[36mwell formed[0m, see [1m2.1-13[0m 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  [22m[32mShow();[0m  one  can  browse  the original input in the [1m[34mPager[0m ([1mReference:
  Pager[0m),  starting  with  the line where the error occurred. All entities are
  resolved  when  they  are  either entities defined in the [1mGAPDoc[0m package (in
  particular  the standard XML entities) or if their definition is included in
  the [22m[32m<!DOCTYPE ..>[0m tag of the document.
  
  Note  that [1m[34mParseTreeXMLString[0m does not parse and interpret the corresponding
  document  type  definition  (the  [22m[32m.dtd[0m-file given in the [22m[32m<!DOCTYPE ..>[0m tag).
  Hence  it  also  does not check the [22m[36mvalidity[0m of the document (i.e., it is no
  [22m[36mvalidating XML parser[0m).
  
  If  you  are  using  this  function  to  parse a [1mGAPDoc[0m document you can use
  [1m[34mCheckAndCleanGapDocTree[0m  ([1m5.2-4[0m) for some validation and additional checking
  of the document structure.
  
  [1m[4m[31m5.2-2 DisplayXMLStructure[0m
  
  [1m[34m> DisplayXMLStructure( [0m[22m[34mtree[0m[1m[34m ) ______________________________________[0mfunction
  
  This  utility  displays  the  tree  structure  of  an  XML document as it is
  returned by [1m[34mParseTreeXMLString[0m ([1m5.2-1[0m) (without the [22m[32mPCDATA[0m leaves).
  
  Since  this  is  usually  quite  long  the  result  is shown using the [1m[34mPager[0m
  ([1mReference: Pager[0m).
  
  [1m[4m[31m5.2-3 ApplyToNodesParseTree[0m
  
  [1m[34m> ApplyToNodesParseTree( [0m[22m[34mtree, fun[0m[1m[34m ) _______________________________[0mfunction
  [1m[34m> AddRootParseTree( [0m[22m[34mtree[0m[1m[34m ) _________________________________________[0mfunction
  [1m[34m> RemoveRootParseTree( [0m[22m[34mtree[0m[1m[34m ) ______________________________________[0mfunction
  
  The  function  [1m[34mApplyToNodesParseTree[0m  applies a function [22m[34mfun[0m to all nodes of
  the  parse  tree  [22m[34mtree[0m  of  an  XML  document returned by [1m[34mParseTreeXMLString[0m
  ([1m5.2-1[0m).
  
  The  function  [1m[34mAddRootParseTree[0m  is  an  application of this. It adds to all
  nodes  a  component [22m[32m.root[0m to which the top node tree [22m[34mtree[0m is assigned. These
  components can be removed afterwards with [1m[34mRemoveRootParseTree[0m.
  
  And here are utilities for processing [1mGAPDoc[0m XML documents.
  
  [1m[4m[31m5.2-4 CheckAndCleanGapDocTree[0m
  
  [1m[34m> CheckAndCleanGapDocTree( [0m[22m[34mtree[0m[1m[34m ) __________________________________[0mfunction
  [1mReturns:[0m  nothing
  
  The  argument  [22m[34mtree[0m of this function is a parse tree from [1m[34mParseTreeXMLString[0m
  ([1m5.2-1[0m) of some [1mGAPDoc[0m document. This function does an (incomplete) validity
  check  of  the  document  according  to  the  document  type  declaration in
  [1mgapdoc.dtd[0m. 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 [22m[32mShow();[0m one can browse the
  original input in the [1m[34mPager[0m ([1mReference: Pager[0m).
  
  [1m[4m[31m5.2-5 AddParagraphNumbersGapDocTree[0m
  
  [1m[34m> AddParagraphNumbersGapDocTree( [0m[22m[34mtree[0m[1m[34m ) ____________________________[0mfunction
  [1mReturns:[0m  nothing
  
  The argument [22m[34mtree[0m must be an XML tree returned by [1m[34mParseTreeXMLString[0m ([1m5.2-1[0m)
  applied  to a [1mGAPDoc[0m document. This function adds to each node of the tree a
  component   [22m[32m.count[0m   which  is  of  form  [22m[32m[Chapter[,  Section[,  Subsection,
  Paragraph]  ] ][0m. 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  [22m[32m0[0m  and  similarly  for  sections and subsections. Some
  elements are always considered to start a new paragraph.
  
  
  [1m[4m[31m5.3 The Converters[0m
  
  Here  are  more  details  about  the  conversion  programs  for  [1mGAPDoc[0m  XML
  documents.
  
  [1m[4m[31m5.3-1 GAPDoc2LaTeX[0m
  
  [1m[34m> GAPDoc2LaTeX( [0m[22m[34mtree[0m[1m[34m ) _____________________________________________[0mfunction
  [1mReturns:[0m  LaTeX document as string
  
  The  argument  [22m[34mtree[0m  for  this  function  is  a tree describing a [1mGAPDoc[0m XML
  document  as  returned  by [1m[34mParseTreeXMLString[0m ([1m5.2-1[0m) (probably also checked
  with  [1m[34mCheckAndCleanGapDocTree[0m  ([1m5.2-4[0m)). 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 [22m[32mmakeindex[0m).
  
  The  output  uses  the  [22m[32mreport[0m  document class and needs the following LaTeX
  packages:  [22m[32ma4wide[0m, [22m[32mamssymb[0m, [22m[32misolatin1[0m, [22m[32mmakeidx[0m, [22m[32mcolor[0m, [22m[32mfancyvrb[0m, [22m[32mpslatex[0m and
  [22m[32mhyperref[0m.  These  are  for example provided by the [1mteTeX-1.0[0m distribution of
  TeX  (which  in  turn  is  used  for  most  TeX  packages  of  current Linux
  distributions); see [34mhttp://www.tug.org/tetex/[0m.
  
  In  particular,  the  resulting  [22m[32mdvi[0m-  or  [22m[32mpdf[0m-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 [22m[32m.pnr[0m which is [1mGAP[0m
  readable  and  contains  the  page  numbers  for  all  (sub)sections  of the
  document.  This  can  be  used by [1mGAP[0m's online help; see [1m[34mAddPageNumbersToSix[0m
  ([1m5.3-4[0m). 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:
  
  [22m[35m-----------------  in top level of XML document  -----------------[0m
    [22m[35m<?LaTeX Options="12pt"?>[0m
    [22m[35m<?LaTeX ExtraPreamble="\usepackage{blabla}[0m
    [22m[35m\newcommand{\bla}{blabla}[0m
    [22m[35m"?>[0m
  [22m[35m------------------------------------------------------------------[0m
  
  A  hint  for large documents: In many TeX installations one can easily reach
  some    memory    limitations    with    documents    which   contain   many
  (cross-)references.  In [1mteTeX[0m you can look for a file [1mtexmf.cnf[0m which allows
  to enlarge certain memory sizes.
  
  This  function  works  by  running recursively through the document tree and
  calling  a  handler  function  for  each  [1mGAPDoc[0m  XML element. These handler
  functions  are  all quite easy 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.
  
  [1m[4m[31m5.3-2 GAPDoc2Text[0m
  
  [1m[34m> GAPDoc2Text( [0m[22m[34mtree[, bibpath][,][width][0m[1m[34m ) _________________________[0mfunction
  [1mReturns:[0m  record containing text files as strings and other information
  
  The  argument  [22m[34mtree[0m  for  this  function  is  a tree describing a [1mGAPDoc[0m XML
  document  as  returned  by [1m[34mParseTreeXMLString[0m ([1m5.2-1[0m) (probably also checked
  with [1m[34mCheckAndCleanGapDocTree[0m ([1m5.2-4[0m)). This function produces a text version
  of  the document which can be used with [1mGAP[0m's online help (with the [22m[32m"screen"[0m
  viewer,  see  [1m[34mSetHelpViewer[0m  ([1mReference:  SetHelpViewer[0m)). It includes title
  page,   bibliography  and  index.  The  bibliography  is  made  from  BibTeX
  databases. Their location must be given with the argument [22m[34mbibpath[0m (as string
  or directory object).
  
  The  output is a record with one component for each chapter (with names [22m[32m"0"[0m,
  [22m[32m"1"[0m,  ...,  [22m[32m"Bib"[0m and [22m[32m"Ind"[0m). Each such component is again a record with the
  following components:
  
  [1m[33m[22m[32mtext[0m[0m
        the text of the whole chapter as a string
  
  [1m[33m[22m[32mssnr[0m[0m
        list  of  subsection  numbers  in  this  chapter  (like  [22m[32m[3, 2, 1][0m for
        chapter 3, section 2, subsection 1)
  
  [1m[33m[22m[32mlinenr[0m[0m
        corresponding list of line numbers where the subsections start
  
  [1m[33m[22m[32mlen[0m[0m
        number of lines of this chapter
  
  The    result    can    be    written    into   files   with   the   command
  [1m[34mGAPDoc2TextPrintTextFiles[0m ([1m5.3-3[0m).
  
  As  a  side  effect  this  function also produces the [1mmanual.six[0m information
  which is used for searching in [1mGAP[0m's online help. This is stored in [22m[32m[22m[34mtree[0m.six[0m
  and  can  be  printed  into  a  [1mmanual.six[0m  file  with  [1m[34mPrintSixFile[0m ([1m5.3-5[0m)
  (preferably  after  producing  a  LaTeX  version of the document as well and
  adding the page number information to [22m[32m[22m[34mtree[0m.six[0m, see [1m[34mGAPDoc2LaTeX[0m ([1m5.3-1[0m) and
  [1m[34mAddPageNumbersToSix[0m ([1m5.3-4[0m)).
  
  The  text  produced  by  this function contains color markup via ANSI escape
  sequences,  see  [1m[34mTextAttr[0m  ([1m5.5-2[0m).  To  view  the  colored  text you need a
  terminal  which  interprets these escape sequences correctly and you have to
  set  the  variable  [22m[32mANSI_COLORS[0m to [22m[32mtrue[0m (a good place for doing this is your
  [1m.gaprc[0m file).
  
  With the optional argument [22m[34mwidth[0m 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.
  
  [1m[4m[31m5.3-3 GAPDoc2TextPrintTextFiles[0m
  
  [1m[34m> GAPDoc2TextPrintTextFiles( [0m[22m[34mt[, path][0m[1m[34m ) ___________________________[0mfunction
  [1mReturns:[0m  nothing
  
  The  first  argument  must  be a result returned by [1m[34mGAPDoc2Text[0m ([1m5.3-2[0m). 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 [1mchap0.txt[0m, [1mchap1.txt[0m, ..., [1mchapBib.txt[0m, and [1mchapInd.txt[0m.
  
  If  you  want  to  make your document accessible via the [1mGAP[0m online help you
  must  put at least these files for the text version into a directory and use
  the  name  of  this  directory  as  an  argument  for  one  of  the commands
  [1m[34mDeclarePackageDocumentation[0m   ([1mReference:   DeclarePackageDocumentation[0m)  or
  [1m[34mDeclarePackageAutoDocumentation[0m                                  ([1mReference:
  DeclarePackageAutoDocumentation[0m).  Furthermore  you  need  to  put  the file
  [1mmanual.six[0m into this directory, see [1m[34mPrintSixFile[0m ([1m5.3-5[0m).
  
  Optionally  you  can add the [22m[32mdvi[0m- and [22m[32mpdf[0m-versions of the document which are
  produced  with  [1m[34mGAPDoc2LaTeX[0m  ([1m5.3-1[0m) to this directory. The files must have
  the  names  [1mmanual.dvi[0m  and  [1mmanual.pdf[0m,  respectively. Also you can add the
  files  of  the  HTML  version  produced  with  [1m[34mGAPDoc2HTML[0m  ([1m5.3-6[0m)  to this
  directory,  see  [1m[34mGAPDoc2HTMLPrintHTMLFiles[0m ([1m5.3-7[0m). The handler functions in
  [1mGAP[0m  for this help format detect automatically which of the optional formats
  of a book are actually available.
  
  [1m[4m[31m5.3-4 AddPageNumbersToSix[0m
  
  [1m[34m> AddPageNumbersToSix( [0m[22m[34mtree, pnrfile[0m[1m[34m ) _____________________________[0mfunction
  [1mReturns:[0m  nothing
  
  Here  [22m[34mtree[0m  must  be  the  XML  tree  of  a  [1mGAPDoc[0m  document,  returned  by
  [1m[34mParseTreeXMLString[0m  ([1m5.2-1[0m).  Running  [22m[32mlatex[0m  on  the result of [1m[34mGAPDoc2LaTeX[0m
  ([1m5.3-1[0m)[22m[32m([22m[34mtree[0m)[0m  produces  a  file  [22m[34mpnrfile[0m (with extension [22m[32m.pnr[0m). The command
  [1m[34mGAPDoc2Text[0m  ([1m5.3-2[0m)[22m[32m([22m[34mtree[0m)[0m  creates  a component [22m[32m[22m[34mtree[0m.six[0m which contains all
  information  about  the  document  for  the [1mGAP[0m online help, except the page
  numbers  in  the [22m[32m.dvi, .ps, .pdf[0m versions of the document. This command adds
  the missing page number information to [22m[32m[22m[34mtree[0m.six[0m.
  
  [1m[4m[31m5.3-5 PrintSixFile[0m
  
  [1m[34m> PrintSixFile( [0m[22m[34mtree, bookname, fname[0m[1m[34m ) ____________________________[0mfunction
  [1mReturns:[0m  nothing
  
  This  function  prints  the  [22m[32m.six[0m file [22m[34mfname[0m for a [1mGAPDoc[0m document stored in
  [22m[34mtree[0m with name [22m[34mbookname[0m. Such a file contains all information about the book
  which  is  needed  by  the  [1mGAP[0m  online help. This information must first be
  created by calls of [1m[34mGAPDoc2Text[0m ([1m5.3-2[0m) and [1m[34mAddPageNumbersToSix[0m ([1m5.3-4[0m).
  
  [1m[4m[31m5.3-6 GAPDoc2HTML[0m
  
  [1m[34m> GAPDoc2HTML( [0m[22m[34mtree[, bibpath[, gaproot]][,][mtrans][0m[1m[34m ) _____________[0mfunction
  [1mReturns:[0m  record containing HTML files as strings and other information
  
  The  argument  [22m[34mtree[0m  for  this  function  is  a tree describing a [1mGAPDoc[0m XML
  document  as  returned  by [1m[34mParseTreeXMLString[0m ([1m5.2-1[0m) (probably also checked
  with  [1m[34mCheckAndCleanGapDocTree[0m  ([1m5.2-4[0m)).  Without  an  [22m[34mmtrans[0m  argument this
  function produces an HTML version of the document which can be read with any
  Web-browser  and  also  be  used  with  [1mGAP[0m's online help (see [1m[34mSetHelpViewer[0m
  ([1mReference:  SetHelpViewer[0m)).  It  includes  title  page,  bibliography, and
  index.  The  bibliography is made from BibTeX databases. Their location must
  be  given  with  the argument [22m[34mbibpath[0m (as string or directory object, if not
  given the current directory is used). If the third argument [22m[34mgaproot[0m is given
  and  is  a  string then this string is interpreted as relative path to [1mGAP[0m's
  root  directory.  Reference-URLs to external HTML-books which begin with the
  [1mGAP[0m 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 [1mGAP[0m root.
  
  The  output is a record with one component for each chapter (with names [22m[32m"0"[0m,
  [22m[32m"1"[0m,  ..., [22m[32m"Bib"[0m, and [22m[32m"Ind"[0m). Each such component is again a record with the
  following components:
  
  [1m[33m[22m[32mtext[0m[0m
        the text of an HTML file containing the whole chapter (as a string)
  
  [1m[33m[22m[32mssnr[0m[0m
        list  of  subsection  numbers  in  this  chapter  (like  [22m[32m[3, 2, 1][0m for
        chapter 3, section 2, subsection 1)
  
  [22m[36mStandard output format without[0m [22m[34mmtrans[0m [22m[36margument[0m
  
  The HTML code produced with this converter conforms to the W3C specification
  "XHTML  1.0 strict", see [34mhttp://www.w3.org/TR/xhtml1[0m. 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 [1m[34mGAPDoc2Text[0m
  ([1m5.3-2[0m). We don't want to assume that the browser can use symbol fonts. Some
  [1mGAP[0m  users  like  to  browse  the  online  help with [22m[32mlynx[0m, see [1m[34mSetHelpViewer[0m
  ([1mReference:  SetHelpViewer[0m),  which runs inside the same terminal windows as
  [1mGAP[0m.
  
  [22m[36mUsing a stylesheet file[0m
  
  The  layout  information  for  a  browser should be specified in a cascading
  style  sheet  (CSS)  file.  The [1mGAPDoc[0m package contains an example of such a
  style  sheet,  see the file [1mgapdoc.css[0m in the root directory of the package.
  This    file    conforms   to   the   W3C   specification   CSS   2.0,   see
  [34mhttp://www.w3.org/TR/REC-CSS2[0m.  You  may  just  copy that file as [1mmanual.css[0m
  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 [1mmanual.css[0m.
  
  [22m[36mOutput format with[0m [22m[34mmtrans[0m argument
  
  Currently,  there  are two experimental variants of this converter available
  which  handle  mathematical  formulae differently. They are accessed via the
  optional last [22m[34mmtrans[0m argument.
  
  If  this  argument is set to [22m[32m"Tth"[0m it is assumed that you have installed the
  LaTeX  to  HTML  translation  program  [22m[32mtth[0m.  This  is  used to translate the
  contents  of  the [22m[32mM[0m, [22m[32mMath[0m and [22m[32mDisplay[0m 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 [34mhttp://hutchinson.belmont.ma.us/tth/[0m for more details.
  
  If  the  [22m[34mmtrans[0m  argument  is  set  to  [22m[32m"MathML"[0m it is assumed that you have
  installed      the      translation      program      [22m[32mttm[0m,      see     also
  [34mhttp://hutchinson.belmont.ma.us/tth/[0m).   This   is  used  to  translate  the
  contents  of  the  [22m[32mM[0m,  [22m[32mMath[0m  and  [22m[32mDisplay[0m elements to MathML 2.0 markup. The
  resulting  files should conform to the "XHTML 1.1 plus MathML 2.0" standard,
  see  [34mhttp://www.w3.org/TR/MathML2/[0m for more details. It is expected that the
  next generation of graphical browsers will be able to render such files (try
  for  example [22m[32mMozilla[0m, at least 0.9.9). You must copy the [22m[32m.xsl[0m and [22m[32m.css[0m files
  from  [1mGAPDoc[0ms [1mmathml[0m directory to the directory containing the output files.
  The translation with [22m[32mttm[0m is still experimental. The output of this converter
  variant is garbage for browsers which don't support MathML.
  
  The  result  of  this  converter  can  be  written to files with the command
  [1m[34mGAPDoc2HTMLPrintHTMLFiles[0m ([1m5.3-7[0m).
  
  [1m[4m[31m5.3-7 GAPDoc2HTMLPrintHTMLFiles[0m
  
  [1m[34m> GAPDoc2HTMLPrintHTMLFiles( [0m[22m[34mt[, path][0m[1m[34m ) ___________________________[0mfunction
  [1mReturns:[0m  nothing
  
  The  first  argument  must  be a result returned by [1m[34mGAPDoc2HTML[0m ([1m5.3-6[0m). 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 [1mchap0.html[0m, [1mchap1.html[0m, ..., [1mchapBib.html[0m, and [1mchapInd.html[0m.
  
  The  experimental  versions which are produced with [22m[32mtth[0m or [22m[32mttm[0m use different
  names  for  the files, namely [1mchap0_sym.html[0m, and so on for files which need
  symbol fonts and [1mchap0_mml.xml[0m for files with MathML translations.
  
  You  can make these files accessible via the [1mGAP[0m online help by putting them
  into  a  directory  and  using  this  as an argument for one of the commands
  [1m[34mDeclarePackageDocumentation[0m   ([1mReference:   DeclarePackageDocumentation[0m)  or
  [1m[34mDeclarePackageAutoDocumentation[0m                                  ([1mReference:
  DeclarePackageAutoDocumentation[0m). You may also want to put a file [1mmanual.css[0m
  into that directory, see [1m[34mGAPDoc2HTML[0m ([1m5.3-6[0m).
  
  
  [1m[4m[31m5.4 Parsing BibTeX Files[0m
  
  Here  are functions for parsing, normalizing and printing reference lists in
  BibTeX format. The reference describing this format is [L85, Appendix B].
  
  [1m[4m[31m5.4-1 ParseBibFiles[0m
  
  [1m[34m> ParseBibFiles( [0m[22m[34mbibfile[0m[1m[34m ) _________________________________________[0mfunction
  [1mReturns:[0m  list [22m[32m[list of bib-records, list of abbrevs, list of expansions][0m
  
  This  function  parses  a  file  [22m[34mbibfile[0m  (if  this  file does not exist the
  extension  [22m[32m.bib[0m is appended) in BibTeX format and returns a list as follows:
  [22m[32m[entries, strings, texts][0m. Here [22m[32mentries[0m is a list of records, one record for
  each reference contained in [22m[34mbibfile[0m. Then [22m[32mstrings[0m is a list of abbreviations
  defined  by [22m[32m@string[0m-entries in [22m[34mbibfile[0m and [22m[32mtexts[0m is a list which contains in
  the corresponding position the full text for such an abbreviation.
  
  The  records  in  [22m[32mentries[0m store key-value pairs of a BibTeX reference in the
  form  [22m[32mrec(key1  = value1, ...)[0m. The names of the keys are converted to lower
  case.  The type of the reference (i.e., book, article, ...) and the citation
  key are stored as components [22m[32m.Type[0m and [22m[32m.Label[0m.
  
  As an example consider the following BibTeX file.
  
  [22m[35m----------------------------  my.bib  ----------------------------[0m
    [22m[35m@string{ j  = "Important Journal" }[0m
    [22m[35m@article{ AB2000, Author=  "Fritz A. First and Sec, X. Y.", [0m
    [22m[35mTITLE="Short", journal = j, year = 2000 }[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> bib := ParseBibFiles("my.bib");[0m
    [22m[35m[ [ rec( Type := "article", Label := "AB2000", [0m
    [22m[35m          author := "Fritz A. First and Sec, X. Y.", title := "Short", [0m
    [22m[35m          journal := "Important Journal", year := "2000" ) ], [0m
    [22m[35m  [ "j" ], [0m
    [22m[35m  [ "Important Journal" ] ][0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.4-2 NormalizeNameAndKey[0m
  
  [1m[34m> NormalizeNameAndKey( [0m[22m[34mr[0m[1m[34m ) _________________________________________[0mfunction
  [1mReturns:[0m  nothing
  
  This  function  normalizes  in  a  record describing a BibTeX reference (see
  [1m[34mParseBibFiles[0m ([1m5.4-1[0m)) the [22m[32mauthor[0m and editor fields using the description in
  [L85,  Appendix  B  1.2]. The original entries are stored in [22m[32m.authororig[0m and
  [22m[32m.editororig[0m.
  
  Furthermore a short and a long citation key is generated.
  
  We continue the example from [1m[34mParseBibFiles[0m ([1m5.4-1[0m).
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> NormalizeNameAndKey(bib[1][1]);[0m
    [22m[35mgap> bib[1][1];[0m
    [22m[35mrec( Type := "article", Label := "AB2000", [0m
    [22m[35m  author := "First, F. A. and Sec, X. Y. ", title := "Short", [0m
    [22m[35m  journal := "Important Journal", year := "2000", [0m
    [22m[35m  authororig := "Fritz A. First and Sec, X. Y.", key := "FS00", [0m
    [22m[35m  keylong := "firstsec2000" )[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.4-3 WriteBibFile[0m
  
  [1m[34m> WriteBibFile( [0m[22m[34mbibfile, bib[0m[1m[34m ) _____________________________________[0mfunction
  [1mReturns:[0m  nothing
  
  This  is  the converse of [1m[34mParseBibFiles[0m ([1m5.4-1[0m). Here [22m[34mbib[0m must have a format
  as it is returned by [1m[34mParseBibFiles[0m ([1m5.4-1[0m). A BibTeX file [22m[34mbibfile[0m is written
  and  the entries are formatted in a uniform way. All given abbreviations are
  used while writing this file.
  
  We continue the example from [1m[34mNormalizeNameAndKey[0m ([1m5.4-2[0m). The command
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> WriteBibFile("nicer.bib", bib);[0m
  [22m[35m------------------------------------------------------------------[0m
  
  produces a file [1mnicer.bib[0m as follows:
  
  [22m[35m--------------------------  nicer.bib  ---------------------------[0m
    [22m[35m@string{j = "Important Journal" }[0m
    [22m[35m[0m
    [22m[35m@article{ AB2000,[0m
    [22m[35m  author =           {First, F. A. and Sec, X. Y.},[0m
    [22m[35m  title =            {Short},[0m
    [22m[35m  journal =          j,[0m
    [22m[35m  year =             {2000},[0m
    [22m[35m  key =              {FS00},[0m
    [22m[35m  authororig =       {Fritz A. First and Sec, X. Y.},[0m
    [22m[35m  keylong =          {firstsec2000}[0m
    [22m[35m}[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m5.5 Text Utilities[0m
  
  This section describes some utility functions for handling texts within [1mGAP[0m.
  They  are  used by the functions in the [1mGAPDoc[0m package but may be useful for
  other  purposes  as  well.  We  start  with some variables containing useful
  strings and go on with functions for parsing and reformatting text.
  
  [1m[4m[31m5.5-1 WHITESPACE[0m
  
  [1m[34m> WHITESPACE_________________________________________________[0mglobal variable
  [1m[34m> CAPITALLETTERS_____________________________________________[0mglobal variable
  [1m[34m> SMALLLETTERS_______________________________________________[0mglobal variable
  [1m[34m> LETTERS____________________________________________________[0mglobal variable
  [1m[34m> DIGITS_____________________________________________________[0mglobal variable
  [1m[34m> HEXDIGITS__________________________________________________[0mglobal variable
  
  These  variables  contain  sets  of  characters  which  are  useful for text
  processing. They are defined as follows.
  
  [1m[33mWHITESPACE[0m
        [22m[32m" \n\t\r"[0m
  
  [1m[33mCAPITALLETTERS[0m
        [22m[32m"ABCDEFGHIJKLMNOPQRSTUVWXYZ"[0m
  
  [1m[33mSMALLLETTERS[0m
        [22m[32m"abcdefghijklmnopqrstuvwxyz"[0m
  
  [1m[33mLETTERS[0m
        concatenation of CAPITALLETTERS and SMALLLETTERS
  
  [1m[33mDIGITS[0m
        [22m[32m"0123456789"[0m
  
  [1m[33mHEXDIGITS[0m
        [22m[32m"0123456789ABCDEFabcdef"[0m
  
  [1m[4m[31m5.5-2 TextAttr[0m
  
  [1m[34m> TextAttr___________________________________________________[0mglobal variable
  
  The  record  [1m[34mTextAttr[0m  contains  strings  which can be printed to change the
  terminal  attribute  for  the  following  characters.  This  only works with
  terminals  which  understand  basic ANSI escape sequences. Try the following
  example  to see if this is the case for the terminal you are using. It shows
  the  effect  of  the  foreground  and background color attributes and of the
  [22m[32m.bold[0m, [22m[32m.blink[0m, [22m[32m.normal[0m, [22m[32m.reverse[0m and[22m[32m.underscore[0m which can partly be mixed.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mextra := ["CSI", "reset", "delline", "home"];;[0m
    [22m[35mfor t in Difference(RecNames(TextAttr), extra) do[0m
    [22m[35m  Print(TextAttr.(t), "TextAttr.", t, TextAttr.reset,"\n");[0m
    [22m[35mod;[0m
  [22m[35m------------------------------------------------------------------[0m
  
  The  suggested  defaults for colors [22m[32m0..7[0m are black, red, green, brown, blue,
  magenta,   cyan,  white.  But  this  may  be  different  for  your  terminal
  configuration.
  
  The  escape  sequence  [22m[32m.delline[0m  deletes the content of the current line and
  [22m[32m.home[0m moves the cursor to the beginning of the current line.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mfor i in [1..5] do [0m
    [22m[35m  Print(TextAttr.home, TextAttr.delline, String(i,-6), "\c"); [0m
    [22m[35m  Sleep(1); [0m
    [22m[35mod;[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Whenever you use this in some printing routines you should make it optional.
  Use these attributes only, when the variable [22m[32mANSI_COLORS[0m has the value [22m[32mtrue[0m.
  
  [1m[4m[31m5.5-3 FormatParagraph[0m
  
  [1m[34m> FormatParagraph( [0m[22m[34mstr[, len[, flush[, attr]]][0m[1m[34m ) ___________________[0mfunction
  [1mReturns:[0m  the formatted paragraph as string
  
  This  function  formats  a  text given in the string [22m[34mstr[0m as a paragraph. The
  optional arguments have the following meaning:
  
  [1m[33m[22m[34mlen[0m[0m
        the length of the lines of the resulting text (default is [22m[32m78[0m)
  
  [1m[33m[22m[34mflush[0m[0m
        can  be [22m[32m"left"[0m, [22m[32m"right"[0m, [22m[32m"center"[0m or [22m[32m"both"[0m, telling that lines should
        be  flushed  left,  flushed  right,  centered or left-right justified,
        respectively (default is [22m[32m"both"[0m)
  
  [1m[33m[22m[34mattr[0m[0m
        is  a  list  of  two  strings;  the  first is prepended and the second
        appended  to  each  line  of  the  result (can for example be used for
        indenting, [22m[32m[" ", ""][0m, or some markup, [22m[32m[TextAttr.bold, TextAttr.reset][0m,
        default is [22m[32m["", ""][0m)
  
  This  function tries to handle markup with the escape sequences explained in
  [1m[34mTextAttr[0m ([1m5.5-2[0m) correctly.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> str := "One two three four five six seven eight nine ten eleven.";;[0m
    [22m[35mgap> Print(FormatParagraph(str, 25, "left", ["/* ", " */"]));           [0m
    [22m[35m/* One two three four five */[0m
    [22m[35m/* six seven eight nine ten */[0m
    [22m[35m/* eleven. */[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.5-4 SubstitutionSublist[0m
  
  [1m[34m> SubstitutionSublist( [0m[22m[34mlist, sublist, new[, flag][0m[1m[34m ) ________________[0mfunction
  [1mReturns:[0m  the changed list
  
  This  function  looks for (non-overlapping) occurrences of a sublist [22m[34msublist[0m
  in  a  list  [22m[34mlist[0m (compare [1m[34mPositionSublist[0m ([1mReference: PositionSublist[0m)) and
  returns a list where these are substituted with the list [22m[34mnew[0m.
  
  The  optional  argument [22m[34mflag[0m can either be [22m[32m"all"[0m (this is the default if not
  given)  or [22m[32m"one"[0m. In the second case only the first occurrence of [22m[34msublist[0m is
  substituted.
  
  If  [22m[34msublist[0m  does  not occur in [22m[34mlist[0m then [22m[34mlist[0m itself is returned (and not a
  [22m[32mShallowCopy(list)[0m).
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> SubstitutionSublist("xababx", "ab", "a");[0m
    [22m[35m"xaax"[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.5-5 StripBeginEnd[0m
  
  [1m[34m> StripBeginEnd( [0m[22m[34mlist, strip[0m[1m[34m ) _____________________________________[0mfunction
  [1mReturns:[0m  changed string
  
  Here [22m[34mlist[0m and [22m[34mstrip[0m must be lists. This function returns the sublist of list
  which does not contain the leading and trailing entries which are entries of
  [22m[34mstrip[0m. If the result is equal to [22m[34mlist[0m then [22m[34mlist[0m itself is returned.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> StripBeginEnd(" ,a, b,c,   ", ", ");[0m
    [22m[35m"a, b,c"[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.5-6 StripEscapeSequences[0m
  
  [1m[34m> StripEscapeSequences( [0m[22m[34mstr[0m[1m[34m ) ______________________________________[0mfunction
  [1mReturns:[0m  string without escape sequences
  
  This  function  returns  the string one gets from the string [22m[34mstr[0m by removing
  all  escape  sequences  which are explained in [1m[34mTextAttr[0m ([1m5.5-2[0m). If [22m[34mstr[0m does
  not contain such a sequence then [22m[34mstr[0m itself is returned.
  
  [1m[4m[31m5.5-7 RepeatedString[0m
  
  [1m[34m> RepeatedString( [0m[22m[34mc, len[0m[1m[34m ) _________________________________________[0mfunction
  
  Here  [22m[34mc[0m  must  be  either  a character or a string and [22m[34mlen[0m is a non-negative
  number.  Then  [1m[34mRepeatedString[0m  returns  a string of length [22m[34mlen[0m consisting of
  copies of [22m[34mc[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> RepeatedString('=',51);[0m
    [22m[35m"==================================================="[0m
    [22m[35mgap> RepeatedString("*=",51);[0m
    [22m[35m"*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*"[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.5-8 NumberDigits[0m
  
  [1m[34m> NumberDigits( [0m[22m[34mstr, base[0m[1m[34m ) ________________________________________[0mfunction
  [1mReturns:[0m  integer
  
  [1m[34m> DigitsNumber( [0m[22m[34mn, base[0m[1m[34m ) __________________________________________[0mfunction
  [1mReturns:[0m  string
  
  The  argument  [22m[34mstr[0m  of  [1m[34mNumberDigits[0m  must be a string consisting only of an
  optional leading [22m[32m'-'[0m and characters in [22m[32m0123456789abcdefABCDEF[0m, describing an
  integer  in  base  [22m[34mbase[0m  with  2  <=  [22m[34mbase[0m  <= 16. This function returns the
  corresponding integer.
  
  The function [1m[34mDigitsNumber[0m does the reverse.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> NumberDigits("1A3F",16);[0m
    [22m[35m6719[0m
    [22m[35mgap> DigitsNumber(6719, 16);[0m
    [22m[35m"1A3F"[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.5-9 PositionMatchingDelimiter[0m
  
  [1m[34m> PositionMatchingDelimiter( [0m[22m[34mstr, delim, pos[0m[1m[34m ) _____________________[0mfunction
  [1mReturns:[0m  position as integer or [22m[32mfail[0m
  
  Here  [22m[34mstr[0m must be a string and [22m[34mdelim[0m a string with two different characters.
  This  function searches the smallest position [22m[32mr[0m of the character [22m[32m[22m[34mdelim[0m[2][0m in
  [22m[34mstr[0m such that the number of occurrences of [22m[32m[22m[34mdelim[0m[2][0m in [22m[34mstr[0m between positions
  [22m[32m[22m[34mpos[0m+1[0m  and  [22m[32mr[0m is by one greater than the corresponding number of occurrences
  of [22m[32m[22m[34mdelim[0m[1][0m.
  
  If such an [22m[32mr[0m exists, it is returned. Otherwise [22m[32mfail[0m is returned.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> PositionMatchingDelimiter("{}x{ab{c}d}", "{}", 0);[0m
    [22m[35mfail[0m
    [22m[35mgap> PositionMatchingDelimiter("{}x{ab{c}d}", "{}", 1);[0m
    [22m[35m2[0m
    [22m[35mgap> PositionMatchingDelimiter("{}x{ab{c}d}", "{}", 6);[0m
    [22m[35m11[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.5-10 WordsString[0m
  
  [1m[34m> WordsString( [0m[22m[34mstr[0m[1m[34m ) _______________________________________________[0mfunction
  [1mReturns:[0m  list of strings containing the words
  
  This  returns  the  list  of  words  of a text stored in the string [22m[34mstr[0m. All
  non-letters are considered as word boundaries and are removed.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> WordsString("one_two \n    three!?");[0m
    [22m[35m[ "one", "two", "three" ][0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m5.6 Print Utilities[0m
  
  The  following  printing  utilities  turned out to be useful for interactive
  work  with  texts  in [1mGAP[0m. But they are more general and so we document them
  here.
  
  [1m[4m[31m5.6-1 PrintTo1[0m
  
  [1m[34m> PrintTo1( [0m[22m[34mfilename, fun[0m[1m[34m ) ________________________________________[0mfunction
  [1m[34m> AppendTo1( [0m[22m[34mfilename, fun[0m[1m[34m ) _______________________________________[0mfunction
  
  The  argument  [22m[34mfun[0m must be a function without arguments. Everything which is
  printed  by  a call [22m[34mfun()[0m is printed into the file [22m[34mfilename[0m. As with [1m[34mPrintTo[0m
  ([1mReference:  PrintTo[0m)  and [1m[34mAppendTo[0m ([1mReference: AppendTo[0m) this overwrites or
  appends to, respectively, a previous content of [22m[34mfilename[0m.
  
  These functions can be particularly efficient when many small pieces of text
  shall  be  written  to  a file, because no multiple reopening of the file is
  necessary.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> f := function() local i; [0m
    [22m[35m>   for i in [1..100000] do Print(i, "\n"); od; end; [0m
    [22m[35mgap> PrintTo1("nonsense", f); # now check the local file `nonsense'[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.6-2 StringPrint[0m
  
  [1m[34m> StringPrint( [0m[22m[34mobj1[, obj2[, ...]][0m[1m[34m ) _______________________________[0mfunction
  [1m[34m> StringView( [0m[22m[34mobj[0m[1m[34m ) ________________________________________________[0mfunction
  
  These  functions return a string containing the output of a [22m[32mPrint[0m or [22m[32mViewObj[0m
  call with the same arguments.
  
  This should be considered as a (temporary?) hack. It would be better to have
  [1m[34mString[0m ([1mReference: String[0m) methods for all [1mGAP[0m objects and to have a generic
  [1m[34mPrint[0m ([1mReference: Print[0m)-function which just interprets these strings.
  
  [1m[4m[31m5.6-3 PrintFormattedString[0m
  
  [1m[34m> PrintFormattedString( [0m[22m[34mstr[0m[1m[34m ) ______________________________________[0mfunction
  
  This  function prints a string [22m[34mstr[0m. The difference to [22m[32mPrint(str);[0m is that no
  additional  line breaks are introduced by [1mGAP[0m's standard printing mechanism.
  This  can  be  used  to print lines which are longer than the current screen
  width. In particular one can print text which contains escape sequences like
  those  explained  in  [1m[34mTextAttr[0m ([1m5.5-2[0m), where lines may have more characters
  than [22m[36mvisible characters[0m.
  
  [1m[4m[31m5.6-4 Page[0m
  
  [1m[34m> Page( [0m[22m[34m...[0m[1m[34m ) ______________________________________________________[0mfunction
  [1m[34m> PageDisplay( [0m[22m[34mobj[0m[1m[34m ) _______________________________________________[0mfunction
  
  These  functions  are  similar  to  [1m[34mPrint[0m  ([1mReference:  Print[0m)  and  [1m[34mDisplay[0m
  ([1mReference: Display[0m), respectively. The difference is that the output is not
  sent  directly to the screen, but is piped into the current pager; see [1m[34mPAGER[0m
  ([1mReference: Pager[0m).
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> Page([1..1421]+0);[0m
    [22m[35mgap> PageDisplay(CharacterTable("Symmetric", 14));[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m5.6-5 StringFile[0m
  
  [1m[34m> StringFile( [0m[22m[34mfilename[0m[1m[34m ) ___________________________________________[0mfunction
  [1m[34m> FileString( [0m[22m[34mfilename, str[, append][0m[1m[34m ) ____________________________[0mfunction
  
  The  function  [1m[34mStringFile[0m  returns the content of file [22m[34mfilename[0m as a string.
  This  works  efficiently with arbitrary (binary or text) files. If something
  went wrong, this function returns [22m[32mfail[0m.
  
  Conversely  the  function [1m[34mFileString[0m writes the content of a string [22m[34mstr[0m into
  the file [22m[34mfilename[0m. If the optional third argument [22m[34mappend[0m is given and equals
  [22m[32mtrue[0m  then  the  content  of [22m[34mstr[0m is appended to the file. Otherwise previous
  content  of  the  file is deleted. This function returns the number of bytes
  written or [22m[32mfail[0m if something went wrong.
  
  Both functions are quite efficient, even with large files.
  
