doc: Create documentation for pacman-db-upgrade and testpkg

There are two "binaries" that are currently missing documentation,
pacman-db-upgrade and testpkg. This patch adds that documentation.

Signed-off-by: Ben Westover <kwestover.kw@gmail.com>
---
 doc/meson.build                  |  2 ++
 doc/pacman-db-upgrade.8.asciidoc | 39 ++++++++++++++++++++++++++++++++
 doc/testpkg.8.asciidoc           | 21 +++++++++++++++++
 3 files changed, 62 insertions(+)
 create mode 100644 doc/pacman-db-upgrade.8.asciidoc
 create mode 100644 doc/testpkg.8.asciidoc

On 3/8/22 11:58, Ben Westover wrote:
> There are two "binaries" that are currently missing documentation,
> pacman-db-upgrade and testpkg. This patch adds that documentation.
> 
> Signed-off-by: Ben Westover <kwestover.kw@gmail.com>
> ---
>   doc/meson.build                  |  2 ++
>   doc/pacman-db-upgrade.8.asciidoc | 39 ++++++++++++++++++++++++++++++++
>   doc/testpkg.8.asciidoc           | 21 +++++++++++++++++
>   3 files changed, 62 insertions(+)
>   create mode 100644 doc/pacman-db-upgrade.8.asciidoc
>   create mode 100644 doc/testpkg.8.asciidoc
> 
> diff --git a/doc/meson.build b/doc/meson.build
> index 06df92c9..a18e7f3f 100644
> --- a/doc/meson.build
> +++ b/doc/meson.build
> @@ -5,7 +5,9 @@ manpages = [
>     { 'name': 'makepkg-template.1' },
>     { 'name': 'repo-add.8' },
>     { 'name': 'vercmp.8' },
> +  { 'name': 'testpkg.8' },
>     { 'name': 'pacman-key.8' },
> +  { 'name': 'pacman-db-upgrade.8' },
>     { 'name': 'PKGBUILD.5', 'extra_depends' : [ 'PKGBUILD-example.txt' ] },
>     { 'name': 'makepkg.conf.5' },
>     { 'name': 'pacman.conf.5' },
> diff --git a/doc/pacman-db-upgrade.8.asciidoc b/doc/pacman-db-upgrade.8.asciidoc
> new file mode 100644
> index 00000000..d984179b
> --- /dev/null
> +++ b/doc/pacman-db-upgrade.8.asciidoc
> @@ -0,0 +1,39 @@
> +pacman-db-upgrade(8)
> +====================
> +
> +Name
> +----
> +pacman-db-upgrade - upgrade the local pacman database to a newer format
> +
> +Synopsis
> +--------
> +'pacman-db-upgrade' [options]
> +
> +Description
> +-----------
> +'pacman-db-upgrade' is a script that upgrades the local database used
> +by linkman:pacman[8] to a newer format.
> +
> +Common Options
> +--------------
> +*-h, \--help*::
> +Show the built-in help message and exit.
> +*-V, \--version*::
> +Show version information and exit.
> +*\--nocolor*::
> +Remove color from output.

I'm not sure I understand the split of Common Options.  Common with what?

> +
> +pacman-db-upgrade Options
> +-------------------------
> +*-d, \--dbpath* <path>::
> +Set an alternate database location.
> +*\--config* <path>::
> +Set an alternate configuration file.
> +*-r, \--root* <path>::
> +Sset an alternate installation root.

Typo.

> +
> +See Also
> +--------
> +linkman:pacman[8]
> +
> +include::footer.asciidoc[]
> diff --git a/doc/testpkg.8.asciidoc b/doc/testpkg.8.asciidoc
> new file mode 100644
> index 00000000..6401a9be
> --- /dev/null
> +++ b/doc/testpkg.8.asciidoc
> @@ -0,0 +1,21 @@
> +testpkg(8)
> +==========
> +
> +Name
> +----
> +testpkg - test a pacman package for validity
> +
> +Synopsis
> +--------
> +'testpkg' <package file>
> +
> +Description
> +-----------
> +'testpkg' is a script used to make sure packages produced by
> +linkman:makepkg[8] are valid.

There is at least one other tool that can make a valid pacman package 
that I know of.  So this is not quite correct.

'testpkg' is a script used to make sure that a pacman package is valid.


> +
> +See Also
> +--------
> +linkman:makepkg[8]

linkman:pacman[8]

> +
> +include::footer.asciidoc[]

On 8/3/22 1:25 AM, Allan McRae wrote:
> On 3/8/22 11:58, Ben Westover wrote:
>> There are two "binaries" that are currently missing documentation,
>> pacman-db-upgrade and testpkg. This patch adds that documentation.
>>
>> Signed-off-by: Ben Westover <kwestover.kw@gmail.com>
>> ---
>>   doc/meson.build                  |  2 ++
>>   doc/pacman-db-upgrade.8.asciidoc | 39 ++++++++++++++++++++++++++++++++
>>   doc/testpkg.8.asciidoc           | 21 +++++++++++++++++
>>   3 files changed, 62 insertions(+)
>>   create mode 100644 doc/pacman-db-upgrade.8.asciidoc
>>   create mode 100644 doc/testpkg.8.asciidoc
>>
>> diff --git a/doc/meson.build b/doc/meson.build
>> index 06df92c9..a18e7f3f 100644
>> --- a/doc/meson.build
>> +++ b/doc/meson.build
>> @@ -5,7 +5,9 @@ manpages = [
>>     { 'name': 'makepkg-template.1' },
>>     { 'name': 'repo-add.8' },
>>     { 'name': 'vercmp.8' },
>> +  { 'name': 'testpkg.8' },
>>     { 'name': 'pacman-key.8' },
>> +  { 'name': 'pacman-db-upgrade.8' },
>>     { 'name': 'PKGBUILD.5', 'extra_depends' : [ 'PKGBUILD-example.txt'
>> ] },
>>     { 'name': 'makepkg.conf.5' },
>>     { 'name': 'pacman.conf.5' },
>> diff --git a/doc/pacman-db-upgrade.8.asciidoc
>> b/doc/pacman-db-upgrade.8.asciidoc
>> new file mode 100644
>> index 00000000..d984179b
>> --- /dev/null
>> +++ b/doc/pacman-db-upgrade.8.asciidoc
>> @@ -0,0 +1,39 @@
>> +pacman-db-upgrade(8)
>> +====================
>> +
>> +Name
>> +----
>> +pacman-db-upgrade - upgrade the local pacman database to a newer format
>> +
>> +Synopsis
>> +--------
>> +'pacman-db-upgrade' [options]
>> +
>> +Description
>> +-----------
>> +'pacman-db-upgrade' is a script that upgrades the local database used
>> +by linkman:pacman[8] to a newer format.
>> +
>> +Common Options
>> +--------------
>> +*-h, \--help*::
>> +Show the built-in help message and exit.
>> +*-V, \--version*::
>> +Show version information and exit.
>> +*\--nocolor*::
>> +Remove color from output.
> 
> I'm not sure I understand the split of Common Options.  Common with what?

I used repo-add.8.asciidoc as a reference because I've never used
asciidoc before. It has two sections "Common Options" and "repo-add
Options". I thought this meant options that other programs in the pacman
project also had. Now, I realize that since repo-add and repo-remove are
in one file, "Common Options" means options that both repo-add and
repo-remove share, and "repo-add Options" are options that only repo-add
has.
I've unified the options in PATCHv2.

>> +
>> +pacman-db-upgrade Options
>> +-------------------------
>> +*-d, \--dbpath* <path>::
>> +Set an alternate database location.
>> +*\--config* <path>::
>> +Set an alternate configuration file.
>> +*-r, \--root* <path>::
>> +Sset an alternate installation root.
> 
> Typo.

Fixed in PATCHv2.

>> +
>> +See Also
>> +--------
>> +linkman:pacman[8]
>> +
>> +include::footer.asciidoc[]
>> diff --git a/doc/testpkg.8.asciidoc b/doc/testpkg.8.asciidoc
>> new file mode 100644
>> index 00000000..6401a9be
>> --- /dev/null
>> +++ b/doc/testpkg.8.asciidoc
>> @@ -0,0 +1,21 @@
>> +testpkg(8)
>> +==========
>> +
>> +Name
>> +----
>> +testpkg - test a pacman package for validity
>> +
>> +Synopsis
>> +--------
>> +'testpkg' <package file>
>> +
>> +Description
>> +-----------
>> +'testpkg' is a script used to make sure packages produced by
>> +linkman:makepkg[8] are valid.
> 
> There is at least one other tool that can make a valid pacman package
> that I know of.  So this is not quite correct.
> 
> 'testpkg' is a script used to make sure that a pacman package is valid.

repo-add.8.asciidoc mentions "packages built with linkman:makepkg[8]",
so I assumed that was correct. This is fixed in PATCHv2.

>> +
>> +See Also
>> +--------
>> +linkman:makepkg[8]
> 
> linkman:pacman[8]

Fixed in PATCHv2.

> 
>> +
>> +include::footer.asciidoc[]
> 

Thanks for the corrections,
--
Ben Westover