GNU bug report logs - #59286
Documentation for seq-count

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 59286 in the body.
You can then email your comments to 59286 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Heime <heimeborgia <at> protonmail.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: Documentation for seq-count
Date: Tue, 15 Nov 2022 16:18:46 +0000

Have scrutinised the documentation for "seq-count".  A description that is quite undecipherable.

(seq-count PRED SEQUENCE)
Return the number of elements for which (PRED element) is non-nil in SEQUENCE.

Message #8 received at 59286 <at> debbugs.gnu.org (full text, mbox):

From: Rudolf Adamkovič <salutis <at> me.com>
To: Heime <heimeborgia <at> protonmail.com>, 59286 <at> debbugs.gnu.org
Subject: Re: bug#59286: Documentation for seq-count
Date: Wed, 16 Nov 2022 18:18:22 +0100

Heime via "Bug reports for GNU Emacs, the Swiss army knife of text
editors" <bug-gnu-emacs <at> gnu.org> writes:

> A description that is quite undecipherable.

I have recently used this function for the first time (when contributing
to Org), and I found its description *exceptionally* clear.  What do you
find undecipherable?

P.S. #1

It helps to know that "PRED" stands for the English word PREDICATE.

Experienced users and native speakers may laugh, but the fact that "BEG"
does not mean "to beg" but "the beginning", adds completely unnecessary
cognitive overhead to some.  The same applies to "PRED".

(The Scheme standard, for example, also uses shorthand forms, such as
"obj", but it lists all of them, right at the beginning.  Perhaps Emacs
has such a list too?  If so, the help browser should use it to assist
the user to make sense of these non-words.)

P.S. #2

