[pacman-dev] [PATCH] doc: add man page for pacman-conf

[Eli Schwartz]

On 2/19/19 3:38 PM, Jelle van der Waa wrote:
> Signed-off-by: Jelle van der Waa <jelle at vdwaa.nl>
> ---
>  doc/Makefile.am            |  3 +-
>  doc/pacman-conf.8.asciidoc | 60 ++++++++++++++++++++++++++++++++++++++
>  2 files changed, 62 insertions(+), 1 deletion(-)
>  create mode 100644 doc/pacman-conf.8.asciidoc
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index de87c409..f68f4ea0 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -16,7 +16,8 @@ MANPAGES = \
>  	makepkg.conf.5 \
>  	pacman.conf.5 \
>  	libalpm.3 \
> -	BUILDINFO.5
> +	BUILDINFO.5 \
> +	pacman-conf.8
>  
>  DOXYGEN_MANS = $(wildcard man3/*.3)

Needs to be added to doc/meson.build as well

> diff --git a/doc/pacman-conf.8.asciidoc b/doc/pacman-conf.8.asciidoc
> new file mode 100644
> index 00000000..0e4c96be
> --- /dev/null
> +++ b/doc/pacman-conf.8.asciidoc
> @@ -0,0 +1,60 @@
> +pacman-conf(8)
> +==============
> +
> +Name
> +----
> +pacman-conf - query pacman's configuration file
> +
> +
> +Synopsis
> +--------
> +'pacman-conf' [options] [<directive> ...]

As per the help text, it might be worth mentioning

pacman-conf (--repo-list|--help|--version)

Due to these three not making sense in combination with directives -- in
fact, for the first one, you can actually get an error message if you
try to add a directive:

error: directives may not be specified with --repo-list

> +
> +Description
> +-----------
> +The 'pacman-conf' utility is created since parsing pacman's configuration file
> +is non-trivial and extremely difficult to do correctly from scripts. It makes it
> +easy for scripts to get the same configuration value which pacman itself would
> +use.

"is created" is not important information, we know it is created because
it exists.

How about something like:

'pacman-conf' is a utility for parsing the 'pacman' configuration file
and returning script-friendly output. It is designed to properly handle
non-trivial configuration features such as variable interpolation and
the use of the Include directive, and guarantees that it will return the
same configuration values which 'pacman' itself would use.

'pacman-conf' will output the fully-resolved contents of the
configuration file by default, or, if provided with the name of a
configuration directive, output the contents of the given directive alone.

> +Options
> +-------
> +*-c, \--config* <path>::
> +	Specify an alternate configuration file.
> +
> +*-R, \--rootdir* <path>::
> +	Specify an alternate installation root (default is `/`).

This is incorrect and it depends on the value of:
./configure --with-root-dir

Note: Gentoo is one example of a system that provides a pacman
compilation using a root directory that is not "/"

(They use /var/chroot/archlinux "to avoid breaking Gentoo systems due to
oscitancy".)

This being said, we currently do not provide an asciidoc defines for
such a variable and the only other place that I've found which refers to
the root-dir, also hardcodes "/", so we are already incorrect...

> +*-r, \--repo* <remote>::
> +	Query options for a specific repository.
> +
> +*-v, \--verbose*::
> +	Always shown directive names.
> +
> +*-l, \--repo-list*::
> +	List configured repositories.
> +
> +*-V, \--version*::
> +	Display version and exit.
> +
> +*-h, \--help*::
> +	Output syntax and command line options.

Curious why the help and version flags appear in the opposite order from
the --help output.

> +Examples
> +--------
> +
> +pacman-conf -r core Usage::
> +	Show the value of the Usage configuration option for core repository.
> +
> +pacman-conf HoldPkg::
> +	Show the value of the HoldPkg configuration option.

I'm hesitant to have an Examples section, for the simple fact that if it
is needed in order to let users understand how to use the program, then
the Description section has probably already failed.

> +See Also
> +--------
> +linkman:pacman.conf[5]
> +
> +include::footer.asciidoc[]

-- 
Eli Schwartz
Bug Wrangler and Trusted User

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 1601 bytes
Desc: OpenPGP digital signature
URL: <https://lists.archlinux.org/pipermail/pacman-dev/attachments/20190220/38beab30/attachment.sig>