[pacman-dev] [PATCH] doc: add man page for pacman-conf
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) 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> ...] + + +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. + + +Options +------- +*-c, \--config* <path>:: + Specify an alternate configuration file. + +*-R, \--rootdir* <path>:: + Specify an alternate installation root (default is `/`). + +*-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. + + +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. + + +See Also +-------- +linkman:pacman.conf[5] + +include::footer.asciidoc[] -- 2.20.1
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
On 20/2/19 5:35 pm, Eli Schwartz wrote:
+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.
Like the pacman man page! A
On 2/20/19 2:43 AM, Allan McRae wrote:
On 20/2/19 5:35 pm, Eli Schwartz wrote:
+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.
Like the pacman man page!
I'm not necessarily saying ditch the examples section -- but its presence made it fairly noticeable that the rest of the page did not describe how pacman-conf's directive parameter functions (nor indeed that without it, it will flatten the configuration and return all of it for you). OTOH maybe we could go wild and delete stuff from the pacman manpage too... who doesn't like deleting things... -- Eli Schwartz Bug Wrangler and Trusted User
Signed-off-by: Jelle van der Waa <jelle@vdwaa.nl> --- doc/Makefile.am | 3 +- doc/meson.build | 1 + doc/pacman-conf.8.asciidoc | 67 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 70 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) diff --git a/doc/meson.build b/doc/meson.build index b7514ef7..e4d9b98f 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -12,6 +12,7 @@ manpages = [ { 'name': 'pacman.conf.5' }, { 'name': 'libalpm.3' }, { 'name': 'BUILDINFO.5' }, + { 'name': 'pacman-conf.8' }, ] sitepages = [ diff --git a/doc/pacman-conf.8.asciidoc b/doc/pacman-conf.8.asciidoc new file mode 100644 index 00000000..c067166d --- /dev/null +++ b/doc/pacman-conf.8.asciidoc @@ -0,0 +1,67 @@ +pacman-conf(8) +============== + +Name +---- +pacman-conf - query pacman's configuration file + + +Synopsis +-------- +'pacman-conf' [options] [<directive> ...] + +'pacman-conf' (--repo-list|--help|--version) + + +Description +----------- +'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 `/`). + +*-r, \--repo* <remote>:: + Query options for a specific repository. + +*-v, \--verbose*:: + Always shown directive names. + +*-l, \--repo-list*:: + List configured repositories. + +*-h, \--help*:: + Output syntax and command line options. + +*-V, \--version*:: + Display version and exit. + + +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. + + +See Also +-------- +linkman:pacman.conf[5] + +include::footer.asciidoc[] -- 2.20.1
On 02/20/19 at 02:57am, Eli Schwartz wrote:
On 2/20/19 2:43 AM, Allan McRae wrote:
On 20/2/19 5:35 pm, Eli Schwartz wrote:
+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.
Like the pacman man page!
I'm not necessarily saying ditch the examples section -- but its presence made it fairly noticeable that the rest of the page did not describe how pacman-conf's directive parameter functions (nor indeed that without it, it will flatten the configuration and return all of it for you).
OTOH maybe we could go wild and delete stuff from the pacman manpage too... who doesn't like deleting things...
In my opinion the example section is fine and can be used as a quick reference. -- Jelle van der Waa
On 21/2/19 10:20 pm, Jelle van der Waa wrote:
Signed-off-by: Jelle van der Waa <jelle@vdwaa.nl> --- doc/Makefile.am | 3 +- doc/meson.build | 1 + doc/pacman-conf.8.asciidoc | 67 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 doc/pacman-conf.8.asciidoc
Looks good to me. Applied. A
participants (3)
-
Allan McRae
-
Eli Schwartz
-
Jelle van der Waa