GNU bug report logs - #42835
26.3; Doc of `cl-' functions, (cl) Naming Conventions

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 42835 in the body.
You can then email your comments to 42835 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: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.3; Doc of `cl-' functions, (cl) Naming Conventions
Date: Wed, 12 Aug 2020 20:18:48 +0000 (UTC)

This node has a list of functions and macros, some of which have
footnotes.  I don't understand the footnotes (which are not sentences,
BTW).

For example, `cl-incf' has footnote [1], which says:

 [1] Only when PLACE is a plain variable name.

What happens only when PLACE (the first arg to `cl-incf') is a plain
variable name?  What happens when PLACE is not a plain variable name?

`C-h f cl-incf' doesn't help at all in this regard.  It doesn't say
anything at all about different behaviors for different kinds of PLACE.

Similarly for the other names and their footnotes.

There's no doc specifying the behaviors of `cl-pushnew' etc. for any
particular kinds of PLACE.  Nothing says what happens "only if :test is
___ or :key is ___. 

This doc is completely unclear to me.  I have no idea what it's trying
to say.  And the doc strings of these functions and macros don't help at
all with this.

If I look up the doc for, say `cl-incf' in the CL manual, it doesn't
help.  It says nothing about a non-variable PLACE (and nothing specific
about a variable PLACE, for that matter).  It just shows an example.

The manual entry for `cl-pushnew' is even worse.  It talks only about
`eql' and doesn't say anything about :test.  There's an xref to node
`Lists as Sets' for info about the keyword args, but that node also says
nothing about :test.  Instead, that node just punts further, to node
`Sequences'.

In general, this doc in this manual, and the CL doc strings, are nearly
useless, and perhaps harmful/misleading.  Certainly not very helpful.

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''

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 42835 <at> debbugs.gnu.org
Subject: Re: bug#42835: 26.3; Doc of `cl-' functions, (cl) Naming Conventions
Date: Wed, 09 Dec 2020 14:34:10 +0100

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

> This node has a list of functions and macros, some of which have
> footnotes.  I don't understand the footnotes (which are not sentences,
> BTW).
>
> For example, `cl-incf' has footnote [1], which says:
>
>  [1] Only when PLACE is a plain variable name.

This is modifying the statement before the table:

---
The following simple functions and macros are defined in @file{cl-lib.el};
they do not cause other components like @file{cl-extra} to be loaded.
---

> Similarly for the other names and their footnotes.

Same for them.

> The manual entry for `cl-pushnew' is even worse.  It talks only about
> `eql' and doesn't say anything about :test.  There's an xref to node
> `Lists as Sets' for info about the keyword args, but that node also says
> nothing about :test.  Instead, that node just punts further, to node
> `Sequences'.

I've now removed the eql claim, and punted the explanation for :test to
"Lists as Sets".

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 42835 <at> debbugs.gnu.org
Subject: RE: bug#42835: 26.3; Doc of `cl-' functions, (cl) Naming Conventions
Date: Wed, 9 Dec 2020 08:27:46 -0800 (PST)

> > This node has a list of functions and macros, some of which have
> > footnotes.  I don't understand the footnotes (which are not
> > sentences, BTW). For example, `cl-incf' has footnote [1], which says:
> >   [1] Only when PLACE is a plain variable name.
> 
> This is modifying the statement before the table:
> 
> ---
> The following simple functions and macros are defined in
> @file{cl-lib.el}; they do not cause other components like
> @file{cl-extra} to be loaded.
> ---

Still not clear.  They are defined in cl-lib only when
PLACE is a var name?  They don't cause other components
to be loaded only when PLACE is a var name?

> > Similarly for the other names and their footnotes.
> 
> Same for them.

It's not clear to me whether you've fixed the doc or are
just trying to explain it to me.  If the latter then this
is, I guess, a "won't fix".  (It needs to be fixed.)

> > The manual entry for `cl-pushnew' is even worse.  It talks only about
> > `eql' and doesn't say anything about :test.  There's an xref to node
> > `Lists as Sets' for info about the keyword args, but that node also
> > says nothing about :test.  Instead, that node just punts further, to
> >  node `Sequences'.
> 
> I've now removed the eql claim, and punted the explanation for :test to
> "Lists as Sets".

Dunno what that means.  Does it mean that `Lists as Sets'
has been updated to cover the keyword args, including
:test?

Previous Next

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