bug#59286: Documentation for seq-count

bug#59286: Documentation for seq-count

[Heime via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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.

bug#59286: Documentation for seq-count

[Rudolf Adamkovič via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Heime via "Bug reports for GNU Emacs, the Swiss army knife of text
editors" <bug-gnu-emacs@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@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

bug#59286: Documentation for seq-count

[Heime via Bug reports for GNU Emacs, the Swiss army knife of text editors]

------- 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@gnu.org> wrote:


> Heime via "Bug reports for GNU Emacs, the Swiss army knife of text
> editors" bug-gnu-emacs@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@me.com [he/him]
> 
> Studenohorská 25
> 84103 Bratislava
> Slovakia
>

bug#59286: Documentation for seq-count

[Jim Porter]

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?

bug#59286: Documentation for seq-count

[Heime via Bug reports for GNU Emacs, the Swiss army knife of text editors]

------- Original Message -------
On Wednesday, November 16th, 2022 at 6:09 PM, Jim Porter <jporterbugs@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.

bug#59286: Documentation for seq-count

[Eli Zaretskii]

> Cc: 59286@debbugs.gnu.org, Rudolf Adamkovič <salutis@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@gnu.org>
> 
> It also says "Undocumented" at the end.

You misunderstood what that means in this case.

bug#59286: Documentation for seq-count

[Eli Zaretskii]

> Cc: 59286@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@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.

bug#59286: Documentation for seq-count

[Stefan Kangas]

Heime <heimeborgia@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.