[PATCH] Add --info-path and --man-path options to git.

[PATCH] Add --info-path and --man-path options to git.

[Jon Seymour]

To better support git extensions provided by 3rd parties
which would like to install their own man pages and Info files
in the same place as git's own man pages and Info files
add support for --man-path and --info-path options.

Signed-off-by: Jon Seymour <jon.seymour@gmail.com>
---
 Documentation/git.txt |   10 +++++++++-
 Makefile              |    4 +++-
 git.c                 |    8 +++++++-
 3 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index e4d43a9..c495322 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -9,7 +9,7 @@ git - the stupid content tracker
 SYNOPSIS
 --------
 [verse]
-'git' [--version] [--exec-path[=<path>]] [--html-path]
+'git' [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
     [-p|--paginate|--no-pager] [--no-replace-objects]
     [--bare] [--git-dir=<path>] [--work-tree=<path>]
     [-c <name>=<value>]
@@ -285,6 +285,14 @@ help ...`.
 	Print the path to wherever your git HTML documentation is installed
 	and exit.
 
+--man-path::
+	Print the path to wherever your git man pages are installed
+	and exit.
+
+--info-path::
+	Print the path to wherever your git Info files are installed
+	and exit.
+
 -p::
 --paginate::
 	Pipe all output into 'less' (or if set, $PAGER) if standard
diff --git a/Makefile b/Makefile
index f5308fe..9119aaa 100644
--- a/Makefile
+++ b/Makefile
@@ -1684,7 +1684,9 @@ strip: $(PROGRAMS) git$X
 
 git.o: common-cmds.h
 git.s git.o: EXTRA_CPPFLAGS = -DGIT_VERSION='"$(GIT_VERSION)"' \
-	'-DGIT_HTML_PATH="$(htmldir_SQ)"'
+	'-DGIT_HTML_PATH="$(htmldir_SQ)"' \
+	'-DGIT_MAN_PATH="$(mandir_SQ)"' \
+	'-DGIT_INFO_PATH="$(infodir_SQ)"'
 
 git$X: git.o $(BUILTIN_OBJS) $(GITLIBS)
 	$(QUIET_LINK)$(CC) $(ALL_CFLAGS) -o $@ git.o \
diff --git a/git.c b/git.c
index ef598c3..60a9403 100644
--- a/git.c
+++ b/git.c
@@ -6,7 +6,7 @@
 #include "run-command.h"
 
 const char git_usage_string[] =
-	"git [--version] [--exec-path[=<path>]] [--html-path]\n"
+	"git [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]\n"
 	"           [-p|--paginate|--no-pager] [--no-replace-objects]\n"
 	"           [--bare] [--git-dir=<path>] [--work-tree=<path>]\n"
 	"           [-c name=value] [--help]\n"
@@ -95,6 +95,12 @@ static int handle_options(const char ***argv, int *argc, int *envchanged)
 		} else if (!strcmp(cmd, "--html-path")) {
 			puts(system_path(GIT_HTML_PATH));
 			exit(0);
+		} else if (!strcmp(cmd, "--man-path")) {
+			puts(system_path(GIT_MAN_PATH));
+			exit(0);
+		} else if (!strcmp(cmd, "--info-path")) {
+			puts(system_path(GIT_INFO_PATH));
+			exit(0);
 		} else if (!strcmp(cmd, "-p") || !strcmp(cmd, "--paginate")) {
 			use_pager = 1;
 		} else if (!strcmp(cmd, "--no-pager")) {
-- 
1.7.5.rc3.46.g7f712.dirty

Re: [PATCH] Add --info-path and --man-path options to git.

[Junio C Hamano]

Jon Seymour <jon.seymour@gmail.com> writes:

> To better support git extensions provided by 3rd parties
> which would like to install their own man pages and Info files
> in the same place as git's own man pages and Info files
> add support for --man-path and --info-path options.
>
> Signed-off-by: Jon Seymour <jon.seymour@gmail.com>
> ---

This an improvement that is pretty much independent from the issue of
third party extensions. In fact, even people who would oppose to the idea
of any third party crap [*1*] contaminating the install directories owned
by git may want to this patch.

It is useful to have these options even for read-only users. Cf. 89a56bf
(add --html-path to get the location of installed HTML docs, 2009-04-05).

I'll rewrite the proposed commit message before queuing this to 'pu'.

Thanks.


[Footnote]

*1* Not all extensions may be crappy, but some extension will be, and you
may find out the crappiness only after installing it, but at that point it
already has contaminated your git directories.

Re: [PATCH] Add --info-path and --man-path options to git.

[Jon Seymour]

On Mon, May 2, 2011 at 4:15 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Jon Seymour <jon.seymour@gmail.com> writes:
>
>> To better support git extensions provided by 3rd parties
>> which would like to install their own man pages and Info files
>> in the same place as git's own man pages and Info files
>> add support for --man-path and --info-path options.
>>
>> Signed-off-by: Jon Seymour <jon.seymour@gmail.com>
>> ---
>
> This an improvement that is pretty much independent from the issue of
> third party extensions. In fact, even people who would oppose to the idea
> of any third party crap [*1*] contaminating the install directories owned
> by git may want to this patch.
>

Thanks.

I agree the sentiment that suggests that we don't want to pollute
git's own directories with 3rd party contributions.

This, indeed, is part of the motivation for a --plugins-path option
which would provide a physically separate location for 3rd party
contributions, per the earlier discussions between yourself and
Jonathan Nieder. I'll put together a suggested patch for how this
might work in the next week or so.

jon.

Re: [PATCH] Add --info-path and --man-path options to git.

[Jonathan Nieder]

Junio C Hamano wrote:

> This an improvement that is pretty much independent from the issue of
> third party extensions. In fact, even people who would oppose to the idea
> of any third party crap [*1*] contaminating the install directories owned
> by git may want to this patch.
>
> It is useful to have these options even for read-only users. Cf. 89a56bf
> (add --html-path to get the location of installed HTML docs, 2009-04-05).

I don't mind this patch at all, but I do not have a full picture yet
of how it helps.

In the case of HTML, the standard way to show git documentation in your
custom documentation viewer is to pull up file://$(git --html-path)/index.html,
using the full path to the HTML files.  So if "git gui" were to gain a
documentation viewer widget instead of relying on git web--browse, it
would need the HTML path.

By contrast, man and info typically use standard search mechanisms:
man using $MANPATH and info using the dir.info file.  The usual
interface to git's documentation through a man browser is not

	man /usr/share/man/man1/git-add.1.gz

but

	man git-add;	# or "man git add" if your man viewer supports it

And the usual interface through an info browser is

	info git

.

So it is not clear to me how this would help when you want to view
documentation.  Similarly, if you want to sneak documentation into an
existing git installation (ignoring the question of whether that's a
good idea), using HTML you would have to modify git's index.html and
add your HTML files alongside it, while using "man" or "info" you
would have to modify the index page (git.1 or gitman.info) but could
put your custom pages wherever you want in the viewer's search path.

So while I can't see the harm in exposing --info-path and --man-path,
the current patch seems to do an incomplete job of documenting them.
Perhaps this is about finding the documentation corresponding to a
particular copy of git when a machine has multiple copies?

Re: [PATCH] Add --info-path and --man-path options to git.

[Jonathan Nieder]

Hi again,

Two quick corrections.

Jonathan Nieder wrote:

> So if "git gui" were to gain a
> documentation viewer widget instead of relying on git web--browse, it
> would need the HTML path.

Actually, it already uses the HTML path. :)

> So while I can't see the harm in exposing --info-path and --man-path,
> the current patch seems to do an incomplete job of documenting them.
> Perhaps this is about finding the documentation corresponding to a
> particular copy of git when a machine has multiple copies?

It seems Jon's and my mails crossed.  Here's another use case for
--man-path: if your frontend wants to fall back to HTML documentation
without spawning a man pager when the manpages are not installed, it
needs to know where to look.

(See also gitgui-0.6.0~32, git-gui: Offer quick access to the HTML
formatted documentation, 2007-01-28)

Re: [PATCH] Add --info-path and --man-path options to git.

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> By contrast, man and info typically use standard search mechanisms:
> man using $MANPATH and info using the dir.info file.  The usual
> interface to git's documentation through a man browser is not
>
> 	man /usr/share/man/man1/git-add.1.gz
>
> but
>
> 	man git-add;	# or "man git add" if your man viewer supports it

I think you are forgetting the case where the git-man-path the user uses
to install git may be outside /usr/share/man (e.g. $HOME/share/man).  In
such an installation, by setting $PATH to include your installed git
binary (e.g. $HOME/bin), you should be able to say "git help -m git" to
tell help.c to internally prepend $HOME/share/man to the $MANPATH before
it kicks "man".  Does "man git-add" work without you knowing where that
directory is (iow, without having $HOME/share/man on $MANPATH)?  And if it
does not, how would you learn what directory to add to your $MANPATH?

Isn't that what this patch is solving?  I am not sure where the similarity
with the html documentation breaks donw.  The same thing for info.

Re: [PATCH] Add --info-path and --man-path options to git.

[Jon Seymour]

On Mon, May 2, 2011 at 10:02 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:
>
>> By contrast, man and info typically use standard search mechanisms:
>> man using $MANPATH and info using the dir.info file.  The usual
>> interface to git's documentation through a man browser is not
>>
>>       man /usr/share/man/man1/git-add.1.gz
>>
>> but
>>
>>       man git-add;    # or "man git add" if your man viewer supports it
>
> I think you are forgetting the case where the git-man-path the user uses
> to install git may be outside /usr/share/man (e.g. $HOME/share/man).  In
> such an installation, by setting $PATH to include your installed git
> binary (e.g. $HOME/bin), you should be able to say "git help -m git" to
> tell help.c to internally prepend $HOME/share/man to the $MANPATH before
> it kicks "man".  Does "man git-add" work without you knowing where that
> directory is (iow, without having $HOME/share/man on $MANPATH)?  And if it
> does not, how would you learn what directory to add to your $MANPATH?
>
> Isn't that what this patch is solving?  I am not sure where the similarity
> with the html documentation breaks donw.  The same thing for info.

Good point. For non-distro installed installations of git, this would
be handy, even for read-only purposes.

jon.

Re: [PATCH] Add --info-path and --man-path options to git.

[Jon Seymour]

On Mon, May 2, 2011 at 10:06 AM, Jon Seymour <jon.seymour@gmail.com> wrote:
> On Mon, May 2, 2011 at 10:02 AM, Junio C Hamano <gitster@pobox.com> wrote:
>

BTW: should it be --man-path and --info-path or --man-dir and --info-dir.

I chose --man-path to be consistent with the other options, but in
reality, I think all these options specify directories rather than
paths (e.g. lists of directories).

jon.

Re: [PATCH] Add --info-path and --man-path options to git.

[Jonathan Nieder]

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:

>> The usual
>> interface to git's documentation through a man browser is not
>>
>> 	man /usr/share/man/man1/git-add.1.gz
>>
>> but
>>
>> 	man git-add;	# or "man git add" if your man viewer supports it
>
> I think you are forgetting the case where the git-man-path the user uses
> to install git may be outside /usr/share/man (e.g. $HOME/share/man).  In
> such an installation, by setting $PATH to include your installed git
> binary (e.g. $HOME/bin), you should be able to say "git help -m git" to
> tell help.c to internally prepend $HOME/share/man to the $MANPATH before
> it kicks "man".

I was not forgetting it, but you are right that we have an opportunity
to be more helpful in that case.  (My own MANPATH already includes
~/share/man, but I can see that it is easy to forget to add.)

I am still not very happy about it.  The man browser is in a much
better position to help: the default MANPATH (at least under Debian;
see manpath(5)[1]) is generated by mapping $PATH entries on the fly, and
it seems like only an oversight that it deals with directories under
/usr but not /home.  And it does not thrill me that we would be
training people that

	git help git

will cover for the installer's mistakes, while the more conventional

	man git

mechanism (which is also used for other programs installed to $HOME)
will not.

> Isn't that what this patch is solving?

I find the "use the right version of help when multiple copies of git"
use case compelling enough already.  Please don't mind my complaints
too much.

Thanks for clarifying.
Jonathan

[1] http://man.he.net/man5/manpath

Re: [PATCH] Add --info-path and --man-path options to git.

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> I am still not very happy about it.  The man browser is in a much
> better position to help: the default MANPATH (at least under Debian;
> see manpath(5)[1]) is generated by mapping $PATH entries on the fly, and
> it seems like only an oversight that it deals with directories under
> /usr but not /home.  And it does not thrill me that we would be
> training people that
>
> 	git help git
>
> will cover for the installer's mistakes, while the more conventional
>
> 	man git
>
> mechanism (which is also used for other programs installed to $HOME)
> will not.

Well, is there anything I can do to help your unhappiness about that?

Where is your unhappiness coming from?  Is this your argument?

	'git help' allows distros' oversight with its -m and -i options;
	it discourages distros to get their act together.

I personally do not think punishing users of distros by not helping would
be an effective way to encourage distros to help their users, so even
though I kind of agree with that statement, I wouldn't conclude that with
"therefore, git shouldn't try to be helpful with 'help [-m|-i]'".

Re: [PATCH] Add --info-path and --man-path options to git.

[Jonathan Nieder]

Junio C Hamano wrote:

> Where is your unhappiness coming from?  Is this your argument?
>
>	'git help' allows distros' oversight with its -m and -i options;
>	it discourages distros to get their act together.

No, my discomfort was not on behalf of distros.  It wouldn't do
anything to help or hurt distros, since they would be installing to
/usr/share/man.

When I said "installers' mistakes", I specifically meant the user that
installs manual pages to ~/share/man without setting MANPATH to
include that.  I agreed that that's an unfortunate thing to happen to
anybody, but I didn't think git is the right place to fix it.  Because
it affects anyone else installing something to $HOME, and as a user I
wouldn't _expect_ git to fix it.

What my analysis was missing is that this is not only about the user
who runs "git help -m" as a fancy way of running "man git" and expects
it to work better (who I still have no sympathy for).  It is much more
about the user who runs

	git add --help

or chooses Help → Manual in her porcelain, who certainly deserves some
documentation whether her MANPATH is set correctly or not.

I also should have remembered v1.5.4-rc0~54 (Let git-help prefer
man-pages installed with this version of git, 2007-12-06), which is
about showing the manual in /opt/git-next/man in preference to a stale
manpage from /opt/git-master/man when running
"/opt/git-next/bin/git add --help".

So I was very confused indeed.  Sorry to waste your time, and thanks
for setting me straight.

[PATCH] Documentation: clarify meaning of --html-path, --man-path, and --info-path

[Jonathan Nieder]

These options tell UI programs where git put its documentation, so
"Help" actions can show the documentation for *this* version of git
without regard to how MANPATH and INFOPATH are set up.  Details:

. Each variable tells where documentation is expected to be.  They do
  not indicate whether documentation was actually installed.

. The output of "git --html-path" is an absolute path and can be used
  in "file://$(git --html-path)/git-add.html" to name the HTML file
  documenting a particular command.

. --man-path names a manual page hierarchy (e.g.,
  /home/user/share/man).  Its output can be passed to "man -M" or put
  at the beginning of $MANPATH.

. --info-path names a directory with info files (e.g.,
  /home/user/share/info).  Its output is suitable as an argument to
  "info -d" or for inclusion in $INFOPATH.

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Sorry for the long tangent.  Maybe a summary can be useful.

 Documentation/git.txt |   12 ++++++------
 1 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 7e9b521..5295315 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -287,16 +287,16 @@ help ...`.
 	the current setting and then exit.
 
 --html-path::
-	Print the path to wherever your git HTML documentation is installed
-	and exit.
+	Print the path, without trailing slash, where git's HTML
+	documentation is installed and exit.
 
 --man-path::
-	Print the path to wherever your git man pages are installed
-	and exit.
+	Print the manpath (see `man(1)`) for the man pages for
+	this version of git and exit.
 
 --info-path::
-	Print the path to wherever your git Info files are installed
-	and exit.
+	Print the path where the Info files documenting this
+	version of git are installed and exit.
 
 -p::
 --paginate::
-- 
1.7.5

Re: [PATCH] Documentation: clarify meaning of --html-path, --man-path, and --info-path

[Jon Seymour]

Acked.

On Mon, May 2, 2011 at 4:07 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> These options tell UI programs where git put its documentation, so
> "Help" actions can show the documentation for *this* version of git
> without regard to how MANPATH and INFOPATH are set up.  Details:
>
> . Each variable tells where documentation is expected to be.  They do
>  not indicate whether documentation was actually installed.
>
> . The output of "git --html-path" is an absolute path and can be used
>  in "file://$(git --html-path)/git-add.html" to name the HTML file
>  documenting a particular command.
>
> . --man-path names a manual page hierarchy (e.g.,
>  /home/user/share/man).  Its output can be passed to "man -M" or put
>  at the beginning of $MANPATH.
>
> . --info-path names a directory with info files (e.g.,
>  /home/user/share/info).  Its output is suitable as an argument to
>  "info -d" or for inclusion in $INFOPATH.
>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> ---
> Sorry for the long tangent.  Maybe a summary can be useful.
>
>  Documentation/git.txt |   12 ++++++------
>  1 files changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 7e9b521..5295315 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -287,16 +287,16 @@ help ...`.
>        the current setting and then exit.
>
>  --html-path::
> -       Print the path to wherever your git HTML documentation is installed
> -       and exit.
> +       Print the path, without trailing slash, where git's HTML
> +       documentation is installed and exit.
>
>  --man-path::
> -       Print the path to wherever your git man pages are installed
> -       and exit.
> +       Print the manpath (see `man(1)`) for the man pages for
> +       this version of git and exit.
>
>  --info-path::
> -       Print the path to wherever your git Info files are installed
> -       and exit.
> +       Print the path where the Info files documenting this
> +       version of git are installed and exit.
>
>  -p::
>  --paginate::
> --
> 1.7.5
>
>

Re: [PATCH] Documentation: clarify meaning of --html-path, --man-path, and --info-path

[Junio C Hamano]

Thanks.