%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  hints.tex              GAP documentation                  Greg Gamble
%%
%H  $Id: hints.tex,v 4.6 2003/06/20 02:35:57 gap Exp $
%%
%Y  Copyright (C) 2001, School of Math & Comp. Sci., St Andrews, Scotland
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Hints for writing a GAP Package}

The {\Example} package is intended to be a prototype for a package.  Here
we describe just what features one should emulate when writing one's  own
{\GAP} package for popular consumption, and a few pointers as to where to
go for more information.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Structure of a GAP Package}

This  section  is  intended  to  amplify  the  recommendations  made   in
Section~"ext:The Files of  a  GAP  Package"  of  the  Extending  {\GAP}~4
Reference Manual.

A {\GAP} package should have an alphanumeric name (<package-name>,  say);
mixed case is fine, but there should  be  no  whitespace.  The  directory
<package-dir> containing the files of package  <package-name>  should  be
just  <package-name>  converted  to  lowercase  (the   restriction   that
<package-dir> must contain only lowercase characters may  change  in  the
future).

The directory  <package-dir>  should  be  a  subdirectory  of  `pkg'  and
preferably should have the following structure  (below,  a  trailing  `/'
distinguishes directories from ordinary files):

\){\kernttindent}<package-dir>/
\){\kernttindent}\ \ README
\){\kernttindent}\ \ configure
\){\kernttindent}\ \ Makefile.in
\){\kernttindent}\ \ PackageInfo.g
\){\kernttindent}\ \ init.g
\){\kernttindent}\ \ read.g
\){\kernttindent}\ \ doc/
\){\kernttindent}\ \ lib/
\){\kernttindent}\ \ src/

We now describe the above files and directories:

\beginitems

`README'&
This should contain ``how  to  get  it''  (from  the  {\GAP}  `ftp'-  and
web-sites) instructions, as well as installation instructions  and  names
of the package  authors  and  their  email  addresses.  The  installation
instructions and authors' names and addresses should be repeated  in  the
package's documentation (which should be in the `doc' directory).

`configure', `Makefile.in'&
These files are only necessary if the package has a non-{\GAP} component,
e.g.~some C code (the files of which should be in the  `src'  directory).
The `configure' and `Makefile.in' files of the {\Example} package provide
prototypes. The `configure' file typically takes a  path  <path>  to  the
{\GAP} root  directory  as  argument  and  uses  the  value  assigned  to
`GAParch' in the file `sysinfo.gap' (created when {\GAP} was compiled) to
determine the compilation architecture, inserts  this  in  place  of  the
string `@GAPARCH@' in `Makefile.in' and creates a file  `Makefile'.  When
`make' is run (which, of course, reads  the  constructed  `Makefile'),  a
directory `bin' (if necessary) and a  subdirectory  of  `bin'  with  name
equal to the string assigned  to  `GAParch'  in  the  file  `sysinfo.gap'
should be created; any binaries constructed  by  compiling  the  code  in
`src' should end up in this subdirectory of `bin'.

`PackageInfo.g'&
Since {\GAP}~4.4, a {\GAP} package *must* have  a  `PackageInfo.g'  file.
The {\Example}  package's  `PackageInfo.g'  file  is  well-commented  and
should be used as a prototype.

`init.g', `read.g'&
A {\GAP} package *must* have a file `init.g' (see Section~"ext:The  Files
of a GAP Package" in the Extending  {\GAP}~4  Reference  Manual).  As  of
{\GAP}~4.4, the typical  `init.g'  and  `read.g'  files  should  normally
consist entirely of `ReadPackage' (see~"ref:ReadPackage" in the  {\GAP}~4
Reference Manual) commands (and possibly also `Read'  commands).  If  the
``declaration'' and ``implementation'' parts of the package are separated
(and  this  is  recommended),  there  should  be  a  `read.g'  file.  The
``declaration'' part of a  package  consists  of  function  and  variable
*name* declarations and these go in files with  `.gd'  extensions;  these
files are read in via `ReadPackage' commands in the  `init.g'  file.  The
``implementation'' part of a package consists of the  actual  definitions
of  the  functions  and  variables  whose  names  were  declared  in  the
``declaration'' part, and these go in files with `.gi' extensions;  these
files are read in via `ReadPackage' commands in the  `read.g'  file.  The
reason for following the above dichotomy is that  the  `read.g'  file  is
read *after* the `init.g'  file,  thus  enabling  the  possibility  of  a
function's implementation to refer to  another  function  whose  name  is
known but is not actually defined yet. The {\GAP} code (whether or not it
is split into ``declaration'' and ``implementation'' parts) should go  in
the package's `lib' directory (see below).

`doc'&
This directory should contain the package's documentation. Traditionally,
a {\TeX}-based system has been used for {\GAP}  documentation,  which  is
thoroughly described in Section~"ext:The gapmacro.tex Manual  Format"  of
the Extending {\GAP}~4 Reference Manual.  There  is  now  an  alternative
XML-based  system  provided  by  the  {\GAP}   package   \package{GAPDoc}
(see Chapter~"gapdoc:Introduction and Example"  of  the  \package{GAPDoc}
Manual). Please spend some time reading the documentation  for  whichever
system you decide to use for writing your  package's  documentation.  The
{\Example} package's documentation  was  written  using  the  traditional
{\TeX}-based system. If you plan on using this, please use the {\Example}
package's `doc' directory as a prototype, which you will observe contains
the following files:

\){\kernttindent}manual.tex\ \# master file
\){\kernttindent}<chapi>.tex\ \# chapter file(s) ... 1 for each chapter
\){\kernttindent}manual.mst\ \# MakeIndex style file
\){\kernttindent}make_doc\ \ \ \# script that generates the manuals

