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

[Junio C Hamano <gitster@pobox.com>]

René Scharfe <l.s.r@web.de> writes:

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

Since "does not begin", "does not end", "should be wrapped" are
about how it appears in the initializer of the struct option, I had
to read twice before realizing that "Is enclosed" is *not* about
what the developer has to do.

Making it clear that this is not part of "enumeration of sentences,
which omit the same subject, that describe how the value appears in
the source", e.g.

	When "git cmd -h" shows it, `argh` is enclosed in
	<brackets>, unless ...

would have avoided the confusion.

Other than that, I think this version is the clearest and easiest to
understand among the options in this thread we have seen so far.

Thanks.


>   *
>   * `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