[pacman-dev,v2] doc: Add a man page describing PKGINFO

From: Jelle van der Waa <jelle@archlinux.org>

Describe the PKGINFO format which resides in a package produced makepkg.
---
 doc/Makefile.am        |  4 +-
 doc/PKGINFO.5.asciidoc | 87 ++++++++++++++++++++++++++++++++++++++++++
 doc/meson.build        |  1 +
 3 files changed, 91 insertions(+), 1 deletion(-)
 create mode 100644 doc/PKGINFO.5.asciidoc

On 06/28/19 at 08:55pm, Jelle van der Waa wrote:
> From: Jelle van der Waa <jelle@archlinux.org>
> 
> Describe the PKGINFO format which resides in a package produced makepkg.
> ---
>  doc/Makefile.am        |  4 +-
>  doc/PKGINFO.5.asciidoc | 87 ++++++++++++++++++++++++++++++++++++++++++
>  doc/meson.build        |  1 +
>  3 files changed, 91 insertions(+), 1 deletion(-)
>  create mode 100644 doc/PKGINFO.5.asciidoc
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 5c575832..634388e8 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -16,7 +16,8 @@ MANPAGES = \
>  	pacman.conf.5 \
>  	libalpm.3 \
>  	BUILDINFO.5 \
> -	pacman-conf.8
> +	pacman-conf.8 \
> +	PKGINFO.5
>  
>  DOXYGEN_MANS = $(wildcard man3/*.3)
>  
> @@ -47,6 +48,7 @@ EXTRA_DIST = \
>  	makepkg.conf.5.asciidoc \
>  	pacman.conf.5.asciidoc \
>  	BUILDINFO.5.asciidoc \
> +	PKGINFO.5.asciidoc \
>  	libalpm.3.asciidoc \
>  	footer.asciidoc \
>  	index.asciidoc \
> diff --git a/doc/PKGINFO.5.asciidoc b/doc/PKGINFO.5.asciidoc
> new file mode 100644
> index 00000000..101ba34c
> --- /dev/null
> +++ b/doc/PKGINFO.5.asciidoc
> @@ -0,0 +1,87 @@
> +/////
> +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us:
> +/////

A few have sneaked in since the removal, but we don't include vim
modelines anymore.

> +PKGINFO(5)
> +==========
> +
> +Name
> +----
> +PKGINFO - package information file
> +
> +
> +Synopsis
> +--------
> +This manual page describes the format of a PKGINFO file found in the root of
> +a package created by makepkg. The file contains a description of the package's
> +information. The information is formatted in key-value pairs separated by
> +a '=', one value per line. Arrays are represented multiple keys with the same
> +value.

Key-value pairs are separated by " = ", not "=".

Arrays are represented by repeating the same key multiple times, each
line presumably has a different value, not the same one.

Empty lines and lines beginning with "#" are ignored.

> +
> +
> +Description
> +-----------
> +
> +*pkgname*::
> +	The name of the package.
> +
> +*pkgbase*::
> +	The base name of a package, usually the same as the pkgname except for
> +	split packages.
> +
> +*pkgver*::
> +	The version of the package including pkgrel and epoch.

This should include the actual format.

> +*pkgdesc*::
> +	A description of the software contained in the package.
> +
> +*url*::
> +	The upstream url of the package.

packaged software.

> +*builddate*::
> +	The build date of the package in epoch.
> +
> +*packager*::
> +	The packager of the package formatted "Name <Email>".

Neither makepkg nor libalpm says anything about the format of this
field, neither should this documentation.

> +*size*::
> +	The size of the package in bytes.

"installation size" or "packaged files", it is not the size of the
package itself.

> +*arch*::
> +	The architecture of the package.
> +
> +*license*::
> +	The license of the package.

License is an array.

> +*replaces (array)*::
> +	An array of packages that this package should replace.
> +
> +*group (array)*::
> +	An array of names that represent groups of packages.

Groups to which this package belongs.

> +*conflict (array)*::
> +	An array of packages that will conflict with this package.
> +
> +*provides (array)*::
> +	An array of "virtual provisions" this package provides.
> +
> +*backup (array)*::
> +	An array of file names, which should be backed up if the package is removed
> +	or upgraded.
> +
> +*depend (array)*::
> +	The dependencies of the package.
> +
> +*optdepend (array)*::
> +	The optional dependencies of the package.
> +
> +*makedepend (array)*::
> +	The make dependencies of the package.
> +
> +*checkdepend (array)*::
> +	The check dependencies of the package.

This should document the format for dependency values.

> +See Also
> +--------
> +linkman:makepkg[8], linkman:pkgbuild[5]
> +
> +include::footer.asciidoc[]
> diff --git a/doc/meson.build b/doc/meson.build
> index a5bcd5b3..2f966616 100644
> --- a/doc/meson.build
> +++ b/doc/meson.build
> @@ -12,6 +12,7 @@ manpages = [
>    { 'name': 'libalpm.3' },
>    { 'name': 'BUILDINFO.5' },
>    { 'name': 'pacman-conf.8' },
> +  { 'name': 'PKGINFO.5' },
>  ]
>  
>  sitepages = [
> -- 
> 2.22.0

On 6/28/19 2:55 PM, Jelle van der Waa wrote:
> From: Jelle van der Waa <jelle@archlinux.org>
> 
> Describe the PKGINFO format which resides in a package produced makepkg.
As mentioned on IRC, there's a lot of duplication with the PKGBUILD
fields, so I'd feel better if we could somehow document just a list of
fields and say that their contents are derived from the PKGBUILD(5) meaning.

The PKGINFO manpage should just describe the format of the file (as
given in the suggested synopsis) and pointers to where the relevant
metadata comes from.

Some PKGINFO keys are specific to the built package, e.g. size,
builddate, or mean something different, like arch/pkgver -- we should
document why and how they differ.

On 06/29/19 at 11:18pm, Eli Schwartz wrote:
> On 6/28/19 2:55 PM, Jelle van der Waa wrote:
> > From: Jelle van der Waa <jelle@archlinux.org>
> > 
> > Describe the PKGINFO format which resides in a package produced makepkg.
> As mentioned on IRC, there's a lot of duplication with the PKGBUILD
> fields, so I'd feel better if we could somehow document just a list of
> fields and say that their contents are derived from the PKGBUILD(5) meaning.
> 
> The PKGINFO manpage should just describe the format of the file (as
> given in the suggested synopsis) and pointers to where the relevant
> metadata comes from.
> 
> Some PKGINFO keys are specific to the built package, e.g. size,
> builddate, or mean something different, like arch/pkgver -- we should
> document why and how they differ.

This is low-level documentation.  If we're going to document the file
format, we should document it as libalpm sees it, not just the flavor
that makepkg generates.  For example, all of the dependency fields,
that includes provides, replaces, and conflicts, can have an optional
description even though makepkg doesn't allow one.  There are only
a handful of fields that actually map directly.