
                             Debian GAP Policy
                             -----------------

                   Bill Allombert <ballombe@debian.org>

                       version 0.1, 5 novembre 2022


-------------------------------------------------------------------------------


Abstract
--------

     This unofficial policy describes the conventions that Debian packages
     of GAP (https://www.gap-system.org) components must follows to get
     along nicely with the gap-core package and others.


-------------------------------------------------------------------------------


Contents
--------

     1.        Convention used in this policy

     2.        Package name

     3.        Package versions

     4.        Installation

     5.        Global GAP workspace

     6.        GAP2DEB

     7.        Documentation


-------------------------------------------------------------------------------


1. Convention used in this policy
---------------------------------

     Since GAP and Debian have a different concept of package, we will use
     the following conventions:

     1.   <$pkg> denote the name of the GAP package as stated on the GAP
          website.

     2.   <$package> denote the name of your Debian package.


-------------------------------------------------------------------------------


2. Package name
---------------

     Name of GAP packages (<$pkg>) are usually short and cryptic, like
     `ctbllib'.  You should choose a more verbose name (<$package>) like
     gap-character-tables.

     1.   <$package> must start by `gap-'.

     2.   Package must provide `gap-pkg-$pkg' so GAP users can do `apt-get
          gap-pkg-$pkg' without having to guess <$package>.


-------------------------------------------------------------------------------


3. Package versions
-------------------

     Write the version with the format X.Y.Z.  The old format XrYpZ was an
     historical accident.


-------------------------------------------------------------------------------


4. Installation
---------------

     GAP packages should be installed in the `/usr/share/gap/pkg/$pkg'
     directory.  Architecture dependent part of the package should go to
     `/usr/lib/gap/pkg/$pkg'.  You can provide symlinks if this is
     necessary.

     If your package include large (say around 1MB) datasets (library of
     groups, etc...), you should compress them (after checking GAP is able
     to automatically uncompress them) with `gzip --best' to save
     diskspace.  Try to not compress source code files (`.g' files) if
     possible.


-------------------------------------------------------------------------------


5. Global GAP workspace
-----------------------

     To allow GAP to start faster, Debian provides a global workspace file
     in `/var/lib/gap/workspace.gz'.  This file is managed by
     `update-gap-workspace'.  If this file exists, it will be automatically
     updated whenever a Debian GAP package is installed or upgraded,
     through a gap-core dpkg trigger.


-------------------------------------------------------------------------------


6. GAP2DEB
----------

     The GAP script `gap2deb' can be used to generate a basic `debian'
     directory from a `PackageInfo.g' file.  It must be run in the package
     directory.


-------------------------------------------------------------------------------


7. Documentation
----------------

     GAP packages come usually with extensive documentation.

     1.   TeX files used by the online help system must be shipped.

     2.   Documentation must be shipped preferably in `html' and `pdf'.

     3.   Ship the file `manual.toc' compressed.  This enables
          `SetHelpviewer()' to function properly.

     4.   If you need to use the script `etc/convert.pl', set the
          environment variable `GAP_CONVERT_DATE' to the string appearing
          as the date in the original manual (e.g.
          `GAP_CONVERT_DATE="Februar 2010"', `GAP_CONVERT_DATE' is not
          interpolated).


-------------------------------------------------------------------------------


     Debian GAP Policy

     Bill Allombert <ballombe@debian.org>


     version 0.1, 5 novembre 2022

