From: "René Scharfe" <l.s.r@web.de>
To: Junio C Hamano <gitster@pobox.com>
Cc: Josh Steadmon <steadmon@google.com>,
git@vger.kernel.org, avarab@gmail.com
Subject: Re: [PATCH] parse-options: document automatic PARSE_OPT_LITERAL_ARGHELP
Date: Fri, 21 Jan 2022 10:42:58 +0100 [thread overview]
Message-ID: <f6cc8042-a455-6398-9f91-0e64921252e4@web.de> (raw)
In-Reply-To: <xmqqiluejmcp.fsf@gitster.g>
Am 20.01.22 um 19:25 schrieb Junio C Hamano:
> 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
next prev parent reply other threads:[~2022-01-21 9:43 UTC|newest]
Thread overview: 103+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-09-08 20:15 [RFC PATCH] branch: add "inherit" option for branch.autoSetupMerge Josh Steadmon
2021-09-08 20:44 ` Josh Steadmon
2021-09-11 0:25 ` [PATCH v2] " Josh Steadmon
2021-09-11 0:52 ` Junio C Hamano
2021-10-17 4:35 ` Josh Steadmon
2021-10-17 5:50 ` Junio C Hamano
2021-11-15 21:57 ` Josh Steadmon
2021-10-17 4:45 ` [PATCH v3] branch: add flags and config to inherit tracking Josh Steadmon
2021-10-18 18:31 ` Ævar Arnfjörð Bjarmason
2021-10-18 21:44 ` Junio C Hamano
2021-10-18 22:11 ` Ævar Arnfjörð Bjarmason
2021-11-15 22:22 ` Josh Steadmon
2021-10-18 17:50 ` [RFC PATCH] branch: add "inherit" option for branch.autoSetupMerge Glen Choo
2021-10-18 18:08 ` Glen Choo
2021-11-15 21:44 ` Josh Steadmon
2021-11-16 18:25 ` [PATCH v4] branch: add flags and config to inherit tracking Josh Steadmon
2021-11-17 0:33 ` Glen Choo
2021-11-18 22:29 ` Junio C Hamano
2021-11-30 22:05 ` Josh Steadmon
2021-11-19 6:47 ` Ævar Arnfjörð Bjarmason
2021-11-30 21:34 ` Josh Steadmon
2021-12-01 9:11 ` Ævar Arnfjörð Bjarmason
2021-12-07 7:12 ` [PATCH v5 0/2] branch: inherit tracking configs Josh Steadmon
2021-12-07 7:12 ` [PATCH v5 1/2] branch: accept multiple upstream branches for tracking Josh Steadmon
2021-12-07 8:57 ` Ævar Arnfjörð Bjarmason
2021-12-09 23:03 ` Josh Steadmon
2021-12-10 1:00 ` Ævar Arnfjörð Bjarmason
2021-12-07 19:28 ` Junio C Hamano
2021-12-14 20:35 ` Josh Steadmon
2021-12-08 0:16 ` Glen Choo
2021-12-08 0:17 ` Glen Choo
2021-12-09 22:45 ` Josh Steadmon
2021-12-09 23:47 ` Glen Choo
2021-12-10 1:03 ` Ævar Arnfjörð Bjarmason
2021-12-10 17:32 ` Glen Choo
2021-12-11 2:18 ` Ævar Arnfjörð Bjarmason
2021-12-08 23:53 ` Glen Choo
2021-12-09 0:08 ` Glen Choo
2021-12-09 22:49 ` Josh Steadmon
2021-12-09 23:43 ` Glen Choo
2021-12-07 7:12 ` [PATCH v5 2/2] branch: add flags and config to inherit tracking Josh Steadmon
2021-12-07 9:08 ` Ævar Arnfjörð Bjarmason
2021-12-08 0:35 ` Glen Choo
2021-12-14 22:15 ` Josh Steadmon
2021-12-14 22:27 ` Josh Steadmon
2021-12-07 19:41 ` Junio C Hamano
2021-12-14 20:37 ` Josh Steadmon
2021-12-08 1:02 ` Glen Choo
2021-12-14 22:10 ` Josh Steadmon
2021-12-07 18:52 ` [PATCH v5 0/2] branch: inherit tracking configs Junio C Hamano
2021-12-08 17:06 ` Glen Choo
2021-12-10 22:48 ` Johannes Schindelin
2021-12-14 22:11 ` Josh Steadmon
2021-12-14 23:44 ` [PATCH v6 0/3] " Josh Steadmon
2021-12-14 23:44 ` [PATCH v6 1/3] branch: accept multiple upstream branches for tracking Josh Steadmon
2021-12-15 21:30 ` Junio C Hamano
2021-12-16 19:57 ` Glen Choo
2021-12-17 5:10 ` Josh Steadmon
2021-12-20 18:29 ` Glen Choo
2021-12-21 3:27 ` Josh Steadmon
2021-12-14 23:44 ` [PATCH v6 2/3] branch: add flags and config to inherit tracking Josh Steadmon
2021-12-16 21:27 ` Glen Choo
2021-12-17 5:11 ` Josh Steadmon
2021-12-14 23:44 ` [PATCH v6 3/3] config: require lowercase for branch.autosetupmerge Josh Steadmon
2021-12-15 0:43 ` [PATCH v6 0/3] branch: inherit tracking configs Josh Steadmon
2021-12-16 0:02 ` Junio C Hamano
2021-12-16 0:37 ` Glen Choo
2021-12-16 1:20 ` Junio C Hamano
2021-12-17 5:12 ` [PATCH v7 " Josh Steadmon
2021-12-17 5:12 ` [PATCH v7 1/3] branch: accept multiple upstream branches for tracking Josh Steadmon
2021-12-17 5:12 ` [PATCH v7 2/3] branch: add flags and config to inherit tracking Josh Steadmon
2021-12-17 5:12 ` [PATCH v7 3/3] config: require lowercase for branch.*.autosetupmerge Josh Steadmon
2021-12-20 21:05 ` [PATCH v7 0/3] branch: inherit tracking configs Glen Choo
2021-12-21 3:30 ` [PATCH v8 " Josh Steadmon
2021-12-21 3:30 ` [PATCH v8 1/3] branch: accept multiple upstream branches for tracking Josh Steadmon
2021-12-21 6:55 ` Junio C Hamano
2021-12-21 18:25 ` Glen Choo
2021-12-21 3:30 ` [PATCH v8 2/3] branch: add flags and config to inherit tracking Josh Steadmon
2021-12-21 18:17 ` Glen Choo
2022-01-11 1:57 ` incorrect 'git (checkout|branch) -h' output with new --track modes (was: [PATCH v8 2/3] branch: add flags and config to inherit tracking) Ævar Arnfjörð Bjarmason
2022-01-18 20:49 ` [PATCH] branch,checkout: fix --track usage strings Josh Steadmon
2022-01-18 22:26 ` Junio C Hamano
2022-01-19 10:56 ` [PATCH] parse-options: document automatic PARSE_OPT_LITERAL_ARGHELP René Scharfe
2022-01-19 14:41 ` Ævar Arnfjörð Bjarmason
[not found] ` <CA++g3E-azP3wFTtNkbFdmT7VW3hvULL0WkkAdwfrMb6HDtcXdg@mail.gmail.com>
2022-01-19 15:30 ` René Scharfe
2022-01-19 18:16 ` Junio C Hamano
2022-01-20 10:30 ` René Scharfe
2022-01-20 18:25 ` Junio C Hamano
2022-01-21 9:42 ` René Scharfe [this message]
2022-01-21 20:59 ` Junio C Hamano
2022-01-20 12:05 ` [PATCH] branch,checkout: fix --track usage strings Ævar Arnfjörð Bjarmason
2022-01-20 12:18 ` Andreas Schwab
2022-01-20 14:00 ` Ævar Arnfjörð Bjarmason
2022-01-20 18:38 ` Junio C Hamano
2022-01-21 11:27 ` Ævar Arnfjörð Bjarmason
2022-01-21 21:12 ` Junio C Hamano
2022-01-19 10:20 ` incorrect 'git (checkout|branch) -h' output with new --track modes (was: [PATCH v8 2/3] branch: add flags and config to inherit tracking) René Scharfe
2022-01-20 12:00 ` Ævar Arnfjörð Bjarmason
2022-01-20 12:35 ` [PATCH] branch,checkout: fix --track documentation René Scharfe
2022-01-20 13:57 ` Ævar Arnfjörð Bjarmason
2022-01-20 19:08 ` Junio C Hamano
2021-12-21 3:30 ` [PATCH v8 3/3] config: require lowercase for branch.*.autosetupmerge Josh Steadmon
2021-12-21 18:13 ` [PATCH v8 0/3] branch: inherit tracking configs Glen Choo
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=f6cc8042-a455-6398-9f91-0e64921252e4@web.de \
--to=l.s.r@web.de \
--cc=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=steadmon@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).