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

From: Junio C Hamano <[email-masked]>
Date: Fri, 29 Jul 2022 17:17:50 -0700

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

> While we're at it remove a stray newline that had been added after the
> "return name;" statement.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <[email-masked]>
> ---
>  help.c | 10 ++++++++--
>  1 file changed, 8 insertions(+), 2 deletions(-)
>
> diff --git a/help.c b/help.c
> index 41c41c2aa11..80d516abb0b 100644
> --- a/help.c
> +++ b/help.c
> @@ -44,13 +44,19 @@ static struct category_description main_categories[] = {
>  static const char *drop_prefix(const char *name, uint32_t category)
>  {
>  	const char *new_name;
> +	const char *prefix;
>  
>  	if (skip_prefix(name, "git-", &new_name))
>  		return new_name;
> -	if (category == CAT_guide && skip_prefix(name, "git", &new_name))
> +	switch (category) {
> +	case CAT_guide:
> +		prefix = "git";
> +		if (!skip_prefix(name, prefix, &new_name))
> +			BUG("'%s' in category #%d should have '%s' prefix",
> +			    name, category, prefix);
>  		return new_name;
> +	}
>  	return name;
> -
>  }
>  
>  static void extract_cmds(struct cmdname_help **p_cmds, uint32_t mask)