documentation: help: add info about "man.<tool>.cmd" config var

This patch also describes the current behavior for "konqueror" and
how to modify it using "man.<tool>.cmd" if needed.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 138ba9ad8f51665981f231525cbfdf657b2020db..3b65c075175818a927829752914a417cb44b5ae2 100644 (file)
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -805,6 +805,11 @@ merge.<driver>.recursive::
        performing an internal merge between common ancestors.
        See linkgit:gitattributes[5] for details.
 
+man.<tool>.cmd::
+       Specify the command to invoke the specified man viewer. The
+       specified command is evaluated in shell with the man page
+       passed as argument. (See linkgit:git-help[1].)
+
 man.<tool>.path::
        Override the path for the given tool that may be used to
        display help in the 'man' format. See linkgit:git-help[1].

diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 4c6cb2194cc77123e15ad73eeead0152e075d5d6..bfbba9e235495b0a7e31b4d3ed558bef105ad02d 100644 (file)
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -82,22 +82,28 @@ man.viewer
 ~~~~~~~~~~
 
 The 'man.viewer' config variable will be checked if the 'man' format
-is chosen. Only the following values are currently supported:
+is chosen. The following values are currently supported:
 
 * "man": use the 'man' program as usual,
 * "woman": use 'emacsclient' to launch the "woman" mode in emacs
 (this only works starting with emacsclient versions 22),
-* "konqueror": use a man KIO slave in konqueror.
+* "konqueror": use 'kfmclient' to open the man page in a new konqueror
+tab (see 'Note about konqueror' below).
 
-Multiple values may be given to this configuration variable. Their
-corresponding programs will be tried in the order listed in the
-configuration file.
+Values for other tools can be used if there is a corresponding
+'man.<tool>.cmd' configuration entry (see below).
+
+Multiple values may be given to the 'man.viewer' configuration
+variable. Their corresponding programs will be tried in the order
+listed in the configuration file.
 
 For example, this configuration:
 
+------------------------------------------------
        [man]
                viewer = konqueror
                viewer = woman
+------------------------------------------------
 
 will try to use konqueror first. But this may fail (for example if
 DISPLAY is not set) and in that case emacs' woman mode will be tried.
@@ -113,6 +119,38 @@ can configure the absolute path to konqueror by setting
 'man.konqueror.path'. Otherwise, 'git help' assumes the tool is
 available in PATH.
 
+man.<tool>.cmd
+~~~~~~~~~~~~~~
+
+When the man viewer, specified by the 'man.viewer' configuration
+variables, is not among the supported ones, then the corresponding
+'man.<tool>.cmd' configuration variable will be looked up. If this
+variable exists then the specified tool will be treated as a custom
+command and a shell eval will be used to run the command with the man
+page passed as arguments.
+
+Note about konqueror
+~~~~~~~~~~~~~~~~~~~~
+
+When 'konqueror' is specified in the 'man.viewer' configuration
+variable, we launch 'kfmclient' to try to open the man page on an
+already opened konqueror in a new tab if possible.
+
+For consistency, we also try such a trick if 'man.konqueror.path' is
+set to something like 'A_PATH_TO/konqueror'. That means we will try to
+launch 'A_PATH_TO/kfmclient' instead.
+
+If you really want to use 'konqueror', then you can use something like
+the following:
+
+------------------------------------------------
+       [man]
+               viewer = konq
+
+       [man "konq"]
+               cmd = A_PATH_TO/konqueror
+------------------------------------------------
+
 Note about git config --global
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~