unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
* Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
@ 2020-04-24 12:53 Ciprian Dorin Craciun
  2020-04-27 17:53 ` David Bremner
  0 siblings, 1 reply; 19+ messages in thread
From: Ciprian Dorin Craciun @ 2020-04-24 12:53 UTC (permalink / raw)
  To: notmuch

[Again sorry for double reporting.  BTW, where should I search for
previous bugs?  I've currently tried the mailing list archive.]


Trying to play with `notmuch` from a wrapper, I've stumbled upon the
following command line flags handling bug:

~~~~
notmuch show --format json --entire-thread true --body false --
'ciprian@volution.ro'
notmuch show --format json --entire-thread true --body=false --
'ciprian@volution.ro'
#=> yields nothing

notmuch show --format json --entire-thread=true --body false --
'ciprian@volution.ro'
#=> yields some emails

notmuch show --format json --entire-thread=true --body=false --
'ciprian@volution.ro'
#=> yields lots of emails
~~~~


I would expect that `--flag value` and `--flag=value` are equivalent,
at least for the options that the manual states `--flag=(true|false)`.

However based on the previous experiments it seems that using anything
except `--flag=value` yields inconsistent results.

Hope it helps,
Ciprian.

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-24 12:53 Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun
@ 2020-04-27 17:53 ` David Bremner
  2020-04-27 18:02   ` Daniel Kahn Gillmor
  0 siblings, 1 reply; 19+ messages in thread
From: David Bremner @ 2020-04-27 17:53 UTC (permalink / raw)
  To: Ciprian Dorin Craciun, notmuch

Ciprian Dorin Craciun <ciprian.craciun@gmail.com> writes:

> [Again sorry for double reporting.  BTW, where should I search for
> previous bugs?  I've currently tried the mailing list archive.]

Another option is

        https://nmbug.notmuchmail.org/status

This is just pointers into the mailing archive, but triaged.

>
> Trying to play with `notmuch` from a wrapper, I've stumbled upon the
> following command line flags handling bug:
>
> ~~~~
> notmuch show --format json --entire-thread true --body false --
> 'ciprian@volution.ro'
> notmuch show --format json --entire-thread true --body=false --
> 'ciprian@volution.ro'

Quoting notmuch(1)

   OPTION SYNTAX
       All options accepting an argument can be used with '='
       or ':' as a separator. For the cases where it's not ambiguous
       (in particular excluding boolean options), a space can also be
       used.

So what you are seeing is a side effect of "--entire-thread true" not
being supported syntax.

You can see what's happening with

 NOTMUCH_DEBUG_QUERY=t notmuch show --format json --entire-thread true djkldsfjkl

the "true" is considered the first search term.

In your example you could just delete the "true" to switch on the
option.

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-27 17:53 ` David Bremner
@ 2020-04-27 18:02   ` Daniel Kahn Gillmor
  2020-04-27 18:20     ` Tomi Ollila
  0 siblings, 1 reply; 19+ messages in thread
From: Daniel Kahn Gillmor @ 2020-04-27 18:02 UTC (permalink / raw)
  To: David Bremner, Ciprian Dorin Craciun, notmuch


