%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  hints.tex              GAP documentation                  Greg Gamble
%%
%H  $Id: hints.tex,v 4.3 2002/02/28 17:46:27 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}

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 be contain only lowercase characters may change in the
future); this is so that a user may load the  <package-name>  package  by
calling  the  `RequirePackage'  command  (which  lowercases   its   first
argument; see~"ref:RequirePackage" in the Reference Manual)  with  either
<package-name> or <package-dir> (in doublequotes).

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}\ \ 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'.

`init.g', `read.g'&
A {\GAP} package *must*  have  a  file  `init.g'  (see  Sections~"ext:The
Structure of a GAP Package" and~"ext:The Init File of a GAP  Package"  in
the Reference Manual; the latter section describes what  `init.g'  should
contain). 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  `ReadPkg'  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  `ReadPkg'  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 {\GAP}~4 Programming Reference Manual. There is  now  an  alternative
XML-based  system  provided  by  the  {\GAP}   package   \package{GAPDoc}
(see~"gapdoc:Title  page").  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 `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} 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 describe 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 {\GAP}~4  Programming
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  `ReadPkg'
statements in the package `init.g' file, and the `Install...' definitions
should go in files with `.gi'  extensions  and  be  loaded  by  `ReadPkg'
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 `ReadPkg' 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{Having a Banner}

\index{banner!suppression}
Typically a banner for a package is produced by  a  sequence  of  `Print'
statements in a file named `banner.g' which is  loaded  via  a  `ReadPkg'
statement in the package `init.g' file. The execution of the printing  of
the banner should be nested inside `if not QUIET and BANNER then ... fi;'
(see the  {\Example}  package  `init.g'  file)  so  that  the  banner  is
suppressed during package autoloading and when {\GAP} is started up  with
the `-q' or `-b' command line options.

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}''
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
