all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#42324: 26.3; Doc string of `seq-concatenate'
@ 2020-07-11 16:10 Drew Adams
  2020-08-25 22:24 ` Stefan Kangas
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2020-07-11 16:10 UTC (permalink / raw)
  To: 42324

C-h f seq-concatenate
___

 seq-concatenate is a compiled Lisp function in 'seq.el'.

 (seq-concatenate TYPE SEQUENCE...)

 Concatenate SEQUENCES into a single sequence of type TYPE.
 TYPE must be one of following symbols: vector, string or list.


 This is a generic function.

 Implementations:

 (type &rest sequences) in 'seq.el'.

 Undocumented
___

1. See bug #42323 for the problem of the unhelpful, implicit reference
   to CL implementations and "generic function".

2. The doc of `seq-concatenate' _really_ needs a description of how it
   differs from `cl-concatenate'.  That's completely unclear.

3. The doc says nothing about each SEQUENCE actually being automatically
   converted (by copying, presumably) into a real sequence:
   `seq-into-sequence'.  It's not clear what's allowed as SEQUENCE.

#2 is the main reason I filed this bug report.  What's the difference?
Why/when would you use one rather than the other?


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''





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

* bug#42324: 26.3; Doc string of `seq-concatenate'
  2020-07-11 16:10 bug#42324: 26.3; Doc string of `seq-concatenate' Drew Adams
@ 2020-08-25 22:24 ` Stefan Kangas
  2020-08-25 22:46   ` Drew Adams
  0 siblings, 1 reply; 9+ messages in thread
From: Stefan Kangas @ 2020-08-25 22:24 UTC (permalink / raw)
  To: Drew Adams; +Cc: 42324

Drew Adams <drew.adams@oracle.com> writes:

> C-h f seq-concatenate
> ___
>
>  seq-concatenate is a compiled Lisp function in 'seq.el'.
>
>  (seq-concatenate TYPE SEQUENCE...)
>
>  Concatenate SEQUENCES into a single sequence of type TYPE.
>  TYPE must be one of following symbols: vector, string or list.
>
>
>  This is a generic function.
>
>  Implementations:
>
>  (type &rest sequences) in 'seq.el'.
>
>  Undocumented
> ___
>
> 1. See bug #42323 for the problem of the unhelpful, implicit reference
>    to CL implementations and "generic function".

Do we need two bugs to track that?  It looks to me like essentially the
same issue.

> 2. The doc of `seq-concatenate' _really_ needs a description of how it
>    differs from `cl-concatenate'.  That's completely unclear.

On current master I see:

cl-concatenate is an alias for ‘seq-concatenate’ in ‘cl-extra.el’.

> 3. The doc says nothing about each SEQUENCE actually being automatically
>    converted (by copying, presumably) into a real sequence:
>    `seq-into-sequence'.  It's not clear what's allowed as SEQUENCE.

I'm not sure I understand this.

> #2 is the main reason I filed this bug report.  What's the difference?
> Why/when would you use one rather than the other?

Best regards,
Stefan Kangas





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

* bug#42324: 26.3; Doc string of `seq-concatenate'
  2020-08-25 22:24 ` Stefan Kangas
@ 2020-08-25 22:46   ` Drew Adams
  2020-08-26  6:00     ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2020-08-25 22:46 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 42324

> > 1. See bug #42323 for the problem of the unhelpful, implicit reference
> >    to CL implementations and "generic function".
> 
> Do we need two bugs to track that?  It looks to me like essentially the
> same issue.

Point #1 is common to both bugs, i.e., it's a problem
for both doc strings.  But #1 is not the only problem
for `seq-concatenate'.  If you fix #1 in a general way,
so it is fixed for both doc strings (and hopefully
others), then you can close #42323.  But if only #1 is
fixed then #42324 isn't fixed.

That's why there are 2 bug reports.  I don't know how
#1 will be fixed, e.g. whether it will be fixed for
only this or that doc string or all relevant doc strings.

> > 2. The doc of `seq-concatenate' _really_ needs a description of how it
> >    differs from `cl-concatenate'.  That's completely unclear.
> 
> On current master I see:
> 
> cl-concatenate is an alias for ‘seq-concatenate’ in ‘cl-extra.el’.

I see.  That's not the case in the Emacs version of the
bug report.

Is that correct?  Does `seq-concatenate' correctly
implement Common Lisp `concatenate'?  If so, then the
alias is good.  If not, then `cl-concatenate' needs
to be fixed to correctly fit the bill.

> > 3. The doc says nothing about each SEQUENCE actually being automatically
> >    converted (by copying, presumably) into a real sequence:
> >    `seq-into-sequence'.  It's not clear what's allowed as SEQUENCE.
> 
> I'm not sure I understand this.

In Emacs 26.3, this is the definition of `seq-concatenate':

