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

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

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