<!-- $Id: conv.xml,v 1.27 2007/09/25 09:30:35 gap Exp $ -->

<Chapter Label="ch:conv">
<Heading>The Converters and an XML Parser</Heading>

The &GAPDoc; package contains a set of programs which allow us to  convert a
&GAPDoc; book  into several output  versions and  to make them  available to
&GAP;'s online help.<P/>

Currently  the following  output  formats are  provided:  text for  browsing
inside a  terminal running  &GAP;, &LaTeX; with  <C>hyperref</C>-package for
cross references via hyperlinks and HTML for reading with a Web-browser.<P/>



<Section Label="MakeDoc">
<Heading>Producing Documentation from Source Files</Heading>

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   <F>MyBook.xml</F>   of   a   book
<C>"MyBook"</C>  in the  directory  <F>/my/book/path</F>. This  contains
<C>&lt;#Include    ...></C>-statements    as   explained    in
Chapter&nbsp;<Ref Sect="Distributing"/>. These refer to some other files
as well as pieces of text which  are found in the comments of some &GAP;
source files <F>../lib/a.gd</F> and  <F>../lib/b.gi</F> (relative to the
path above). A &BibTeX; database  <F>MyBook.bib</F> for the citations is
also  in  the  directory  given  above. We  want  to  produce  a  text-,
<C>pdf-</C> and HTML-version of the  document. (A &LaTeX; version of the
manual  is produced,  so it  is also  easy to  compile <C>dvi</C>-,  and
postscript-versions.)<P/>

All the commands shown in this  Section are collected in the single function
<Ref Func="MakeGAPDocDoc"/>.<P/>

First   we  construct   the   complete  XML-document   as   a  string   with
<Ref   Func="ComposedDocument"/>.     This   interprets    recursively   the
<C>&lt;#Include ...></C>-statements.

<Log>
gap> path := Directory("/my/book/path");;
gap> main := "MyBook.xml";;
gap> files := ["../lib/a.gd", "../lib/b.gi"];;
gap> bookname := "MyBook";;
gap> doc := ComposedDocument("GAPDoc", path, main, files, true);;
</Log>

Now  <C>doc</C> 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. <P/>

Next  we parse  the document  and store  its structure  in a  tree-like data
structure. The  commands for  this are <Ref  Func="ParseTreeXMLString"/> and
<Ref Func="CheckAndCleanGapDocTree"/>. 

<Log>
gap> r := ParseTreeXMLString(doc[1], doc[2]);;
gap> CheckAndCleanGapDocTree(r);
true
</Log>

We start  to produce  a text version  of the manual,  which can  be read
in  a  terminal  (window).  The command  is  <Ref  Func="GAPDoc2Text"/>.
This  produces  a  record  with  the actual  text  and  some  additional
information.  The text  can  be  written  chapter-wise  into files  with
<Ref Func="GAPDoc2TextPrintTextFiles"/>.  The names  of these  files are
<F>chap0.txt</F>,  <F>chap1.txt</F> and  so on.  The text  contains some
markup using  ANSI escape sequences.  This markup is substituted  by the
&GAP;  help system  (user configurable)  to  show the  text with  colors
and  other  attributes.  For  the  bibliography we  have  to  tell  <Ref
Func="GAPDoc2Text"/> the location of the &BibTeX; database by specifying
a <C>path</C> as second argument.

<Log>
gap> t := GAPDoc2Text(r, path);;
gap> GAPDoc2TextPrintTextFiles(t, path);
</Log>

This   command  constructs   all   parts  of   the  document   including
table  of   contents,  bibliography   and  index.  The   functions  <Ref
Func="FormatParagraph"/>  for   formatting  text  paragraphs   and  <Ref
Func="ParseBibFiles"/> for reading  &BibTeX; files with &GAP;  may be of
independent interest.<P/>

With the  text version we  have also  produced the information  which is
used for searching  with &GAP;'s online help. Also,  labels are produced
which can be  used by links in the HTML-  and <C>pdf</C>-versions of the
manual. <P/>

Next   we   produce   a   &LaTeX;  version   of   the   document.   <Ref
Func="GAPDoc2LaTeX"/> returns  a string  containing the  &LaTeX; source.
The utility  function <Ref Func="FileString"/>  writes the content  of a
string to a file, we choose <F>MyBook.tex</F>.

<Log>
gap> l := GAPDoc2LaTeX(r);;
gap> FileString(Filename(path, Concatenation(bookname, ".tex")), l);
</Log>

Assuming  that  you  have  a sufficiently  good  installation  of  &TeX;
available  (see  <Ref Func="GAPDoc2LaTeX"/>  for  details)  this can  be
processed with a series of commands like in the following example.

<Log>
cd /my/book/path
pdflatex MyBook
bibtex MyBook
pdflatex MyBook
makeindex MyBook
pdflatex MyBook
mv MyBook.pdf manual.pdf
</Log>

After this  we have  a <C>pdf</C>-version  of the  document in  the file
<F>manual.pdf</F>. It  contains hyperlink information which  can be used
with  appropriate browsers  for convenient  reading of  the document  on
screen  (e.g., <C>xpdf</C>  is nice  because it  allows remote  calls to
display named locations  of the document). Of course, we  could also use
other commands like <C>latex</C> or  <C>dvips</C> to process the &LaTeX;
source file.

