APKBUILD.5: fix mdoc syntax warnings

1 files changed, 170 insertions, 229 deletions

diff --git a/APKBUILD.5 b/APKBUILD.5
index ad3f82e..67f2eaa 100644
--- a/APKBUILD.5
+++ b/APKBUILD.5
@@ -1,17 +1,11 @@
 .Dd February 13, 2018
 .Dt APKBUILD 5 PRM
 .Os "Alpine Linux"
-
-
 .Sh NAME
 .Nm APKBUILD
 .Nd metadata and instructions to build a package
-
-
 .Sh SYNOPSIS
 .Nm /usr/src/packages/<repo>/<package>/APKBUILD
-
-
 .Sh DESCRIPTION
 An
 .Nm
@@ -19,10 +13,11 @@ file is used by tools such as
 .Xr abuild 1
 to build a package for eventual installation by the
 .Xr apk 8
-package manager.  It defines metadata such as the name of the package, the
-version information, the source license, and contact information for the
-developer.  It additionally contains the commands needed to build, test, and
-install the package.
+package manager.
+It defines metadata such as the name of the package, the version information,
+the source license, and contact information for the developer.
+It additionally contains the commands needed to build, test, and install the
+package.
 .Pp
 The
 .Nm
@@ -30,34 +25,34 @@ format is similar to a typical shell script; you set pre-defined variables and
 implement pre-defined functions, and the
 .Xr abuild 1
 (or similar) utility will use them to create the package.
-
-
 .Ss Required Variables
 The following variables must be set in all
 .Nm
 files:
-
 .Bl -tag -width Ds
 .It Cm pkgname
-Specifies name of the package.  This is typically the name of the package
-upstream; however, note that all letters must be lowercased.
+Specifies name of the package.
+This is typically the name of the package upstream; however, note that all
+letters must be lowercased.
 .Pp
 Libraries for scripting languages should have a prefix before the library name
-describing the language.  Such prefixes include
+describing the language.
+Such prefixes include
 .Em lua- ,
 .Em perl- ,
 .Em py- ,
 and
 .Em rb- .
-Not all languages use prefixes.  For a definitive list, consult the PREFIXES
-file in the root directory of the repository you are using for packaging.
-
+Not all languages use prefixes.
+For a definitive list, consult the PREFIXES file in the root directory of the
+repository you are using for packaging.
 .It Cm pkgver
-Specifies the version of the software being packaged.  The version of a package
-must consist of one or more numbers separated by the radix (decimal point).
+Specifies the version of the software being packaged.
+The version of a package must consist of one or more numbers separated by the
+radix (decimal point).
 The final number may have a single letter following it, for upstreams that use
 such a versioning scheme (such as 1.5a, 1.5b, 1.5c).
-
+.Pp
 After the final number (and optional single letter), a suffix may be appended,
 which must be an underscore (_) followed by one of
 .Em alpha ,
@@ -70,7 +65,8 @@ which must be an underscore (_) followed by one of
 .Em hg ,
 or
 .Em p ,
-optionally followed by another number.  If the suffix is
+optionally followed by another number.
+If the suffix is
 .Em alpha ,
 .Em beta ,
 .Em pre ,
@@ -85,132 +81,121 @@ is
 or
 .Em p ,
 it is considered to be later than the version without a suffix.
-
 All of the following examples are valid versions, in order from lowest to
 highest:
-
+.Pp
 1.0, 1.1_alpha2, 1.1.3_pre, 1.1.3, 1.1.3_hg, 1.2, 1.2a, 1.2b
-
 .It Cm pkgrel
-Specifies the package release number of this particular package version.  This
-indicates when a package has changed without a corresponding change in version.
+Specifies the package release number of this particular package version.
+This indicates when a package has changed without a corresponding change in
+version.
 Always increment
 .Cm pkgrel
-when you change the contents, dependencies, or metadata of a package.  The
-first release of a package is always
+when you change the contents, dependencies, or metadata of a package.
+The first release of a package is always
 .Li 0 .
