bug#32125: 26; Doc of `seqp` versus `sequencep`

bug#32125: 26; Doc of `seqp` versus `sequencep`

[Drew Adams]

Neither the doc strings nor the descriptions in (elisp) `Sequence
Functions' make clear what the difference is between these predicates.

(It's not even clear why `seq' was added.  What's that about?)

And the name `seqp' seems like a bad choice.  the predicate names
themselves should at least give some hint of the difference.

The doc for `seqp' should not just punt and tell users to go look in
`seq.el' to figure out what it means: "or any additional type of
sequence defined via 'seq.el' generic functions."

And in (elisp) `Sequence Functions' the entries for these two predicates
should be right next to each other.


In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#32125: 26; Doc of `seqp` versus `sequencep`

[Eli Zaretskii]

> Date: Wed, 11 Jul 2018 06:50:44 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Neither the doc strings nor the descriptions in (elisp) `Sequence
> Functions' make clear what the difference is between these predicates.

I think it does:

     This function returns non-‘nil’ if OBJECT is a sequence (a list or
     array), or any additional type of sequence defined via ‘seq.el’
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     generic functions.
     ^^^^^^^^^^^^^^^^^

> (It's not even clear why `seq' was added.  What's that about?)

See above.  At least on the level your question was asked, the answer
is clearly there.

> And the name `seqp' seems like a bad choice.  the predicate names
> themselves should at least give some hint of the difference.

Is this a separate bug?  Is it really important?

> The doc for `seqp' should not just punt and tell users to go look in
> `seq.el' to figure out what it means: "or any additional type of
> sequence defined via 'seq.el' generic functions."

What would you suggest as a better wording?  The difficulty here is
that seq.el provides features that are inherently extensible, so I
don't think an exhaustive list can be given.  But I might be wrong.

> And in (elisp) `Sequence Functions' the entries for these two predicates
> should be right next to each other.

I don't see a compelling reason to have them adjacent, but I did add
some text in the description of each one of them to mention the other
one.

Thanks.

bug#32125: 26; Doc of `seqp` versus `sequencep`

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Wed, 11 Jul 2018 06:50:44 -0700 (PDT)
>> From: Drew Adams <drew.adams@oracle.com>
>>
>> Neither the doc strings nor the descriptions in (elisp) `Sequence
>> Functions' make clear what the difference is between these predicates.
>
> I think it does:
>
>      This function returns non-‘nil’ if OBJECT is a sequence (a list or
>      array), or any additional type of sequence defined via ‘seq.el’
>              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>      generic functions.
>      ^^^^^^^^^^^^^^^^^
>
>> (It's not even clear why `seq' was added.  What's that about?)
>
> See above.  At least on the level your question was asked, the answer
> is clearly there.
>
>> And the name `seqp' seems like a bad choice.  the predicate names
>> themselves should at least give some hint of the difference.
>
> Is this a separate bug?  Is it really important?
>
>> The doc for `seqp' should not just punt and tell users to go look in
>> `seq.el' to figure out what it means: "or any additional type of
>> sequence defined via 'seq.el' generic functions."
>
> What would you suggest as a better wording?  The difficulty here is
> that seq.el provides features that are inherently extensible, so I
> don't think an exhaustive list can be given.  But I might be wrong.
>
>> And in (elisp) `Sequence Functions' the entries for these two predicates
>> should be right next to each other.
>
> I don't see a compelling reason to have them adjacent, but I did add
> some text in the description of each one of them to mention the other
> one.

Last update here was one year ago, and I can't see that there is
anything else to do here after Eli's fixes.  I'm therefore closing
this bug.

If anyone disagrees, feel free to re-open.

Best regards,
Stefan Kangas