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

[Jelle van der Waa]

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?

-- 
Jelle van der Waa
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: not available
URL: <https://lists.archlinux.org/pipermail/pacman-dev/attachments/20180106/deada9e1/attachment.asc>