Subject: Re: Custom subcommand help handlers

From: Sean Allred <[email-masked]>
Date: Sat, 12 Feb 2022 16:29:39 -0600

Philip Oakley <[email-masked]> writes:

> On 24/12/2021 00:16, Junio C Hamano wrote:
>> Philip Oakley <[email-masked]> writes:
>>
>>> They had the issue that their windows users, using Git for Windows, do
>>> not have the `man` package installed. Rather the `web` help of using the
>>> .html version of the man page is used (needs administrator install in
>>> some case). So user commands would need to provide both the man page for
>>> Linux systems and some process to get the html equivalent into the right
>>> folder - this latter case was the problem step.
>> So are they willing to prepare `web` help pages, because that is
>> what the users of Git for Windows are already familiar with, if "git
>> foo --help" is capable of showing it, just like "git commit --help"
>> shows the `web` help page for the subcommand?
>>
>> As I said elsewhere on this thread, lack of equivalent for MANPATH
>> and INFOPATH makes `web` help harder to customize in that direction,
>> but that is a problem we can solve in our code.  Once it is there,
>> they can let the user install their `web` help pages into somewhere
>> the user has write access to and point at the "folder" with
>> GIT_HTMLPATH, I would presume?
>>
>> Thanks.
>>
> I'm not sure if they are willing to create web versions of the man page
> or not. The request was that we should let their code decide by passing
> the --help option so they could link out to whatever process they have -
> maybe it's a SharePoint server with fancy presentations (I never liked
> them, but many places have drunk the cool aid).
>
> Having an alternate GIT_HTMLPATH could help some users who do have html
> documents, but I was cautious about letting ourselves over automate the
> mechanisation and still leave the users out of the picture.
>
> Hopefully Sean will be able to clarify if I've misunderstood the details
> of their problems.

Sorry for my delayed responses -- I lost the battle to make Gmail do
what I wanted and needed to set up an alternative email client.  This
took more time than I care to admit :-)

Yes, the core of the issue is that Git (for Windows, at least, but
evidently this also applies to normal Git) looks in one spot for HTML
help pages.  We'd be willing to create the documentation in HTML format
if that means making `git foo --help` work, but needing to drop these in
the installation directory of Git for Windows raises questions of how we
keep both Git and the documentation for our tool up-to-date.  (This is
assuming we can hack around the obvious 'admin privileges needed'
problem.)

Having a GIT_HTMLPATH variable could resolve this problem for our
use-case (provided that the resolution is similar to PATH).  Making this
a normal PATH-like variable (with support for multiple paths as you
would see with `echo $PATH`) sounds like a good, extensible path (hah)
forward.

--
Sean Allred