(cl-defgeneric seq-concatenate (type &rest sequences)
  "Concatenate SEQUENCES into a single sequence of type TYPE.
TYPE must be one of following symbols: vector, string or list.

\n(fn TYPE SEQUENCE...)"
  (apply #'cl-concatenate
         type
         (seq-map #'seq-into-sequence sequences)))

First, in this Emacs version clearly `cl-concatenate' can't
be the same as `seq-concatenate'.

Second, `seq-into-sequence' seems like a really bad name,
for something that either raises an error or is `identity'.
The name suggests that something that is not quite a sequence
gets converted into a sequence.  I was misled by the name,
I guess.

Well, maybe not.  Apparently `cl-defgeneric' just defines
_default_ behavior.  So the point remains: the doc string
should say that the SEQUENCES are first converted into
proper sequences (in some way), which are then passed to
`cl-concatenate'.  And it should probably state the
default behavior of just raising an error if not already
a sequence.

I'd say, overall, that I don't understand the behavior
by reading the doc string.  And we should.  We shouldn't
have to guess that `cl-defgeneric' is used, and so the
behavior might actually be this, that, or the other
thing (or whatever the case may be).  The do string
should say what the behavior is, including what it _can
be_, if `cl-defgeneric' allows it to end up differing,
depending on SEQUENCES.

> > #2 is the main reason I filed this bug report.  What's the difference?
> > Why/when would you use one rather than the other?





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

* bug#42324: 26.3; Doc string of `seq-concatenate'
  2020-08-25 22:46   ` Drew Adams
@ 2020-08-26  6:00     ` Eli Zaretskii
  0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2020-08-26  6:00 UTC (permalink / raw)
  To: Drew Adams; +Cc: 42324, stefan

> Date: Tue, 25 Aug 2020 15:46:59 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 42324@debbugs.gnu.org
> 
> In Emacs 26.3, this is the definition of `seq-concatenate':
> 
> (cl-defgeneric seq-concatenate (type &rest sequences)
>   "Concatenate SEQUENCES into a single sequence of type TYPE.
> TYPE must be one of following symbols: vector, string or list.
> 
> \n(fn TYPE SEQUENCE...)"
>   (apply #'cl-concatenate
>          type
>          (seq-map #'seq-into-sequence sequences)))

If the bug report is about the doc string, please don't show the
implementation as your evidence.  The issue is (or should be) with the
text of the doc string.

> I'd say, overall, that I don't understand the behavior
> by reading the doc string.

Which part(s) of the doc string's text are unclear?  The text is short
and IMO very clear, so I'm puzzled by this bug report to begin with.

In general, it sounds like what you are after is to understand the
implementation, and that can only be done by reading the code.  In
that case, I see no bug to report here.





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

* bug#42324: 26.3; Doc string of `seq-concatenate'
       [not found]     ` <<83a6yi3q0p.fsf@gnu.org>
@ 2020-08-26 18:14       ` Drew Adams
  2020-08-26 18:30         ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2020-08-26 18:14 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: 42324, stefan

> > In Emacs 26.3, this is the definition of `seq-concatenate':
> >
> > (cl-defgeneric seq-concatenate (type &rest sequences)
> >   "Concatenate SEQUENCES into a single sequence of type TYPE.
> > TYPE must be one of following symbols: vector, string or list.
> >
> > \n(fn TYPE SEQUENCE...)"
> >   (apply #'cl-concatenate
> >          type
> >          (seq-map #'seq-into-sequence sequences)))
> 
> If the bug report is about the doc string, please don't show the
> implementation as your evidence.  The issue is (or should be) with the
> text of the doc string.

You took that out of context.  The context was the
(apparent) change since 26.3, when the bug was reported.
And the bug report is (only) about the doc, including
differences `seq-concatenate' vs `cl-concatenate'.

IF those are now the same thing, and that's said
in the doc (which it apparently is), then #2 of this
bug report disappears.

And #1 is the same as bug #42323.  See also #3.

> > I'd say, overall, that I don't understand the behavior
> > by reading the doc string.
> 
> Which part(s) of the doc string's text are unclear?  The text is short
> and IMO very clear, so I'm puzzled by this bug report to begin with.
> 
> In general, it sounds like what you are after is to understand the
> implementation, and that can only be done by reading the code.  In
> that case, I see no bug to report here.

All of #1, #2, and #3 are only about the doc string.

In any case, the real difficulty is #1, which is bug
#42323.  If that gets fixed properly, AND if
`seq-concatenate' is now exactly the same as
`cl-concatenate' and that's stated in the doc, then
things should be clear.

What's discussed in this thread is, however, relevant
to bug #42323, I think.  Including if the behavior
can change depending on SEQUENCES, as seems to be
the case from looking at the code and `cl-defgeneric'.

The bug report is not about the implementation at
all.  It's about the doc specifying the behavior.





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

* bug#42324: 26.3; Doc string of `seq-concatenate'
  2020-08-26 18:14       ` Drew Adams
@ 2020-08-26 18:30         ` Eli Zaretskii
  0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2020-08-26 18:30 UTC (permalink / raw)
  To: Drew Adams; +Cc: 42324, stefan

> Date: Wed, 26 Aug 2020 11:14:52 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: stefan@marxist.se, 42324@debbugs.gnu.org
> 
> The bug report is not about the implementation at
> all.  It's about the doc specifying the behavior.

The doc string seems clear to me.  And since I don't understand what
are #1, #2, and #3 in your notation, I cannot continue this discussion
in any useful way, sorry.





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

* bug#42324: 26.3; Doc string of `seq-concatenate'
       [not found]         ` <<83mu2h2rah.fsf@gnu.org>
@ 2020-08-26 18:37           ` Drew Adams
  2020-08-26 18:57             ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2020-08-26 18:37 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: 42324, stefan

> > The bug report is not about the implementation at
> > all.  It's about the doc specifying the behavior.
> 
> The doc string seems clear to me.  And since I don't understand what
> are #1, #2, and #3 in your notation, I cannot continue this discussion
> in any useful way, sorry.

From the bug report (and elsewhere in the thread I
also made clear what #1, #2, and #3 referred to):

  1. See bug #42323 for the problem of the unhelpful,
     implicit reference to CL implementations and
     "generic function".

  2. The doc of `seq-concatenate' _really_ needs a
     description of how it differs from `cl-concatenate'.
     That's completely unclear.

  3. The doc says nothing about each SEQUENCE actually
     being automatically converted (by copying, presumably)
     into a real sequence: `seq-into-sequence'.  It's
     not clear what's allowed as SEQUENCE.

  #2 is the main reason I filed this bug report.  What's the difference?
  Why/when would you use one rather than the other?





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

* bug#42324: 26.3; Doc string of `seq-concatenate'
  2020-08-26 18:37           ` Drew Adams
@ 2020-08-26 18:57             ` Eli Zaretskii
  2020-08-27 14:27               ` Lars Ingebrigtsen
  0 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2020-08-26 18:57 UTC (permalink / raw)
  To: Drew Adams; +Cc: 42324, stefan

> Date: Wed, 26 Aug 2020 11:37:39 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: stefan@marxist.se, 42324@debbugs.gnu.org
> 
> > The doc string seems clear to me.  And since I don't understand what
> > are #1, #2, and #3 in your notation, I cannot continue this discussion
> > in any useful way, sorry.
> 
> >From the bug report (and elsewhere in the thread I
> also made clear what #1, #2, and #3 referred to):
> 
>   1. See bug #42323 for the problem of the unhelpful,
>      implicit reference to CL implementations and
>      "generic function".

There's no reference to CL in the current doc string.

>   2. The doc of `seq-concatenate' _really_ needs a
>      description of how it differs from `cl-concatenate'.
>      That's completely unclear.

There's no reference to cl-concatenate in the current doc string.

>   3. The doc says nothing about each SEQUENCE actually
>      being automatically converted (by copying, presumably)
>      into a real sequence: `seq-into-sequence'.

Why should it mention something like that?

>      It's
>      not clear what's allowed as SEQUENCE.

Any sequence, obviously.  Anyway, the current doc string spells it
out:

  TYPE must be one of following symbols: vector, string or list.

>   #2 is the main reason I filed this bug report.  What's the difference?
>   Why/when would you use one rather than the other?

I guess that problem no longer exists with the current doc string.





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

* bug#42324: 26.3; Doc string of `seq-concatenate'
  2020-08-26 18:57             ` Eli Zaretskii
@ 2020-08-27 14:27               ` Lars Ingebrigtsen
  0 siblings, 0 replies; 9+ messages in thread
From: Lars Ingebrigtsen @ 2020-08-27 14:27 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 42324, stefan

The doc string of seq-concatenate seems excessively clear to me, so I'm
closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no






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

end of thread, other threads:[~2020-08-27 14:27 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-07-11 16:10 bug#42324: 26.3; Doc string of `seq-concatenate' Drew Adams
2020-08-25 22:24 ` Stefan Kangas
2020-08-25 22:46   ` Drew Adams
2020-08-26  6:00     ` Eli Zaretskii
     [not found] <<efa23108-da23-4a5b-8bd7-23f25007bed0@default>
     [not found] ` <<CADwFkmma0jyd8P0CNqXp80KghqSqkdFS_fHsMm3v2cXMKmEEqw@mail.gmail.com>
     [not found]   ` <<f5df3cc5-3fad-4295-9f67-e2359317832a@default>
     [not found]     ` <<83a6yi3q0p.fsf@gnu.org>
2020-08-26 18:14       ` Drew Adams
2020-08-26 18:30         ` Eli Zaretskii
     [not found] <<<efa23108-da23-4a5b-8bd7-23f25007bed0@default>
     [not found] ` <<<CADwFkmma0jyd8P0CNqXp80KghqSqkdFS_fHsMm3v2cXMKmEEqw@mail.gmail.com>
     [not found]   ` <<<f5df3cc5-3fad-4295-9f67-e2359317832a@default>
     [not found]     ` <<<83a6yi3q0p.fsf@gnu.org>
     [not found]       ` <<a12959b1-2625-49b8-82df-004a3f6afaa4@default>
     [not found]         ` <<83mu2h2rah.fsf@gnu.org>
2020-08-26 18:37           ` Drew Adams
2020-08-26 18:57             ` Eli Zaretskii
2020-08-27 14:27               ` Lars Ingebrigtsen

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.