short help: allow multi-line opthelp
PATCH 1/1 short help: allow multi-line opthelp
When "-h" triggers the short-help in a command that implements its option parsing using the parse-options API, the option help text is shown with a single fprintf() as a long line. When the text is multi-line, the second and subsequent lines are not left padded, that breaks the alignment across options.
Borrowing the idea from the advice API where its hint strings are shown with (localized) "hint:" prefix, let's internally split the (localized) help text into lines, and showing the first line, pad the remaining lines to align.
--- parse-options.c | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-)
parse-options.c +11 -1
@@ -1109,6 +1109,7 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_tfor (; opts->type !=OPTION_END ; opts++) {size_t pos;int pad; +const char *cp, *np;if (opts->type ==OPTION_SUBCOMMAND )continue ;
@@ -1157,7 +1158,16 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t (const char *)opts->value);continue ; } -fprintf (outfile,"%*s%s\n" , pad +USAGE_GAP ,"" ,_ (opts->help)); + +for (cp =_ (opts->help); *cp; cp = np) { + np =strchrnul (cp,'\n' ); +fprintf (outfile, +"%*s%.*s\n" , pad +USAGE_GAP ,"" , + (int )(np - cp), cp); +if (*np) + np++; + pad =USAGE_OPTS_WIDTH ; + } }fputc ('\n' , outfile);
Signature · 1 line
2.41.0-376-gcba07a324d
PATCH 1/1 remote: simplify "remote add --tags" help text
The help text for the --tags option was split into two option[] entries, which was a hacky way to give two lines of help text (the second entry did not have either short or long help, and there was no way to invoke its entry---it was there only for the help text).
As we now support multi-line text in the option help, let's make the second line of the help a proper second line and remove the hacky second entry.
--- builtin/remote.c | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
builtin/remote.c +2 -3
@@ -167,10 +167,9 @@ static int add(int argc, const char **argv, const char *prefix)struct option options[] = {OPT_BOOL ('f' ,"fetch" , &fetch,N_ ("fetch the remote branches" )),OPT_SET_INT (0 ,"tags" , &fetch_tags, -N_ ("import all tags and associated objects when fetching" ), +N_ ("import all tags and associated objects when fetching\n" +"or do not fetch any tag at all (--no-tags)" ),TAGS_SET ), -OPT_SET_INT (0 ,NULL , &fetch_tags, -N_ ("or do not fetch any tag at all (--no-tags)" ),TAGS_UNSET ),OPT_STRING_LIST ('t' ,"track" , &track,N_ ("branch" ),N_ ("branch(es) to track" )),OPT_STRING ('m' ,"master" , &master,N_ ("branch" ),N_ ("master branch" )),
Signature · 1 line
2.41.0-376-gcba07a324d
PATCH v2 1/1 short help: allow multi-line opthelp
In reply to Junio C HamanoWhen "-h" triggers the short-help in a command that implements its option parsing using the parse-options API, the option help text is shown with a single fprintf() as a long line. When the text is multi-line, the second and subsequent lines are not left padded, that breaks the alignment across options.
Borrowing the idea from the advice API where its hint strings are shown with (localized) "hint:" prefix, let's internally split the (localized) help text into lines, and showing the first line, pad the remaining lines to align.
---
* With a new test.
parse-options.c | 12 +++++++++++- t/t0040-parse-options.sh | 2 ++ 2 files changed, 13 insertions(+), 1 deletion(-)
parse-options.c +11 -1
@@ -1109,6 +1109,7 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_tfor (; opts->type !=OPTION_END ; opts++) {size_t pos;int pad; +const char *cp, *np;if (opts->type ==OPTION_SUBCOMMAND )continue ;
@@ -1157,7 +1158,16 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t (const char *)opts->value);continue ; } -fprintf (outfile,"%*s%s\n" , pad +USAGE_GAP ,"" ,_ (opts->help)); + +for (cp =_ (opts->help); *cp; cp = np) { + np =strchrnul (cp,'\n' ); +fprintf (outfile, +"%*s%.*s\n" , pad +USAGE_GAP ,"" , + (int )(np - cp), cp); +if (*np) + np++; + pad =USAGE_OPTS_WIDTH ; + } }fputc ('\n' , outfile);
t/t0040-parse-options.sh +2 -0
@@ -35,6 +35,8 @@ String options --string2 <str> get another string --st <st> get another string (pervert ordering) -o <str> get another string + --longhelp help text of this entry + spans multiple lines --list <str> add str to list Magic arguments
Signature · 1 line
2.41.0-376-gcba07a324d
RFC 1/1 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.
---
* 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(-)
parse-options.c +3 -1
@@ -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);
t/helper/test-parse-options.c +2 -0
@@ -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",
t/t0040-parse-options.sh +1 -2
@@ -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
Signature · 1 line
2.41.0-376-gcba07a324d
Re: [RFC] short help: allow a gap smaller than USAGE_GAP
Hi
On 19.07.23 00:58, Junio C Hamano wrote:
[...]
t/helper/test-parse-options.c int cmd__parse_options(int argc, const char **argv) · line 140
Quoted 13 lines
t/helper/test-parse-options.c +2
-0@@ -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",
I think this chunk should be part of the previous commit.
Beat
Re: [RFC] short help: allow a gap smaller than USAGE_GAP
Quoted 7 lines · Beat Bolli
t/helper/test-parse-options.c int cmd__parse_options(int argc, const char **argv) · line 140
Quoted 5 lines
t/helper/test-parse-options.c +2
-0+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",I think this chunk should be part of the previous commit.
Good eyes. Thanks.