                               README.tools

The files in the tools.tar.gz archive have mainly been provided to assist
package authors. They are briefly described below according to the
directory hierarchy. More information is contained in the Appendix of the
Example package manual and in the gapmacro.tex manual (gapmacrodoc.pdf file
in this archive).

    gap4r5/
        doc/
           gapmacro.tex
               TeX macros file for writing documentation (the main GAP 
               manuals and almost a half of the currently redistributed 
               GAP packages are already using GAPDoc format which provides 
               a better functionality, so we keep gapmacro.tex here only 
               for packages which are still using it).
           gapmacrodoc.pdf   
               gapmacro.tex manual, which is made using the same 
               gapmacro.tex format (so it may be used as an example).
           gapmacrodoc.tex
               TeX source for the gapmacrodoc.pdf.
           manualindex
               awk script that creates manual.ind for a main or package
               manual (calls MakeIndex).

        etc/
           classifyfiles.py
               Python script which we use in the package update mechanism
               to classify files into text and binary and to exclude some
               files or directories from distribution. It may be used to
               check how files in your package will be classified. Also it
               is possible to use it in your own package wrapping scripts.
               Usage instructions are at the beginning of classifyfiles.py.
           patternstextbinary.txt
               file describing patterns for text and binary files, used
               by the classifyfiles.py script.
           patternscolor.txt
               file describing file exclusion/inclusion patterns, used
               by the classifyfiles.py script.
           buildman.pe
               Perl script that builds a .tex file from a .msk file and 
               a config file (see gapmacrodoc.pdf for usage instructions).
           convert.pl
               Perl script that builds an HTML manual from TeX files that
               follow the gapmacro.tex conventions (see gapmacrodoc.pdf 
               and comments in the script itself for usage instructions).
           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. You may modify it to remove some parts; for 
               example, we do not use the ``zoo'' archive format any more,
               so you do not have to provide it).
           unzoo.c
               C source file for the unzoo program (in case you need it to
               unpack some legacy zoo archive).
           README.tools
               this file!
              
Most of the software required to use the above tools comes standard with 
various UNIX/Linux installations, e.g. you should already have tex, bibtex, 
makeindex, pdftex, perl, awk, python etc. See the Appendix of the Example
package manual and the gapmacro.tex manual (gapmacrodoc.pdf file in this
archive) for more details about such external dependencies and further 
usage instructions.

The GAP Group
October 2011
