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

Message ID 20190621213913.21263-1-jelle@vdwaa.nl
State New
Headers show
Series
  • [pacman-dev] doc: Add a man page describing PKGINFO
Related show

Commit Message

Jelle van der Waa June 21, 2019, 9:39 p.m. UTC
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 | 86 ++++++++++++++++++++++++++++++++++++++++++
 doc/meson.build        |  1 +
 3 files changed, 90 insertions(+), 1 deletion(-)
 create mode 100644 doc/PKGINFO.5.asciidoc

Comments

Allan McRae June 28, 2019, 12:30 a.m. UTC | #1
On 22/6/19 7:39 am, 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 | 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@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 = [
>

Patch

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.
+
+
+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.
+
+*url*::
+	The upstream of the package.
+
+*builddate*::
+	The build date of the package in epoch.
+
+*packager*::
+	The packager of the package formatted Foo <foo@bar.com>.
+
+*size*::
+	The size of the package.
+
+*arch*::
+	The architecture of the package.
+
+*license*::
+	The license of the package.
+
+*replaces (array)*::
+	An array of packages this package should replace.
+
+*group (array)*::
+	An array of symbolic names that represent groups of packages.
+
+*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.
+
+*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 = [