&
Generally, one should also provide a `manual.bib' Bib{\TeX} database file
(or write one's  own  bibliography  `manual.bbl'  file).  Generating  the
various formats of the manuals requires various software tools which  are
called directly or indirectly by  `make_doc'  and  these  are  listed  in
Section~"Documentation Software Tools Needed". The file  `manual.mst'  is
needed for generating a manual index; it should be  a  copy  of  the  one
provided in the {\Example} package. The only adjustments that  a  package
writer should need to make to `make_doc' is to replace occurrences of the
word `Example' with <package-name>.

`lib'&
This is the preferred place for the {\GAP} code, i.e.~the `.g', `.gd' and
`.gi' files (other than `PackageInfo.g', `init.g' and `read.g'). For some
packages (the {\Example} package included), the directory `gap' has  been
used instead of `lib'; `lib' has the slight  advantage  that  it  is  the
default  subdirectory  of  a  package  directory  searched  for  by   the
`DirectoriesPackageLibrary' command  (see~"ref:DirectoriesPackageLibrary"
in the {\GAP}~4 Reference Manual).

`src'&
If the package has non-{\GAP} code, e.g.~C  code,  then  this  ``source''
code should go in the `src' directory.  If  there  are  `.h'  ``include''
files you may prefer to put these all together in  a  separate  `include'
directory.

\enditems

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Documentation Software Tools Needed}

Whether you use the traditional  `gapmacro.tex'  {\TeX}-based  system  or
\package{GAPDoc} you will need to have the various following {\TeX} tools
installed:

\beginitems

`tex' (or `latex' for \package{GAPDoc}), `bibtex' and `makeindex'&
for generating `.dvi';

`dvips'&
for generating `.ps'; and