When I used this function, I wished it would take ELEMENT-OR-PREDICATE,
so that

  (seq-count 2 '(0 2 2 2 0)) => 3,

and I still wonder if Emacs comes with any such function.

(I ended up using `equal' wrapped in the PREDICATE.)

Rudy
-- 
"Mathematics takes us still further from what is human into the region
of absolute necessity, to which not only the actual world, but every
possible world, must conform."
-- Bertrand Russell, 1902

Rudolf Adamkovič <salutis <at> me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Message #11 received at 59286 <at> debbugs.gnu.org (full text, mbox):

From: Heime <heimeborgia <at> protonmail.com>
To: Rudolf Adamkovič <salutis <at> me.com>
Cc: 59286 <at> debbugs.gnu.org
Subject: Re: bug#59286: Documentation for seq-count
Date: Wed, 16 Nov 2022 17:59:44 +0000

------- Original Message -------
On Wednesday, November 16th, 2022 at 5:18 PM, Rudolf Adamkovič via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org> wrote:


> Heime via "Bug reports for GNU Emacs, the Swiss army knife of text
> editors" bug-gnu-emacs <at> gnu.org writes:
> 
> > A description that is quite undecipherable.
> 
> 
> I have recently used this function for the first time (when contributing
> to Org), and I found its description exceptionally clear. What do you
> find undecipherable?
> 
> P.S. #1
> 
> It helps to know that "PRED" stands for the English word PREDICATE.

Fine, but how do you use that?  No information, no example.  Seems to me that
authors of documentation willfully avoid showing examples or where to find them.

> Experienced users and native speakers may laugh, but the fact that "BEG"
> does not mean "to beg" but "the beginning", adds completely unnecessary
> cognitive overhead to some. The same applies to "PRED".
> 
> (The Scheme standard, for example, also uses shorthand forms, such as
> "obj", but it lists all of them, right at the beginning. Perhaps Emacs
> has such a list too? If so, the help browser should use it to assist
> the user to make sense of these non-words.)
> 
> P.S. #2
> 
> When I used this function, I wished it would take ELEMENT-OR-PREDICATE,
> so that
> 
> (seq-count 2 '(0 2 2 2 0)) => 3,
> 
> 
> and I still wonder if Emacs comes with any such function.
> 
> (I ended up using `equal' wrapped in the PREDICATE.)
> 
> Rudy
> --
> "Mathematics takes us still further from what is human into the region
> of absolute necessity, to which not only the actual world, but every
> possible world, must conform."
> -- Bertrand Russell, 1902
> 
> Rudolf Adamkovič salutis <at> me.com [he/him]
> 
> Studenohorská 25
> 84103 Bratislava
> Slovakia
>

Message #14 received at 59286 <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: Heime <heimeborgia <at> protonmail.com>, Rudolf Adamkovič
 <salutis <at> me.com>
Cc: 59286 <at> debbugs.gnu.org
Subject: Re: bug#59286: Documentation for seq-count
Date: Wed, 16 Nov 2022 10:09:39 -0800

On 11/16/2022 9:59 AM, Heime via Bug reports for GNU Emacs, the Swiss 
army knife of text editors wrote:
> Fine, but how do you use that?  No information, no example.  Seems to me that
> authors of documentation willfully avoid showing examples or where to find them.

In a *Help* buffer, just below the docstring is this message:

  Other relevant functions are documented in the _sequence_ group.

Clicking on "sequence" takes you to shortdocs, which shows an example:

  (seq-count #'numberp '(1 b c 4))
    ⇒ 2

Maybe the "Other relevant functions" wording could be improved so that 
it's clearer though. It doesn't really indicate that you'll find more 
details about 'seq-count' in particular, just "other relevant 
functions". Something like, "See the _sequence_ group for more 
information on this and other relevant functions," maybe?

Message #17 received at 59286 <at> debbugs.gnu.org (full text, mbox):

From: Heime <heimeborgia <at> protonmail.com>
To: Jim Porter <jporterbugs <at> gmail.com>
Cc: 59286 <at> debbugs.gnu.org, Rudolf Adamkovič <salutis <at> me.com>
Subject: Re: bug#59286: Documentation for seq-count
Date: Wed, 16 Nov 2022 18:50:41 +0000

------- Original Message -------
On Wednesday, November 16th, 2022 at 6:09 PM, Jim Porter <jporterbugs <at> gmail.com> wrote:


> On 11/16/2022 9:59 AM, Heime via Bug reports for GNU Emacs, the Swiss
> army knife of text editors wrote:
> 
> > Fine, but how do you use that? No information, no example. Seems to me that
> > authors of documentation willfully avoid showing examples or where to find them.
> 
> 
> In a Help buffer, just below the docstring is this message:
> 
> Other relevant functions are documented in the sequence group.
> 
> Clicking on "sequence" takes you to shortdocs, which shows an example:
> 
>  (seq-count #'numberp '(1 b c 4))
> ⇒ 2
> 
> Maybe the "Other relevant functions" wording could be improved so that
> it's clearer though. It doesn't really indicate that you'll find more
> details about 'seq-count' in particular, just "other relevant
> functions". Something like, "See the sequence group for more
> information on this and other relevant functions," maybe?


It also says "Undocumented" at the end.  Documentation is not as
helpful as many people think they are.

Message #20 received at 59286 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Heime <heimeborgia <at> protonmail.com>
Cc: 59286 <at> debbugs.gnu.org, salutis <at> me.com
Subject: Re: bug#59286: Documentation for seq-count
Date: Wed, 16 Nov 2022 21:40:19 +0200

> Cc: 59286 <at> debbugs.gnu.org
> Date: Wed, 16 Nov 2022 17:59:44 +0000
> From:  Heime via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> > It helps to know that "PRED" stands for the English word PREDICATE.
> 
> Fine, but how do you use that?  No information, no example.  Seems to me that
> authors of documentation willfully avoid showing examples or where to find them.

Where did you look for examples?  There's an example in the ELisp
manual.

Message #23 received at 59286 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Heime <heimeborgia <at> protonmail.com>
Cc: jporterbugs <at> gmail.com, salutis <at> me.com, 59286 <at> debbugs.gnu.org
Subject: Re: bug#59286: Documentation for seq-count
Date: Wed, 16 Nov 2022 21:51:48 +0200

> Cc: 59286 <at> debbugs.gnu.org, Rudolf Adamkovič <salutis <at> me.com>
> Date: Wed, 16 Nov 2022 18:50:41 +0000
> From:  Heime via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> It also says "Undocumented" at the end.

You misunderstood what that means in this case.

Message #28 received at 59286-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Heime <heimeborgia <at> protonmail.com>
Cc: 59286-done <at> debbugs.gnu.org
Subject: Re: bug#59286: Documentation for seq-count
Date: Sun, 10 Sep 2023 12:31:57 -0700

Heime <heimeborgia <at> protonmail.com> writes:

> Have scrutinised the documentation for "seq-count".  A description that is quite undecipherable.
>
> (seq-count PRED SEQUENCE)
> Return the number of elements for which (PRED element) is non-nil in SEQUENCE.

This now reads:

    Return the number of elements in SEQUENCE for which PRED returns
    non-nil.

This seems more readable to me, so I'm closing this bug.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.