diff --git a/doc/ref/gappkg.xml b/doc/ref/gappkg.xml index 4fc3f51eca..e2844ffa27 100644 --- a/doc/ref/gappkg.xml +++ b/doc/ref/gappkg.xml @@ -165,7 +165,194 @@ Each package has the file PackageInfo.g which contains meta-information about the package (package name, version, author(s), relations to other packages, homepage, download archives, etc.). This file is used by the package -loading mechanism and also for the redistribution of a package with ⪆ +loading mechanism and also for the redistribution of a package with ⪆. + +

+ +A PackageInfo.g file contains a call to the function +SetPackageInfo, with argument a record. +The following components of this record are mandatory. + + +PackageName + + a nonempty string denoting the name of the package, + +Subtitle + + a string that describes the package's contents, + may be used by a default banner or on a web page, + should fit on one line, + +Version + + a nonempty string that does not start with =, + denoting the version number of the package + (see Section ), + +Date + + a string of the form yyyy-mm-dd + + denoting the release date of the current version of the package + (a date since 1999, when &GAP; 4 appeared), + +ArchiveURL + + a string started with http://, https://, or ftp://, + denoting an URL from where the current package archive can be downloaded, + +ArchiveFormats + + a string that lists the supported formats (among .tar.gz, + .tar.bz2, -win.zip), separated by whitespace or commas, + +Status + + one of "accepted", "submitted", "deposited", + "dev", "other"; + if the value is "accepted" then also + CommunicatedBy (a string of the form name (place)) and + AcceptDate (a string of the form mm/yyyy) are mandatory, + +README_URL + + a string started with http://, https://, or ftp://, + denoting an URL from where the current README.md or README + file of the package can be downloaded, + +PackageInfoURL + + a string started with http://, https://, or ftp://, + denoting an URL from where the current PackageInfo.g file of the + package can be downloaded, + +AbstractHTML + + a string that describes the package's contents in a few lines, + in HTML format; this text will be displayed on the package overview + web page of &GAP;, + +PackageWWWHome + + a string started with http://, https://, or ftp://, + denoting the address of the package's home page, + +PackageDoc + + a record or a list of records; each record describes a book of the package + documentation, with the components + BookName (a string, the name of the book), + LongTitle (a string shown by ?books), + SixFile (a string denoting a relative path to the manual.six + file of the book), + HTMLStart (a string denoting a relative path to the start file of + the HTML version of the book), + PDFFile (a string denoting a relative path to the .pdf file + of the book), + ArchiveURLSubset (a list of strings denoting relative paths to those + files and directories from the archive that are needed for the online + manual; typically, [ "doc" ] suffices), + +AvailabilityTest + + a function with no arguments that returns true if the package is + available, and false otherwise + (can be if the package consists only of &GAP; + code), + + + +The following components of the record are optional. + + +License + + a nonempty string containing an SPDX ID + (see https://spdx.org/licenses for a list of choices), + +TextFiles or BinaryFiles or TextBinaryFilesPatterns + + a list of strings that specify which files in the archive are text files + or binary files (at most one of the three components can be available, + each string in TextBinaryFilesPatterns must start with T + for text files and by B for binary files), + +Persons + + a list of records, each with mandatory components + LastName (a string), FirstNames (a string), + at least one of IsAuthor or IsMaintainer + (true or false), + and optional components + PostalAddress, Place, Institution (each a string); + if the IsMaintainer value is true then also one of the + components + Email (a string), WWWHome (a string denoting an URL), + or PostalAddress (a string) is mandatory, + +SourceRepository + + a record with the components + Type (the version control system, e.g. "git" or "hg") + and URL (the URL of the repository), both strings, + +IssueTrackerURL + + a string started with http://, https://, or ftp://, + +SupportEmail + + a string denoting an e-mail address, + +Dependencies + + a record with the optional components + GAP (a string denoting the needed version of &GAP;), + NeededOtherPackages + (a list of pairs [ pkgname, pkgversion ] of strings, + denoting the other packages which must be available if the current package + shall be loadable), + SuggestedOtherPackages + (a list of pairs [ pkgname, pkgversion ] of strings, + denoting the other packages which shall be loaded together with the + current package if they are available), + OtherPackagesLoadedInAdvance + (a list of pairs [ pkgname, pkgversion ] of strings, + denoting the other packages that must be completely loaded before loading + of the current package is started), + ExternalConditions + (a list of strings or of pairs [ text, URL ] of strings, + denoting conditions on external programs), + +BannerString + + a string that is used as the package banner + (useful if the default banner string is not suitable), + +BannerFunction + + a function with no arguments that returns a string that is used + as the package banner + (useful if the banner shall show information that is available + only at runtime), + +TestFile + + a string denoting a relative path to a readable file + which contains tests of the package's functionality, + +Keywords + + a list of strings that are keywords related to the topic of the package. + + + + <#Include Label="ValidatePackageInfo">