Re: [PATCH] parse-options: document automatic PARSE_OPT_LITERAL_ARGHELP
- From
René Scharfe <l.s.r@web.de>
- Date
- Jan 21, 2022, 09:42 UTC
- Message-ID
- <f6cc8042-a455-6398-9f91-0e64921252e4@web.de>
- In-Reply-To
- <xmqqiluejmcp.fsf@gitster.g>
Am 20.01.22 um 19:25 schrieb Junio C Hamano:
Show 46 quoted lines
> René Scharfe <l.s.r@web.de> writes: > >> Now that I read the whole comment, I think the right place to introduce >> the automatic brackets is the description of argh some lines up. >> >> --- >8 --- >> Subject: [PATCH 5/5] parse-options: document bracketing of argh >> >> Signed-off-by: René Scharfe <l.s.r@web.de> >> --- >> parse-options.h | 5 +++++ >> 1 file changed, 5 insertions(+) >> >> diff --git a/parse-options.h b/parse-options.h >> index e22846d3b7..88d589d159 100644 >> --- a/parse-options.h >> +++ b/parse-options.h >> @@ -85,6 +85,11 @@ typedef enum parse_opt_result parse_opt_ll_cb(struct parse_opt_ctx_t *ctx, >> * 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. >> + * Is automatically enclosed in brackets when printed, unless it >> + * contains any of the following characters: ()<>[]| >> + * E.g. "name" is shown as "<name>" to indicate that a name value >> + * needs to be supplied, not the literal string "name", but >> + * "<start>,<end>" and "(this|that)" are printed verbatim. >> * >> * `help`:: >> * the short help associated to what the option does. > > Very nice. > > This version gives the necessary information in (almost) one place. > > I said (almost) because "it contains any of ..." is not the only way > to decline the <automatic angle brackets>, and am wondering if it is > more helpful to say something like > > ... when printed, unless PARSE_OPT_LITERAL_ARGHELP is set in > the flags, or it contains any of the following characters: ... > > and then shrink the description of the flag bit to > > PARSE_OPT_LITERAL_ARGHELP: controls if `argh` is enclosed in in > brackets when shown (see the description on `argh` above). >
The idea was to document the base behavior at the top and the effects of flags at the bottom. Blurring this distinction and cross-referencing gives a better whole, though, I agree. It would have helped me find the right place to put the list of special chars, for one thing. So how about this?
--- >8 --- Subject: [PATCH v2] parse-options: document bracketing of argh
Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: René Scharfe <l.s.r@web.de> --- parse-options.h | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-)
diff --git a/parse-options.h b/parse-options.h index e22846d3b7..2e801b3c9a 100644 --- a/parse-options.h +++ b/parse-options.h @@ -85,6 +85,11 @@ typedef enum parse_opt_result parse_opt_ll_cb(struct parse_opt_ctx_t *ctx, * 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. + * Is enclosed in brackets when printed, unless PARSE_OPT_LITERAL_ARGHELP + * is set in `flags` or it contains any of the following characters: ()<>[]| + * E.g. "name" is shown as "<name>" to indicate that a name value + * needs to be supplied, not the literal string "name", but + * "<start>,<end>" and "(this|that)" are printed verbatim. * * `help`:: * the short help associated to what the option does. @@ -105,9 +110,8 @@ typedef enum parse_opt_result parse_opt_ll_cb(struct parse_opt_ctx_t *ctx, * not last it will require an argument. * Should not be used with PARSE_OPT_OPTARG. * PARSE_OPT_NODASH: this option doesn't start with a dash. - * 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. + * PARSE_OPT_LITERAL_ARGHELP: says that `argh` shouldn't be enclosed in + * brackets (see `argh` description above). * 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