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

[Andrew Gregory]

On 06/28/19 at 08:55pm, Jelle van der Waa wrote:
> From: Jelle van der Waa <jelle at 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