[PATCH] parse-options: document automatic PARSE_OPT_LITERAL_ARGHELP

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

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>
---
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)",
 		  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>"),
 			       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
@@ -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