-
 .It Cm pkgdesc
 Specifies what the package contains.
 .Cm pkgdesc
 must be 128 characters or less, and should concisely describe what actions the
-software or items being packaged will allow the user to perform.  For example,
-.Li Dq Fully-featured word processor with spell check and many plugins
+software or items being packaged will allow the user to perform.
+For example,
+.Dq Fully-featured word processor with spell check and many plugins
 would be a sufficient
 .Cm pkgdesc
 for AbiWord.
-
 .It Cm url
-Specifies the Web address of the package's upstream.  This allows users and
-future maintainers to find documentation, release information, and contact
-information for the package.  If no Web address is available for the package,
-you must set
+Specifies the Web address of the package's upstream.
+This allows users and future maintainers to find documentation, release
+information, and contact information for the package.
+If no Web address is available for the package, you must set
 .Cm url
 to an empty string ("").
-
 .It Cm arch
-Specifies the architectures for which the package may be built.  It is highly
-recommended that you set this variable to "all" if the package is portable.
-
+Specifies the architectures for which the package may be built.
+It is highly recommended that you set this variable to "all" if the package is
+portable.
+.Pp
 You may use "noarch" if the package does not contain any architecture-specific
-binary files - that is, any files that are compiled for the target only.  Such
-packages may include pure Python packages, shell script packages, and JARs.  If
-you are not sure what this means, using "all" is safe.
-
+binary files - that is, any files that are compiled for the target only.
+Such packages may include pure Python packages, shell script packages, and
+JARs.
+If you are not sure what this means, using "all" is safe.
 .It Cm license
-Specifies the license under which the package is distributed.  The value
-provided must match a SPDX license identifier.
-
+Specifies the license under which the package is distributed.
+The value provided must match a SPDX license identifier.
 .It Cm source
 Specifies the location of both local and remote source files used to build the
-package.  Typically, the remote source file(s) or archive(s) is specified,
-followed by any local patches, install scripts, configuration files, or other
-necessary files.
-
+package.
+Typically, the remote source file(s) or archive(s) is specified, followed by
+any local patches, install scripts, configuration files, or other necessary
+files.
 .El
-
-
 .Ss Optional Variables
 The following variables are not required, but may be set in any
 .Nm
 file:
-
 .Bl -tag -width Ds
 .It Cm checkdepends
-Specifies test-time dependencies of the package.  Common packages that are
-used for testing include check, dejagnu, and perl-test-command.
-
+Specifies test-time dependencies of the package.
+Common packages that are used for testing include check, dejagnu, and
+perl-test-command.
 .It Cm depends
-Specifies the run-time dependencies of the package.  The
+Specifies the run-time dependencies of the package.
+The
 .Xr abuild 1
 utility will automatically scan the resultant package for shared library (.so)
 dependencies; do not specify them here.
-
 .It Cm install
-Specifies install scripts for the package, if any.  See
+Specifies install scripts for the package, if any.
+See
 .Sx Install Scripts
 for more information about install scripts.
-
 .It Cm install_if
 Specifies a condition when
 .Xr apk 8
-should automatically install the package (or subpackage).  For instance, the
-OpenRC subpackages set
+should automatically install the package (or subpackage).
+For instance, the OpenRC subpackages set
 .Cm install_if
 to
-.Li Dq $pkgname=$pkgver openrc
+.Li $pkgname=$pkgver openrc
 which means that the OpenRC subpackage will be automatically installed if the
 origin package and OpenRC are both installed on the same computer.
-
 .It Cm makedepends
 Specifies build dependencies for the package.
-
 .It Cm pkggroups
 Specifies a space-separated list of login groups to create during build-time.
 Note that you will need to create the login groups in a pre-install install
 script as well; see
 .Sx Install Scripts
 for more information about install scripts.
-
 .It Cm pkgusers
 Specifies a space-separated list of user logins to create during build-time.
 Note that you will ned to create the user logins in a pre-install install
 script as well; see
 .Sx Install Scripts
 for more information about install scripts.
-
 .It Cm provides
 Specifies that the package "provides" the same contents as another package.
 There are two formats that you may use for
 .Cm provides :
 a provider name, and a provider name with version.
