Subject: Re: [PATCH v6 1/9] help.c: BUG() out if "help --guides" can't remove "git" prefixes

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Mon, 01 Aug 2022 13:55:11 +0200

On Fri, Jul 29 2022, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason  <[email-masked]> writes:
>
>> Adjust code added in 929d9192828 (git docs: split "User-facing file
>> formats" off from "Guides", 2021-06-04) to be more strict about the
>> prefix trimming of the "guides" category.
>>
>> There are no guides in the command-list.txt that don't start with
>> "git", and we're unlikely to ever add any, if we do we can remove this
>> BUG() invocation, but in the meantime this makes the intent more
>> clear.
>
> I am not sure what this buys us.  After dealing with pages that
> begin with "git-", if the set of documentation we have happen to all
> share "git" as their prefix, then this new BUG() does not do
> anything to them, and when we ever add say "scalar-guide.txt", the
> new BUG() would only force people to rewrite this part of the code.
>
> Instead we could be more forward looking and do something like
> "Yield a name without 'git' prefix if it begins with it, or the
> original name", and then new guides that are outside "git" namespace
> can be added without touching this part of the code again.
>
> IOW, it is not entirely clear to me what we are adding this extra
> roadblock for.

I think if we ever have non-git documentation such as scalar's being
shipped as part of our build it would be good to run into this BUG(),
since presumably a "git help -g" should not list them, but e.g. "scalar
help -g" or whatever.

Or if "git help -g" should list them we should extend it somehow so that
it's not listed under the main "The Git concept guides are" heading.

But per that rationale I should give "git-" the same BUG() treatment,
which I didn't because I wanted to focus just on "git" here, to make
this easier to explain (but perhaps it wasn't).

So I can remove this stricture entirely, or make the BUG() stricter and
remove the "git" (or "git-" requirenment. Whatever you prefer after
reading the above..