On 2/19/19 3:38 PM, Jelle van der Waa wrote:
Signed-off-by: Jelle van der Waa <jelle@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