Furthermore  we   have  produced  a  file   <F>MyBook.pnr</F>  which  is
&GAP;-readable  and  contains  the  page  number  information  for  each
(sub-)section of the document. <P/>

We  can add  this page  number information  to the  indexing information
collected by the text converter  and then print a <F>manual.six</F> file
which is read by &GAP; when the manual is loaded. This is done with <Ref
Func="AddPageNumbersToSix"/> and <Ref Func="PrintSixFile"/>.

<Log>
gap> AddPageNumbersToSix(r, Filename(path, "MyBook.pnr"));
gap> PrintSixFile(Filename(path, "manual.six"), r, bookname);
</Log>

Finally  we  produce  an  HTML-version  of the  document  and  write  it
(chapter-wise)  into  files   <F>chap0.html</F>,  <F>chap1.html</F>  and
so  on.  They  can  be  read with  any  Web-browser.  The  commands  are
<Ref  Func="GAPDoc2HTML"/> and  <Ref Func="GAPDoc2HTMLPrintHTMLFiles"/>.
We  also  add  a  link  from  <F>manual.html</F>  to  <F>chap0.html</F>.
You  probably   want  to   add  a   file  <F>manual.css</F>,   see  <Ref
Func="GAPDoc2HTMLPrintHTMLFiles"/>  for   more  details.   The  argument
<C>path</C>  of   <Ref  Func="GAPDoc2HTML"/>  specifies   the  directory
containing the &BibTeX; database files.

<Log>
gap> h := GAPDoc2HTML(r, path);;
gap> GAPDoc2HTMLPrintHTMLFiles(h, path);
</Log>

<ManSection >
<Func Arg="path, main, files, bookname[, gaproot]" Name="MakeGAPDocDoc" />

<Description>
This  function  collects  all  the   commands  for  producing  a  text-,
<C>pdf</C>-  and HTML-version  of a  &GAPDoc; document  as described  in
Section&nbsp;<Ref Sect="MakeDoc"/>. It checks the <C>.log</C> file from
the call of <C>pdflatex</C> and reports if there are errors, warnings or
overfull boxes.<P/>

<Emph>Note:</Emph> If this function works for you depends on your
operating system and installed software. It will probably work on most
<C>UNIX</C> 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. <P/>

Here <A>path</A> must  be the directory (as string  or directory object)
containing  the main  file <A>main</A>  of the  document (given  with or
without the <C>.xml</C>  extension. The argument <A>files</A>  is a list
of (probably  source code) files  relative to <A>path</A>  which contain
pieces  of documentation  which must  be included  in the  document, see
Chapter&nbsp;<Ref Chap="Distributing"/>. And <A>bookname</A> is the name
of  the  book  used  by  &GAP;'s  online  help.  The  optional  argument
<A>gaproot</A>  must be  a string  which  gives the  relative path  from
<A>path</A> to the main &GAP; root directory. If this is given, the HTML
files are produced with relative paths to external books.<P/>

Experimental:  <Ref Func="MakeGAPDocDoc"/>  can  be  called with  additional
arguments   <C>"Tth"</C>  and/or   <C>"MathML"</C>.  If   these  are   given
additional  variants   of  the   HTML  conversion   are  called,   see  <Ref
Func="GAPDoc2HTML"/> for details.<P/>

It is possible to use &GAPDoc; with other languages than English, see
<Ref Func="SetGapDocLanguage"/> for more details.<P/>
</Description>
</ManSection>
</Section>

<Section Label="ParseXML">
<Heading>Parsing XML Documents</Heading>
Arbitrary well-formed XML documents can be parsed and browsed by the
following functions.

<#Include Label="ParseTreeXMLString">

<#Include Label="StringXMLElement">

<#Include Label="EntitySubstitution">

<#Include Label="DisplayXMLStructure">

<#Include Label="ApplyToNodesParseTree">

Here are two more utilities which use <Ref
Func="ApplyToNodesParseTree"/>.

<#Include Label="GetTextXMLTree">

<#Include Label="XMLElements">

And here are utilities for processing &GAPDoc; XML documents.

<#Include Label="CheckAndCleanGapDocTree">

<#Include Label="AddParagraphNumbersGapDocTree">

<#Include Label="InfoXMLParser">

</Section>

<Section Label="Converters">
<Heading>The Converters</Heading>
Here  are  more details  about  the  conversion  programs for  &GAPDoc;  XML
documents.

<#Include Label="GAPDoc2LaTeX">

<#Include Label="GAPDoc2Text">

<#Include Label="GAPDoc2TextPrintTextFiles">

<#Include Label="AddPageNumbersToSix">

<#Include Label="PrintSixFile">

<#Include Label="SetGAPDocTextTheme">

<#Include Label="GAPDoc2HTML">

<#Include Label="GAPDoc2HTMLPrintHTMLFiles">

<#Include Label="InfoGAPDoc">

<#Include Label="SetGapDocLanguage">

</Section>

<Section Label="Sec:TestExample">
<Heading>Testing Manual Examples</Heading>
We also provide some tools to check the examples given in
<C>&lt;Example></C>-elements. 

<#Include Label="ManualExamples">

<#Include Label="TestExamples">

</Section>

</Chapter>