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

Ævar Arnfjörð Bjarmason  [off-list ref] writes:

quoted

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..