The tools4rX archive contains the following files listed according to
directory hierarchy, where X is the current revision number of GAP 4.

  gap4rX/
        doc/
           allmanualsindex
               awk script that creates fullindex.ind, the index entries
               required for fullindex.tex (calls MakeIndex)
           fullindex.tex
               TeX master file for comprehensive index for the five
               main GAP manuals (ext, new, prg, ref, tut)
           fullindex.mst
               MakeIndex style file - imposes the GAP style on the full
               index
           gapmacro.tex
               TeX macros file for GAP documentation (currently most GAP
               documentation uses it; the GAPDoc package provides an
               alternative)
           make_doc
               generates .dvi, .ps, .pdf, .htm documentation including
               the five manuals, and the CTblLib and GAPDoc package
               manuals (GAPDoc is in the deppkg archive); a complete
               build requires the doc/build/ directory which we do
               not provide here
           manualindex
               awk script that creates manual.ind for a main or package
               manual (calls MakeIndex)
           htm/
              Makefile
                  contains targets for building the main GAP manuals in
                  HTML format
              allhtmlindex
                  awk script for generating comprehensive index files 
                  for all five main GAP manuals and all letters by calling 
                  onehtmlindex
              onehtmlindex
                  awk script for generating an index file for one letter
                  of the alphabet covering all five main GAP manuals

        etc/
           buildman.pe
               Perl script that builds a .tex file from a .msk file and 
               a config file (see "Using buildman.pe" in the ext manual)
           convert.pl
               Perl script that builds an HTML manual from TeX files that
               follow the gapmacro.tex conventions (see "The gapmacro.tex
               Manual Format" in the ext manual). Usage instructions are
               at the beginning of convert.pl itself.
           packpack
               shell script that creates archives in several formats (.zoo,
               .zip, .tar.gz, .tar.bz2) of a package (i.e. it ``packs up a
               package''). Usage instructions are at the beginning of
               packpack.
           unzoo.c
               C source file for the unzoo program (this is not zoo - to get
               that see "Wrapping Up a GAP Package" in the ref manual)
           README.tools
               this file!

The files in the tools4rX archive have mainly been provided to assist package
authors. More information is contained in the Appendix of the Example package
manual. The make_doc file provided in the Example package's doc directory
provides a template for using the manualindex and convert.pl programs listed
above. You will probably need to run the make_doc of *this* archive once to
build the manual.lab files of the main GAP manuals before attempting to build
the HTML manual of your own package manual (it shouldn't matter that you are
missing the doc/build/ directory; you may wish to comment out parts of the
file so only the manual.lab files are generated).

The GAP development team principally use Linux when developing GAP. Most of
the software required to use the above comes standard with UNIX and Linux
e.g. you should already have:

  tex, bibtex, makeindex, dvips, pdftex
    If you don't have this it is all packaged up very nicely in the teTeX
    distribution of TeX and its friends (see http://www.tug.org/teTeX/).
    One possible problem one may have is the building of the PDF manual if
    the pool_size is too small; one way of remedying this is by doing
 
      kpsewhich texmf.cnf

    to find the location of the texmf.cnf on your system and then editing
    the pool_size line to say

    pool_size = 250000
   
  perl
    You need Perl 5 (probably later than 5.003; but 5.004_004+ should be
    fine). You may have to edit the path of the first line of the perl scripts
    provided above.
 
    which perl

    will tell you where perl is on your system.

  awk
    Awk on your system may actually be a symbolic link to nawk or gawk (the
    scripts have been ``sanitised'' to work with these, so this shouldn't
    matter).

Two programs you may not have are:

  zoo
    As mentioned above, see "Wrapping Up a GAP Package" in the ref manual
    for hints on where to get this.

  tth
    This is used by the convert.pl script when called with the -t option to
    translate maths formulae. For good results you need version 2.52+.
    Download the latest tth from URL:
       http://hutchinson.belmont.ma.us/tth/tth-noncom/download.html
    (Compiling what is downloaded via the `C code for any platform.' link is
    easy with gcc.)

GAP Group (gap@dcs.st-and.ac.uk), 16 Apr 02