-
+.Pp
 Specifying a provider name with version such as
-.Li Dq foobar=1.2
-will cause the package to be an "alias" of foobar version 1.2.  It will be
-automatically installed if a user then runs
+.Li foobar=1.2
+will cause the package to be an "alias" of foobar version 1.2.
+It will be automatically installed if a user then runs
 .Li apk add foobar
 or similar, and it will conflict with a package named foobar.
-
+.Pp
 Specifying a provider name without a version such as
-.Li Dq baz
-will cause the package to provide a "virtual" called baz.  Multiple packages
-with the same virtual provider can be installed on a system; however, if a user
-runs
+.Li baz
+will cause the package to provide a "virtual" called baz.
+Multiple packages with the same virtual provider can be installed on a system;
+however, if a user runs
 .Li apk add baz
 they will provided a list of packages that provide baz and must select one and
 install it.
-
 .It Cm provider_priority
 Specifies the numeric value for
 .Xr apk 8
@@ -218,25 +203,24 @@ to use for the package when considering which provider should be installed for
 the same
 .Cm provides
 virtual provider.
-
 .It Cm replaces
-Specifies packages that the package replaces.  This is typically used for
-packages renamed by upstream.
-
+Specifies packages that the package replaces.
+This is typically used for packages renamed by upstream.
 .It Cm subpackages
-Specifies subpackages or split packages built with this package.  Typically,
-this will include
-.Li Dq $pkgname-dev
+Specifies subpackages or split packages built with this package.
+Typically, this will include
+.Li $pkgname-dev
 for development files (such as /usr/include and static library files) and
-.Li Dq $pkgname-doc
+.Li $pkgname-doc
 for documentation (such as /usr/share/doc and /usr/share/man).
-
-Each subpackage may be specified using three different methods.  The first, and
-most common, is
-.Li Dq $pkgname-foo
+.Pp
+Each subpackage may be specified using three different methods.
+The first, and most common, is
+.Li $pkgname-foo
 where
 .Li foo
-is the name of the split function specified later in the file.  Similar to the
+is the name of the split function specified later in the file.
+Similar to the
 .Cm package
 function, the
 .Li foo
@@ -248,18 +232,18 @@ to
 .Pa $subpkgdir
 after creating
 .Pa $subpkgdir .
-
+.Pp
 The second method is to simply call the subpackage
-.Li Dq foo
+.Li foo
 which will create a package called
 .Li foo
 instead of pkgname-foo.
-
+.Pp
 However,
 .Li foo
 in both of these examples cannot contain a hyphen, as shell function names
 cannot have hyphens in them.  In this case, the third method may be used:
-.Li Dq foo:funcname
+.Li foo:funcname
 where
 .Li foo
 is the name of the subpackage and
@@ -267,11 +251,12 @@ is the name of the subpackage and
 is the name of the shell function in the
 .Nm
 that creates it.
-
+.Pp
 Note that an additional colon may be used to specify an architecture for the
 subpackage; typically, this is used for marking miscellaneous files that are
-not architecture-specific as noarch.  For example,
-.Li Dq $pkgname-doc $pkgname-foo $pkgname-foo-misc:foo_misc:noarch
+not architecture-specific as noarch.
+For example,
+.Li $pkgname-doc $pkgname-foo $pkgname-foo-misc:foo_misc:noarch
 will create the $pkgname-doc package using the
 .Cm doc
 function, the $pkgname-foo package using the
@@ -279,68 +264,61 @@ function, the $pkgname-foo package using the
 function, and the $pkgname-foo-misc package using the
 .Cm foo_misc
 function and set $pkgname-foo-misc as noarch.
-
 .It Cm triggers
-Specifies a trigger script used by the package.  A trigger script is a shell
-script that is called whenever monitored files or directories are modified.
+Specifies a trigger script used by the package.
+A trigger script is a shell script that is called whenever monitored files or
+directories are modified.
 You may specify the paths to monitor using the triggers variable as follows:
