Re: Custom subcommand help handlers

[Junio C Hamano <gitster@pobox.com>]

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.