GAP (Utils) - Chapter 1: Introduction

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

1 Introduction
1.1 Information for package authors

### 1 Introduction

The Utils package provides a space for utility functions from a variety of GAP packages to be collected together into a single package. In this way it is hoped that they will become more visible to other package authors. This package was first distributed as part of the GAP 4.8.2 distribution.

The package is loaded with the command

    gap> LoadPackage( "utils" );

Functions have been transferred from the following packages:

- Conversion of a GAP group to a \({\sf Magma}\) output string, taken from various sources including `other.gi` in the main library.

Transfer is complete (for now) for functions from the following packages:

- AutoDoc [GH16] (with function names changed);

- ResClasses [Koh17b];

- RCWA [Koh17a];

- XMod [WAOU17].

The package may be obtained either as a compressed `.tar` file or as a `.zip` file, `utils-version_number.tar.gz`, by ftp from one of the following sites:

- the Utils GitHub release site: https://gap-packages.github.io/utils/.

- any GAP archive, e.g. https://www.gap-system.org/Packages/packages.html;

The package also has a GitHub repository at: https://github.com/gap-packages/utils.

Once the package is loaded, the manual `doc/manual.pdf` can be found in the documentation folder. The `html` versions, with or without \({\sf MathJax}\), may be rebuilt as follows:

    gap> ReadPackage( "utils", "makedoc.g" );

It is possible to check that the package has been installed correctly by running the test files (which terminates the GAP session):

    gap> ReadPackage( "utils", "tst/testall.g" );
    Architecture: . . . . .
    testing: . . . . .
    . . .
    #I  No errors detected while testing

Note that functions listed in this manual that are currently in the process of being transferred are only read from the source package Home (say), and so can only be used if Home has already been loaded. There are no such functions in transition at present.

#### 1.1 Information for package authors

A function (or collection of functions) is suitable for transfer from a package Home to Utils if the following conditions are satisfied.

- The function is sufficiently non-specialised so that it might be of use to other authors.

- The function does not depend on the remaining functions in Home

- The function does not do what can already be done with a GAP library function.

- Documentation of the function and test examples are available.

- When there is more than one active author of Home, they should all be aware (and content) that the transfer is taking place.

Authors of packages may be reluctant to let go of their utility functions. The following principles may help to reassure them. (Suggestions for more items here are welcome.)

- A function that has been transferred to Utils will not be changed without the approval of the original author.

- The current package maintainer has every intention of continuing to maintain Utils. In the event that this proves impossible, the GAP development team will surely find someone to take over.

- Function names will not be changed unless specifically requested by Home's author(s) or unless they have the form `HOME_FunctionName`.

- In order to speed up the transfer process, only functions from one package will be in transition at any given time. Hopefully a week or two will suffice for most packages.

- Any package author who transfers a function to Utils will become an author of Utils. (In truth, Utils does not have authors, just a large number of contributors.)

The process for transferring utility functions from Home to Utils is described in Chapter 12.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 Bib Ind

generated by GAPDoc2HTML