From 99f70da13cfcf57e457639b318a04250aa2c36c9 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Apr 04 2024 16:47:04 +0000 Subject: Add semantic linebreaks. Adds semantic linebreaks to the GAP guidelines page. --- diff --git a/guidelines/modules/ROOT/pages/GAP.adoc b/guidelines/modules/ROOT/pages/GAP.adoc index 08deeb4..1793add 100644 --- a/guidelines/modules/ROOT/pages/GAP.adoc +++ b/guidelines/modules/ROOT/pages/GAP.adoc @@ -1,42 +1,82 @@ = 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-rpm-macros, 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. +The main GAP package and its attendant libraries and help system +are in packages named +gap, gap-libs, gap-core, gap-online-help, +gap-rpm-macros, 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 frequently distributed in tarballs with a top-level directory of the form `addon-version`. +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 frequently distributed in tarballs +with a top-level directory of the form `addon-version`. The add-on SHOULD be installed without the version number. -Documentation for one package often crosslinks into documentation for other packages. -If the directories involved contain version numbers, then the crosslinks can be broken by a package upgrade. +Documentation for one package often crosslinks +into documentation for other packages. +If the directories involved contain version numbers, +then the crosslinks can be broken by a package upgrade. Avoid this situation by omitting the version numbers. -GAP itself can retrieve the version number from the add-on's `+PackageInfo.g+` file, so no information is lost. +GAP itself can retrieve the version number from the add-on's +`+PackageInfo.g+` file, so no information is lost. == 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+` @@ -48,33 +88,54 @@ Add-ons containing any of the following files should be modified to link to the === 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 -All add-ons MUST include `+Requires: gap-core+`, either directly or transitively. -In addition, dependencies on other GAP packages, as recorded in `+PackageInfo.g+`, MUST be specified, with the exception of `+GAPDoc+`, as noted above. -GAP has a 2-level dependency system, specified with `+NeededOtherPackages+` and `+SuggestedOtherPackages+` tags in `+PackageInfo.g+`. -How these dependencies map onto the 3-level RPM dependency system of Requires, Recommends, and Suggests is left to the discretion of the Fedora packager. +All add-ons MUST include `+Requires: gap-core+`, +either directly or transitively. +In addition, dependencies on other GAP packages, +as recorded in `+PackageInfo.g+`, +MUST be specified, +with the exception of `+GAPDoc+`, as noted above. +GAP has a 2-level dependency system, +specified with +`+NeededOtherPackages+` +and `+SuggestedOtherPackages+` +tags in `+PackageInfo.g+`. +How these dependencies map onto the 3-level RPM dependency system +of Requires, Recommends, and Suggests +is left to the discretion of the Fedora packager. == 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. +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.) * Files for building documentation, often called `+make_doc+` -* Files generated by LaTeX and associated tools, including files with these suffixes: +* Files generated by LaTeX and associated tools, +including files with these suffixes: ** .aux ** .bbl ** .blg @@ -84,26 +145,55 @@ Files that should not appear there include: ** .log ** .toc -Note that License files MUST still be included in the package with the %license tag, and other documentation such as README files can be included as %doc. +Note that License files MUST still be included in the package +with the %license tag, +and other documentation such as README files +can be included as %doc. -The `+%gap_copy_docs+` macro is intended to make installation of documentation files easier. -For most packages, ensure that the `doc` subdirectory exists in the buildroot, then invoke the macro without arguments in `+%install+`. +The `+%gap_copy_docs+` macro is intended +to make installation of documentation files easier. +For most packages, +ensure that the `doc` subdirectory exists in the buildroot, +then invoke the macro without arguments in `+%install+`. For special cases, two optional arguments can be given: -* `+-d directory+`: for cases where the documentation directory is not named `doc`, or there are multiple documentation directories -* `+-n package+`: the installed add-on directory name is assumed to be available from a macro `+%pkgname+`. If that is not the case, use this macro to give the main add-on directory name. +* `+-d directory+`: +for cases where the documentation directory is not named `doc`, +or there are multiple documentation directories + +* `+-n package+`: +the installed add-on directory name is assumed +to be available from a macro `+%pkgname+`. + If that is not the case, +use this macro to give the main add-on directory name. == 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+`. == Other RPM macros -Other RPM macros that may be useful for GAP add-on spec files include the following: +Other RPM macros that may be useful + for GAP add-on spec files include the following: + +* `+%gap_version+`: +the version of the main GAP package; e.g., 4.12.0. + +* `+%gap_archdir+`: + parent directory for arch-specific GAP add-ons, +currently `+%{_libdir}/gap+`. + +* `+%gap_libdir+`: + the root directory of the GAP installation, currently `+%{_datadir}/gap+`. -* `+%gap_version+`: the version of the main GAP package; e.g., 4.12.0. -* `+%gap_archdir+`: parent directory for arch-specific GAP add-ons, currently `+%{_libdir}/gap+`. -* `+%gap_libdir+`: the root directory of the GAP installation, currently `+%{_datadir}/gap+`. -* `+%gap_arch+`: the GAP name for the build architecture; e.g., `x86_64-redhat-linux-gnu`. +* `+%gap_arch+`: + the GAP name for the build architecture; e.g., `x86_64-redhat-linux-gnu`.