From: Junio C Hamano <gitster@pobox.com>
To: git@vger.kernel.org
Subject: [RFC] short help: allow a gap smaller than USAGE_GAP
Date: Tue, 18 Jul 2023 15:58:00 -0700 [thread overview]
Message-ID: <xmqqlefcesjr.fsf_-_@gitster.g> (raw)
In-Reply-To: <xmqqttu0esqb.fsf@gitster.g> (Junio C. Hamano's message of "Tue, 18 Jul 2023 15:54:04 -0700")
The parse-options API responds to "git cmd -h" by listing the option
flag (padded to the USAGE_OPTS_WIDTH column), followed by USAGE_GAP
(set to 2) whitespaces, followed by the help text. If the flags
part does not fit within the USAGE_OPTS_WIDTH, the help text is given
on its own line. Imagine that "@" below depicts the USAGE_OPTS_WIDTH'th
column, and "#" are for the usage help text, the output may look
like this:
@@@@@@@@@@@@@ ########################################
-f description of the flag '-f' comes here
--short=<num> description of the flag '--short'
--very-long-option=<number>
description of the flag '--very-long-option'
This is all good and nice in principle, but it becomes awkward when
the flags part is just one column over the limit and forces a line
break. See the description of the "--almost" option below:
@@@@@@@@@@@@@ ########################################
-f description of the flag '-f' comes here
--short=<num> description of the flag '--short'
--almost=<num>
description of the flag '--almost'
--very-long-option=<number>
description of the flag '--very-long-option'
If we allow shrinking the gap to a single whitespace only in such a
case, we would instead get:
@@@@@@@@@@@@@ ########################################
-f description of the flag '-f' comes here
--short=<num> description of the flag '--short'
--almost=<num> description of the flag '--almost'
--very-long-option=<number>
description of the flag '--very-long-option'
and the boundary between the flags and their descriptions does not
become any harder to see, while saving precious vertical screen real
estate.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
* This makes "git remote add -h" a bit easier to read, because
there is one such option whose flag part is exactly 24-columns
long. Also the changes to t0040 illustrates the effect.
parse-options.c | 4 +++-
t/helper/test-parse-options.c | 2 ++
t/t0040-parse-options.sh | 3 +--
3 files changed, 6 insertions(+), 3 deletions(-)
diff --git a/parse-options.c b/parse-options.c
index 817416db99..87c9fae634 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -1146,7 +1146,9 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t
!(opts->flags & PARSE_OPT_NOARG))
pos += usage_argh(opts, outfile);
- if (pos <= USAGE_OPTS_WIDTH)
+ if (pos == USAGE_OPTS_WIDTH + 1)
+ pad = -1;
+ else if (pos <= USAGE_OPTS_WIDTH)
pad = USAGE_OPTS_WIDTH - pos;
else {
fputc('\n', outfile);
diff --git a/t/helper/test-parse-options.c b/t/helper/test-parse-options.c
index 00fa281a9c..a4f6e24b0c 100644
--- a/t/helper/test-parse-options.c
+++ b/t/helper/test-parse-options.c
@@ -133,6 +133,8 @@ int cmd__parse_options(int argc, const char **argv)
OPT_STRING(0, "st", &string, "st", "get another string (pervert ordering)"),
OPT_STRING('o', NULL, &string, "str", "get another string"),
OPT_NOOP_NOARG(0, "obsolete"),
+ OPT_SET_INT_F(0, "longhelp", &integer, "help text of this entry\n"
+ "spans multiple lines", 0, PARSE_OPT_NONEG),
OPT_STRING_LIST(0, "list", &list, "str", "add str to list"),
OPT_GROUP("Magic arguments"),
OPT_NUMBER_CALLBACK(&integer, "set integer to NUM",
diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh
index 83e5d4eeb6..e19a199636 100755
--- a/t/t0040-parse-options.sh
+++ b/t/t0040-parse-options.sh
@@ -30,8 +30,7 @@ usage: test-tool parse-options <options>
-F, --file <file> set file to <file>
String options
- -s, --string <string>
- get a string
+ -s, --string <string> get a string
--string2 <str> get another string
--st <st> get another string (pervert ordering)
-o <str> get another string
--
2.41.0-376-gcba07a324d
next prev parent reply other threads:[~2023-07-18 22:58 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-07-18 22:29 [PATCH] short help: allow multi-line opthelp Junio C Hamano
2023-07-18 22:31 ` [PATCH] remote: simplify "remote add --tags" help text Junio C Hamano
2023-07-18 22:54 ` [PATCH v2] short help: allow multi-line opthelp Junio C Hamano
2023-07-18 22:58 ` Junio C Hamano [this message]
2023-07-19 22:04 ` [RFC] short help: allow a gap smaller than USAGE_GAP Beat Bolli
2023-07-19 23:26 ` Junio C Hamano
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=xmqqlefcesjr.fsf_-_@gitster.g \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
/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).