[PATCH] usage_with_options: omit double new line on empty option list

[PATCH] usage_with_options: omit double new line on empty option list

[Stefan Beller]

Currently the worktree command gives its usage, when no subcommand is
given. However there are no general options, all options are related to
the subcommands itself, such that:

    $ git worktree
    usage: git worktree add [<options>] <path> [<branch>]
       or: git worktree list [<options>]
       or: git worktree lock [<options>] <path>
       or: git worktree prune [<options>]
       or: git worktree unlock <path>


    $

Note the two empty lines at the end of the usage string. This is because
the toplevel usage is printed with an empty options list.

Only print one new line after the usage string if the option list is empty.

Signed-off-by: Stefan Beller <sbeller@google.com>
---
 parse-options.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/parse-options.c b/parse-options.c
index 0dd9fc6a0d..1307c82861 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -603,7 +603,7 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
 		usagestr++;
 	}
 
-	if (opts->type != OPTION_GROUP)
+	if (opts->type != OPTION_GROUP && opts->type != OPTION_END)
 		fputc('\n', outfile);
 
 	for (; opts->type != OPTION_END; opts++) {
-- 
2.14.0.rc0.3.g6c2e499285

Re: [PATCH] usage_with_options: omit double new line on empty option list

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> Currently the worktree command gives its usage, when no subcommand is
> given. However there are no general options, all options are related to
> the subcommands itself, such that:
>
>     $ git worktree
>     usage: git worktree add [<options>] <path> [<branch>]
>        or: git worktree list [<options>]
>        or: git worktree lock [<options>] <path>
>        or: git worktree prune [<options>]
>        or: git worktree unlock <path>
>
>
>     $
>
> Note the two empty lines at the end of the usage string. This is because
> the toplevel usage is printed with an empty options list.
>
> Only print one new line after the usage string if the option list is empty.

Good find.  Shouldn't the last word in the sentence "non-empty", though?

>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>  parse-options.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/parse-options.c b/parse-options.c
> index 0dd9fc6a0d..1307c82861 100644
> --- a/parse-options.c
> +++ b/parse-options.c
> @@ -603,7 +603,7 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
>  		usagestr++;
>  	}
>  
> -	if (opts->type != OPTION_GROUP)
> +	if (opts->type != OPTION_GROUP && opts->type != OPTION_END)
>  		fputc('\n', outfile);
>  
>  	for (; opts->type != OPTION_END; opts++) {

Re: [PATCH] usage_with_options: omit double new line on empty option list

[Stefan Beller]

On Fri, Aug 25, 2017 at 10:18 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>> Currently the worktree command gives its usage, when no subcommand is
>> given. However there are no general options, all options are related to
>> the subcommands itself, such that:
>>
>>     $ git worktree
>>     usage: git worktree add [<options>] <path> [<branch>]
>>        or: git worktree list [<options>]
>>        or: git worktree lock [<options>] <path>
>>        or: git worktree prune [<options>]
>>        or: git worktree unlock <path>
>>
>>
>>     $
>>
>> Note the two empty lines at the end of the usage string. This is because
>> the toplevel usage is printed with an empty options list.
>>
>> Only print one new line after the usage string if the option list is empty.
>
> Good find.  Shouldn't the last word in the sentence "non-empty", though?\

Yes.

Originally I wrote a lot more and then deleted it all, mixing up the negations
of what I was trying to say.

Re: [PATCH] usage_with_options: omit double new line on empty option list

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Stefan Beller <sbeller@google.com> writes:
>
>> Currently the worktree command gives its usage, when no subcommand is
>> given. However there are no general options, all options are related to
>> the subcommands itself, such that:
>>
>>     $ git worktree
>>     usage: git worktree add [<options>] <path> [<branch>]
>>        or: git worktree list [<options>]
>>        or: git worktree lock [<options>] <path>
>>        or: git worktree prune [<options>]
>>        or: git worktree unlock <path>
>>
>>
>>     $
>>
>> Note the two empty lines at the end of the usage string. This is because
>> the toplevel usage is printed with an empty options list.
>>
>> Only print one new line after the usage string if the option list is empty.
>
> Good find.  Shouldn't the last word in the sentence "non-empty", though?

Ah, the "do this" part was hard to understand and I misread it.  I
thought you were saying "only give a blank if we have something that
need to be separated from the stuff above".

So what you wrote above is not incorrect per-se, but I think it is
prone to be misunderstood.

>
>>
>> Signed-off-by: Stefan Beller <sbeller@google.com>
>> ---
>>  parse-options.c | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/parse-options.c b/parse-options.c
>> index 0dd9fc6a0d..1307c82861 100644
>> --- a/parse-options.c
>> +++ b/parse-options.c
>> @@ -603,7 +603,7 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
>>  		usagestr++;
>>  	}
>>  
>> -	if (opts->type != OPTION_GROUP)
>> +	if (opts->type != OPTION_GROUP && opts->type != OPTION_END)
>>  		fputc('\n', outfile);
>>  
>>  	for (; opts->type != OPTION_END; opts++) {

Re: [PATCH] usage_with_options: omit double new line on empty option list

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> Currently the worktree command gives its usage, when no subcommand is
> given. However there are no general options, all options are related to
> the subcommands itself, such that:
>
>     $ git worktree
>     usage: git worktree add [<options>] <path> [<branch>]
>        or: git worktree list [<options>]
>        or: git worktree lock [<options>] <path>
>        or: git worktree prune [<options>]
>        or: git worktree unlock <path>
>
>
>     $
>
> Note the two empty lines at the end of the usage string. This is because
> the toplevel usage is printed with an empty options list.

I have this feeling that this patch may not be sufficient.  

The reason for the first blank line is because we unconditionally
emit one, expecting that we would have a list of options to show and
want to separate the usage from that list, and the fix in this patch
is correct---it is the right way to suppress it.

But why do we need the second blank line in this case?  There is a
similar unconditional LF near the end of this function.  Is somebody
else (other than usage_with_options() which will exit immeidately)
calls this function and expects to say something more after what
this function said, and is this extra blank line at the end is to
prepare for that caller?

> Only print one new line after the usage string if the option list is empty.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>  parse-options.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/parse-options.c b/parse-options.c
> index 0dd9fc6a0d..1307c82861 100644
> --- a/parse-options.c
> +++ b/parse-options.c
> @@ -603,7 +603,7 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
>  		usagestr++;
>  	}
>  
> -	if (opts->type != OPTION_GROUP)
> +	if (opts->type != OPTION_GROUP && opts->type != OPTION_END)
>  		fputc('\n', outfile);
>  
>  	for (; opts->type != OPTION_END; opts++) {

[PATCH] usage_with_options: omit double new line on empty option list

[Stefan Beller]

Currently the worktree command gives its usage, when no subcommand is
given. However there are no general options, all options are related to
the subcommands itself, such that:

 #    $ git worktree
 #    usage: git worktree add [<options>] <path> [<branch>]
 #       or: git worktree list [<options>]
 #       or: git worktree lock [<options>] <path>
 #       or: git worktree prune [<options>]
 #       or: git worktree unlock <path>
 #
 #
 #    $

Note the two empty lines at the end of the usage string. This is because
the toplevel usage is printed with an empty options list.

Only print a new line after the option list if it is not empty.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

> I have this feeling that this patch may not be sufficient.
>
> The reason for the first blank line is because we unconditionally
> emit one, expecting that we would have a list of options to show and
> want to separate the usage from that list, and the fix in this patch
> is correct---it is the right way to suppress it.
>
> But why do we need the second blank line in this case?  There is a
> similar unconditional LF near the end of this function.  Is somebody
> else (other than usage_with_options() which will exit immeidately)
> calls this function and expects to say something more after what
> this function said, and is this extra blank line at the end is to
> prepare for that caller?

Good point, parse_options[_step] also makes use of the 
usage_with_options_internal, such that the regular options
need to work, with a potentially interesting arrangement of OPTION_GROUPs.

I think this one is cleaner, as it omits the correct LF.

Thanks,
Stefan

 parse-options.c | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/parse-options.c b/parse-options.c
index 0dd9fc6a0d..2829c16b01 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -580,6 +580,7 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
 				       const char * const *usagestr,
 				       const struct option *opts, int full, int err)
 {
+	int new_line_after_opts;
 	FILE *outfile = err ? stderr : stdout;
 
 	if (!usagestr)
@@ -606,6 +607,8 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
 	if (opts->type != OPTION_GROUP)
 		fputc('\n', outfile);
 
+	new_line_after_opts = (opts->type != OPTION_END);
+
 	for (; opts->type != OPTION_END; opts++) {
 		size_t pos;
 		int pad;
@@ -645,7 +648,9 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
 		}
 		fprintf(outfile, "%*s%s\n", pad + USAGE_GAP, "", _(opts->help));
 	}