`pdftex' or `gs' and `ps2pdf' (or `pdflatex' for \package{GAPDoc})&
for generating `.pdf';

\enditems

Note that using `gs' and `ps2pdf' in lieu of `pdftex' or `pdflatex' is  a
poor substitute unless your `gs' is at  least  version  6.<xx>  for  some
<xx>.

The rest of this section describes the various  additional  tools  needed
for the `gapmacro.tex' documentation system.

To produce the `.dvi', `.ps' and `.pdf'  manual  formats,  the  following
{\GAP} tools (usually located  in  {\GAP}'s  main  `doc'  directory)  are
needed (provided by `tools<XXX>.zoo' for some version number <XXX> at the
{\GAP}  `ftp'-  or  web-sites,   or   can   be   obtained   by   emailing
\Mailto{gap-trouble@dcs.st-and.ac.uk}).

\beginitems

`gapmacro.tex'&
The macros file that dictates the style and mark-up for  the  traditional
{\TeX}-based system of {\GAP} documentation.

`manualindex'&
This is an `awk' script that adjusts the  {\TeX}-produced  index  entries
and calls `makeindex' to process them.

`mrabbrev.bib'&
This is usually supplied with your {\TeX} tools but nevertheless  a  copy
of `mrabbrev.bib' should be located in {\GAP}'s main `doc' directory.  To
find it on your system, try:

\begintt
kpsewhich mrabbrev.bib
\endtt

&
or if that doesn't work and you can't otherwise find it check out a  CTAN
site, e.g.~search for it at:
\URL{http://www.dante.de/cgi-bin/ctan-index}

\enditems

If your manual cross-refers to other `gapmacro.tex'-produced manuals (and
so  has  `\\UseReferences'  commands  in  its   `manual.tex'),   then   a
`manual.lab' file (generated by running `tex manual') for each such other
manual is needed (this includes the ``main'' manuals, e.g.~those  in  the
`doc/ref', `doc/ext' etc.~directories).

If your manual cross-refers to \package{GAPDoc}-produced manuals (and  so
has  `\\UseGapDocReferences'  commands   in   its   `manual.tex'),   then
`manual.lab' files need to be generated for these too. This  is  done  by
starting {\GAP} (at least {\GAP}~4.3) and running:

\){\kernttindent}gap> GapDocManualLab( "<package>" );

for each <package> whose manual is cross-referred to.

To produce an HTML version of the manual one needs  the  Perl  5  program
`convert.pl' which is usually located in the subdirectory  `etc'  of  the
{\GAP} root directory. The `etc' directory  is  not  part  of  the  usual
{\GAP}  distribution.  The  `etc'  directory  files  are  obtained   from
`tools<XXX>.zoo' for some version number <XXX> at the  {\GAP}  `ftp'-  or
web-sites,      or      can      be      obtained       by       emailing
\Mailto{gap-trouble@dcs.st-and.ac.uk}.

Finally, to ensure the mathematics formulae are rendered as well as  they
can be in the HTML version,  one  should  also  have  the  program  `tth'
({\TeX}  to  HTML  converter);  `convert.pl'  calls  `tth'  to  translate
mathmode formulae to HTML (if it's available). The `tth' program is  easy
to compile and can be obtained from
\URL{http://hutchinson.belmont.ma.us/tth/tth-noncom/download.html}

As a package author, you are not obliged to provide an  HTML  version  of
your  package  manual,  but  if  you  have  kept  to  the  guidelines  in
Section~"ext:The gapmacro.tex Manual Format" of  the  Extending  {\GAP}~4
Reference Manual,  you  should  have  no  trouble  in  producing  one.  A
prototype of the command to execute is in the file `make_doc'; note  that
the HTML manual  is  produced  in  files  with  `.htm'  extensions  in  a
directory `htm' outside the `doc' directory. The beginning  of  the  file
`convert.pl' contains instructions on its usage should you need them.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Functions and Variables and Choices of Their Names}

In writing the {\GAP} code for your package  you  need  to  be  a  little
careful on just how you define your functions and variables.

*Firstly*, in general one should avoid defining functions  and  variables
via assignment statements in the way you would interactively, e.g.

\beginexample
gap> Cubed := function(x) return x^3; end;
\endexample

The reason for this is that such  functions  and  variables  are  *easily
overwritten* and what's more you are not warned about it when it happens.

To protect a function  or  variable  against  overwriting  there  is  the
command  `BindGlobal'  (see~"ref:BindGlobal"  in  the  {\GAP}   Reference
Manual), or alternatively (and equivalently)  you  may  define  a  global
function via a `DeclareGlobalFunction' and  `InstallGlobalFunction'  pair
or a global variable via  a  `DeclareGlobalVariable'  and  `InstallValue'
pair. There are also operations and their methods,  and  related  objects
like attributes and filters which also have `Declare...' and `Install...'
pairs.

*Secondly*,  it's  a  good  idea  to  reduce  the  chance  of  accidental
overwriting by choosing names for your functions and variables that begin
with a string that identifies it  with  the  package,  e.g.~some  of  the
undocumented functions in the {\Example} package begin with `Eg'. This is
especially important in cases where you actually want the user to be able
to change the value of a function or variable defined  by  your  package,
for which you haved used direct assignments  (for  which  the  user  will
receive no warning  if  she  accidentally  overwrites  them).  It's  also
important  for  functions  and  variables   defined   via   `BindGlobal',
`DeclareGlobalFunction'/`InstallGlobalFunction'                       and
`DeclareGlobalVariable'/`InstallValue', in order to  avoid  name  clashes
that may  occur  with  (extensions  of)  the  {\GAP}  library  and  other
packages. On the other hand, operations and their  methods  (defined  via
`DeclareOperation', `InstallMethod' etc.~pairs) and  their  relatives  do
not need this consideration, as they avoid name clashes by  allowing  for
more than one ``method'' for the same-named object.

The method `Recipe' was included in the {\Example} package to demonstrate
the definition of a  function  via  a  `DeclareOperation'/`InstallMethod'
pair; `Recipe( FruitCake );' gives a ``method'' for making a  fruit  cake
(forgive the pun).

*Thirdly*, functions or variables with  `Set<XXX>'  or  `Has<XXX>'  names
(even if they are defined as operations) should be avoided as  these  may
clash with objects associated with attributes or  properties  (attributes
and  properties   <XXX>   declared   via   the   `DeclareAttribute'   and
`DeclareProperty' commands have associated  with  them  testers  of  form
`Has<XXX>' and setters of form `Set<XXX>').

*Fourthly*, it is a good  idea  to  have  some  convention  for  internal
functions and variables  (i.e.~the  functions  and  variables  you  don't
intend for the  user  to  use).  For  example,  they  might  be  entirely
capitalised.

*Finally*,        note        the        advantage        of        using
`DeclareGlobalFunction'/`InstallGlobalFunction',
`DeclareGlobalVariable'/`InstallValue',    etc.~pairs    (rather     than
`BindGlobal') to define functions and variables, which allow the  package
author to organise her function- and variable- definitions in  any  order
without worrying about any interdependence. The  `Declare...'  statements
should go in files with `.gd' extensions and be loaded  by  `ReadPackage'
statements in the package `init.g' file, and the `Install...' definitions
should go in files with `.gi' extensions and be loaded  by  `ReadPackage'
statements in the package `read.g' file;  this  ensures  that  the  `.gi'
files are read *after* the `.gd' files. All other package code should  go
in `.g' files (other than the `init.g' and `read.g' files themselves) and
be loaded via `ReadPackage' statements in the `init.g' file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Having an InfoClass}

It is a good idea to declare an `InfoClass' for your package. This  gives
the package user the opportunity  to  control  the  verbosity  of  output
and/or the possibility of receiving debugging information  (see~"ref:Info
functions" in the {\GAP}  Reference  Manual).  Below,  we  give  a  quick
overview of its utility.

An `InfoClass' is defined with  a  `DeclareInfoClass(  <InfoPkgname>  );'
statement and may be set to have an initial `InfoLevel'  other  than  the
zero default (which means no `Info' statement is to  output  information)
via a `SetInfoLevel( <InfoPkgname>, <level>  );'  statement.  An  initial
`InfoLevel' of 1 is typical.

`Info' statements have the form: `Info( <InfoPkgname>, <level>,  <expr1>,
<expr2>, ... );'  where  the  expression  list  `<expr1>,  <expr2>,  ...'
appears just like it would in a `Print' statement. The only difference is
that the expression list is  only  printed  (or  even  executed)  if  the
`InfoLevel' of <InfoPkgname> is at least <level>.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The Banner}

Since {\GAP}~4.4, a default package  banner  is  provided  which  may  be
over-ridden by assigning a string to  the  `BannerString'  field  of  the
record argument of `SetPackageInfo' in the `PackageInfo.g' file.

It is a good idea to have a hook into  your  package  documentation  from
your banner. The {\Example} package suggests to the {\GAP} user:

\begintt
For help, type: ?Example package
\endtt

In order for this to display the introduction of the  {\Example}  package
an `\\atindex' equivalent of the following index-entry:

\)\kernttindent\\index\{Example package\}

was added just before the first paragraph of the introductory section  in
the file `example.tex'. The {\Example} package  uses  the  `gapmacro.tex'
system  (see   Section~"Documentation   Software   Tools   Needed")   for
documentation (you will need some different scheme to achieve this  using
\package{GAPDoc}).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Packing up your GAP Package}

Ideally, your {\GAP} package should  be  packed  via  the  `zoo'  program
(Section "ext:Wrapping Up  a  GAP  Package"  in  the  Extending  {\GAP}~4
Reference Manual contains more information). The {\Example} package  file
`make_zoo' provides a template packing-up script  that  uses  `zoo'.  The
`etc' directory obtained from `tools<XXX>.zoo' for  some  version  number
<XXX> (this is described above in Section~"Documentation  Software  Tools
Needed") contains a file  `packpack'  which  provides  a  more  versatile
packing-up script.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{CVS}

When your package is ready to be refereed and/or  made  available  as  an
``accepted'' {\GAP} package, it may be of benefit to obtain CVS access to
{\GAP}; as a first step towards this you should make  a  request  to  the
{\GAP} team via an email to \Mailto{gap-trouble@dcs.st-and.ac.uk}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E
