Custom subcommand help handlers

Custom subcommand help handlers

[Sean Allred]

Hi folks,

I've got a custom subcommand I'm distributing in my company to
integrate with our bug-tracker. It's a pretty robust utility and has
its own help function, but running `git foo --help` doesn't pass
--help to my git-foo utility. I asked a question[1] about this
scenario on the Windows fork and they directed me upstream.

It sounds like `git foo --help` is internally consumed as `git help
foo`, which forwards requests to info/man/web handlers per config.
Being on Windows and knowing my peers as I do, the vast majority of my
users won't be familiar with info or man. The HTML documentation used
by the web handler is in a Git4Win-controlled installation directory
that I'd really rather not touch/maintain. I really just want `git foo
--help` to call `git-foo --help`.

What's the best way to go about this?

In the event the best next step is to start a patch, does it sound
reasonable to simply not perform this `git foo --help` -> `git help
foo` transformation for non-builtins? Or, while I don't relish the
idea, would some kind of config option be needed?

Best,
Sean Allred

[1]: https://github.com/git-for-windows/git/discussions/3553

Re: Custom subcommand help handlers

[Ævar Arnfjörð Bjarmason]

On Sat, Dec 18 2021, Sean Allred wrote:

> Hi folks,
>
> I've got a custom subcommand I'm distributing in my company to
> integrate with our bug-tracker. It's a pretty robust utility and has
> its own help function, but running `git foo --help` doesn't pass
> --help to my git-foo utility. I asked a question[1] about this
> scenario on the Windows fork and they directed me upstream.
>
> It sounds like `git foo --help` is internally consumed as `git help
> foo`, which forwards requests to info/man/web handlers per config.
> Being on Windows and knowing my peers as I do, the vast majority of my
> users won't be familiar with info or man. The HTML documentation used
> by the web handler is in a Git4Win-controlled installation directory
> that I'd really rather not touch/maintain. I really just want `git foo
> --help` to call `git-foo --help`.
>
> What's the best way to go about this?
>
> In the event the best next step is to start a patch, does it sound
> reasonable to simply not perform this `git foo --help` -> `git help
> foo` transformation for non-builtins? Or, while I don't relish the
> idea, would some kind of config option be needed?
>
> Best,
> Sean Allred
>
> [1]: https://github.com/git-for-windows/git/discussions/3553

I don't know if there's a solution that'll please everyone here, but
it's definitely not narrowing this to built-ins. E.g. "git send-email
--help" will expect to show the manual, so will "git annex --help".

Re: Custom subcommand help handlers

[Erik Cervin Edin]

It looks like any git cmd --help is transformed into
"git help --exclude-guides cmd"
This is used to differentiate "git cmd --help" and "git help cmd".

It's used with aliases to print the alias as well as execute "git help cmd"
Maybe something similar can be done for non built-ins that are missing
man-pages / html-docs

Currently, you may "git-foo --help" directly or use "git foo -h"
instead of "git foo --help" but this may be confusing to users

On Mon, Dec 20, 2021 at 12:54 PM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
>
> On Sat, Dec 18 2021, Sean Allred wrote:
>
> > Hi folks,
> >
> > I've got a custom subcommand I'm distributing in my company to
> > integrate with our bug-tracker. It's a pretty robust utility and has
> > its own help function, but running `git foo --help` doesn't pass
> > --help to my git-foo utility. I asked a question[1] about this
> > scenario on the Windows fork and they directed me upstream.
> >
> > It sounds like `git foo --help` is internally consumed as `git help
> > foo`, which forwards requests to info/man/web handlers per config.
> > Being on Windows and knowing my peers as I do, the vast majority of my
> > users won't be familiar with info or man. The HTML documentation used
> > by the web handler is in a Git4Win-controlled installation directory
> > that I'd really rather not touch/maintain. I really just want `git foo
> > --help` to call `git-foo --help`.
> >
> > What's the best way to go about this?
> >
> > In the event the best next step is to start a patch, does it sound
> > reasonable to simply not perform this `git foo --help` -> `git help
> > foo` transformation for non-builtins? Or, while I don't relish the
> > idea, would some kind of config option be needed?
> >
> > Best,
> > Sean Allred
> >
> > [1]: https://github.com/git-for-windows/git/discussions/3553
>
> I don't know if there's a solution that'll please everyone here, but
> it's definitely not narrowing this to built-ins. E.g. "git send-email
> --help" will expect to show the manual, so will "git annex --help".

-- 
Erik Cervin-Edin

Re: Custom subcommand help handlers

[Johannes Schindelin]

Hi Sean,

On Sat, 18 Dec 2021, Sean Allred wrote:

> I've got a custom subcommand I'm distributing in my company to integrate
> with our bug-tracker. It's a pretty robust utility and has its own help
> function, but running `git foo --help` doesn't pass --help to my git-foo
> utility. I asked a question[1] about this scenario on the Windows fork
> and they directed me upstream.
>
> It sounds like `git foo --help` is internally consumed as `git help
> foo`, which forwards requests to info/man/web handlers per config.
> Being on Windows and knowing my peers as I do, the vast majority of my
> users won't be familiar with info or man. The HTML documentation used
> by the web handler is in a Git4Win-controlled installation directory
> that I'd really rather not touch/maintain. I really just want `git foo
> --help` to call `git-foo --help`.
>
> What's the best way to go about this?
>
> In the event the best next step is to start a patch, does it sound
> reasonable to simply not perform this `git foo --help` -> `git help
> foo` transformation for non-builtins? Or, while I don't relish the
> idea, would some kind of config option be needed?

I think you might need to be a bit more careful than just looking whether
the command in question is a built-in or not. It could be delivered as a
script or executable inside `libexec/git-core`. So maybe check that,
something like this:

-- snip --
diff --git a/git.c b/git.c
index c802dfe98004..d609f90cc117 100644
--- a/git.c
+++ b/git.c
@@ -688,6 +688,33 @@ static void strip_extension(const char **argv)
 #define strip_extension(cmd)
 #endif

+static int is_in_git_exec_path(const char *command_name)
+{
+	struct strbuf path = STRBUF_INIT;
+	int ret = 0;
+
+	if (!command_name)
+		return 0;
+
+	strbuf_addf(&path, "%s/git-%s", git_exec_path(), command_name);
+	ret = !access(path.buf, X_OK);
+
+#ifdef STRIP_EXTENSION
+	if (!ret) {
+		/*
+		 * If `command_name` ended in `.exe`, strip it, otherwise
+		 * append it.
+		 */
+		if (!strbuf_strip_suffix(&path, STRIP_EXTENSION))
+			strbuf_addstr(&path, STRIP_EXTENSION);
+		ret = !access(path.buf, X_OK);
+	}
+#endif
+
+	strbuf_release(&path);
+	return ret;
+}
+
 static void handle_builtin(int argc, const char **argv)
 {
 	struct strvec args = STRVEC_INIT;
@@ -697,8 +724,11 @@ static void handle_builtin(int argc, const char **argv)
 	strip_extension(argv);
 	cmd = argv[0];

+	builtin = get_builtin(cmd);
+
 	/* Turn "git cmd --help" into "git help --exclude-guides cmd" */
-	if (argc > 1 && !strcmp(argv[1], "--help")) {
+	if (argc > 1 && !strcmp(argv[1], "--help") &&
+	    (builtin || is_in_git_exec_path(argv[0]))) {
 		int i;

 		argv[1] = argv[0];
@@ -714,7 +744,6 @@ static void handle_builtin(int argc, const char **argv)
 		argv = args.v;
 	}

-	builtin = get_builtin(cmd);
 	if (builtin)
 		exit(run_builtin(builtin, argc, argv));
 	strvec_clear(&args);
-- snap --

Of course, this might break existing users' setups where they ship a Git
command together with a manual page.

A potential remedy against that would be, as you say, a config option.
Maybe defaulting to the manual page if `help.format` is `man`, otherwise
defaulting to passing `--help` to the command.

Ciao,
Dscho

>
> Best,
> Sean Allred
>
> [1]: https://github.com/git-for-windows/git/discussions/3553
>

Re: Custom subcommand help handlers

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1155 bytes --]

On 2021-12-20 at 12:37:26, Erik Cervin Edin wrote:
> It looks like any git cmd --help is transformed into
> "git help --exclude-guides cmd"
> This is used to differentiate "git cmd --help" and "git help cmd".
> 
> It's used with aliases to print the alias as well as execute "git help cmd"
> Maybe something similar can be done for non built-ins that are missing
> man-pages / html-docs

I don't know that you can effectively distinguish whether there's
documentation for man.  It isn't guaranteed that it will exit
differently if the page is missing versus if it encountered an error.

One thought I have is that on some Unix systems, you can use MANPATH to
set a list of directories in which to search for manual pages.  Maybe
there's a standard environment variable that I'm not aware of that would
provide a similar functionality.

I should point out that in most cases on Unix, it _is_ expected that you
install your manual pages into the same place as everyone else, so in
this case, installing the HTML documentation alongside Git's may be the
best solution.
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

Re: Custom subcommand help handlers

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> I should point out that in most cases on Unix, it _is_ expected that you
> install your manual pages into the same place as everyone else, so in
> this case, installing the HTML documentation alongside Git's may be the
> best solution.

Yup, that sounds like the most sensible way to do things.

Re: Custom subcommand help handlers

[Ævar Arnfjörð Bjarmason]

On Mon, Dec 20 2021, Johannes Schindelin wrote:

> Hi Sean,
>
> On Sat, 18 Dec 2021, Sean Allred wrote:
>
>> I've got a custom subcommand I'm distributing in my company to integrate
>> with our bug-tracker. It's a pretty robust utility and has its own help
>> function, but running `git foo --help` doesn't pass --help to my git-foo
>> utility. I asked a question[1] about this scenario on the Windows fork
>> and they directed me upstream.
>>
>> It sounds like `git foo --help` is internally consumed as `git help
>> foo`, which forwards requests to info/man/web handlers per config.
>> Being on Windows and knowing my peers as I do, the vast majority of my
>> users won't be familiar with info or man. The HTML documentation used
>> by the web handler is in a Git4Win-controlled installation directory
>> that I'd really rather not touch/maintain. I really just want `git foo
>> --help` to call `git-foo --help`.
>>
>> What's the best way to go about this?
>>
>> In the event the best next step is to start a patch, does it sound
>> reasonable to simply not perform this `git foo --help` -> `git help
>> foo` transformation for non-builtins? Or, while I don't relish the
>> idea, would some kind of config option be needed?
>
> I think you might need to be a bit more careful than just looking whether
> the command in question is a built-in or not. It could be delivered as a
> script or executable inside `libexec/git-core`. So maybe check that,
> something like this:
>
> -- snip --
> diff --git a/git.c b/git.c
> index c802dfe98004..d609f90cc117 100644
> --- a/git.c
> +++ b/git.c
> @@ -688,6 +688,33 @@ static void strip_extension(const char **argv)
>  #define strip_extension(cmd)
>  #endif
>
> +static int is_in_git_exec_path(const char *command_name)
> +{
> +	struct strbuf path = STRBUF_INIT;
> +	int ret = 0;
> +
> +	if (!command_name)
> +		return 0;
> +
> +	strbuf_addf(&path, "%s/git-%s", git_exec_path(), command_name);
> +	ret = !access(path.buf, X_OK);
> +
> +#ifdef STRIP_EXTENSION
> +	if (!ret) {
> +		/*
> +		 * If `command_name` ended in `.exe`, strip it, otherwise
> +		 * append it.
> +		 */
> +		if (!strbuf_strip_suffix(&path, STRIP_EXTENSION))
> +			strbuf_addstr(&path, STRIP_EXTENSION);
> +		ret = !access(path.buf, X_OK);
> +	}
> +#endif
> +
> +	strbuf_release(&path);
> +	return ret;
> +}
> +
>  static void handle_builtin(int argc, const char **argv)
>  {
>  	struct strvec args = STRVEC_INIT;
> @@ -697,8 +724,11 @@ static void handle_builtin(int argc, const char **argv)
>  	strip_extension(argv);
>  	cmd = argv[0];
>
> +	builtin = get_builtin(cmd);
> +
>  	/* Turn "git cmd --help" into "git help --exclude-guides cmd" */
> -	if (argc > 1 && !strcmp(argv[1], "--help")) {
> +	if (argc > 1 && !strcmp(argv[1], "--help") &&
> +	    (builtin || is_in_git_exec_path(argv[0]))) {
>  		int i;
>
>  		argv[1] = argv[0];
> @@ -714,7 +744,6 @@ static void handle_builtin(int argc, const char **argv)
>  		argv = args.v;
>  	}
>
> -	builtin = get_builtin(cmd);
>  	if (builtin)
>  		exit(run_builtin(builtin, argc, argv));
>  	strvec_clear(&args);
> -- snap --
>
> Of course, this might break existing users' setups where they ship a Git
> command together with a manual page.
>
> A potential remedy against that would be, as you say, a config option.
> Maybe defaulting to the manual page if `help.format` is `man`, otherwise
> defaulting to passing `--help` to the command.

What are the cases that require us to inexpect our --exec-path at
runtime, as opposed to having a list of commands we know we put there at
"install" time?

The only ones I can think of are e.g. Debian's packaging which might
compile the git with "git-send-email", but it won't be there unless you
install "git-email" in addition to "git".

But for those cases any such logic would presumably want the hardcoded
full list over the dynamic access() check, since e.g. "git-doc" on that
platform orthagonally installs "git-send-email.html" and the like, and
"git help send-email" would presumably like to error saying that we know
about git-send-email, we just can't find its documentation, even if we
can't find it in --exec-path.

Re: Custom subcommand help handlers

[Erik Cervin Edin]

> I should point out that in most cases on Unix, it _is_ expected that you
> install your manual pages into the same place as everyone else, so in
> this case, installing the HTML documentation alongside Git's may be the
> best solution.

I also think this sounds sensible
A hurdle is that while Unix man pages are well established
and I'm not aware of a standard or convention around HTML documentation.

On windows, you can install the HTML pages into
/mingw64/share/doc/git-doc/
the problem is "git for windows" default installs in program files
so admin rights are required.

You can supply a custom path for HTML pages
git -c help.htmlPath=`realpath.exe ~/doc/git/html/` help git-filter-repo
so an option is for user/admins to move/copy
all the help documentation to a different path.

An idea is that if HTML documentation is not found at help.htmlPath
to look for HTML documentation at the path of the command before failing
I don't know if that's a good idea but it sounds simple



On Tue, Dec 21, 2021 at 12:06 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
>
> > I should point out that in most cases on Unix, it _is_ expected that you
> > install your manual pages into the same place as everyone else, so in
> > this case, installing the HTML documentation alongside Git's may be the
> > best solution.
>
> Yup, that sounds like the most sensible way to do things.

Re: Custom subcommand help handlers

[Johannes Schindelin]

[-- Attachment #1: Type: text/plain, Size: 1392 bytes --]

Hi Ævar,

On Tue, 21 Dec 2021, Ævar Arnfjörð Bjarmason wrote:

> On Mon, Dec 20 2021, Johannes Schindelin wrote:
>
> > On Sat, 18 Dec 2021, Sean Allred wrote:
> >
> >> I've got a custom subcommand I'm distributing in my company to integrate
> >> with our bug-tracker. It's a pretty robust utility and has its own help
> >> function, but running `git foo --help` doesn't pass --help to my git-foo
> >> utility. [...]
> >>
> >> What's the best way to go about this?
> >
> > I think you might need to be a bit more careful than just looking whether
> > the command in question is a built-in or not. It could be delivered as a
> > script or executable inside `libexec/git-core`. So maybe check that,
> > something like this:
> >
> > -- snip --
> > [...]
> > -- snap --
> >
> > Of course, this might break existing users' setups where they ship a Git
> > command together with a manual page.
> >
> > A potential remedy against that would be, as you say, a config option.
> > Maybe defaulting to the manual page if `help.format` is `man`, otherwise
> > defaulting to passing `--help` to the command.
>
> What are the cases that require us to inexpect our --exec-path at
> runtime, as opposed to having a list of commands we know we put there at
> "install" time?

It is a simple solution. Why even suggest a complex alternative, I wonder.

Ciao,
Johannes

Re: Custom subcommand help handlers

[Johannes Schindelin]

Hi Junio,

On Mon, 20 Dec 2021, Junio C Hamano wrote:

> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
>
> > I should point out that in most cases on Unix, it _is_ expected that you
> > install your manual pages into the same place as everyone else, so in
> > this case, installing the HTML documentation alongside Git's may be the
> > best solution.
>
> Yup, that sounds like the most sensible way to do things.

So what about `~/bin/git-my-reply-to-junio`? Do we expect people to write
a manual page and install it into `~/man/man1` and for `man` to pick that
up?

In other words: I think you're trying to make the problem sound less
complex than it is.

Ciao,
Dscho

Re: Custom subcommand help handlers

[Ævar Arnfjörð Bjarmason]

On Wed, Dec 22 2021, Johannes Schindelin wrote:

> Hi Ævar,
>
> On Tue, 21 Dec 2021, Ævar Arnfjörð Bjarmason wrote:
>
>> On Mon, Dec 20 2021, Johannes Schindelin wrote:
>>
>> > On Sat, 18 Dec 2021, Sean Allred wrote:
>> >
>> >> I've got a custom subcommand I'm distributing in my company to integrate
>> >> with our bug-tracker. It's a pretty robust utility and has its own help
>> >> function, but running `git foo --help` doesn't pass --help to my git-foo
>> >> utility. [...]
>> >>
>> >> What's the best way to go about this?
>> >
>> > I think you might need to be a bit more careful than just looking whether
>> > the command in question is a built-in or not. It could be delivered as a
>> > script or executable inside `libexec/git-core`. So maybe check that,
>> > something like this:
>> >
>> > -- snip --
>> > [...]
>> > -- snap --
>> >
>> > Of course, this might break existing users' setups where they ship a Git
>> > command together with a manual page.
>> >
>> > A potential remedy against that would be, as you say, a config option.
>> > Maybe defaulting to the manual page if `help.format` is `man`, otherwise
>> > defaulting to passing `--help` to the command.
>>
>> What are the cases that require us to inexpect our --exec-path at
>> runtime, as opposed to having a list of commands we know we put there at
>> "install" time?
>
> It is a simple solution. Why even suggest a complex alternative, I wonder.

You're suggesting the more complex alternative.

We already have a way in that same file to dump both built-ins and other
known commands:

	git --list-cmds=builtins
	git --list-cmds=main

And isn't your is_in_git_exec_path() basically a re-implementation of
what we already get from:

	git --list-cmds=others

?

Hence my question. I.e. if you don't have git-send-email installed why
would you take your is_in_git_exec_path()? I.e. start treating it as
"others" would be treated. We know it's ours, it's just not installed at
the moment.

But those aren't the same thing, so either you didn't know that we have
this data already, or the difference is important for some reason you
haven't explained.

Re: Custom subcommand help handlers

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> On Mon, 20 Dec 2021, Junio C Hamano wrote:
>
>> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
>>
>> > I should point out that in most cases on Unix, it _is_ expected that you
>> > install your manual pages into the same place as everyone else, so in
>> > this case, installing the HTML documentation alongside Git's may be the
>> > best solution.
>>
>> Yup, that sounds like the most sensible way to do things.
>
> So what about `~/bin/git-my-reply-to-junio`? Do we expect people to write
> a manual page and install it into `~/man/man1` and for `man` to pick that
> up?

Yes, if they write one, and then tell man that you have extra
manpages there via MANPATH.

I expect people *not* to write a manual page in practice for such a
thing, though ;-)

Re: Custom subcommand help handlers

[Erik Cervin Edin]

Another observation.

This also applies to external aliases
  git -c alias.fr='!git-filter-repo' fr --help
returns
  'fr' is aliased to '!git-filter-repo'
 w exit code 0

On Wed, Dec 22, 2021 at 8:53 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>
> > On Mon, 20 Dec 2021, Junio C Hamano wrote:
> >
> >> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
> >>
> >> > I should point out that in most cases on Unix, it _is_ expected that you
> >> > install your manual pages into the same place as everyone else, so in
> >> > this case, installing the HTML documentation alongside Git's may be the
> >> > best solution.
> >>
> >> Yup, that sounds like the most sensible way to do things.
> >
> > So what about `~/bin/git-my-reply-to-junio`? Do we expect people to write
> > a manual page and install it into `~/man/man1` and for `man` to pick that
> > up?
>
> Yes, if they write one, and then tell man that you have extra
> manpages there via MANPATH.
>
> I expect people *not* to write a manual page in practice for such a
> thing, though ;-)

Re: Custom subcommand help handlers

[Junio C Hamano]

Erik Cervin Edin <erik@cervined.in> writes:

> Another observation.
>
> This also applies to external aliases
>   git -c alias.fr='!git-filter-repo' fr --help
> returns
>   'fr' is aliased to '!git-filter-repo'
>  w exit code 0

I do not know what your 'w' is.  To me I get

    $ git -c alias.fr='!git-filter-repo' fr --help
    'fr' is aliased to '!git-filter-repo'

which is consistent with what I get for other aliases, e.g.

    $ git -c alias.lg='log --oneline' lg --help
    'lg' is aliased to 'log --oneline'

folowed by whatever "log --help" would give us.

So hopefully when your 'w' learns to show the documentation for
'git-filter-repo' command, such an alias would also work as
expected, no?

Anyway, unlike "man" and "info" where there is a standard way to
tell the command that "I have documentation pages in these places"
so that additional documentation can be installed to locations the
user chooses (and has access to), the "web" format viewers are
invoked without such customizability, i.e. in builtin/help.c, we see
this code snippet:

static void get_html_page_path(struct strbuf *page_path, const char *page)
{
	struct stat st;
	char *to_free = NULL;

	if (!html_path)
		html_path = to_free = system_path(GIT_HTML_PATH);

	/*
	 * Check that the page we're looking for exists.
	 */
	if (!strstr(html_path, "://")) {
		if (stat(mkpath("%s/%s.html", html_path, page), &st)
		    || !S_ISREG(st.st_mode))
			die("'%s/%s.html': documentation file not found.",
				html_path, page);
	}

	strbuf_init(page_path, 0);
	strbuf_addf(page_path, "%s/%s.html", html_path, page);
	free(to_free);
}

It may not be a bad idea to extand the function to understand a new
GIT_HTML_PATH environment variable, which can be a colon-separated
list of directories just like MANPATH and INFOPATH are.  It would be
rather trivial to update the block with a call to stat() above to a
loop over these directories.

Re: Custom subcommand help handlers

[Erik Cervin Edin]

> I do not know what your 'w' is.

Sorry, I was unclear.
With exit code 0

I was experimenting to see if you could use
an external alias to force --help to be passed to cmd.

But you can't because
    if (!exclude_guides || alias[0] == '!') {
        printf_ln(_("'%s' is aliased to '%s'"), cmd, alias);
        free(alias);
        exit(0);
    }

Which is probably reasonable


On Thu, Dec 23, 2021 at 1:11 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Erik Cervin Edin <erik@cervined.in> writes:
>
> > Another observation.
> >
> > This also applies to external aliases
> >   git -c alias.fr='!git-filter-repo' fr --help
> > returns
> >   'fr' is aliased to '!git-filter-repo'
> >  w exit code 0
>
> I do not know what your 'w' is.  To me I get
>
>     $ git -c alias.fr='!git-filter-repo' fr --help
>     'fr' is aliased to '!git-filter-repo'
>
> which is consistent with what I get for other aliases, e.g.
>
>     $ git -c alias.lg='log --oneline' lg --help
>     'lg' is aliased to 'log --oneline'
>
> folowed by whatever "log --help" would give us.
>
> So hopefully when your 'w' learns to show the documentation for
> 'git-filter-repo' command, such an alias would also work as
> expected, no?
>
> Anyway, unlike "man" and "info" where there is a standard way to
> tell the command that "I have documentation pages in these places"
> so that additional documentation can be installed to locations the
> user chooses (and has access to), the "web" format viewers are
> invoked without such customizability, i.e. in builtin/help.c, we see
> this code snippet:
>
> static void get_html_page_path(struct strbuf *page_path, const char *page)
> {
>         struct stat st;
>         char *to_free = NULL;
>
>         if (!html_path)
>                 html_path = to_free = system_path(GIT_HTML_PATH);
>
>         /*
>          * Check that the page we're looking for exists.
>          */
>         if (!strstr(html_path, "://")) {
>                 if (stat(mkpath("%s/%s.html", html_path, page), &st)
>                     || !S_ISREG(st.st_mode))
>                         die("'%s/%s.html': documentation file not found.",
>                                 html_path, page);
>         }
>
>         strbuf_init(page_path, 0);
>         strbuf_addf(page_path, "%s/%s.html", html_path, page);
>         free(to_free);
> }
>
> It may not be a bad idea to extand the function to understand a new
> GIT_HTML_PATH environment variable, which can be a colon-separated
> list of directories just like MANPATH and INFOPATH are.  It would be
> rather trivial to update the block with a call to stat() above to a
> loop over these directories.
>
>
>

Re: Custom subcommand help handlers

[Philip Oakley]

On 22/12/2021 19:53, Junio C Hamano wrote:
> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>
>> On Mon, 20 Dec 2021, Junio C Hamano wrote:
>>
>>> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
>>>
>>>> I should point out that in most cases on Unix, it _is_ expected that you
>>>> install your manual pages into the same place as everyone else, so in
>>>> this case, installing the HTML documentation alongside Git's may be the
>>>> best solution.
>>> Yup, that sounds like the most sensible way to do things.
>> So what about `~/bin/git-my-reply-to-junio`? Do we expect people to write
>> a manual page and install it into `~/man/man1` and for `man` to pick that
>> up?
> Yes, if they write one, and then tell man that you have extra
> manpages there via MANPATH.
>
> I expect people *not* to write a manual page in practice for such a
> thing, though ;-)

In the very original use case reported in the git for windows issues
pages, I understood it that the provider of the git-foo script expected
that they would include some detection and response to the --help being
given as an option.

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. 

The expectation from the XY-Problem was that if the html (and possibly,
by implication, the man page) was not found by git, that the --help
option would be passed to the command itself for it the command to
process (or ignore)..

It is a bit of a rabbit hole.

Philip

Re: Custom subcommand help handlers

[Junio C Hamano]

Philip Oakley <philipoakley@iee.email> 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.

Re: Custom subcommand help handlers

[Philip Oakley]

On 24/12/2021 00:16, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.email> 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.

Philip
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

Re: Custom subcommand help handlers

[Sean Allred]

> I think you might need to be a bit more careful than just looking whether
> the command in question is a built-in or not. It could be delivered as a
> script or executable inside `libexec/git-core`.

I apologize, yes -- I used 'built-in' as a synonym for 'distributed with
Git', but this of course is not how this project uses the term :-)

> Of course, this might break existing users' setups where they ship a Git
> command together with a manual page.
>
> A potential remedy against that would be, as you say, a config option.
> Maybe defaulting to the manual page if `help.format` is `man`, otherwise
> defaulting to passing `--help` to the command.

It's worth noting that Git for Windows does not distribute a
manpage-viewer :-(

--
Sean Allred

Re: Custom subcommand help handlers

[Sean Allred]

Philip Oakley <philipoakley@iee.email> writes:

> On 24/12/2021 00:16, Junio C Hamano wrote:
>> Philip Oakley <philipoakley@iee.email> 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