all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#42835: 26.3; Doc of `cl-' functions, (cl) Naming Conventions
@ 2020-08-12 20:18 Drew Adams
  2020-12-09 13:34 ` Lars Ingebrigtsen
  0 siblings, 1 reply; 3+ messages in thread
From: Drew Adams @ 2020-08-12 20:18 UTC (permalink / raw)
  To: 42835

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





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

* bug#42835: 26.3; Doc of `cl-' functions, (cl) Naming Conventions
  2020-08-12 20:18 bug#42835: 26.3; Doc of `cl-' functions, (cl) Naming Conventions Drew Adams
@ 2020-12-09 13:34 ` Lars Ingebrigtsen
  2020-12-09 16:27   ` Drew Adams
  0 siblings, 1 reply; 3+ messages in thread
From: Lars Ingebrigtsen @ 2020-12-09 13:34 UTC (permalink / raw)
  To: Drew Adams; +Cc: 42835

Drew Adams <drew.adams@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





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

* bug#42835: 26.3; Doc of `cl-' functions, (cl) Naming Conventions
  2020-12-09 13:34 ` Lars Ingebrigtsen
@ 2020-12-09 16:27   ` Drew Adams
  0 siblings, 0 replies; 3+ messages in thread
From: Drew Adams @ 2020-12-09 16:27 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: 42835

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





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

end of thread, other threads:[~2020-12-09 16:27 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-08-12 20:18 bug#42835: 26.3; Doc of `cl-' functions, (cl) Naming Conventions Drew Adams
2020-12-09 13:34 ` Lars Ingebrigtsen
2020-12-09 16:27   ` Drew Adams

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.