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

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@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

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@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

Thanks for the review!

On 01/04/18 at 07:23pm, Andrew Gregory wrote:
> On 01/01/18 at 02:53pm, Jelle van der Waa wrote:
> > +----
> > +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.

Yup, I agree wil adjust this.
> 
> > +
> > +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.

I'll adjust this in v2.

> > +
> > +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.

Ack.

> > +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?

More specific as in? I guess "file format version" would be more
specific?

> > +*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.

Maybe the PKGBUILD man page needs a patch to reword this. I'll try to
improve the text.

> 
> > +*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.

Do you mean I should describe what an array is? I guess that should be
done in the Synopsis.

 
> > +*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...

Spaces in a name is not legal I assume?

On 06/01/18 09:56, Jelle van der Waa wrote:
>>> +*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?
> More specific as in? I guess "file format version" would be more
> specific?
> 


It will stay an integer.

A

On 01/06/18 at 12:56am, Jelle van der Waa wrote:
> Thanks for the review!
> 
> On 01/04/18 at 07:23pm, Andrew Gregory wrote:
> > On 01/01/18 at 02:53pm, Jelle van der Waa wrote:

...

> > > +
> > > +*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?
> 
> More specific as in? I guess "file format version" would be more
> specific?

I meant more specific as in what kind of number (i.e. a plain positive
integer as opposed to a float).

...

> > > +*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...
> 
> Spaces in a name is not legal I assume?

Unfortunately, what makepkg accepts as a valid package name and what
libalpm accepts are not the same (improving that is on my TODO list).
libalpm accepts any characters except '\n', '/', and NUL.  The
packages being listed weren't necessarily built by makepkg, so they
can include the full range of characters that libalpm allows.

I keep a list of the various pacman/alpm/makepkg restrictions here:
https://wiki.archlinux.org/index.php/User:Apg#pacman_LIMITS