-
-.Li Dq $pkgname.trigger=/usr/share/man:/usr/local/share/man
-
+.Pp
+.Li $pkgname.trigger=/usr/share/man:/usr/local/share/man
+.Pp
 This will run the package trigger script whenever files in
 .Pa /usr/share/man
 or
 .Pa /usr/local/share/man
 are created, modified, or removed.
-
 .El
-
-
 .Ss options
 The
 .Cm options
-variable allows you to set parameters for the package at build time.  There are
-a number of valid options you may set, and you may set multiple options by
-inserting a space between each one.
-
+variable allows you to set parameters for the package at build time.
+There are a number of valid options you may set, and you may set multiple
+options by writing a space between each one.
 .Bl -tag -width Ds
 .It Cm !archcheck
 Specifies that the package contains binaries that cannot run on the target
-architecture.  This is primarily used for packages containing firmware, and
-should typically never need to be used.
-
+architecture.
+This is primarily used for packages containing firmware, and should typically
+never need to be used.
 .It Cm charset.alias
 Specifies that the package ships a /usr/lib/charset.alias file and that it
-should be installed on the user's system.  This is almost never the case.  Do
-not use this option.
-
+should be installed on the user's system.
+This is almost never the case.
+Do not use this option.
 .It Cm !check
-Specifies that the package will not run a test suite.  The reason for disabling
-the check phase should be noted in a comment.
-
+Specifies that the package will not run a test suite.
+The reason for disabling the check phase should be noted in a comment.
 .It Cm !checkroot
 Specifies that the package's test suite will be run as a non-privileged user
 instead of using
 .Xr fakeroot 8 .
 This is necessary for some test suites which fail when run as root.
-
 .It Cm !dbg
 Specifies that the package should not be built with a debug information
-package.  This is the default unless
+package.
+This is the default unless
 .Ev DEFAULT_DBG
 is set in the environment or
 .Xr abuild.conf 5 .
 It is typically used on packages that do not generate debug information (such
 as pure Python packages) or packages that do not support debug information
 packages.
-
 .It Cm !fhs
 Specifies that the package violates FHS and installs to a location such as
 .Pa /usr/local ,
 .Pa /opt ,
 or
 .Pa /srv .
-
 .It Cm ldpath-recursive
 Specifies that
 .Xr abuild 1
@@ -349,99 +327,84 @@ should use the
 argument to
 .Xr scanelf 1
 when attempting to find shared library (.so) dependencies for the package.
-
 .It Cm libtool
-Specifies that the package requires its libtool (.la) files.  They will not be
-automatically removed by
+Specifies that the package requires its libtool (.la) files.
+They will not be automatically removed by
 .Xr abuild 1 .
-
 .It Cm net
-Specifies that the package build system requires access to a network.  This is
-discouraged and an issue should be filed with the package's authors.
-
+Specifies that the package build system requires access to a network.
+This is discouraged and an issue should be filed with the package's authors.
 .It Cm !strip
 Specifies that
 .Xr strip 1
-should not be run on any of the package's binaries.  This is automatically
-implied if the -dbg subpackage is enabled, or if you are using
+should not be run on any of the package's binaries.
+This is automatically implied if the -dbg subpackage is enabled, or if you are
+using
 .Ev DEFAULT_DBG .
-
 .It Cm suid
-Specifies that binaries in the package may be installed set-uid.  This is a
-security risk and it is highly recommended to use capabilities or process
-separation instead of set-uid where available.
-
+Specifies that binaries in the package may be installed set-uid.
+This is a security risk and it is highly recommended to use capabilities or
+process separation instead of set-uid where available.
 .It Cm textrels
 Specifies that the package's binaries are known to contain relocations against
-text segments.  By default,
+text segments.
+By default,
 .Xr abuild 1
 will refuse to create such a package because this is a security concern.
-
 .It Cm toolchain
 Specifies that the package is part of the base toolchain set and may depend
 on packages like
 .Li g++ .
-
 .It Cm !tracedeps
 Specifies that
 .Xr abuild 1
 should not automatically populate
 .Cm depends
 with shared library (.so) or symlink target dependencies.
