[PATCH] doc: Create documentation for pacman-db-upgrade and testpkg

[Ben Westover]

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 at 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