unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
* Meaning of offset in notmuch search --output=files --offset=
@ 2024-05-20 18:24 Teemu Likonen
  2024-05-25  7:07 ` Teemu Likonen
  0 siblings, 1 reply; 7+ messages in thread
From: Teemu Likonen @ 2024-05-20 18:24 UTC (permalink / raw)
  To: notmuch


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

It doesn't seem clear how offset is counted on command like

    notmuch search --output=files --offset=10 ...

Does it skip 10 output files (which may belong to less than 10 messages)
or does it skip 10 messages (so it possibly skips more than 10 files)?
Manual page speaks of "results" but I think it can be interpreted either
as "displayed output results" or "search match results (messages)".

Perhaps the manual page needs a few more words to make it clear.

-- 
/// Teemu Likonen - .-.. https://www.iki.fi/tlikonen/
// OpenPGP: 6965F03973F0D4CA22B9410F0F2CAE0E07608462

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

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



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

* Re: Meaning of offset in notmuch search --output=files --offset=
  2024-05-20 18:24 Meaning of offset in notmuch search --output=files --offset= Teemu Likonen
@ 2024-05-25  7:07 ` Teemu Likonen
  2024-05-25 10:05   ` David Bremner
  0 siblings, 1 reply; 7+ messages in thread
From: Teemu Likonen @ 2024-05-25  7:07 UTC (permalink / raw)
  To: notmuch


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

* 2024-05-20 21:24:01+0300, Teemu Likonen wrote:

> It doesn't seem clear how offset is counted on command like
>
>     notmuch search --output=files --offset=10 ...
>
> Does it skip 10 output files (which may belong to less than 10 messages)
> or does it skip 10 messages (so it possibly skips more than 10 files)?
> Manual page speaks of "results" but I think it can be interpreted either
> as "displayed output results" or "search match results (messages)".

I tested and the answer is: --offset option skips that many search match
messages. So it looks to me that command

    notmuch search --output=files --offset=10 ...

internally lists all matched messages, skips to the offset, and then
starts printing the file names of the rest of the message list.

> Perhaps the manual page needs a few more words to make it clear.

    --offset=[-]N
            Skip displaying the first N results. With the leading '-',
            start at the Nth result from the end.

What if we change the first sentence to "Skip displaying the first N
search results"?

-- 
/// Teemu Likonen - .-.. https://www.iki.fi/tlikonen/
// OpenPGP: 6965F03973F0D4CA22B9410F0F2CAE0E07608462

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

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



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

* Re: Meaning of offset in notmuch search --output=files --offset=
  2024-05-25  7:07 ` Teemu Likonen
@ 2024-05-25 10:05   ` David Bremner
  2024-05-25 11:20     ` Michael J Gruber
  0 siblings, 1 reply; 7+ messages in thread
From: David Bremner @ 2024-05-25 10:05 UTC (permalink / raw)
  To: Teemu Likonen, notmuch

Teemu Likonen <tlikonen@iki.fi> writes:

>
>> Perhaps the manual page needs a few more words to make it clear.
>
>     --offset=[-]N
>             Skip displaying the first N results. With the leading '-',
>             start at the Nth result from the end.
>
> What if we change the first sentence to "Skip displaying the first N
> search results"?

For me personally that doesn't make it that much clearer, but I'm
willing to follow a concensus if there is one.

d

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

* Re: Meaning of offset in notmuch search --output=files --offset=
  2024-05-25 10:05   ` David Bremner
@ 2024-05-25 11:20     ` Michael J Gruber
  2024-05-26  7:57       ` Teemu Likonen
  0 siblings, 1 reply; 7+ messages in thread
From: Michael J Gruber @ 2024-05-25 11:20 UTC (permalink / raw)
  To: David Bremner; +Cc: notmuch

Am Sa., 25. Mai 2024 um 12:06 Uhr schrieb David Bremner <david@tethera.net>:
>
> Teemu Likonen <tlikonen@iki.fi> writes:
>
> >
> >> Perhaps the manual page needs a few more words to make it clear.
> >
> >     --offset=[-]N
> >             Skip displaying the first N results. With the leading '-',
> >             start at the Nth result from the end.
> >
> > What if we change the first sentence to "Skip displaying the first N
> > search results"?
>
> For me personally that doesn't make it that much clearer, but I'm
> willing to follow a concensus if there is one.

... because it was clear to you before, already ;-)

Once you are aware of the conceptual difference between "search" and
"output", the change makes it clearer.

Maybe even "Skip displaying output for the first N search results", in
an effort to hint at said difference?

Michael

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

* Re: Meaning of offset in notmuch search --output=files --offset=
  2024-05-25 11:20     ` Michael J Gruber
