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

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Aug 1, 2022, 11:55 UTC
Message-ID: <220801.86czdki3ad.gmgdl@evledraar.gmail.com>
In-Reply-To: <xmqq35ej313l.fsf@gitster.g>

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

Show 24 quoted lines

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> 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..