From 8b3c2cb6918b3f4571ec1624b273deff97ea35d7 Mon Sep 17 00:00:00 2001 From: Jerry James Date: Feb 16 2023 23:03:27 +0000 Subject: Add semantic line breaks to GAP.adoc --- diff --git a/guidelines/modules/ROOT/pages/GAP.adoc b/guidelines/modules/ROOT/pages/GAP.adoc index 7d48af4..13a6fd2 100644 --- a/guidelines/modules/ROOT/pages/GAP.adoc +++ b/guidelines/modules/ROOT/pages/GAP.adoc @@ -1,16 +1,24 @@ = GAP Packaging Guidelines -This document describes the conventions and customs surrounding the proper packaging of https://www.gap-system.org/[GAP] add-on packages in Fedora. Throughout this document, we use the word _add-on_ to substitute for GAP upstream's use of the word _package_, to avoid confusion with RPM packages. +This document describes the conventions and customs surrounding the proper packaging of https://www.gap-system.org/[GAP] add-on packages in Fedora. +Throughout this document, we use the word _add-on_ to substitute for GAP upstream's use of the word _package_, to avoid confusion with RPM packages. == Naming -The main GAP package and its attendant libraries and help system are in packages named gap, gap-libs, gap-core, gap-online-help, gap-devel, gap-vim, and libgap. To distinguish add-on packages from these core packages, add-ons MUST have names of the form gap-pkg-foo. For example, the FGA add-on is named gap-pkg-fga. +The main GAP package and its attendant libraries and help system are in packages named gap, gap-libs, gap-core, gap-online-help, gap-devel, gap-vim, and libgap. +To distinguish add-on packages from these core packages, add-ons MUST have names of the form gap-pkg-foo. +For example, the FGA add-on is named gap-pkg-fga. == Add-on Location Architecture-independent (noarch) packages MUST be installed in `+%{gap_libdir}/pkg/%{pkgname}+`, and architecture-specific packages in `+%{gap_archdir}/pkg/%{pkgname}+`, where `+%{pkgname}+` expands to the GAP name for the add-on. -GAP add-ons are written to be installed simply by unpacking them in an existing GAP directory tree. For most add-ons, the only build action necessary is building the documentation. However, since the add-on authors assumed this would happen within the GAP tree, add-ons freely use relative paths to access GAP files. For example, packages that use TTH to build documentation (see below) commonly invoke `+../../../convert.pl+`. The RPM spec file MUST account for this, either by altering the add-on to point to paths under `+%{gap_libdir}+`, or by creating symbolic links to create the appearance that the build is taking place inside the GAP tree. If the add-on is altered for the build, the spec file SHOULD arrange for the original (unaltered) files to be installed, so that paths are correct after installation. +GAP add-ons are written to be installed simply by unpacking them in an existing GAP directory tree. +For most add-ons, the only build action necessary is building the documentation. +However, since the add-on authors assumed this would happen within the GAP tree, add-ons freely use relative paths to access GAP files. +For example, packages that use TTH to build documentation (see below) commonly invoke `+../../../convert.pl+`. +The RPM spec file MUST account for this, either by altering the add-on to point to paths under `+%{gap_libdir}+`, or by creating symbolic links to create the appearance that the build is taking place inside the GAP tree. +If the add-on is altered for the build, the spec file SHOULD arrange for the original (unaltered) files to be installed, so that paths are correct after installation. GAP add-ons are frequently distributed in tarballs with a top-level directory of the form `addon-version`. The add-on SHOULD be installed without the version number. @@ -21,11 +29,14 @@ GAP itself can retrieve the version number from the add-on's `+PackageInfo.g+` f == BuildRequires -All add-ons MUST include `+BuildRequires: gap-devel+`, as that package contains essential tools needed for compiling binary modules and building documentation, as well as a set of RPM macros for use in spec files. Each add-on also MUST contain a `+BuildRequires+` that is dependent on the documentation style used by the GAP add-on. +All add-ons MUST include `+BuildRequires: gap-devel+`, as that package contains essential tools needed for compiling binary modules and building documentation, as well as a set of RPM macros for use in spec files. +Each add-on also MUST contain a `+BuildRequires+` that is dependent on the documentation style used by the GAP add-on. === TTH -Add-ons that use a `+buildman.pe+` or `+convert.pl+` script to build documentation also need `+BuildRequires: tth+` in order to build HTML documentation pages from TeX input. Some add-ons bundle these scripts, as well as a few auxiliary files. Add-ons containing any of the following files should be modified to link to the version of the file contained in the gap or gap-devel packages. +Add-ons that use a `+buildman.pe+` or `+convert.pl+` script to build documentation also need `+BuildRequires: tth+` in order to build HTML documentation pages from TeX input. +Some add-ons bundle these scripts, as well as a few auxiliary files. +Add-ons containing any of the following files should be modified to link to the version of the file contained in the gap or gap-devel packages. * `+gapmacro.tex+` → `+%{gap_libdir}/doc/gapmacro.tex+` * `+gapmacrodoc.tex+` → `+%{gap_libdir}/doc/gapmacrodoc.tex+` @@ -37,11 +48,13 @@ Add-ons that use a `+buildman.pe+` or `+convert.pl+` script to build documentati === GAPDoc -Add-ons that use GAPDoc to build documentation MUST include `+BuildRequires: GAPDoc-latex+` to pull in the necessary LaTeX packages. These packages do not need `+Requires: GAPDoc+`, since `+gap-core+` depends on GAPDoc. +Add-ons that use GAPDoc to build documentation MUST include `+BuildRequires: GAPDoc-latex+` to pull in the necessary LaTeX packages. +These packages do not need `+Requires: GAPDoc+`, since `+gap-core+` depends on GAPDoc. === Autodoc -Add-ons that use Autodoc to build documentation MUST include `+BuildRequires: gap-pkg-autodoc+`. Such packages do not need to include `+BuildRequires: GAPDoc-latex+`, as the Autodoc package `+Requires: GAPDoc-latex+`. +Add-ons that use Autodoc to build documentation MUST include `+BuildRequires: gap-pkg-autodoc+`. +Such packages do not need to include `+BuildRequires: GAPDoc-latex+`, as the Autodoc package `+Requires: GAPDoc-latex+`. == Requires, Recommends, and Suggests @@ -52,7 +65,11 @@ How these dependencies map onto the 3-level RPM dependency system of Requires, R == Unnecessary Files -GAP add-ons are intended to be unpacked in place within a GAP directory tree. Ordinarily, the entire distribution directory is copied into `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+`. This includes the documentation directories, which are consumed by the tools contained in gap-online-help. However, some files are not needed in the final install directory. Files that should not appear there include: +GAP add-ons are intended to be unpacked in place within a GAP directory tree. +Ordinarily, the entire distribution directory is copied into `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+`. +This includes the documentation directories, which are consumed by the tools contained in gap-online-help. +However, some files are not needed in the final install directory. +Files that should not appear there include: * Textual descriptions of the add-on, such as a README * License files (COPYING, COPYRIGHT, LICENSE, etc.) @@ -78,7 +95,9 @@ For special cases, two optional arguments can be given: == Documentation -Since GAP documentation MUST be installed under `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+` for the builtin documentation browser to find it, such documentation SHOULD NOT be duplicated with `+%doc+`. However, the documentation SHOULD still be marked as such so that documentation-free installs work as expected. Most add-ons SHOULD include `+%docdir+` declarations in the `+%files+` section of the spec file; e.g., `+%docdir %{gap_libdir}/pkg/%{pkgname}/doc+` and `+%docdir %{gap_libdir}/pkg/%{pkgname}/htm+`. +Since GAP documentation MUST be installed under `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+` for the builtin documentation browser to find it, such documentation SHOULD NOT be duplicated with `+%doc+`. +However, the documentation SHOULD still be marked as such so that documentation-free installs work as expected. +Most add-ons SHOULD include `+%docdir+` declarations in the `+%files+` section of the spec file; e.g., `+%docdir %{gap_libdir}/pkg/%{pkgname}/doc+` and `+%docdir %{gap_libdir}/pkg/%{pkgname}/htm+`. == Architecture