-
 .El
-
-
 .Ss Automatic Variables
 The following variables are defined for you by
 .Xr abuild 1 ,
 but may be overridden if necessary.
-
 .Bl -tag -width Ds
 .It Cm builddir
 Specifies the directory where the source code of the package will be built.
 The default value is
 .Pa $srcdir/$pkgname-$pkgver
-which is appropriate for most source distributions.  If the source tarball does
-not create a $pkgname-$pkgver directory when it is unpacked, you must override
+which is appropriate for most source distributions.
+If the source tarball does not create a $pkgname-$pkgver directory when it is
+unpacked, you must override
 .Cm builddir .
-
 .It Cm pkgdir
-Specifies the directory where the built files will be installed.  Typically,
-you will call
-.Li Dq make DESTDIR="$pkgdir" install
-or similar to install the files.  The default value is
+Specifies the directory where the built files will be installed.
+Typically, you will call
+.Li make DESTDIR="$pkgdir" install
+or similar to install the files.
+The default value is
 .Pa $startdir/pkg
 and you should not modify this variable.
-
 .It Cm srcdir
 Specifies the directory where the files specified in
 .Cm source
-are downloaded and unpacked.  The default value is
+are downloaded and unpacked.
+The default value is
 .Pa $startdir/src
 and you should not need to modify this.
-
 .It Cm startdir
 Specifies the directory where the
 .Nm
 file resides.
-
 .It Cm subpkgdir
-Specifies the directory where the subpackage's files should be placed.  This
-variable is only set inside subpackage functions.
-
+Specifies the directory where the subpackage's files should be placed.
+This variable is only set inside subpackage functions.
 .El
-
-
 .Ss Special Variables
 The following variables are used only in special circumstances, and may be
 required or optional depending on their usage and the contents of other
 variables.
-
 .Bl -tag -width Ds
 .It Cm depends_dev
 Specifies the run-time dependencies of the -dev subpackage.
-
 .It Cm giturl
 Specifies the URL of the Git repository to use with
 .Cm abuild checkout .
@@ -451,32 +414,27 @@ specified by appending
 where
 .Cm branch
 is the branch to checkout.
-
 .El
-
-
 .Ss Functions
 Functions specified here may be present in any
 .Nm
 file, but with the exception of
 .Cm package ,
 are not strictly required.
-
 .Bl -tag -width Ds
 .It Cm fetch
 This function is called to download the remote files in
 .Cm source .
-
 .It Cm unpack
 This function unpacks any archives in
 .Cm source
 to
 .Ev srcdir .
-
 .It Cm prepare
 Prepares the source in
 .Ev srcdir
-to be built.  The default
+to be built.
+The default
 .Cm prepare
 function ensures the build directories are set up correctly and applies any
 *.patch files specified in
@@ -486,19 +444,17 @@ You must call
 if you write a custom
 .Cm prepare
 function.
-
 .It Cm build
 Compiles the source in
 .Ev builddir .
-You must implement this function yourself.  If no compilation is required, you
-may omit it.
-
+You must implement this function yourself.
+If no compilation is required, you may omit it.
 .It Cm check
-Runs the package's test suite.  This function must be implemented unless
-.Li Dq !check
+Runs the package's test suite.
+This function must be implemented unless
+.Li !check
 was specified in
 .Cm options .
-
 .It Cm package
 Installs the package into
 .Ev pkgdir .
@@ -508,116 +464,101 @@ is not created for you; if this package installs no files (for example, a
 metapackage), you must use
 .Li mkdir -p "$pkgdir"
 to skip the package phase.
-
 .El
-
-
 .Ss Install Scripts
 An install script is run when an action is taken on a package by
 .Xr apk 8 .
 An install script must be written in shell and must have a
-.Li Dq #!/bin/sh
-interpreter declaration as the first line.  The
+.Li #!/bin/sh
+interpreter declaration as the first line.
+The
 .Cm install
 variable must contain the install scripts needed by the package.
-
+.Pp
 The install script will be run inside the root filesystem where the package is
