Meaning of offset in notmuch search --output=files --offset=

Meaning of offset in notmuch search --output=files --offset=

[Teemu Likonen]

[-- 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 --]

Re: Meaning of offset in notmuch search --output=files --offset=

[Teemu Likonen]

[-- 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 --]

Re: Meaning of offset in notmuch search --output=files --offset=

[David Bremner]

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

Re: Meaning of offset in notmuch search --output=files --offset=

[Michael J Gruber]

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

Re: Meaning of offset in notmuch search --output=files --offset=

[Teemu Likonen]

[-- 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 --]

Re: Meaning of offset in notmuch search --output=files --offset=

[Daniel Kahn Gillmor]

[-- 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 --]

Re: Meaning of offset in notmuch search --output=files --offset=

[Teemu Likonen]

[-- 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 --]