Subject: Re: [PATCH] parse-options: document automatic PARSE_OPT_LITERAL_ARGHELP

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Wed, 19 Jan 2022 15:41:48 +0100

On Wed, Jan 19 2022, René Scharfe wrote:

> The help strings for arguments are enclosed in angle brackets
> automatically.  E.g. if argh is specified as "name", "--option <name>"
> is printed, to indicate that users need to supply an actual name.  The
> flag PARSE_OPT_LITERAL_ARGHELP turns this off, so that "--option name"
> is printed instead, to indicate that the literal string needs to be
> supplied -- a rare case.
>
> This flag is enabled automatically if argh contains special characters
> like brackets.  The developer is supposed to provide any required angle
> brackets for more complicated cases.  E.g. if argh is "<start>,<end>"
> then "--option <start>,<end>" is printed.
>
> Add a comment to mention this PARSE_OPT_LITERAL_ARGHELP behavior.
>
> Also remove the flag from option definitions for which it's inferred
> automatically.
>
> Signed-off-by: René Scharfe <[email-masked]>
> ---
> Somehow I feel this is not enough, but I can't pin down what's
> missing.

Rather than just remove the flag from {am,push}.c and document this it
would be better to add it to the optbug() checks in
parse_options_check().

That way we'll ensure that these flags won't be redunantly specified, if
we care enough...