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

["René Scharfe" <l.s.r@web.de>]

Am 19.01.22 um 16:15 schrieb Bryce Ekrem:
> Can you clarify what argh is instead of argc and argv
> sounds like you said arghelp

argh is a member of struct option, defined in parse-options.h.  It is a
string that describes the argument of an option, i.e. it's a short
"argument help" or "argument hint".

> On Wed, Jan 19, 2022 at 2:57 AM René Scharfe <l.s.r@web.de <mailto:l.s.r@web.de>> 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 <l.s.r@web.de <mailto:l.s.r@web.de>>
>     ---
>     Somehow I feel this is not enough, but I can't pin down what's
>     missing.
>
>      builtin/am.c    | 2 +-
>      builtin/push.c  | 2 +-
>      parse-options.h | 2 ++
>      3 files changed, 4 insertions(+), 2 deletions(-)
>
>     diff --git a/builtin/am.c b/builtin/am.c
>     index b6be1f1cb1..fa8d28794a 100644
>     --- a/builtin/am.c
>     +++ b/builtin/am.c
>     @@ -2402,7 +2402,7 @@ int cmd_am(int argc, const char **argv, const char *prefix)
>                     { OPTION_CALLBACK, 0, "show-current-patch", &resume.mode,
>                       "(diff|raw)",
                        ^^^^^^^^^^^^
This is the argh for that particular option (--show-current-patch).

>                       N_("show the patch being applied"),
>     -                 PARSE_OPT_CMDMODE | PARSE_OPT_OPTARG | PARSE_OPT_NONEG | PARSE_OPT_LITERAL_ARGHELP,
>     +                 PARSE_OPT_CMDMODE | PARSE_OPT_OPTARG | PARSE_OPT_NONEG,
>                       parse_opt_show_current_patch, RESUME_SHOW_PATCH },
>                     OPT_CMDMODE(0, "allow-empty", &resume.mode,
>                             N_("record the empty patch as an empty commit"),
>     diff --git a/builtin/push.c b/builtin/push.c
>     index 359db90321..4fa6dfbd09 100644
>     --- a/builtin/push.c
>     +++ b/builtin/push.c
>     @@ -552,7 +552,7 @@ int cmd_push(int argc, const char **argv, const char *prefix)
>                     OPT_BIT('f', "force", &flags, N_("force updates"), TRANSPORT_PUSH_FORCE),
>                     OPT_CALLBACK_F(0, CAS_OPT_NAME, &cas, N_("<refname>:<expect>"),
                                                            ^^^^^^^^^^^^^^^^^^^^^^^^
And here's the one for CAS_OPT_NAME, defined elsewhere, (resolves
to --force-with-lease).

>                                    N_("require old value of ref to be at this value"),
>     -                              PARSE_OPT_OPTARG | PARSE_OPT_LITERAL_ARGHELP, parseopt_push_cas_option),
>     +                              PARSE_OPT_OPTARG, parseopt_push_cas_option),
>                     OPT_BIT(0, TRANS_OPT_FORCE_IF_INCLUDES, &flags,
>                             N_("require remote updates to be integrated locally"),
>                             TRANSPORT_PUSH_FORCE_IF_INCLUDES),
>     diff --git a/parse-options.h b/parse-options.h
>     index e22846d3b7..8d089fb3ae 100644
>     --- a/parse-options.h
>     +++ b/parse-options.h

Here's the comment about argh from parse-options.h:

 * `argh`::
 *   token to explain the kind of argument this option wants. Does not
 *   begin in capital letter, and does not end with a full stop.
 *   Should be wrapped by N_() for translation.


>     @@ -108,6 +108,8 @@ typedef enum parse_opt_result parse_opt_ll_cb(struct parse_opt_ctx_t *ctx,
>       *   PARSE_OPT_LITERAL_ARGHELP: says that argh shouldn't be enclosed in brackets
>       *                             (i.e. '<argh>') in the help message.
>       *                             Useful for options with multiple parameters.
>     + *                             Automatically enabled if argh contains any
>     + *                             of the following characters: ()<>[]|
>       *   PARSE_OPT_NOCOMPLETE: by default all visible options are completable
>       *                        by git-completion.bash. This option suppresses that.
>       *   PARSE_OPT_COMP_ARG: this option forces to git-completion.bash to
>     --
>     2.34.1
>