@ 2024-05-26  7:57       ` Teemu Likonen
  2024-05-27 13:05         ` Daniel Kahn Gillmor
  0 siblings, 1 reply; 7+ messages in thread
From: Teemu Likonen @ 2024-05-26  7:57 UTC (permalink / raw)
  To: Michael J Gruber, David Bremner; +Cc: notmuch


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

* 2024-05-25 13:20:58+0200, Michael J. Gruber wrote:

>> Teemu Likonen <tlikonen@iki.fi> writes:
>>>     --offset=[-]N
>>>             Skip displaying the first N results. With the leading '-',
>>>             start at the Nth result from the end.
>>>
>>> What if we change the first sentence to "Skip displaying the first N
>>> search results"?

> Maybe even "Skip displaying output for the first N search results", in
> an effort to hint at said difference?

Yours is better than the current and mine. Thanks.

-- 
/// Teemu Likonen - .-.. https://www.iki.fi/tlikonen/
// OpenPGP: 6965F03973F0D4CA22B9410F0F2CAE0E07608462

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

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



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

* Re: Meaning of offset in notmuch search --output=files --offset=
  2024-05-26  7:57       ` Teemu Likonen
@ 2024-05-27 13:05         ` Daniel Kahn Gillmor
  2024-05-27 16:50           ` Teemu Likonen
  0 siblings, 1 reply; 7+ messages in thread
From: Daniel Kahn Gillmor @ 2024-05-27 13:05 UTC (permalink / raw)
  To: Teemu Likonen, Michael J Gruber, David Bremner; +Cc: notmuch


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

On Sun 2024-05-26 10:57:14 +0300, Teemu Likonen wrote:
> * 2024-05-25 13:20:58+0200, Michael J. Gruber wrote:
>
>>> Teemu Likonen <tlikonen@iki.fi> writes:
>>>>     --offset=[-]N
>>>>             Skip displaying the first N results. With the leading '-',
>>>>             start at the Nth result from the end.
>>>>
>>>> What if we change the first sentence to "Skip displaying the first N
>>>> search results"?
>
>> Maybe even "Skip displaying output for the first N search results", in
>> an effort to hint at said difference?
>
> Yours is better than the current and mine. Thanks.

I don't see much difference between any of these versions, but i also
don't think any of them make the text concretely worse.  So if more
people understand what is meant by the version suggested by Michael J
Gruber, i'd be fine with going with that version.

      --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] 7+ messages in thread

* Re: Meaning of offset in notmuch search --output=files --offset=
  2024-05-27 13:05         ` Daniel Kahn Gillmor
@ 2024-05-27 16:50           ` Teemu Likonen
  0 siblings, 0 replies; 7+ messages in thread
From: Teemu Likonen @ 2024-05-27 16:50 UTC (permalink / raw)
  To: Daniel Kahn Gillmor, Michael J Gruber, David Bremner; +Cc: notmuch


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

* 2024-05-27 09:05:01-0400, Daniel Kahn Gillmor wrote:

> I don't see much difference between any of these versions,

Then it needs more work still. We want to make it clear for everybody,
don't we? Let's go back to my original confusion. Currently it reads:

    --offset=[-]N
            Skip displaying the first N results. With the leading '-',
            start at the Nth result from the end.

What "results"? The search match or the output? Two interpretations:

 1. "Notmuch search" results an internal message list. "--offset=N" will
    skip N messages in the internal message list and then starts
    printing the rest of the messages in the "--output" format. [This is
    what Notmuch really does.]

 2. "Notmuch search" results an internal message list and it starts
    printing them in "--output" format. It will use "--offset=N" to skip
    N output items, regardless of what they are: summary, threads,
    messages, files, tags. [This is the wrong interpretation.]

So, how do we improve the notmuch-search manual so that everybody
understands "--offset=N" correctly?

-- 
/// Teemu Likonen - .-.. https://www.iki.fi/tlikonen/
// OpenPGP: 6965F03973F0D4CA22B9410F0F2CAE0E07608462

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

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



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

end of thread, other threads:[~2024-05-27 16:50 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-05-20 18:24 Meaning of offset in notmuch search --output=files --offset= Teemu Likonen
2024-05-25  7:07 ` Teemu Likonen
2024-05-25 10:05   ` David Bremner
2024-05-25 11:20     ` Michael J Gruber
2024-05-26  7:57       ` Teemu Likonen
2024-05-27 13:05         ` Daniel Kahn Gillmor
2024-05-27 16:50           ` Teemu Likonen

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).