[RFC] short help: allow a gap smaller than USAGE_GAP
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(-)
Show changes to 3 files +6 −3
parse-options.c, t/helper/test-parse-options.c, t/t0040-parse-options.sh
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
Junio C Hamano