-	fputc('\n', outfile);
+
+	if (new_line_after_opts)
+		fputc('\n', outfile);
 
 	if (!err && ctx && ctx->flags & PARSE_OPT_SHELL_EVAL)
 		fputs("EOF\n", outfile);
-- 
2.14.0.rc0.3.g6c2e499285

Re: [PATCH] usage_with_options: omit double new line on empty option list

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> Currently the worktree command gives its usage, when no subcommand is
> given. However there are no general options, all options are related to
> the subcommands itself, such that:
>
>  #    $ git worktree
>  #    usage: git worktree add [<options>] <path> [<branch>]
>  #       or: git worktree list [<options>]
>  #       or: git worktree lock [<options>] <path>
>  #       or: git worktree prune [<options>]
>  #       or: git worktree unlock <path>
>  #
>  #
>  #    $
>
> Note the two empty lines at the end of the usage string. This is because
> the toplevel usage is printed with an empty options list.
>
> Only print a new line after the option list if it is not empty.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>
>> I have this feeling that this patch may not be sufficient.
>>
>> The reason for the first blank line is because we unconditionally
>> emit one, expecting that we would have a list of options to show and
>> want to separate the usage from that list, and the fix in this patch
>> is correct---it is the right way to suppress it.
>>
>> But why do we need the second blank line in this case?  There is a
>> similar unconditional LF near the end of this function.  Is somebody
>> else (other than usage_with_options() which will exit immeidately)
>> calls this function and expects to say something more after what
>> this function said, and is this extra blank line at the end is to
>> prepare for that caller?
>
> Good point, parse_options[_step] also makes use of the 
> usage_with_options_internal, such that the regular options
> need to work, with a potentially interesting arrangement of OPTION_GROUPs.
>
> I think this one is cleaner, as it omits the correct LF.

