man: Write requested improvements to documentation

2 files changed, 183 insertions, 50 deletions

diff --git a/APKBUILD.5 b/APKBUILD.5
index 4392cd1..917c526 100644
--- a/APKBUILD.5
+++ b/APKBUILD.5
@@ -53,15 +53,13 @@ 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 specified
-must match the pattern
-.Li digit[.digit]*[_suffix[digit]]*
-where
-.Ar digit
-must be a number greater than or equal to zero,
-and
-.Ar suffix
-must be one of
+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).
+
+After the final number (and optional single letter), a suffix may be appended,
+which must be an underscore (_) followed by one of
 .Em alpha ,
 .Em beta ,
 .Em pre ,
@@ -71,15 +69,35 @@ must be one of
 .Em git ,
 .Em hg ,
 or
-.Em p .
+.Em p ,
+optionally followed by another number.  If the suffix is
+.Em alpha ,
+.Em beta ,
+.Em pre ,
+or
+.Em rc ,
+it is considered to be earlier than the version without a suffix; if the suffix
+is
+.Em cvs ,
+.Em svn ,
+.Em git ,
+.Em hg ,
+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:
+
+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.
 Always increment
 .Cm pkgrel
-when you change the contents or dependencies 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
@@ -100,6 +118,15 @@ 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.
+
+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.
+
 .It Cm license
 Specifies the license under which the package is distributed.  The value
 provided must match a SPDX license identifier.
@@ -109,6 +136,7 @@ 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.
+
 .El
 
 
@@ -118,15 +146,6 @@ The following variables are not required, but may be set in any
 file:
 
 .Bl -tag -width Ds
-.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.
-
-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.
-
 .It Cm depends
 Specifies the run-time dependencies of the package.  The
 .Xr abuild 1
@@ -168,7 +187,25 @@ for more information about install scripts.
 
 .It Cm provides
 Specifies that the package "provides" the same contents as another package.
-This is typically used for virtual dependencies.
+There are two formats that you may use for
+.Cm provides :
+a provider name, and a provider name with version.
+
+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 apk add foobar
+or similar, and it will conflict with a package named foobar.
+
+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 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
@@ -182,6 +219,63 @@ virtual provider.
 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
+for development files (such as /usr/include and static library files) and
+.Li Dq $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
+where
+.Li foo
+is the name of the split function specified later in the file.  Similar to the
+.Cm package
+function, the
+.Li foo
+function must move files from
+.Pa $pkgdir
+or
+.Pa $srcdir
+to
+.Pa $subpkgdir
+after creating
+.Pa $subpkgdir .
+
+The second method is to simply call the subpackage
+.Li Dq foo
+which will create a package called
+.Li foo
+instead of pkgname-foo.
+
+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
+where
+.Li foo
+is the name of the subpackage and
+.Li funcname
+is the name of the shell function in the
+.Nm
+that creates it.
+
+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
+will create the $pkgname-doc package using the
+.Cm doc
+function, the $pkgname-foo package using the
+.Cm foo
+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.
@@ -227,10 +321,14 @@ instead of using
 This is necessary for some test suites which fail when run as root.
 
 .It Cm !dbg
-(Adélie-specific) Specifies that the package should not be built with a debug
-information package.  This 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 (such as LLVM).
+Specifies that the package should not be built with a debug information
+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
@@ -279,7 +377,10 @@ 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 
+Specifies that the package's binaries are known to contain relocations against
+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
@@ -296,6 +397,47 @@ 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
+.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
+.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
+.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.
+
+.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
@@ -314,6 +456,7 @@ specified by appending
 where
 .Cm branch
 is the branch to checkout.
+
 .El
 
 
@@ -321,8 +464,7 @@ is the branch to checkout.
 Functions specified here may be present in any
 .Nm
 file, but with the exception of
-.Li build and
-.Li package ,
+.Cm package ,
 are not strictly required.
 
 .Bl -tag -width Ds
@@ -354,9 +496,7 @@ function.
 Compiles the source in
 .Ev builddir .
 You must implement this function yourself.  If no compilation is required, you
-may simply write
-.Li return 0
-to skip the build phase.
+may omit it.
 
 .It Cm check
 Runs the package's test suite.  This function must be implemented unless
@@ -437,32 +577,25 @@ will have no effect.
 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 ash shell, a part of
+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
 .St -p1003.2 ,
-but this cannot be fully relied upon.  The
+with some bash-like extensions.  The
 .Xr abuild 1
-utility as distributed by Adélie uses whatever the user has set as /bin/sh,
-which is typically
-.Xr bash 1
-or
-.Xr dash 1
-on Adélie systems.
-This is something to keep in mind as you write more complex packages.
-
-
-.Sh COMPATIBILITY
-It is highly recommended that package functions comply with
-.St -p1003.2
-for maximum compatibility.
+utility as distributed by Adélie uses the user's preferred /bin/sh, which is
+typically
+.Xr bash 1 .
 
 
 .Sh SEE ALSO
 
-The SPDX License List (Web copy at <https://spdx.org/licenses/>),
+SPDX license reference (on the Web at <https://spdx.org/licenses/>),
 .Xr abuild 1 ,
 .Xr newapkbuild 1 ,
 .Xr apk 8 .
diff --git a/newapkbuild.1 b/newapkbuild.1
index 93471b9..40db004 100644
--- a/newapkbuild.1
+++ b/newapkbuild.1
@@ -214,7 +214,7 @@ SPDX license reference (on the Web at <https://spdx.org/licenses/>),
 .Sh AUTHORS
 
 .Nm :
-.An Natanael Copa Aq ncopa@alpinelinux.org
+.An Natanael Copa Aq Mt ncopa@alpinelinux.org
 
 Documentation:
-.An A. Wilcox Aq awilfox@adelielinux.org
+.An A. Wilcox Aq Mt awilfox@adelielinux.org