[-- Attachment #1.1: Type: text/plain, Size: 1058 bytes --]

On Mon 2020-04-27 14:53:07 -0300, David Bremner wrote:
> Quoting notmuch(1)
>
>    OPTION SYNTAX
>        All options accepting an argument can be used with '='
>        or ':' as a separator. For the cases where it's not ambiguous
>        (in particular excluding boolean options), a space can also be
>        used.

This is a pretty twisty way to say what we mean.  Are there other cases
besides boolean options?  If there are, perhaps it'd be clearer to say
something like this for the last sentence:

    Except for boolean options and other potential ambiguous cases, a
    space can also be used as a separator.

If there aren't, we could say:

    Except for boolean options (which would be ambiguous), a space can
    also be used as a separator.

Alternately, we could deprecate using whitespace for all options,
produce explicit warnings to stderr when whitespace appears on the next
release, remove the suggestion to use a whitespace separator from the
documentation, and eventually phase it out entirely in some future
release.


        --dkg

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

[-- Attachment #2: Type: text/plain, Size: 0 bytes --]



^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-27 18:02   ` Daniel Kahn Gillmor
@ 2020-04-27 18:20     ` Tomi Ollila
  2020-04-27 19:21       ` Ciprian Dorin Craciun
  0 siblings, 1 reply; 19+ messages in thread
From: Tomi Ollila @ 2020-04-27 18:20 UTC (permalink / raw)
  To: Daniel Kahn Gillmor, David Bremner, Ciprian Dorin Craciun,
	notmuch

On Mon, Apr 27 2020, Daniel Kahn Gillmor wrote:

> On Mon 2020-04-27 14:53:07 -0300, David Bremner wrote:
>> Quoting notmuch(1)
>>
>>    OPTION SYNTAX
>>        All options accepting an argument can be used with '='
>>        or ':' as a separator. For the cases where it's not ambiguous
>>        (in particular excluding boolean options), a space can also be
>>        used.
>
> This is a pretty twisty way to say what we mean.  Are there other cases
> besides boolean options?  If there are, perhaps it'd be clearer to say
> something like this for the last sentence:
>
>     Except for boolean options and other potential ambiguous cases, a
>     space can also be used as a separator.
>
> If there aren't, we could say:
>
>     Except for boolean options (which would be ambiguous), a space can
>     also be used as a separator.
>
> Alternately, we could deprecate using whitespace for all options,
> produce explicit warnings to stderr when whitespace appears on the next

was it so, that originally we did not support whitespace, but David
added that in some commit...

> release, remove the suggestion to use a whitespace separator from the
> documentation, and eventually phase it out entirely in some future
> release.

Alternatively we could check that next arg is (case-insensitively)
(subset of) 'true', 'false', 'yes', 'no', '0', '1', 't', 'nil'
(but not tpyoes of these ;) and in that case have that as an option
value...

... would that work better for human user who just wants to be
fluent on command line -- frontends can then always use = and option
values...

>         --dkg

Tomi

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-27 18:20     ` Tomi Ollila
@ 2020-04-27 19:21       ` Ciprian Dorin Craciun
  2020-04-29  2:16         ` Daniel Kahn Gillmor
  0 siblings, 1 reply; 19+ messages in thread
From: Ciprian Dorin Craciun @ 2020-04-27 19:21 UTC (permalink / raw)
  To: Tomi Ollila; +Cc: notmuch, Daniel Kahn Gillmor

On Mon, Apr 27, 2020 at 9:21 PM Tomi Ollila <tomi.ollila@iki.fi> wrote:
> > On Mon 2020-04-27 14:53:07 -0300, David Bremner wrote:
> >> Quoting notmuch(1)
> >>
> >>    OPTION SYNTAX
> >>        All options accepting an argument can be used with '='
> >>        or ':' as a separator. For the cases where it's not ambiguous
> >>        (in particular excluding boolean options), a space can also be
> >>        used.


I definitively skipped over that warning, mainly because I was reading
the man-page for the specific command (i.e. `notmuch-search`, etc.)
that don't feature that warning.

Please note that I understand "why" I get this behavior, and
definitively I agree that it's my fault.  However my initial report
was intended to find a way that new users don't shoot themselves in
the foot, especially since many will use `notmuch` from a script, and
sometimes they don't thoroughly check the arguments passed by the
user.



> > Alternately, we could deprecate using whitespace for all options,
> > produce explicit warnings to stderr when whitespace appears on the next
>
> was it so, that originally we did not support whitespace, but David
> added that in some commit...


From a "correctness" point of view, this would be the best approach.
However I think it could be too late to introduce it, and it would
break too many integrations.



> > release, remove the suggestion to use a whitespace separator from the
> > documentation, and eventually phase it out entirely in some future
> > release.
>
> Alternatively we could check that next arg is (case-insensitively)
> (subset of) 'true', 'false', 'yes', 'no', '0', '1', 't', 'nil'
> (but not tpyoes of these ;) and in that case have that as an option
> value...


This would be perhaps the best approach.  However I don't think it
would solve the issues for integrators that would not see these
warnings in the logs, until it is too late.



> ... would that work better for human user who just wants to be
> fluent on command line -- frontends can then always use = and option
> values...


Perhaps there could be an additional option (either on the command
line or in the configuration) that would apply "strict" checking, and
not letting any other form except `--argument=value`, including the
boolean flags, and failing loudly.

I think this third option would enable much safer integrations.

(BTW, this "strict" option could also apply to the parsing of the
search terms, which most of the time are under the control of the end
user.)

Ciprian.

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-27 19:21       ` Ciprian Dorin Craciun
@ 2020-04-29  2:16         ` Daniel Kahn Gillmor
  2020-04-29 14:18           ` Tomi Ollila
  2020-04-29 15:33           ` Jameson Graef Rollins
  0 siblings, 2 replies; 19+ messages in thread
From: Daniel Kahn Gillmor @ 2020-04-29  2:16 UTC (permalink / raw)
  To: Ciprian Dorin Craciun, Tomi Ollila; +Cc: notmuch


[-- Attachment #1.1: Type: text/plain, Size: 2801 bytes --]

On Mon 2020-04-27 22:21:36 +0300, Ciprian Dorin Craciun wrote:
> On Mon, Apr 27, 2020 at 9:21 PM Tomi Ollila <tomi.ollila@iki.fi> wrote:
>>> [dkg wrote:]
>>> release, remove the suggestion to use a whitespace separator from the
>>> documentation, and eventually phase it out entirely in some future
>>> release.
>>
>> Alternatively we could check that next arg is (case-insensitively)
>> (subset of) 'true', 'false', 'yes', 'no', '0', '1', 't', 'nil'
>> (but not tpyoes of these ;) and in that case have that as an option
>> value...
>
> This would be perhaps the best approach.  However I don't think it
> would solve the issues for integrators that would not see these
> warnings in the logs, until it is too late.

this looks really ugly to me, in that some legitimate queries
(e.g. those that include terms like "true" or "1") might not be
accessible, unless the user supplies --booloption=true instead of
--booloption.

I mean, these are all slightly idiosyncratic corner cases, but this
particular corner case looks super ugly and hard to explain to me.  i'm
trying to imagine writing some example text that explains it for the man
page, and it comes out horribly complex!  If we can't explain it
succinctly in the manpage, should we be implementing it?

> Perhaps there could be an additional option (either on the command
> line or in the configuration) that would apply "strict" checking, and
> not letting any other form except `--argument=value`, including the
> boolean flags, and failing loudly.
>
> I think this third option would enable much safer integrations.
>
> (BTW, this "strict" option could also apply to the parsing of the
> search terms, which most of the time are under the control of the end
> user.)

I've spent many years helping to maintain GnuPG now, and i'm pretty wary
of having contextually different modes of argument parsing and
interacting/intersecting arguments.  It also leads to some weird
ambiguities: if --strict is supplied on the command line, then does it
need to be first on the command line?  or could parsing the command line
turn out different if you tack on --strict at the end?  Seems like we'd
be injecting additional idiosyncracies to chase after the first.

One final way we could normalize everything and make it less
idiosyncratic, with shorter, simpler man pages: deprecate and then drop
the --booloption/--no-booloption mechanisms, requiring --booloption=true
or --booloption=false instead.  Once they're dropped, allow whitespace
between "--booloption true" and "--booloption false" just like every
other type of option.



in case it's not clear: I believe that "we have succinct and yet
complete man pages" is a convenient shorthand for "have we made this
command-line program behave in an understandable/usable way?"

               --dkg

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

[-- Attachment #2: Type: text/plain, Size: 0 bytes --]



^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-29  2:16         ` Daniel Kahn Gillmor
@ 2020-04-29 14:18           ` Tomi Ollila
  2020-04-29 15:39             ` David Bremner
  2020-04-29 15:33           ` Jameson Graef Rollins
  1 sibling, 1 reply; 19+ messages in thread
From: Tomi Ollila @ 2020-04-29 14:18 UTC (permalink / raw)
  To: Daniel Kahn Gillmor, Ciprian Dorin Craciun; +Cc: notmuch

On Tue, Apr 28 2020, Daniel Kahn Gillmor wrote:

>
> One final way we could normalize everything and make it less
> idiosyncratic, with shorter, simpler man pages: deprecate and then drop
> the --booloption/--no-booloption mechanisms, requiring --booloption=true
> or --booloption=false instead.  Once they're dropped, allow whitespace
> between "--booloption true" and "--booloption false" just like every
> other type of option.

I must say, being it perhaps slightly inconvenient to the user, that
this is IMO the best option, and just allowing 'true' and 'false'
(case-sensitively). Least chance to work how used did not expected...

> in case it's not clear: I believe that "we have succinct and yet
> complete man pages" is a convenient shorthand for "have we made this
> command-line program behave in an understandable/usable way?"

Sounds/looks like reasonable expectation...

>
>                --dkg

Tomi

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-29  2:16         ` Daniel Kahn Gillmor
  2020-04-29 14:18           ` Tomi Ollila
@ 2020-04-29 15:33           ` Jameson Graef Rollins
  2020-04-30 16:59             ` Daniel Kahn Gillmor
  1 sibling, 1 reply; 19+ messages in thread
From: Jameson Graef Rollins @ 2020-04-29 15:33 UTC (permalink / raw)
  To: Daniel Kahn Gillmor, Ciprian Dorin Craciun, Tomi Ollila; +Cc: notmuch

On Tue, Apr 28 2020, Daniel Kahn Gillmor <dkg@fifthhorseman.net> wrote:
> One final way we could normalize everything and make it less
> idiosyncratic, with shorter, simpler man pages: deprecate and then drop
> the --booloption/--no-booloption mechanisms, requiring --booloption=true
> or --booloption=false instead.  Once they're dropped, allow whitespace
> between "--booloption true" and "--booloption false" just like every
> other type of option.

Or we could just use only --booloption/--no-booloption...

jamie.

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-29 14:18           ` Tomi Ollila
@ 2020-04-29 15:39             ` David Bremner
  2020-04-29 15:45               ` Jameson Graef Rollins
  2020-04-29 15:59               ` Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun
  0 siblings, 2 replies; 19+ messages in thread
From: David Bremner @ 2020-04-29 15:39 UTC (permalink / raw)
  To: Daniel Kahn Gillmor, Jani Nikula; +Cc: notmuch

Tomi Ollila <tomi.ollila@iki.fi> writes:

> On Tue, Apr 28 2020, Daniel Kahn Gillmor wrote:
>
>>
>> One final way we could normalize everything and make it less
>> idiosyncratic, with shorter, simpler man pages: deprecate and then drop
>> the --booloption/--no-booloption mechanisms, requiring --booloption=true
>> or --booloption=false instead.  Once they're dropped, allow whitespace
>> between "--booloption true" and "--booloption false" just like every
>> other type of option.
>
> I must say, being it perhaps slightly inconvenient to the user, that
> this is IMO the best option, and just allowing 'true' and 'false'
> (case-sensitively). Least chance to work how used did not expected...
>

I guess I'm a bit leery of removing UI features that presumably at least
some people rely on. It's pretty upsetting to have sofware break one's
muscle memory.

d

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-29 15:39             ` David Bremner
@ 2020-04-29 15:45               ` Jameson Graef Rollins
  2020-04-29 16:28                 ` David Bremner
  2020-05-05 18:28                 ` Carl Worth
  2020-04-29 15:59               ` Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun
  1 sibling, 2 replies; 19+ messages in thread
From: Jameson Graef Rollins @ 2020-04-29 15:45 UTC (permalink / raw)
  To: David Bremner, Daniel Kahn Gillmor, Jani Nikula; +Cc: notmuch

On Wed, Apr 29 2020, David Bremner <david@tethera.net> wrote:
> I guess I'm a bit leery of removing UI features that presumably at least
> some people rely on. It's pretty upsetting to have sofware break one's
> muscle memory.

I dare say there are few people that have muscle memory for the notmuch
command line (especially for notmuch show), and fewer that aren't
themselves developers...

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-29 15:39             ` David Bremner
  2020-04-29 15:45               ` Jameson Graef Rollins
@ 2020-04-29 15:59               ` Ciprian Dorin Craciun
  2020-04-29 16:07                 ` Jameson Graef Rollins
  1 sibling, 1 reply; 19+ messages in thread
From: Ciprian Dorin Craciun @ 2020-04-29 15:59 UTC (permalink / raw)
  To: David Bremner; +Cc: notmuch, Daniel Kahn Gillmor

On Wed, Apr 29, 2020 at 6:39 PM David Bremner <david@tethera.net> wrote:
> I guess I'm a bit leery of removing UI features that presumably at least
> some people rely on. It's pretty upsetting to have sofware break one's
> muscle memory.


I think there are two complete different use-cases for the `notmuch` binary:
* a simple CLI to query the database, in which case the current flags seem OK;
* a "poor-mans" API to query the database, more bellow;

(I know there already exists an `libnotmuch` API accessible in many
programming languages.  However for prototyping, and even for safety
and robustness, when performance isn't an issue, I find the tool-based
approach much more resilient.)

Now about the "API" use-case,  I assume that at the moment many users
have already integrated `notmuch` as it is with the current flags and
behaviour.  Thus I agree that changing any flags in backward
incompatible way would make a lot of people unhappy, and will generate
perhaps quite a bit of "customer support".  :)



However, even with my `--strict` argument, I was perhaps leaning
toward adding a more API-friendly command line parser, that would
basically only take arguments in the form `--flag=value`, anything
else being considered a search term, and anything not a flag but
before a single `--` should be considered an error.

Regarding the `--boolean` vs `--no-boolean` it does solve the
strictness problem, however it makes the life of script developers
quite hard, as now he has a `case` or `if/then/else`.  Therefore I
would say that `--flag=value` is the best option as it can be simply
written as `--flag={FLAG:-true}` or in Python for example `"--flag=%s"
% _flag`.



Thinking even further uppon this, perhaps an even simpler idea would
be to provide a new command, like for example `notmuch api` that takes
on `stdin` a JSON with a specific format and does its job.


Ciprian.

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-29 15:59               ` Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun
@ 2020-04-29 16:07                 ` Jameson Graef Rollins
  0 siblings, 0 replies; 19+ messages in thread
From: Jameson Graef Rollins @ 2020-04-29 16:07 UTC (permalink / raw)
  To: Ciprian Dorin Craciun, David Bremner; +Cc: notmuch, Daniel Kahn Gillmor

On Wed, Apr 29 2020, Ciprian Dorin Craciun <ciprian.craciun@gmail.com> wrote:
> I think there are two complete different use-cases for the `notmuch` binary:
> * a simple CLI to query the database, in which case the current flags seem OK;
> * a "poor-mans" API to query the database, more bellow;
>
> (I know there already exists an `libnotmuch` API accessible in many
> programming languages.  However for prototyping, and even for safety
> and robustness, when performance isn't an issue, I find the tool-based
> approach much more resilient.)
>
> Now about the "API" use-case,  I assume that at the moment many users
> have already integrated `notmuch` as it is with the current flags and
> behaviour.  Thus I agree that changing any flags in backward
> incompatible way would make a lot of people unhappy, and will generate
> perhaps quite a bit of "customer support".  :)

This is a good point.  The CLI might be "poor", but important apps like
notmuch-emacs are using them, so we should be careful about changing the
interface.

> Regarding the `--boolean` vs `--no-boolean` it does solve the
> strictness problem, however it makes the life of script developers
> quite hard, as now he has a `case` or `if/then/else`.  Therefore I
> would say that `--flag=value` is the best option as it can be simply
> written as `--flag={FLAG:-true}` or in Python for example `"--flag=%s"
> % _flag`.

Also a good point.  I guess the --flag=value interface is a safer/easier
one to converge on.

> Thinking even further uppon this, perhaps an even simpler idea would
> be to provide a new command, like for example `notmuch api` that takes
> on `stdin` a JSON with a specific format and does its job.

This actually sounds like a pretty good idea...

jamie.

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-29 15:45               ` Jameson Graef Rollins
@ 2020-04-29 16:28                 ` David Bremner
  2020-05-05 18:28                 ` Carl Worth
  1 sibling, 0 replies; 19+ messages in thread
From: David Bremner @ 2020-04-29 16:28 UTC (permalink / raw)
  To: Jameson Graef Rollins, Daniel Kahn Gillmor, Jani Nikula; +Cc: notmuch

Jameson Graef Rollins <jrollins@caltech.edu> writes:

> On Wed, Apr 29 2020, David Bremner <david@tethera.net> wrote:
>> I guess I'm a bit leery of removing UI features that presumably at least
>> some people rely on. It's pretty upsetting to have sofware break one's
>> muscle memory.
>
> I dare say there are few people that have muscle memory for the notmuch
> command line (especially for notmuch show), and fewer that aren't
> themselves developers...

Yep. But those are the users I care the most about.

d

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-29 15:33           ` Jameson Graef Rollins
@ 2020-04-30 16:59             ` Daniel Kahn Gillmor
  0 siblings, 0 replies; 19+ messages in thread
From: Daniel Kahn Gillmor @ 2020-04-30 16:59 UTC (permalink / raw)
  To: Jameson Graef Rollins, Ciprian Dorin Craciun, Tomi Ollila; +Cc: notmuch


[-- Attachment #1.1: Type: text/plain, Size: 962 bytes --]

On Wed 2020-04-29 08:33:24 -0700, Jameson Graef Rollins wrote:
> On Tue, Apr 28 2020, Daniel Kahn Gillmor <dkg@fifthhorseman.net> wrote:
>> One final way we could normalize everything and make it less
>> idiosyncratic, with shorter, simpler man pages: deprecate and then drop
>> the --booloption/--no-booloption mechanisms, requiring --booloption=true
>> or --booloption=false instead.  Once they're dropped, allow whitespace
>> between "--booloption true" and "--booloption false" just like every
>> other type of option.
>
> Or we could just use only --booloption/--no-booloption...

I'd be sad about that, because it seems like a pretty idiosyncratic
thing to have options of a certain type behave so differently from
others.

we've seen boolean options turn into non-boolean options in the past,
and changing the syntax of how they're invoked when that happens feels
ugly (though i guess this is at least in part an aesthetic preference).

            --dkg

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

[-- Attachment #2: Type: text/plain, Size: 0 bytes --]



^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value`
  2020-04-29 15:45               ` Jameson Graef Rollins
  2020-04-29 16:28                 ` David Bremner
@ 2020-05-05 18:28                 ` Carl Worth
  2020-05-07 19:26                   ` [PATCH] notmuch(1): clarify documentation about --option/value separators Daniel Kahn Gillmor
  1 sibling, 1 reply; 19+ messages in thread
From: Carl Worth @ 2020-05-05 18:28 UTC (permalink / raw)
  To: Jameson Graef Rollins, David Bremner, Daniel Kahn Gillmor,
	Jani Nikula
  Cc: notmuch


[-- Attachment #1.1: Type: text/plain, Size: 1722 bytes --]

On Wed, Apr 29 2020, Jameson Graef Rollins wrote:
> I dare say there are few people that have muscle memory for the notmuch
> command line (especially for notmuch show), and fewer that aren't
> themselves developers...

Here, the concern isn't just "muscle memory" (forcing users to learn how
to retype commands at the command line) but also that users can have
developed scripts that call notmuch, and we would need to have an
extremely significant reason to break those.

And the notmuch CLI, from the beginning, was intentionally designed to
be comfortable for users to use directly (by typing at an interactive
shell), and for users to also incorporate into various scripts.

And even if they _are_ developers, they don't deserve to have their
environments broken either.

That said, it is unfortunate that some confusion has crept into the API.

I have to admit that I do not understand what this sentence of the
documentation means:

	For the cases where it's not ambiguous (in particular excluding
	boolean options), a space can also be used.

What are the possible cases where it could be ambiguous?

I'm personally opposed to adding any new option like --strict that
changes how command-line options are parsed.

I'm also opposed to renaming any of our existing command-line options.

It seems clear we could at least fix the wording of the above
documentation to make it clear that a space separator cannot be used for
Boolean options.

The only further change that could possibly make sense (to improve
consistency) would be to back out support for using a space separator
for _any_ options. But that introduces all the opportunities to break
users' environments, so it's probably a non-starter as well.

-Carl

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

[-- Attachment #2: Type: text/plain, Size: 0 bytes --]



^ permalink raw reply	[flat|nested] 19+ messages in thread

* [PATCH] notmuch(1): clarify documentation about --option/value separators
  2020-05-05 18:28                 ` Carl Worth
@ 2020-05-07 19:26                   ` Daniel Kahn Gillmor
  2020-05-07 23:40                     ` Carl Worth
  0 siblings, 1 reply; 19+ messages in thread
From: Daniel Kahn Gillmor @ 2020-05-07 19:26 UTC (permalink / raw)
  To: Notmuch Mail

id:CA+Tk8fzRiqxWpd=r8=DRvEewNZXUZgD7MKyRLB1A=R-LxxGEZw@mail.gmail.com
started a thread of discussion that showed that the cli's current
idiosyncrasies around dealing with boolean options were not
understandable.

This attempts to improve the documentation at least (actual changes to
the API might be better, but have not reached consensus).

Note that no one in the discussion thread identified any other
(non-boolean) command-line options that cannot use space as a
separator.  If such an option is identified (or introduced in the
future), it should be added explicitly to this part of the manual.

Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
---
 doc/man1/notmuch.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
index d2cd8da5..3dcc646c 100644
--- a/doc/man1/notmuch.rst
+++ b/doc/man1/notmuch.rst
@@ -128,9 +128,9 @@ OPTION SYNTAX
 -------------
 
 All options accepting an argument can be used with '=' or ':' as a
-separator. For the cases where it's not ambiguous (in particular
-excluding boolean options), a space can also be used. The following
-are all equivalent:
+separator. Except for boolean options (wihch would be ambiguous), a
+space can also be used as a separator. The following are all
+equivalent:
 
 ::
 
-- 
2.26.2

^ permalink raw reply related	[flat|nested] 19+ messages in thread

* Re: [PATCH] notmuch(1): clarify documentation about --option/value separators
  2020-05-07 19:26                   ` [PATCH] notmuch(1): clarify documentation about --option/value separators Daniel Kahn Gillmor
@ 2020-05-07 23:40                     ` Carl Worth
  2020-05-08 12:01                       ` David Bremner
  2020-05-08 16:06                       ` Daniel Kahn Gillmor
  0 siblings, 2 replies; 19+ messages in thread
From: Carl Worth @ 2020-05-07 23:40 UTC (permalink / raw)
  To: Daniel Kahn Gillmor, Notmuch Mail


[-- Attachment #1.1: Type: text/plain, Size: 364 bytes --]

On Thu, May 07 2020, Daniel Kahn Gillmor wrote:
> +separator. Except for boolean options (wihch would be ambiguous), a

Misspelling of "which". And while I'm here, strictly speaking Boolean is
generally capitalized in English, (being one of those adjectives that is
derived from a proper noun).

Otherwise, this looks like a good improvement to me. Thanks!

-Carl

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

[-- Attachment #2: Type: text/plain, Size: 0 bytes --]



^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH] notmuch(1): clarify documentation about --option/value separators
  2020-05-07 23:40                     ` Carl Worth
@ 2020-05-08 12:01                       ` David Bremner
  2020-05-08 16:06                       ` Daniel Kahn Gillmor
  1 sibling, 0 replies; 19+ messages in thread
From: David Bremner @ 2020-05-08 12:01 UTC (permalink / raw)
  To: Carl Worth, Daniel Kahn Gillmor, Notmuch Mail

Carl Worth <cworth@cworth.org> writes:

> On Thu, May 07 2020, Daniel Kahn Gillmor wrote:
>> +separator. Except for boolean options (wihch would be ambiguous), a
>
> Misspelling of "which". And while I'm here, strictly speaking Boolean is
> generally capitalized in English, (being one of those adjectives that is
> derived from a proper noun).

I pushed this to master with s/wihch/which/. I left boolean for a future
patch since there are around 7 occurences in the docs, currently all
lower case.

d

^ permalink raw reply	[flat|nested] 19+ messages in thread

* Re: [PATCH] notmuch(1): clarify documentation about --option/value separators
  2020-05-07 23:40                     ` Carl Worth
  2020-05-08 12:01                       ` David Bremner
@ 2020-05-08 16:06                       ` Daniel Kahn Gillmor
  1 sibling, 0 replies; 19+ messages in thread
From: Daniel Kahn Gillmor @ 2020-05-08 16:06 UTC (permalink / raw)
  To: Carl Worth, Notmuch Mail


[-- Attachment #1.1: Type: text/plain, Size: 829 bytes --]

On Thu 2020-05-07 16:40:26 -0700, Carl Worth wrote:
> On Thu, May 07 2020, Daniel Kahn Gillmor wrote:
>> +separator. Except for boolean options (wihch would be ambiguous), a
>
> Misspelling of "which". And while I'm here, strictly speaking Boolean is
> generally capitalized in English, (being one of those adjectives that is
> derived from a proper noun).
>
> Otherwise, this looks like a good improvement to me. Thanks!

Thanks for catching the "which" misspelling, which should obviously be
fixed if/when the patch is applied.  notmuch-search-terms(7) contains
both capitalized and non-capitalized spellings of "boolean".  I welcome
capitalization cleanup for this over the whole codebase, and hope that a
decision about this particular nit-pick isn't cause for delay of an
otherwise uncontroversial improvement.

      --dkg

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

[-- Attachment #2: Type: text/plain, Size: 0 bytes --]



^ permalink raw reply	[flat|nested] 19+ messages in thread

end of thread, other threads:[~2020-05-08 16:10 UTC | newest]

Thread overview: 19+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-04-24 12:53 Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun
2020-04-27 17:53 ` David Bremner
2020-04-27 18:02   ` Daniel Kahn Gillmor
2020-04-27 18:20     ` Tomi Ollila
2020-04-27 19:21       ` Ciprian Dorin Craciun
2020-04-29  2:16         ` Daniel Kahn Gillmor
2020-04-29 14:18           ` Tomi Ollila
2020-04-29 15:39             ` David Bremner
2020-04-29 15:45               ` Jameson Graef Rollins
2020-04-29 16:28                 ` David Bremner
2020-05-05 18:28                 ` Carl Worth
2020-05-07 19:26                   ` [PATCH] notmuch(1): clarify documentation about --option/value separators Daniel Kahn Gillmor
2020-05-07 23:40                     ` Carl Worth
2020-05-08 12:01                       ` David Bremner
2020-05-08 16:06                       ` Daniel Kahn Gillmor
2020-04-29 15:59               ` Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun
2020-04-29 16:07                 ` Jameson Graef Rollins
2020-04-29 15:33           ` Jameson Graef Rollins
2020-04-30 16:59             ` Daniel Kahn Gillmor

Code repositories for project(s) associated with this public inbox

	https://yhetil.org/notmuch.git/

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 read-only IMAP folder(s) and NNTP newsgroup(s).