Sorry, but now I am utterly confused, as I do not think I've made a
"good point", and I do not see how your "this one is cleaner than
the previous" can follow from what I said.

The first fputc('\n', outfile) touched in the previous version but
not this one is shown after the usage string.  I think the intention
of that is "We have finished giving the usage; now we are going to
list options, and we need a separator blank line in between", and
the reason why it is not conditional on "do we even have any option
in the list?" is probably those who helped parse-options evolve
never saw a user of parse-options API that actually does not have
any option.  So from that point of view, it is understandable why we
didn't check with OPTION_END and checking OPTION_END there and
omitting the blank makes sense---I understand what the previous
patch did, in other words, and agree with what it did.

By the way, it checked OPTION_GROUP and that is also
understandable.  In the loop, there will be a blank berfore each
option group to visually separate things across groups; if we know
the first entry in the options list is such an entry, then we do not
want a blank, as the blank (meant as a separator between usage and
option list) will be followed by another blank (meant as a separator
between groups) and we waste one blank line.

The other fputc('\n', outfile) that this version of the patch
touches is what I had trouble with, and I still do.  There must be a
similar rationale like the previous one, i.e. "We have finished
giving the usage, and we have finished showing all the options.  Now
we are about to further show X, so let's have a blank line here so
that what we have wrote will be separated from it", but I cannot
tell what that X is.

In other words, what I suspect the _right_ solution is, is to have
the previous patch that omits the first LF when the type of the
first element in the options array is either END or GROUP, plus
unconditional removal of the second LF.  If some caller of this
helper function has "now we are going to also show X and we want a
separator", I think that code should be showing the LF as needed.
usage_with_options(), the caller you showed its behaviour in your
proposed log message, does *not* want either of these two LFs, I
would think.



> Thanks,
> Stefan
>
>  parse-options.c | 7 ++++++-
>  1 file changed, 6 insertions(+), 1 deletion(-)
>
> diff --git a/parse-options.c b/parse-options.c
> index 0dd9fc6a0d..2829c16b01 100644
> --- a/parse-options.c
> +++ b/parse-options.c
> @@ -580,6 +580,7 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
>  				       const char * const *usagestr,
>  				       const struct option *opts, int full, int err)
>  {
> +	int new_line_after_opts;
>  	FILE *outfile = err ? stderr : stdout;
>  
>  	if (!usagestr)
> @@ -606,6 +607,8 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
>  	if (opts->type != OPTION_GROUP)
>  		fputc('\n', outfile);
>  
> +	new_line_after_opts = (opts->type != OPTION_END);
> +
>  	for (; opts->type != OPTION_END; opts++) {
>  		size_t pos;
>  		int pad;
> @@ -645,7 +648,9 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
>  		}
>  		fprintf(outfile, "%*s%s\n", pad + USAGE_GAP, "", _(opts->help));
>  	}
> -	fputc('\n', outfile);
> +
> +	if (new_line_after_opts)
> +		fputc('\n', outfile);
>  
>  	if (!err && ctx && ctx->flags & PARSE_OPT_SHELL_EVAL)
>  		fputs("EOF\n", outfile);

Re: [PATCH] usage_with_options: omit double new line on empty option list

[Stefan Beller]

