<#GAPDoc Label="GAPDoc2HTML">
<ManSection >
<Func Arg="tree[, bibpath[, gaproot]]" Name="GAPDoc2HTML" />
<Returns>record  containing  HTML  files  as  strings  and  other
information</Returns>
<Description>
The   argument  <A>tree</A>   for   this  function   is  a   tree
describing  a   &GAPDoc;  XML   document  as  returned   by  <Ref
Func="ParseTreeXMLString"  /> (probably  also  checked with  <Ref
Func="CheckAndCleanGapDocTree"  />).  This function  produces  an
HTML  version  of  the  document  which  can  be  read  with  any
Web-browser  and also  used with  &GAP;'s online  help (see  <Ref
BookName="Ref" Func="SetHelpViewer" />).  It includes title page,
bibliography, and  index. The bibliography is  made from &BibTeX;
databases.  Their  location  must  be  given  with  the  argument
<A>bibpath</A>  (as string  or  directory object).  If the  third
argument <A>gaproot</A> is given and is a string then this string
is  interpreted  as  relative  path to  &GAP;'s  root  directory.
Reference-URLs to external HTML-books  which begin with the &GAP;
root path  are then  rewritten to start  with the  given relative
path.  This  makes  the HTML-documentation  portable  provided  a
package is  installed in some  standard location below  the &GAP;
root.<P/>

The  output is  a  record  with one  component  for each  chapter
(with  names   <C>"0"</C>,  <C>"1"</C>,  ...,   <C>"Bib"</C>, and
<C>"Ind"</C>).  Each  such  component   is  also  a  record  with
components

The   HTML   code   produced   with   this   converter   conforms
to    the   W3C    specification    HTML    4.01   strict,    see
<URL>http://www.w3.org/TR/html401</URL>. This means in particular
that  the  code  doesn't  contain  any  explicit  font  or  color
information.  The  layout information  for  a  browser should  be
specified in  a cascading  style sheet  (CSS) file.  The &GAPDoc;
package contains an  example of such a style sheet,  see the file
<File>gapdoc.css</File>  in the  root directory  of the  package.
This  file  conforms  to  the  W3C  specification  CSS  2.0,  see
<URL>http://www.w3.org/TR/REC-CSS2</URL>. You may  just copy that
file as <File>manual.css</File> 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 <File>manual.css</File>.


<List >
<Mark><C>text</C></Mark>
<Item>the text of an HTML file containing the whole chapter (as a
string)</Item>
<Mark><C>ssnr</C></Mark>
<Item>list of subsection numbers in  this chapter (like <C>[3, 2,
1]</C>  for  chapter&nbsp;3,  section&nbsp;2,  subsection&nbsp;1)
</Item>
</List>

The  result can  be  written  into files  with  the command  <Ref
Func="GAPDoc2HTMLPrintHTMLFiles" />.<P/>

Mathematical  formulae  are  handled  as in  the  text  converter
<Ref  Func="GAPDoc2Text"/>.  We don't  want  to  assume that  the
browser can  use symbol  fonts. Some &GAP;  users like  to browse
the  online  help  with   <C>lynx</C>,  see  <Ref  BookName="Ref"
Func="SetHelpViewer"  />, which  runs  inside  the same  terminal
windows as &GAP;.

</Description>
</ManSection>
<#/GAPDoc>
