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

[Allan McRae]

On 22/6/19 7:39 am, 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 | 86 ++++++++++++++++++++++++++++++++++++++++++
>  doc/meson.build        |  1 +
>  3 files changed, 90 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..2da25c5b
> --- /dev/null
> +++ b/doc/PKGINFO.5.asciidoc
> @@ -0,0 +1,86 @@
> +/////
> +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us:
> +/////
> +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.

Suggested edit:
The file contains the package's metadata  formatted in key-value pairs,
separated by a '=' and with one value per line.

> +
> +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.
> +
> +*pkgdesc*::
> +	A description of the package.

A description of the software contained in the package.

> +
> +*url*::
> +	The upstream of the package.


upstream url

> +*builddate*::
> +	The build date of the package in epoch.
> +
> +*packager*::
> +	The packager of the package formatted Foo <foo at bar.com>.

usually formatted "Name <Email>"

(there is not restriction on format)

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

in (units)

> +*arch*::
> +	The architecture of the package.
> +
> +*license*::
> +	The license of the package.
> +
> +*replaces (array)*::
> +	An array of packages this package should replace.

packages that this package

> +
> +*group (array)*::
> +	An array of symbolic names that represent groups of packages.
> +

Delete symbolic?

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

More info needed for context please.   Bad example:
An array of file names that are handled according to pacman's rules

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