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