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

From: Jonathan Nieder <jrnieder@gmail.com>
Date: May 1, 2011, 23:48 UTC
Message-ID: <20110501234833.GC11550@elie>
In-Reply-To: <7vbozmthhy.fsf@alter.siamese.dyndns.org>

Junio C Hamano wrote:

Show 7 quoted lines

> 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?