[pacman-dev] [PATCH 1/1] Add BUILDINFO man page

[Andrew Gregory]

On 01/01/18 at 02:53pm, Jelle van der Waa wrote:
> Add a new man page which describes the structure of a BUILDINFO file
> included in a package produced by makepkg.
> 
> Signed-off-by: Jelle van der Waa <jelle at vdwaa.nl>
> ---
>  doc/BUILDINFO.5.txt | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  doc/Makefile.am     |  4 +++-
>  2 files changed, 68 insertions(+), 1 deletion(-)
>  create mode 100644 doc/BUILDINFO.5.txt
> 
> diff --git a/doc/BUILDINFO.5.txt b/doc/BUILDINFO.5.txt
> new file mode 100644
> index 00000000..1a454497
> --- /dev/null
> +++ b/doc/BUILDINFO.5.txt
> @@ -0,0 +1,65 @@
> +/////
> +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us:
> +/////
> +BUILDINFO(5)
> +============
> +
> +Name
> +----
> +BUILDINFO - Arch Linux package build information file

I know you copied this from PKGBUILD(5), but we really shouldn't be
specifically referencing Arch in documentation other than as the
upstream source or the expansion of ALPM.  Just refer to makepkg here.

> +
> +Synopsis
> +--------
> +BUILDINFO

I'm assuming you just copied PKGBUILD(5) here, but this is a pretty
useless section.  If we're going to have a Synopsis section, I would
include some basic information like what BUILDINFO actually is (a
description of a package's build environment), the version of the
format that is being described, and the basic format (key-value pairs
separated by '=', one value per line).  Otherwise that information
needs to be added to Description.

> +
> +Description
> +-----------
> +This manual page describes the format of a BUILDINFO file usually found in a
> +package created by makepkg.
> +
> +Contents
> +--------

To my knowledge, Contents is not a commonly used man page section, I'd
just throw all of this in Description.

> +The following is a list of the contents and a description of the key value pairs
> +in a BUILDINFO file.
> +
> +*format*::
> +	Denotes the file format, represented by a number.

Can we be more specific here?  @Allan: do you intend to keep this as
a plain integer or use something more complex for updates?

> +*pkgname*::
> +	The name of the package.
> +
> +*pkgbase*::
> +	The name used to refer to the group of packages in the output of makepkg.

I find this wording is confusing.  For packages, "group" typically
refers to package groups, not split packages.

> +*pkgver*::
> +	The version of the package including pkgrel and epoch.
> +
> +*pkgbuild_sha256sum*::
> +	The sha256sum of the PKGBUILD used to build the package.

In hex format.

> +*packager*::
> +	The packager which has built the package.
> +
> +*builddate*

Missing ::

> +	The build date of the package in epoch.
> +
> +*builddir*::
> +	The build directory from which makepkg has been invoked.

Not true; it's where the package is built.

> +*buildenv (array)*::
> +	The set BUILDENV from makepkg.conf.

Nowhere is it described what it means for a key to be an array.  It
would probably be a good idea to specifically mention that disabled
options may be included with at '!' prefix.

> +*options (array)*::
> +	A combination of the OPTIONS set in makekg.conf merged with the options set
> +	in the used PKGBUILD.

Ditto.

> +*installed (array)*::
> +	The installed packages at build time including the version of the package.

The actual format of the package name and version should be described
here.  Looking at the actual code, this is also broken for any
packages that include spaces in the name...

> +See Also
> +--------
> +linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5]
> +
> +include::footer.txt[]
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 44e32996..bbf2af66 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -15,7 +15,8 @@ ASCIIDOC_MANS = \
>  	PKGBUILD.5 \
>  	makepkg.conf.5 \
>  	pacman.conf.5 \
> -	libalpm.3
> +	libalpm.3 \
> +	BUILDINFO.5
>  
>  DOXYGEN_MANS = $(wildcard man3/*.3)
>  
> @@ -58,6 +59,7 @@ EXTRA_DIST = \
>  	PKGBUILD-example.txt \
>  	makepkg.conf.5.txt \
>  	pacman.conf.5.txt \
> +	BUILDINFO.5.txt \
>  	libalpm.3.txt \
>  	footer.txt \
>  	index.txt \
> -- 
> 2.15.1