-being installed.  A single argument will be passed to all scripts, which is the
-version of the package being currently installed (or deinstalled).  The
-pre-upgrade and post-upgrade scripts will have an additional second argument,
-which specifies the version of the package before the upgrade process.
-
+being installed.
+A single argument will be passed to all scripts, which is the version of the
+package being currently installed (or deinstalled).
+The pre-upgrade and post-upgrade scripts will have an additional second
+argument, which specifies the version of the package before the upgrade
+process.
+.Pp
 The different actions that may have install scripts specified are as follows:
-
 .Bl -tag -width Ds
 .It Ic $pkgname.pre-install
-Executed before the package is installed.  If this script exits with an error
-(non-zero exit code),
+Executed before the package is installed.
+If this script exits with an error (non-zero exit code),
 .Xr apk 8
-will halt the installation and the package will not be installed.  This install
-script is typically used to create any users or groups needed as described in
+will halt the installation and the package will not be installed.
+This install script is typically used to create any users or groups needed as
+described in
 .Cm pkggroups
 and
 .Cm pkgusers .
-
 .It Ic $pkgname.post-install
-Executed after the package is installed.  If this script exits with an error
-(non-zero exit code),
+Executed after the package is installed.
+If this script exits with an error (non-zero exit code),
 .Xr apk 8
-will mark the package as broken.  The
+will mark the package as broken.
+The
 .Li apk fix
 command will attempt to re-run the post-install script if this occurs.
-
 .It Ic $pkgname.pre-upgrade
-Executed before the package is upgraded.  If this script exits with an error
-(non-zero exit code),
+Executed before the package is upgraded.
+If this script exits with an error (non-zero exit code),
 .Xr apk 8
 will mark the package as broken.
-
 .It Ic $pkgname.post-upgrade
-Executed after the package is upgraded.  If this script exits with an error
-(non-zero exit code),
+Executed after the package is upgraded.
+If this script exits with an error (non-zero exit code),
 .Xr apk 8
-will mark the package as broken.  The
+will mark the package as broken.
+The
 .Li apk fix
 command will attempt to re-run the post-upgrade script if this occurs.
-
 .It Ic $pkgname.pre-deinstall
-Executed before the package is removed from the system.  If this script exits
-with an error (non-zero exit code),
+Executed before the package is removed from the system.
+If this script exits with an error (non-zero exit code),
 .Xr apk 8
 will not remove the package from the system.
-
 .It Ic $pkgname.post-deinstall
-Executed after the package is removed from the system.  Exiting with an error
-will have no effect.
-
+Executed after the package is removed from the system.
+Exiting with an error will have no effect.
 .El
-
-
 .Sh IMPLEMENTATION NOTES
 Currently,
 .Nm
 files are sourced as normal shell scripts.  This may change at a later date.
-
-
 .Sh COMPATIBILITY
 The
 .Xr abuild 1
 utility as distributed by Alpine uses the BusyBox Almquist shell, a part of
 .Xr busybox 1
-that is currently undocumented.  It is mostly compliant with
+that is currently undocumented.
+It is mostly compliant with
 .St -p1003.2 ,
-with some bash-like extensions.  The
+with some bash-like extensions.
+The
 .Xr abuild 1
 utility as distributed by Adélie uses the user's preferred /bin/sh, which is
 typically
 .Xr bash 1 .
-
-
 .Sh SEE ALSO
-
 SPDX license reference (on the Web at <https://spdx.org/licenses/>),
 .Xr abuild 1 ,
 .Xr newapkbuild 1 ,
 .Xr apk 8 .
-
-
 .Sh HISTORY
 The
 .Nm
 format and
 .Xr abuild 1
 utility first appeared in Alpine Linux 1.9.
-
-
 .Sh AUTHORS
 .An Timo Teräs Aq Mt timo.teras@iki.fi
 .An Natanael Copa Aq Mt ncopa@alpinelinux.org
-
+.Pp
 Documentation:
 .An A. Wilcox Aq Mt awilfox@adelielinux.org
-
-
 .\" .Sh BUGS
 .\" if we end up finding bugs that should be documented, put them here.