Re: Custom subcommand help handlers

Johannes Schindelin [off-list ref] writes:

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

quoted

"brian m. carlson" [off-list ref] writes:

quoted

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 ;-)

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 [off-list ref] wrote:

Johannes Schindelin [off-list ref] writes:

quoted

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

quoted

"brian m. carlson" [off-list ref] writes:

quoted

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 ;-)

On 22/12/2021 19:53, Junio C Hamano wrote:

Johannes Schindelin [off-list ref] writes:

quoted

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

quoted

"brian m. carlson" [off-list ref] writes:

quoted

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

Philip Oakley [off-list ref] 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.

On 24/12/2021 00:16, Junio C Hamano wrote:

Philip Oakley [off-list ref] writes:

quoted

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

Philip Oakley [off-list ref] writes:

On 24/12/2021 00:16, Junio C Hamano wrote:

quoted

Philip Oakley [off-list ref] writes:

quoted

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