On Fri, Aug 25, 2017 at 1:27 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>> Currently the worktree command gives its usage, when no subcommand is
>> given. However there are no general options, all options are related to
>> the subcommands itself, such that:
>>
>>  #    $ git worktree
>>  #    usage: git worktree add [<options>] <path> [<branch>]
>>  #       or: git worktree list [<options>]
>>  #       or: git worktree lock [<options>] <path>
>>  #       or: git worktree prune [<options>]
>>  #       or: git worktree unlock <path>
>>  #
>>  #
>>  #    $
>>
>> Note the two empty lines at the end of the usage string. This is because
>> the toplevel usage is printed with an empty options list.
>>
>> Only print a new line after the option list if it is not empty.
>>
>> Signed-off-by: Stefan Beller <sbeller@google.com>
>> ---
>>
>>> I have this feeling that this patch may not be sufficient.
>>>
>>> The reason for the first blank line is because we unconditionally
>>> emit one, expecting that we would have a list of options to show and
>>> want to separate the usage from that list, and the fix in this patch
>>> is correct---it is the right way to suppress it.
>>>
>>> But why do we need the second blank line in this case?  There is a
>>> similar unconditional LF near the end of this function.  Is somebody
>>> else (other than usage_with_options() which will exit immeidately)
>>> calls this function and expects to say something more after what
>>> this function said, and is this extra blank line at the end is to
>>> prepare for that caller?
>>
>> Good point, parse_options[_step] also makes use of the
>> usage_with_options_internal, such that the regular options
>> need to work, with a potentially interesting arrangement of OPTION_GROUPs.
>>
>> I think this one is cleaner, as it omits the correct LF.
>
> Sorry, but now I am utterly confused, as I do not think I've made a
> "good point", and I do not see how your "this one is cleaner than
> the previous" can follow from what I said.
>
> The first fputc('\n', outfile) touched in the previous version but
> not this one is shown after the usage string.  I think the intention
> of that is "We have finished giving the usage; now we are going to
> list options, and we need a separator blank line in between", and
> the reason why it is not conditional on "do we even have any option
> in the list?" is probably those who helped parse-options evolve
> never saw a user of parse-options API that actually does not have
> any option.  So from that point of view, it is understandable why we
> didn't check with OPTION_END and checking OPTION_END there and
> omitting the blank makes sense---I understand what the previous
> patch did, in other words, and agree with what it did.
>
> By the way, it checked OPTION_GROUP and that is also
> understandable.  In the loop, there will be a blank berfore each
> option group to visually separate things across groups; if we know
> the first entry in the options list is such an entry, then we do not
> want a blank, as the blank (meant as a separator between usage and
> option list) will be followed by another blank (meant as a separator
> between groups) and we waste one blank line.

Ah, yes. I did not want to mess with that pattern for option groups
in this patch, but rather omit the "correct" LF, which is the one after
the option listing instead of before the option listing.


> The other fputc('\n', outfile) that this version of the patch
> touches is what I had trouble with, and I still do.  There must be a
> similar rationale like the previous one, i.e. "We have finished
> giving the usage, and we have finished showing all the options.  Now
> we are about to further show X, so let's have a blank line here so
> that what we have wrote will be separated from it", but I cannot
> tell what that X is.

Oh. I assumed that this X is the the next command in the users
terminal, but I checked other commands and that is not the case
at all (at least ls, vi, tar)

Upon closer inspection, I have the impression that f389c808b6
(Rework make_usage to print the usage message immediately,
2007-10-14) introduced the extra new line without giving a rationale.
(I could not find relevant review/discussion of that patch in the archive)

> In other words, what I suspect the _right_ solution is, is to have
> the previous patch that omits the first LF when the type of the
> first element in the options array is either END or GROUP, plus
> unconditional removal of the second LF.

This unconditional removal that you hint at seems to fix the bug
that I suspect introduced at the given commit. And tightening
the condition of the first LF seems to fix the itch that I was having
then.

> If some caller of this
> helper function has "now we are going to also show X and we want a
> separator", I think that code should be showing the LF as needed.
> usage_with_options(), the caller you showed its behaviour in your
> proposed log message, does *not* want either of these two LFs, I
> would think.
>

I can follow that.

Re: [PATCH] usage_with_options: omit double new line on empty option list

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> Upon closer inspection, I have the impression that f389c808b6
> (Rework make_usage to print the usage message immediately,
> 2007-10-14) introduced the extra new line without giving a rationale.

I do not think that is the case.  The code before that patch
collected all the usage strings in a strbuf sb, which had lines with
their own terminating LFs, and then called usage() on sb.buf, which
added an extra LF, so I think the commit was a faithful and bug-to-bug
compatible rewrite.

But that does not matter in the bigger picture, as long as everybody
agrees with the following:

>> The other fputc('\n', outfile) that this version of the patch
>> touches is what I had trouble with, and I still do.  There must be a
>> similar rationale like the previous one, i.e. "We have finished
>> giving the usage, and we have finished showing all the options.  Now
>> we are about to further show X, so let's have a blank line here so
>> that what we have wrote will be separated from it", but I cannot
>> tell what that X is.
>
> Oh. I assumed that this X is the the next command in the users
> terminal, but I checked other commands and that is not the case
> at all (at least ls, vi, tar)

Thanks.