On 2020-02-07 at 10:42:56, paul@pauldsmith.org.uk wrote:
> Adding a custom comment (let’s call is ‘foolish’) is easy but then you
> someone types ‘git help foolish’, they get some strange message about help
> not being found.
> 
> There are two problems with this:
> 
> 1. It’s hard for users to create good documentation in the same format as
> the core git product 2. The git ‘help’ processing currently looks in one,
> and one place only and that location is often ‘locked down’ meaning that
> mere users cannot add their custom help to this directory.

It is possible to extend the set of locations that one can use for man
by setting MANPATH.  If you do so, something like "git foolish --help"
does indeed work.

> I propose that #1 be solved by creating a command/tool and documentation
> that explains how to mimic the input to the standard Git help files and have
> them processed to create the HTML/HTML5/MAN help normally produced.  Ideally
> it would do exactly the same processing as the core tools (perhaps even
> having their docs built using this tool now) and use exactly the same
> template files that core git uses.

There is such a tool, and it's called Asciidoctor.  However, it's
written in Ruby, and not all users will want to install Ruby as part of
their Git installation.  It does work nicely, though, and I use it for
my own custom Git subcommands.

Also, if a user prefers to use a different tool for creating manual
pages or HTML documentation, they can certainly do so.

> I propose that #2 be solved by allowing a new set of ‘git config’ fields.
> The layout should be sensible and should users to be able to set a git
> variable which then means that the core git help finds their help text.
> Possible we want to force
> 
> <where I installed my tool>/docs/man, or html, or html5
> 
> And the git config variable be something like
> “help.custom.foolish=<where-foolish-is-installed>/docs”

I think specifying a single location may be a problem because different
types of documentation live in different locations.  On Debian, man
pages live in /usr/share/man, but HTML documentation lives in
/usr/share/doc.

We could theoretically add support for this if we did help.foolish.man
and help.foolish.html, though.

I don't feel strongly enough about this to implement it, but if you're
interested, I could review a patch.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204