On Fri, Jul 29 2022, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> 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..
