* Improving language in documentation of assoc
@ 2025-02-05 3:08 Heime via Users list for the GNU Emacs text editor
2025-02-05 3:31 ` Pierre Rouleau
2025-02-05 17:40 ` tpeplt
0 siblings, 2 replies; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 3:08 UTC (permalink / raw)
To: Heime via Users list for the GNU Emacs text editor
Have read through the documentation for assoc. It is terse and
cryptic, leaving what in actually does at the end as an additive
elaboration.
Its behavior needs to be clarified to improve understanding.
Have found the reading difficult because it uses language
like "non-nil" and "the value is actually" without being
explicit about what is returned from the start.
A clearer way to describe how assoc works is to state that
assoc searches through an alist for a cons cell whose car
matches the given key. If a match is found, it returns
the entire cons cell ((KEY . VALUE)). If no match is found,
it returns nil.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 3:08 Improving language in documentation of assoc Heime via Users list for the GNU Emacs text editor
@ 2025-02-05 3:31 ` Pierre Rouleau
2025-02-05 5:00 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 5:59 ` Yuri Khan
2025-02-05 17:40 ` tpeplt
1 sibling, 2 replies; 29+ messages in thread
From: Pierre Rouleau @ 2025-02-05 3:31 UTC (permalink / raw)
To: Heime; +Cc: help-gnu-emacs
On Tue, Feb 4, 2025 at 10:09 PM Heime via Users list for the GNU Emacs text
editor <help-gnu-emacs@gnu.org> wrote:
>
> Have read through the documentation for assoc. It is terse and
> cryptic, leaving what in actually does at the end as an additive
> elaboration.
>
The documentation is fine as it is.
> A clearer way to describe how assoc works is to state that
> assoc searches through an alist for a cons cell whose car
> matches the given key. If a match is found, it returns
> the entire cons cell ((KEY . VALUE)). If no match is found,
> it returns nil.
>
> Unfortunately it seems that you did not understand what assoc does and did
not try it.
I recommend you try a simple example in ielm.
You might then see why the documentation is the way it is.
Regards,
/Pierre
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 3:31 ` Pierre Rouleau
@ 2025-02-05 5:00 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 15:17 ` Jean Louis
2025-02-05 5:59 ` Yuri Khan
1 sibling, 1 reply; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 5:00 UTC (permalink / raw)
To: Pierre Rouleau; +Cc: help-gnu-emacs
On Wednesday, February 5th, 2025 at 3:31 PM, Pierre Rouleau <prouleau001@gmail.com> wrote:
> On Tue, Feb 4, 2025 at 10:09 PM Heime via Users list for the GNU Emacs text
> editor help-gnu-emacs@gnu.org wrote:
>
> > Have read through the documentation for assoc. It is terse and
> > cryptic, leaving what in actually does at the end as an additive
> > elaboration.
>
>
> The documentation is fine as it is.
>
> > A clearer way to describe how assoc works is to state that
> > assoc searches through an alist for a cons cell whose car
> > matches the given key. If a match is found, it returns
> > the entire cons cell ((KEY . VALUE)). If no match is found,
> > it returns nil.
> >
> > Unfortunately it seems that you did not understand what assoc does and did
>
> not try it.
> I recommend you try a simple example in ielm.
> You might then see why the documentation is the way it is.
>
> Regards, /Pierre
I might? Might I? How about we get real about why "non-nil" is such a big
deal. Is that the reason folks even bother with this function, or are they
just trying to snag a specific element from the chaos?
Let’s face it: if the documentation is going to be worth a damn, it
needs to be crystal clear. It shouldn’t be a cryptic riddle that
leaves users scratching their heads like a pack of bewildered monkeys.
We shouldn’t have to decipher whether it's actually "fine as it is."
And don’t even get me started on that suggestion to dive into ielm for
a simple example. It's like tossing someone a life raft with a hole
in it - no concrete examples, no steps to follow.
Just more of that usual dismissiveness we see from those pretentious
programming snobs who deflect any real explanation by insinuating that
the original poster doesn't understand or hasn't bothered to try using
assoc.
It's a tired act, really - a classic case of intellectual elitism
masquerading as helpfulness. If you’re going to throw around terms
like "non-nil," at least have the decency to explain why it matters
in plain English, instead of hiding behind jargon and condescension.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 3:31 ` Pierre Rouleau
2025-02-05 5:00 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-05 5:59 ` Yuri Khan
2025-02-05 6:13 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 14:07 ` Eli Zaretskii
1 sibling, 2 replies; 29+ messages in thread
From: Yuri Khan @ 2025-02-05 5:59 UTC (permalink / raw)
To: Pierre Rouleau; +Cc: Heime, help-gnu-emacs
On Wed, 5 Feb 2025 at 10:32, Pierre Rouleau <prouleau001@gmail.com> wrote:
> > Have read through the documentation for assoc. It is terse and
> > cryptic, leaving what in actually does at the end as an additive
> > elaboration.
>
> The documentation is fine as it is.
I’ll side with Heime for this one.
(assoc KEY ALIST &optional TESTFN)
Return non-nil if KEY is equal to the car of an element of ALIST.
The value is actually the first element of ALIST whose car equals KEY.
Elisp is known to have functions whose primary intent is to be a
predicate, returning nil or non-nil depending on some condition. As an
added convenience, some of them return something useful as the non-nil
value. ‘memq’ is an example of such a function — returning non-nil
when a value exists in a list and nil if not; for convenience, the
value is the tail of the list starting with the found match.
‘assoc’ is not this kind of function. Its intent is to find “the”
element of the associative list by key, primarily in order to access
the associated value. Details of the behavior when there is no such
element or more than one are the afterthought/elaboration.
There is also a convention that the first line of the docstring
contains a concise description of the function which should be
sufficient when skimming a list of functions. So the primary intent
should fit into the first line.
Return the first element of ALIST whose car equals KEY, or nil
if there is no such element.
(I’m violating the “first line should be a complete sentence”
guideline here, but a reader who only sees the first line will
probably be able to guess when nil is returned.)
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 5:59 ` Yuri Khan
@ 2025-02-05 6:13 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 14:07 ` Eli Zaretskii
1 sibling, 0 replies; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 6:13 UTC (permalink / raw)
To: Yuri Khan; +Cc: Pierre Rouleau, help-gnu-emacs
On Wednesday, February 5th, 2025 at 5:59 PM, Yuri Khan <yuri.v.khan@gmail.com> wrote:
> On Wed, 5 Feb 2025 at 10:32, Pierre Rouleau prouleau001@gmail.com wrote:
>
> > > Have read through the documentation for assoc. It is terse and
> > > cryptic, leaving what in actually does at the end as an additive
> > > elaboration.
> >
> > The documentation is fine as it is.
>
>
> I’ll side with Heime for this one.
>
> (assoc KEY ALIST &optional TESTFN)
>
> Return non-nil if KEY is equal to the car of an element of ALIST.
> The value is actually the first element of ALIST whose car equals KEY.
>
> Elisp is known to have functions whose primary intent is to be a
> predicate, returning nil or non-nil depending on some condition. As an
> added convenience, some of them return something useful as the non-nil
> value. ‘memq’ is an example of such a function — returning non-nil
> when a value exists in a list and nil if not; for convenience, the
> value is the tail of the list starting with the found match.
I have used such predicates, completing-read as example (passing a
predicate to filter arrays before presenting the list to the user).
> ‘assoc’ is not this kind of function. Its intent is to find “the”
> element of the associative list by key, primarily in order to access
> the associated value. Details of the behavior when there is no such
> element or more than one are the afterthought/elaboration.
Quite so.
> There is also a convention that the first line of the docstring
> contains a concise description of the function which should be
> sufficient when skimming a list of functions. So the primary intent
> should fit into the first line.
That has been my point regarding the docstring for the assoc function.
> Return the first element of ALIST whose car equals KEY, or nil
> if there is no such element.
>
> (I’m violating the “first line should be a complete sentence”
> guideline here, but a reader who only sees the first line will
> probably be able to guess when nil is returned.)
It can be difficult to have a good description on a single line.
This could be changed so that the first sentence gets picked up.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 5:59 ` Yuri Khan
2025-02-05 6:13 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-05 14:07 ` Eli Zaretskii
2025-02-05 14:35 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 14:37 ` Pierre Rouleau
1 sibling, 2 replies; 29+ messages in thread
From: Eli Zaretskii @ 2025-02-05 14:07 UTC (permalink / raw)
To: help-gnu-emacs
> From: Yuri Khan <yuri.v.khan@gmail.com>
> Date: Wed, 5 Feb 2025 12:59:18 +0700
> Cc: Heime <heimeborgia@protonmail.com>, help-gnu-emacs <help-gnu-emacs@gnu.org>
>
> On Wed, 5 Feb 2025 at 10:32, Pierre Rouleau <prouleau001@gmail.com> wrote:
>
> > > Have read through the documentation for assoc. It is terse and
> > > cryptic, leaving what in actually does at the end as an additive
> > > elaboration.
> >
> > The documentation is fine as it is.
>
> I’ll side with Heime for this one.
>
> (assoc KEY ALIST &optional TESTFN)
>
> Return non-nil if KEY is equal to the car of an element of ALIST.
> The value is actually the first element of ALIST whose car equals KEY.
>
> Elisp is known to have functions whose primary intent is to be a
> predicate, returning nil or non-nil depending on some condition. As an
> added convenience, some of them return something useful as the non-nil
> value. ‘memq’ is an example of such a function — returning non-nil
> when a value exists in a list and nil if not; for convenience, the
> value is the tail of the list starting with the found match.
>
> ‘assoc’ is not this kind of function. Its intent is to find “the”
> element of the associative list by key, primarily in order to access
> the associated value. Details of the behavior when there is no such
> element or more than one are the afterthought/elaboration.
I don't see how this confirms Heime's criticism. He said the doc
string leaves what the function actually does to the end. But the
truth is that "what function actually does" is described in the very
second sentence, not at the end. I have hard time understanding why
is that a problem.
I also cannot understand why the doc string is "terse" or "cryptic".
Yes, it tells its story in 2 short sentences, but those sentences say
all there is to say, and they say it clearly.
I also don't agree with you about assoc: it _can_ be used as a
predicate, if the Lisp program is only interested in knowing whether a
key is in the list or not. We all used it like that.
> There is also a convention that the first line of the docstring
> contains a concise description of the function which should be
> sufficient when skimming a list of functions. So the primary intent
> should fit into the first line.
>
> Return the first element of ALIST whose car equals KEY, or nil
> if there is no such element.
>
> (I’m violating the “first line should be a complete sentence”
> guideline here, but a reader who only sees the first line will
> probably be able to guess when nil is returned.)
The rule about the first line of a doc string is because the apropos
commands in Emacs show only the first line. It is not an arbitrary
rule. So following it will help users. In your case, what you left
for the second line is redundant and can be simply omitted.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 14:07 ` Eli Zaretskii
@ 2025-02-05 14:35 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 14:54 ` Alfred M. Szmidt
2025-02-05 14:37 ` Pierre Rouleau
1 sibling, 1 reply; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 14:35 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: help-gnu-emacs
Sent with Proton Mail secure email.
On Thursday, February 6th, 2025 at 2:07 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> > From: Yuri Khan yuri.v.khan@gmail.com
> > Date: Wed, 5 Feb 2025 12:59:18 +0700
> > Cc: Heime heimeborgia@protonmail.com, help-gnu-emacs help-gnu-emacs@gnu.org
> >
> > On Wed, 5 Feb 2025 at 10:32, Pierre Rouleau prouleau001@gmail.com wrote:
> >
> > > > Have read through the documentation for assoc. It is terse and
> > > > cryptic, leaving what in actually does at the end as an additive
> > > > elaboration.
> > >
> > > The documentation is fine as it is.
> >
> > I’ll side with Heime for this one.
> >
> > (assoc KEY ALIST &optional TESTFN)
> >
> > Return non-nil if KEY is equal to the car of an element of ALIST.
> > The value is actually the first element of ALIST whose car equals KEY.
> >
> > Elisp is known to have functions whose primary intent is to be a
> > predicate, returning nil or non-nil depending on some condition. As an
> > added convenience, some of them return something useful as the non-nil
> > value. ‘memq’ is an example of such a function — returning non-nil
> > when a value exists in a list and nil if not; for convenience, the
> > value is the tail of the list starting with the found match.
> >
> > ‘assoc’ is not this kind of function. Its intent is to find “the”
> > element of the associative list by key, primarily in order to access
> > the associated value. Details of the behavior when there is no such
> > element or more than one are the afterthought/elaboration.
>
>
> I don't see how this confirms Heime's criticism. He said the doc
> string leaves what the function actually does to the end. But the
> truth is that "what function actually does" is described in the very
> second sentence, not at the end. I have hard time understanding why
> is that a problem.
>
> I also cannot understand why the doc string is "terse" or "cryptic".
> Yes, it tells its story in 2 short sentences, but those sentences say
> all there is to say, and they say it clearly.
>
> I also don't agree with you about assoc: it can be used as a
> predicate, if the Lisp program is only interested in knowing whether a
> key is in the list or not. We all used it like that.
Yes, it can be used as a predicate, but it is not its most
common use, so should be said in the second sentence, rather
than on the first.
It is not a drastic change, but it works better for people
like myself. And would equally work for the others, because
I am not suggesting to actually change much (except the word
"actually", so that the sentence says exactly what it most
commonly returns). Using it as predicate is far less common
than getting the cons cell matching some key.
> > There is also a convention that the first line of the docstring
> > contains a concise description of the function which should be
> > sufficient when skimming a list of functions. So the primary intent
> > should fit into the first line.
> >
> > Return the first element of ALIST whose car equals KEY, or nil
> > if there is no such element.
> >
> > (I’m violating the “first line should be a complete sentence”
> > guideline here, but a reader who only sees the first line will
> > probably be able to guess when nil is returned.)
>
>
> The rule about the first line of a doc string is because the apropos
> commands in Emacs show only the first line. It is not an arbitrary
> rule. So following it will help users. In your case, what you left
> for the second line is redundant and can be simply omitted.
The rule is only for use to apropos? Having appropos look at the entire
first sentence might provide some sort of improvement upon its search
capabilities.
Very minor things, but which would help some of us, without much difference
to others used to what some specific wordings mean.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 14:07 ` Eli Zaretskii
2025-02-05 14:35 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-05 14:37 ` Pierre Rouleau
2025-02-05 16:27 ` Heime via Users list for the GNU Emacs text editor
2025-02-06 4:42 ` Jean Louis
1 sibling, 2 replies; 29+ messages in thread
From: Pierre Rouleau @ 2025-02-05 14:37 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: help-gnu-emacs
On Wed, Feb 5, 2025 at 9:08 AM Eli Zaretskii <eliz@gnu.org> wrote:
> > From: Yuri Khan <yuri.v.khan@gmail.com>
> > Date: Wed, 5 Feb 2025 12:59:18 +0700
> > Cc: Heime <heimeborgia@protonmail.com>, help-gnu-emacs <
> help-gnu-emacs@gnu.org>
> >
> > On Wed, 5 Feb 2025 at 10:32, Pierre Rouleau <prouleau001@gmail.com>
> wrote:
> >
> > > > Have read through the documentation for assoc. It is terse and
> > > > cryptic, leaving what in actually does at the end as an additive
> > > > elaboration.
> > >
> > > The documentation is fine as it is.
> >
> > I’ll side with Heime for this one.
> >
> > (assoc KEY ALIST &optional TESTFN)
> >
> > Return non-nil if KEY is equal to the car of an element of ALIST.
> > The value is actually the first element of ALIST whose car equals
> KEY.
> >
> > Elisp is known to have functions whose primary intent is to be a
> > predicate, returning nil or non-nil depending on some condition. As an
> > added convenience, some of them return something useful as the non-nil
> > value. ‘memq’ is an example of such a function — returning non-nil
> > when a value exists in a list and nil if not; for convenience, the
> > value is the tail of the list starting with the found match.
> >
> > ‘assoc’ is not this kind of function. Its intent is to find “the”
> > element of the associative list by key, primarily in order to access
> > the associated value. Details of the behavior when there is no such
> > element or more than one are the afterthought/elaboration.
>
> I don't see how this confirms Heime's criticism. He said the doc
> string leaves what the function actually does to the end. But the
> truth is that "what function actually does" is described in the very
> second sentence, not at the end. I have hard time understanding why
> is that a problem.
>
> I also cannot understand why the doc string is "terse" or "cryptic".
> Yes, it tells its story in 2 short sentences, but those sentences say
> all there is to say, and they say it clearly.
>
> I also don't agree with you about assoc: it _can_ be used as a
> predicate, if the Lisp program is only interested in knowing whether a
> key is in the list or not. We all used it like that.
>
That's exactly my point.
The docstring is very clear to me and exactly represents what assoc does.
If one wants to get the value the value is returned, not t.
That's very useful:
It _absolutely can_ be used as a predicate
*and* it _can_ also used to get the value.
I would not want Elisp documentation to become poetic
or theatrical (a la Perl for instance).
The assoc docstring is correct and succinct.
I think this is what people need, no?
--
/Pierre
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 14:35 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-05 14:54 ` Alfred M. Szmidt
2025-02-05 15:27 ` Heime via Users list for the GNU Emacs text editor
0 siblings, 1 reply; 29+ messages in thread
From: Alfred M. Szmidt @ 2025-02-05 14:54 UTC (permalink / raw)
To: Heime; +Cc: eliz, help-gnu-emacs
Yes, it can be used as a predicate, but it is not its most
common use, so should be said in the second sentence, rather
than on the first.
assoc, assq, etc (this includes member, memq, too) are "search
functions", they use different predicates to match the keys. As with
search functions, you either find a value or you don't -- non-nil or
nil.
The docstring reflects that, and there is really nothing cryptic about
it.
It is not a drastic change, but it works better for people
like myself. And would equally work for the others, because
I am not suggesting to actually change much (except the word
"actually", so that the sentence says exactly what it most
commonly returns). Using it as predicate is far less common
than getting the cons cell matching some key.
It also works less well for other people. I'd consider this drastic,
since you're suggesting to replace well known terminology with
something else which is not very clear.
You'd also need to find all places that say "Return non-nil ..." to
make the docstrings match for functions that behave in similar fashion
(assoc/assq, member/memq/memql, ...)
The rule is only for use to apropos? Having appropos look at the entire
first sentence might provide some sort of improvement upon its search
capabilities.
Docstrings provide a short description, if the docstring is still
confusing one should consult the Emacs lisp manual.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 5:00 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-05 15:17 ` Jean Louis
0 siblings, 0 replies; 29+ messages in thread
From: Jean Louis @ 2025-02-05 15:17 UTC (permalink / raw)
To: Heime; +Cc: Pierre Rouleau, help-gnu-emacs
* Heime via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> [2025-02-05 08:02]:
> I might? Might I? How about we get real about why "non-nil" is such a big
> deal. Is that the reason folks even bother with this function, or are they
> just trying to snag a specific element from the chaos?
>
> Let’s face it: if the documentation is going to be worth a damn, it
> needs to be crystal clear. It shouldn’t be a cryptic riddle that
> leaves users scratching their heads like a pack of bewildered
> monkeys.
The key is to clarify each single word you encounter, define the word,
learn definition of each word, then move on reading whole sentence.
Just in any subject, like let's say medicine or maternal medicine, a
student could get stuck if there is no previous knowledge on the
subject.
The spectrum of educational materials encompasses multiple categories
known as documentary tiers or grade-levels; it's important to note
that each manual does not cater equally well to all stages within
these classifications, meaning there isn't one single guide suitable
for every level of a student.
There is Introduction to Emacs Lisp programming which is on more
acceptable level for beginners, and there is Emacs Lisp manual which
basically requires user IMHO to have finished or learned some basics.
(info "(elisp) Association Lists")
That section explains is nice.
> 5.8 Association Lists
> =====================
> An “association list”, or “alist” for short, records a mapping from keys
> to values. It is a list of cons cells called “associations”: the CAR of
> each cons cell is the “key”, and the CDR is the “associated value”.(1)
Above small paragraph required user to have basic knowledge of words
mentioned there:
- association
- list in context of Lisp, it is not in context of grocery
- records -- how does list "record" a mapping?
- mapping -- mathematical expression
- cons cells???
- CAR, CDR
- associated value
Plus there is footnote:
> ---------- Footnotes ----------
> (1) This usage of “key” is not related to the term “key sequence”; it
> means a value used to look up an item in a table. In this case, the
> table is the alist, and the alist associations are the items.
- key sequence?
So by looking at it, user reading it must already have all the
previous Lisp knowledge in order to understand even the simple
paragraph.
It is very easy for someone who is on that level to tell you "but,
documentation is perfect". Not so?
While you are protesting, how it can be perfect?
The key to it is to resolve every misunderstood or not well understood
word, first find definition for each word you do not understand,
clarify it, then move forward.
Otherwise you get lost, and not only in Lisp, person can get lost in
any subject.
Good we have got some really cool tools to make it more
understandable.
I have asked https://chat.deepseek.com to make it more understandable
this way:
> 5.8 Association Lists
> =====================
> An “association list”, or “alist” for short, records a mapping from keys
> to values. It is a list of cons cells called “associations”: the CAR of
> each cons cell is the “key”, and the CDR is the “associated value”.(1)
> ---------- Footnotes ----------
> (1) This usage of “key” is not related to the term “key sequence”; it
> means a value used to look up an item in a table. In this case, the
> table is the alist, and the alist associations are the items.
> Write it for beginner to understand
And I get following answer:
---------------------------
### 5.8 Association Lists (A-Lists)
An **association list**, often called an **alist**, is a simple way to
store and manage a collection of key-value pairs. Think of it like a
dictionary where you can look up a "key" to find its corresponding
"value."
#### How Does It Work?
An alist is a list of pairs, where each pair is made up of two parts:
1. **Key**: This is the part you use to look up the information.
2. **Value**: This is the information associated with the key.
In Lisp, each pair is stored in a **cons cell**. The **CAR** (first
part) of the cons cell holds the **key**, and the **CDR** (second
part) holds the **value**.
#### Example
Let’s say you want to store the following information:
- The key `name` has the value `"Alice"`.
- The key `age` has the value `25`.
- The key `city` has the value `"Wonderland"`.
In Lisp, this would look like:
```lisp
'((name . "Alice") (age . 25) (city . "Wonderland"))
```
Here:
- `(name . "Alice")` is a cons cell where `name` is the key and `"Alice"` is the value.
- `(age . 25)` is another cons cell where `age` is the key and `25` is the value.
- `(city . "Wonderland")` is a third cons cell where `city` is the key and `"Wonderland"` is the value.
#### Why Use an Alist?
Alists are useful when you need to:
- Store small amounts of data in a simple way.
- Look up values by their keys.
- Easily add or remove key-value pairs.
#### How to Use an Alist
To find the value associated with a key, you can use the `assoc`
function. For example:
```lisp
(assoc 'name '((name . "Alice") (age . 25) (city . "Wonderland")))
```
This will return:
```lisp
(name . "Alice")
```
Because `name` is the key, and `"Alice"` is its associated value.
#### Key Point to Remember
- The **key** is what you use to look up the information.
- The **value** is the information you get back when you look up the
key.
- An alist is just a list of these key-value pairs.
#### Footnote
The term **key** here is not related to "key sequences" (like keyboard
shortcuts). It simply means a value used to look up an item in a
table. In this case, the table is the alist, and the items are the
key-value pairs.
---
This explanation should help beginners understand what an alist is and how it works!
> But I do not understand "key sequences"!
No problem! Let me explain what **key sequences** are in a simple way, so it’s clear why they’re different from the **keys** used in association lists (alists).
---
### What Are Key Sequences?
A **key sequence** is a sequence of keyboard inputs (like pressing keys on your keyboard) that you use to perform a specific action in a program. For example:
- In a text editor, you might press `Ctrl + C` to copy text.
- In a web browser, you might press `Ctrl + T` to open a new tab.
These combinations of keys are called **key sequences**. They are like shortcuts that trigger certain actions in software.
---
### Key Sequences vs. Keys in Alists
The term **key** in **key sequences** is completely different from the term **key** in **association lists**. Here’s how they differ:
1. **Key in Key Sequences**:
- Refers to physical keys on your keyboard (like `Ctrl`, `C`, `T`, etc.).
- Used to trigger actions or commands in a program.
- Example: `Ctrl + S` saves a file.
2. **Key in Association Lists**:
- Refers to a value (like a symbol, number, or string) used to look up information in a list.
- Used to find a corresponding value in a key-value pair.
- Example: In the alist `((name . "Alice") (age . 25))`, `name` is a key, and `"Alice"` is its value.
---
### Why the Confusion?
The word **key** is used in both contexts, but it means different things depending on the situation:
- In **key sequences**, it’s about keyboard inputs.
- In **association lists**, it’s about looking up values in a list.
The footnote in the original text was just clarifying that the **key** in alists has nothing to do with **key sequences**. They are unrelated concepts!
---
### Example to Make It Clear
Imagine you’re using a text editor:
- **Key Sequence**: You press `Ctrl + Z` to undo an action. This is a **key sequence**.
- **Association List**: The editor might use an alist internally to store settings, like `((font-size . 12) (theme . "dark"))`. Here, `font-size` is a **key**, and `12` is its value.
---
### Summary
- **Key Sequences**: Keyboard shortcuts (like `Ctrl + C`) to perform actions.
- **Keys in Alists**: Values used to look up information in a list (like `name` in `(name . "Alice")`).
Now you know the difference! Let me know if you have more questions. 😊
As you see, you could use the power of Large Language Model (LLM) to
breakdown knowledge in parts to help you explain some paragraphs you
do not understand.
> We shouldn’t have to decipher whether it's actually "fine as it is."
> And don’t even get me started on that suggestion to dive into ielm for
> a simple example. It's like tossing someone a life raft with a hole
> in it - no concrete examples, no steps to follow.
I can understand what you mean, simply take it so that you have to go
through Emacs Lisp Intro first, as Emacs Lisp manual is simply made
for student who already know Lisp basics.
Or get good access to computer dictionary and clarify each word of a
sentence. You can't go wrong. Sentence consists of words, by
understanding each word in the right context, you will understand the
sentence.
--
Jean Louis
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 14:54 ` Alfred M. Szmidt
@ 2025-02-05 15:27 ` Heime via Users list for the GNU Emacs text editor
0 siblings, 0 replies; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 15:27 UTC (permalink / raw)
To: Alfred M. Szmidt; +Cc: eliz, help-gnu-emacs
Sent with Proton Mail secure email.
On Thursday, February 6th, 2025 at 2:54 AM, Alfred M. Szmidt <ams@gnu.org> wrote:
> Yes, it can be used as a predicate, but it is not its most
> common use, so should be said in the second sentence, rather
> than on the first.
>
> assoc, assq, etc (this includes member, memq, too) are "search
> functions", they use different predicates to match the keys. As with
> search functions, you either find a value or you don't -- non-nil or
> nil.
>
> The docstring reflects that, and there is really nothing cryptic about
> it.
>
> It is not a drastic change, but it works better for people
> like myself. And would equally work for the others, because
> I am not suggesting to actually change much (except the word
> "actually", so that the sentence says exactly what it most
> commonly returns). Using it as predicate is far less common
> than getting the cons cell matching some key.
>
> It also works less well for other people. I'd consider this drastic,
> since you're suggesting to replace well known terminology with
> something else which is not very clear.
I only suggest the order of its most basic use first.
> You'd also need to find all places that say "Return non-nil ..." to
> make the docstrings match for functions that behave in similar fashion
> (assoc/assq, member/memq/memql, ...)
I am not suggesting removing the non-nil part, just a shift in focus to
a second sentence, on the later part of the first sentence. That is it.
> The rule is only for use to apropos? Having appropos look at the entire
> first sentence might provide some sort of improvement upon its search
> capabilities.
>
> Docstrings provide a short description, if the docstring is still
> confusing one should consult the Emacs lisp manual.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 14:37 ` Pierre Rouleau
@ 2025-02-05 16:27 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 17:00 ` Eli Zaretskii
2025-02-06 4:42 ` Jean Louis
1 sibling, 1 reply; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 16:27 UTC (permalink / raw)
To: Pierre Rouleau; +Cc: Eli Zaretskii, help-gnu-emacs
Sent with Proton Mail secure email.
On Thursday, February 6th, 2025 at 2:37 AM, Pierre Rouleau <prouleau001@gmail.com> wrote:
> On Wed, Feb 5, 2025 at 9:08 AM Eli Zaretskii eliz@gnu.org wrote:
>
> > > From: Yuri Khan yuri.v.khan@gmail.com
> > > Date: Wed, 5 Feb 2025 12:59:18 +0700
> > > Cc: Heime heimeborgia@protonmail.com, help-gnu-emacs <
> > > help-gnu-emacs@gnu.org>
> > >
> > > On Wed, 5 Feb 2025 at 10:32, Pierre Rouleau prouleau001@gmail.com
> > > wrote:
> > >
> > > > > Have read through the documentation for assoc. It is terse and
> > > > > cryptic, leaving what in actually does at the end as an additive
> > > > > elaboration.
> > > >
> > > > The documentation is fine as it is.
> > >
> > > I’ll side with Heime for this one.
> > >
> > > (assoc KEY ALIST &optional TESTFN)
> > >
> > > Return non-nil if KEY is equal to the car of an element of ALIST.
> > > The value is actually the first element of ALIST whose car equals
> > > KEY.
> > >
> > > Elisp is known to have functions whose primary intent is to be a
> > > predicate, returning nil or non-nil depending on some condition. As an
> > > added convenience, some of them return something useful as the non-nil
> > > value. ‘memq’ is an example of such a function — returning non-nil
> > > when a value exists in a list and nil if not; for convenience, the
> > > value is the tail of the list starting with the found match.
> > >
> > > ‘assoc’ is not this kind of function. Its intent is to find “the”
> > > element of the associative list by key, primarily in order to access
> > > the associated value. Details of the behavior when there is no such
> > > element or more than one are the afterthought/elaboration.
> >
> > I don't see how this confirms Heime's criticism. He said the doc
> > string leaves what the function actually does to the end. But the
> > truth is that "what function actually does" is described in the very
> > second sentence, not at the end. I have hard time understanding why
> > is that a problem.
> >
> > I also cannot understand why the doc string is "terse" or "cryptic".
> > Yes, it tells its story in 2 short sentences, but those sentences say
> > all there is to say, and they say it clearly.
> >
> > I also don't agree with you about assoc: it can be used as a
> > predicate, if the Lisp program is only interested in knowing whether a
> > key is in the list or not. We all used it like that.
>
>
> That's exactly my point.
> The docstring is very clear to me and exactly represents what assoc does.
> If one wants to get the value the value is returned, not t.
> That's very useful:
> It absolutely can be used as a predicate
> and it can also used to get the value.
>
> I would not want Elisp documentation to become poetic
> or theatrical (a la Perl for instance).
> The assoc docstring is correct and succinct.
> I think this is what people need, no? -- /Pierre
The request is not for it to become poetic or theatrical -
I am not in favour of such things too.
Just a more explicit "Returns cons cell of the element that matches KEY",
removing the "actually" in that sentence.
And we get something like this - nothing major.
Return the first cons cell in ALIST whose car matches KEY. The
function can also serve as a predicate, as it returns a non-nil
value when a match is found.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 16:27 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-05 17:00 ` Eli Zaretskii
2025-02-05 17:38 ` Heime via Users list for the GNU Emacs text editor
0 siblings, 1 reply; 29+ messages in thread
From: Eli Zaretskii @ 2025-02-05 17:00 UTC (permalink / raw)
To: help-gnu-emacs
> Date: Wed, 05 Feb 2025 16:27:54 +0000
> From: Heime <heimeborgia@protonmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, help-gnu-emacs@gnu.org
>
> Return the first cons cell in ALIST whose car matches KEY. The
> function can also serve as a predicate, as it returns a non-nil
> value when a match is found.
And then someone else will complain why we mention the predicate use
only in the second sentence, when he/she needs assoc precisely for
that job.
An Emacs *Help* buffer is usually large enough to show the entire doc
string, so I don't really see why it would matter so much which
sentence comes first and which second.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 17:00 ` Eli Zaretskii
@ 2025-02-05 17:38 ` Heime via Users list for the GNU Emacs text editor
0 siblings, 0 replies; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 17:38 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: help-gnu-emacs
Sent with Proton Mail secure email.
On Thursday, February 6th, 2025 at 5:00 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> > Date: Wed, 05 Feb 2025 16:27:54 +0000
> > From: Heime heimeborgia@protonmail.com
> > Cc: Eli Zaretskii eliz@gnu.org, help-gnu-emacs@gnu.org
> >
> > Return the first cons cell in ALIST whose car matches KEY. The
> > function can also serve as a predicate, as it returns a non-nil
> > value when a match is found.
>
> And then someone else will complain why we mention the predicate use
> only in the second sentence, when he/she needs assoc precisely for
> that job.
To address your valid point, there should be clear criteria for how
this information is presented.
There are two main approaches to consider:
1. By Amount of Information Returned:
Returning a cons cell provides more detailed information
compared to simply returning a non-nil value. Therefore,
emphasizing the cons cell return should take precedence
in the documentation.
2. By Frequency of Use:
Analyzing the Emacs source code: Is assoc more commonly
invoked for its predicate functionality or for retrieving
cons cells? The scenario that occurs most frequently should
be prioritized in the documentation.
By adopting criteria, we can create documentation that is more
thoughtful and aligned with how the largest number of users are
likely to utilize assoc.
> An Emacs Help buffer is usually large enough to show the entire doc
> string, so I don't really see why it would matter so much which
> sentence comes first and which second.
The apropos tool was mentioned.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 3:08 Improving language in documentation of assoc Heime via Users list for the GNU Emacs text editor
2025-02-05 3:31 ` Pierre Rouleau
@ 2025-02-05 17:40 ` tpeplt
2025-02-05 18:10 ` Heime via Users list for the GNU Emacs text editor
` (2 more replies)
1 sibling, 3 replies; 29+ messages in thread
From: tpeplt @ 2025-02-05 17:40 UTC (permalink / raw)
To: Heime via Users list for the GNU Emacs text editor; +Cc: Heime
Heime via Users list for the GNU Emacs text editor
<help-gnu-emacs@gnu.org> writes:
> Have read through the documentation for assoc. It is terse and
> cryptic, leaving what in actually does at the end as an additive
> elaboration.
>
> Its behavior needs to be clarified to improve understanding.
> Have found the reading difficult because it uses language
> like "non-nil" and "the value is actually" without being
> explicit about what is returned from the start.
1. It appears that what you are referring to as "the documentation for
assoc" is the docstring read by typing C-h f assoc. The
documentation for ‘assoc’ is in the Emacs Lisp reference manual,
which can by read by evaluating the following expression in Emacs:
(info "(elisp) Association Lists")
That section of the manual explains association lists and the ‘assoc’
(and other related) function, along with examples. Once that is read
and understood, the docstring for ‘assoc’ is sufficiently descriptive
about what it does and what its arguments are.
(New users to Emacs should be aware that there is an Emacs Lisp
reference manual, which is distinct from the Emacs user manual.)
Beyond the description of ‘assoc’, the docstring also includes the
links ‘list’ and ‘alist’ that reference the ‘shortdoc’ descriptions,
which include more examples.
2. If there were to be a change made to the docstring for ‘assoc’, it
could be improved by making it *more* concise. Replace:
Return non-nil if KEY is equal to the car of an element of ALIST.
The value is actually the first element of ALIST whose car equals KEY.
with:
Retrieve first cons of ALIST whose car equals KEY; else return NIL.
The author of the docstring possibly thought that it was necessary to
emphasize that the element of ALIST that was returned was the FIRST one
found that matches, even though many (most?) readers would assume that
to be the case.
(assoc 'c '((a . b) (c . Dee) (e . f) (c . Queue) (l . m)))
=> (c . Dee)
It is important to note the following about association-list functions,
from the Emacs Lisp reference manual:
"In Emacs Lisp, it is _not_ an error if an element of an association
list is not a cons cell. The alist search functions simply ignore such
elements. Many other versions of Lisp signal errors in such cases."
Example:
(assoc 'c '(z w (a . b) "c" j c (c . Dee) (e . f) (c . Queue) (l . m)))
=> (c . Dee)
--
The lyf so short, the craft so long to lerne.
- Geoffrey Chaucer, The Parliament of Birds.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 17:40 ` tpeplt
@ 2025-02-05 18:10 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 19:30 ` Pierre Rouleau
2025-02-05 19:28 ` mbork
2025-02-05 20:17 ` Eli Zaretskii
2 siblings, 1 reply; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 18:10 UTC (permalink / raw)
To: tpeplt; +Cc: Heime via Users list for the GNU Emacs text editor
Sent with Proton Mail secure email.
On Thursday, February 6th, 2025 at 5:40 AM, tpeplt@gmail.com <tpeplt@gmail.com> wrote:
> Heime via Users list for the GNU Emacs text editor
> help-gnu-emacs@gnu.org writes:
>
> > Have read through the documentation for assoc. It is terse and
> > cryptic, leaving what in actually does at the end as an additive
> > elaboration.
> >
> > Its behavior needs to be clarified to improve understanding.
> > Have found the reading difficult because it uses language
> > like "non-nil" and "the value is actually" without being
> > explicit about what is returned from the start.
>
>
> 1. It appears that what you are referring to as "the documentation for
> assoc" is the docstring read by typing C-h f assoc. The
> documentation for ‘assoc’ is in the Emacs Lisp reference manual,
> which can by read by evaluating the following expression in Emacs:
>
> (info "(elisp) Association Lists")
Yes, I usually check what a function does directly form the function
docstring, rather than going through (info "(elisp) Something")
> That section of the manual explains association lists and the ‘assoc’
> (and other related) function, along with examples. Once that is read
> and understood, the docstring for ‘assoc’ is sufficiently descriptive
> about what it does and what its arguments are.
>
> (New users to Emacs should be aware that there is an Emacs Lisp
> reference manual, which is distinct from the Emacs user manual.)
>
> Beyond the description of ‘assoc’, the docstring also includes the
> links ‘list’ and ‘alist’ that reference the ‘shortdoc’ descriptions,
> which include more examples.
>
> 2. If there were to be a change made to the docstring for ‘assoc’, it
> could be improved by making it more concise. Replace:
>
> Return non-nil if KEY is equal to the car of an element of ALIST.
> The value is actually the first element of ALIST whose car equals KEY.
>
> with:
>
> Retrieve first cons of ALIST whose car equals KEY; else return NIL.
>
> The author of the docstring possibly thought that it was necessary to
> emphasize that the element of ALIST that was returned was the FIRST one
> found that matches, even though many (most?) readers would assume that
> to be the case.
That emphasis does not constitute a problem.
> (assoc 'c '((a . b) (c . Dee) (e . f) (c . Queue) (l . m)))
> => (c . Dee)
>
>
> It is important to note the following about association-list functions,
> from the Emacs Lisp reference manual:
>
> "In Emacs Lisp, it is not an error if an element of an association
> list is not a cons cell. The alist search functions simply ignore such
> elements. Many other versions of Lisp signal errors in such cases."
>
> Example:
> (assoc 'c '(z w (a . b) "c" j c (c . Dee) (e . f) (c . Queue) (l . m)))
> => (c . Dee)
>
>
> --
> The lyf so short, the craft so long to lerne.
> - Geoffrey Chaucer, The Parliament of Birds.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 17:40 ` tpeplt
2025-02-05 18:10 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-05 19:28 ` mbork
2025-02-05 22:42 ` Michael Heerdegen via Users list for the GNU Emacs text editor
2025-02-05 20:17 ` Eli Zaretskii
2 siblings, 1 reply; 29+ messages in thread
From: mbork @ 2025-02-05 19:28 UTC (permalink / raw)
To: tpeplt; +Cc: Heime via Users list for the GNU Emacs text editor, Heime
On 2025-02-05, at 12:40, tpeplt@gmail.com wrote:
> 1. It appears that what you are referring to as "the documentation for
> assoc" is the docstring read by typing C-h f assoc. The
> documentation for ‘assoc’ is in the Emacs Lisp reference manual,
This. IMHO, docstrings may be terse/cryptic/technical, I think they are
mostly for people who know Elisp fairly well and need a reminder about
what a function does, for example. They are not to _teach_ Elisp - that
is the goal of the Elisp manual. They are not even to _explain_
anything.
> 2. If there were to be a change made to the docstring for ‘assoc’, it
> could be improved by making it *more* concise. Replace:
This, too. Personally, I'm not a fan of words like "actually" in this
docstring - it does not carry any useful meaning. If we cut it out, we
get:
--8<---------------cut here---------------start------------->8---
Return non-nil if KEY is equal to the car of an element of ALIST.
The value is the first element of ALIST whose car equals KEY.
--8<---------------cut here---------------end--------------->8---
which sounds strange to me (though English is not my first language, so
there's that). tpeplt's proposal fixes that awkwardness perfectly.
That said, I agree that it's not a big deal. The docstring is good
enough not to waste too much time on improving it. That time would be
much better spent improving the Elisp manual (where needed, the part
about assoc seems fine to me), which is the go-to place for
_explanations_ of Elisp concepts, functions, variables etc.
Just my 2 cents,
--
Marcin Borkowski
https://mbork.pl
https://crimsonelevendelightpetrichor.net/
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 18:10 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-05 19:30 ` Pierre Rouleau
2025-02-05 19:58 ` Alfred M. Szmidt
2025-02-05 20:00 ` Heime via Users list for the GNU Emacs text editor
0 siblings, 2 replies; 29+ messages in thread
From: Pierre Rouleau @ 2025-02-05 19:30 UTC (permalink / raw)
To: Heime; +Cc: tpeplt, Heime via Users list for the GNU Emacs text editor
The proposal:
> Replace:
> >
> > Return non-nil if KEY is equal to the car of an element of ALIST.
> > The value is actually the first element of ALIST whose car equals KEY.
> >
> > with:
> >
> > Retrieve first cons of ALIST whose car equals KEY; else return NIL.
> >
>
... would have been nice to see right at the top of your original email.
It is a valid and even more concise description.
Inside it I would only replace 'NIL' by 'nil',
as uppercase is usually identifying arguments, to get:
Retrieve first cons of ALIST whose car equals KEY; else return nil.
BTW, to search the entire set of loaded function docstrings,
you can use:`apropos-documentation PATTERN DO-ALL` (with 'C-u C-h d' ).
To look for NIL in all docstrings: C-u C-h d NIL RET
Then turn off case folding and search for NIL.
--
/Pierre
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 19:30 ` Pierre Rouleau
@ 2025-02-05 19:58 ` Alfred M. Szmidt
[not found] ` <CALTqLiZs7z24jA9TgDuAp+BdWUwCRzr9DpFhpEoP7tTAwzP-tA@mail.gmail.com>
2025-02-05 20:00 ` Heime via Users list for the GNU Emacs text editor
1 sibling, 1 reply; 29+ messages in thread
From: Alfred M. Szmidt @ 2025-02-05 19:58 UTC (permalink / raw)
To: Pierre Rouleau; +Cc: heimeborgia, tpeplt, help-gnu-emacs
Retrieve first cons of ALIST whose car equals KEY; else return nil.
The assoc function doesn't 'retreive' anything, the above is not what
assoc (or any of the same family) does.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 19:30 ` Pierre Rouleau
2025-02-05 19:58 ` Alfred M. Szmidt
@ 2025-02-05 20:00 ` Heime via Users list for the GNU Emacs text editor
1 sibling, 0 replies; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 20:00 UTC (permalink / raw)
To: Pierre Rouleau; +Cc: tpeplt, Heime via Users list for the GNU Emacs text editor
Sent with Proton Mail secure email.
On Thursday, February 6th, 2025 at 7:30 AM, Pierre Rouleau <prouleau001@gmail.com> wrote:
> The proposal:
>
> > Replace:
> >
> > > Return non-nil if KEY is equal to the car of an element of ALIST.
> > > The value is actually the first element of ALIST whose car equals KEY.
> > >
> > > with:
> > >
> > > Retrieve first cons of ALIST whose car equals KEY; else return NIL.
>
>
> ... would have been nice to see right at the top of your original email.
> It is a valid and even more concise description.
>
> Inside it I would only replace 'NIL' by 'nil',
> as uppercase is usually identifying arguments, to get:
>
> Retrieve first cons of ALIST whose car equals KEY; else return nil.
Yes. We do as you say then.
> BTW, to search the entire set of loaded function docstrings,
> you can use:`apropos-documentation PATTERN DO-ALL` (with 'C-u C-h d' ).
> To look for NIL in all docstrings: C-u C-h d NIL RET
> Then turn off case folding and search for NIL.
> --
> /Pierre
^ permalink raw reply [flat|nested] 29+ messages in thread
* Fwd: Improving language in documentation of assoc
[not found] ` <CALTqLiZs7z24jA9TgDuAp+BdWUwCRzr9DpFhpEoP7tTAwzP-tA@mail.gmail.com>
@ 2025-02-05 20:13 ` Pierre Rouleau
2025-02-05 20:18 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 20:24 ` Alfred M. Szmidt
0 siblings, 2 replies; 29+ messages in thread
From: Pierre Rouleau @ 2025-02-05 20:13 UTC (permalink / raw)
To: help-gnu-emacs, Alfred M. Szmidt
... forgot to cc the list
On Wed, Feb 5, 2025 at 2:58 PM Alfred M. Szmidt <ams@gnu.org> wrote:
> Retrieve first cons of ALIST whose car equals KEY; else return nil.
>
> The assoc function doesn't 'retreive' anything, the above is not what
> assoc (or any of the same family) does.
>
Ah yes, thanks, you are correct. The word 'retrieve' is not correct
technically.
As stated before I'm fine with the current docstring.
But out of curiosity, in a short sentence like that, what word(s) would
you
use to describe the mechanism of "returning" the non-nil
(first element of ALIST whose car equal KEY) value?
--
/Pierre
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 17:40 ` tpeplt
2025-02-05 18:10 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 19:28 ` mbork
@ 2025-02-05 20:17 ` Eli Zaretskii
2025-02-05 22:55 ` Heime via Users list for the GNU Emacs text editor
2 siblings, 1 reply; 29+ messages in thread
From: Eli Zaretskii @ 2025-02-05 20:17 UTC (permalink / raw)
To: help-gnu-emacs
> From: tpeplt@gmail.com
> Cc: Heime <heimeborgia@protonmail.com>
> Date: Wed, 05 Feb 2025 12:40:35 -0500
>
> The author of the docstring possibly thought that it was necessary to
> emphasize that the element of ALIST that was returned was the FIRST one
> found that matches, even though many (most?) readers would assume that
> to be the case.
No, that's just our usual documentation style, first to say something
general, then the details.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Fwd: Improving language in documentation of assoc
2025-02-05 20:13 ` Fwd: " Pierre Rouleau
@ 2025-02-05 20:18 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 20:24 ` Alfred M. Szmidt
1 sibling, 0 replies; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 20:18 UTC (permalink / raw)
To: Pierre Rouleau; +Cc: help-gnu-emacs, Alfred M. Szmidt
Sent with Proton Mail secure email.
On Thursday, February 6th, 2025 at 8:13 AM, Pierre Rouleau <prouleau001@gmail.com> wrote:
> ... forgot to cc the list
>
>
> On Wed, Feb 5, 2025 at 2:58 PM Alfred M. Szmidt ams@gnu.org wrote:
>
> > Retrieve first cons of ALIST whose car equals KEY; else return nil.
> >
> > The assoc function doesn't 'retreive' anything, the above is not what
> > assoc (or any of the same family) does.
>
>
> Ah yes, thanks, you are correct. The word 'retrieve' is not correct
> technically.
Not in the sense of removing or extracting the cons cell from the alist.
> As stated before I'm fine with the current docstring.
>
> But out of curiosity, in a short sentence like that, what word(s) would
> you
> use to describe the mechanism of "returning" the non-nil
> (first element of ALIST whose car equal KEY) value?
>
> --
> /Pierre
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Fwd: Improving language in documentation of assoc
2025-02-05 20:13 ` Fwd: " Pierre Rouleau
2025-02-05 20:18 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-05 20:24 ` Alfred M. Szmidt
1 sibling, 0 replies; 29+ messages in thread
From: Alfred M. Szmidt @ 2025-02-05 20:24 UTC (permalink / raw)
To: Pierre Rouleau; +Cc: help-gnu-emacs
The assoc function doesn't 'retreive' anything, the above is not what
assoc (or any of the same family) does.
Ah yes, thanks, you are correct. The word 'retrieve' is not correct technically.
As stated before I'm fine with the current docstring.
But out of curiosity, in a short sentence like that, what word(s) would you
use to describe the mechanism of "returning" the non-nil
(first element of ALIST whose car equal KEY) value?
I think that is the wrong way to think how to write a good docstring.
One way is to describe the purpose of the function, e.g.:
Search association list ALIST for KEY.
with the details of what ALIST and KEY are later, and any &OPTIONAL
arguments.
Another is to describe the behaviour, which is what the current one
does.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 19:28 ` mbork
@ 2025-02-05 22:42 ` Michael Heerdegen via Users list for the GNU Emacs text editor
2025-02-06 8:42 ` Alfred M. Szmidt
0 siblings, 1 reply; 29+ messages in thread
From: Michael Heerdegen via Users list for the GNU Emacs text editor @ 2025-02-05 22:42 UTC (permalink / raw)
To: help-gnu-emacs
mbork@mbork.pl writes:
> Return non-nil if KEY is equal to the car of an element of ALIST.
> The value is the first element of ALIST whose car equals KEY.
>
> which sounds strange to me (though English is not my first language, so
> there's that). tpeplt's proposal fixes that awkwardness perfectly.
It's a bit more precise in another aspect: `assoc' silently skips
non-cons elements. For example,
(assoc nil (list (cons 1 2) nil (cons 3 4)))
does not return non-nil although there actually is an "element whose car
equals KEY".
Just a very minor detail, though, and it's arguable whether the above
list "counts" as proper ALIST argument.
Michael.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 20:17 ` Eli Zaretskii
@ 2025-02-05 22:55 ` Heime via Users list for the GNU Emacs text editor
2025-02-06 8:49 ` Eli Zaretskii
0 siblings, 1 reply; 29+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2025-02-05 22:55 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: help-gnu-emacs
On Thursday, February 6th, 2025 at 8:17 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> > From: tpeplt@gmail.com
> > Cc: Heime heimeborgia@protonmail.com
> > Date: Wed, 05 Feb 2025 12:40:35 -0500
> >
> > The author of the docstring possibly thought that it was necessary to
> > emphasize that the element of ALIST that was returned was the FIRST one
> > found that matches, even though many (most?) readers would assume that
> > to be the case.
>
>
> No, that's just our usual documentation style, first to say something
> general, then the details.
Having mentioned apropos, I have been scrutinising the case where the first
line would not be enough to extract information about what a function does
well. Can such a case be handled if the information comes later. And if
the docstring excessive, don't we run the risk of matching something that
might not be valid.
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 14:37 ` Pierre Rouleau
2025-02-05 16:27 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-06 4:42 ` Jean Louis
1 sibling, 0 replies; 29+ messages in thread
From: Jean Louis @ 2025-02-06 4:42 UTC (permalink / raw)
To: Pierre Rouleau; +Cc: help-gnu-emacs
* Pierre Rouleau <prouleau001@gmail.com> [2025-02-05 17:38]:
> That's exactly my point.
> The docstring is very clear to me and exactly represents what assoc does.
> If one wants to get the value the value is returned, not t.
> That's very useful:
> It _absolutely can_ be used as a predicate
> *and* it _can_ also used to get the value.
>
> I would not want Elisp documentation to become poetic
> or theatrical (a la Perl for instance).
> The assoc docstring is correct and succinct.
> I think this is what people need, no?
It is very clear as you are on different level of understand each
single point there.
If the description would be easy to understand we wouldn't have
anybody asking about it.
Here is description
-------------------
assoc is a primitive-function in ‘C source code’.
(assoc KEY ALIST &optional TESTFN)
Return non-nil if KEY is equal to the car of an element of ALIST.
The value is actually the first element of ALIST whose car equals KEY.
Equality is defined by the function TESTFN, defaulting to ‘equal’.
TESTFN is called with 2 arguments: a car of an alist element and KEY.
- user must know what is "primitive function" and "C source code"
before understanding what is assoc, as by reading description it
shows it is for advance user. Advance user must know what is
primitive function or may get lost in understanding. Same with "C"
Let me ask IBM Granite Large Language Model (LLM) to say something
about "primitive function" in Emacs Lisp:
---------------------------
In Emacs Lisp, a primitive function is a built-in function that is not written in Emacs Lisp but provided by Emacs itself. These functions offer essential capabilities and are part of the core Emacs Lisp runtime environment. Examples of primitive functions include arithmetic operations, string manipulation, and input/output operations. You can find their source code in the Emacs Lisp source repository.
C source code, in this context, refers to C code that is used to implement the foundation of the C programming language and the GNU Compiler Collection (GCC). GCC is a popular open-source compiler suite used for compiling and optimizing C, C++, and other languages. When discussing Emacs Lisp, C source code is not directly related to Emacs Lisp itself, but it is the underlying system that provides the foundation for implementing and running Emacs Lisp.
In summary:
- Primitive functions in Emacs Lisp are built-in functions provided by Emacs, offering essential capabilities.
- C source code refers to the source code used to implement the C programming language and the GNU Compiler Collection, which serves as the foundation for Emacs Lisp, enabling its execution.
These concepts are related in the sense that they both contribute to
the overall functionality and performance of the Emacs text editor,
with C source code supporting the development of Emacs Lisp.
-------------------------
The above shows that just understanding "primitive function" and "C
source code" requires some serious background.
Even though I do not see a reason why would `assoc' definition of
usage even be mentioning if function is primitive function or not.
And now look at difficulties for reader to understand:
- "primitive function is hyperlinked", saying: primitive-function is a
type (of kind ‘built-in-class’). Inherits from ‘subr’,
‘compiled-function’. This is a built-in type. Type of functions hand
written in C.
I can just say "GOOD LUCK UNDERSTANDING THAT". I do think that IBM
Granite (Granite | IBM: https://www.ibm.com/granite) has better way
to describe the meaning of "primitive function".
- "C source code" is hyperlinked to actual C source code, so now the
user who is learning Lisp and doesn't know about C, like M, is
directly brought to C source code: DEFUN ("assoc", Fassoc, Sassoc,
2, 3, 0, --- what? I am not getting any more documentation, I am
getting now C source code.
A labyrinth obstructs Alice's journey towards her residence,
preventing a return trip from being feasible.
> (assoc KEY ALIST &optional TESTFN)
> Return non-nil if KEY is equal to the car of an element of ALIST.
> The value is actually the first element of ALIST whose car equals KEY.
> Equality is defined by the function TESTFN, defaulting to ‘equal’.
> TESTFN is called with 2 arguments: a car of an alist element and
> KEY.
The local Large Language Model (LLM) IBM Granite with 2 billion
parameters (stupid one) gives me following:
> The function `(assoc KEY ALIST &optional TESTFN)` is used in Common
> Lisp, a dialect of the Lisp programming language. This function is
> part of the ACL (Algebraic Data Types for Common Lisp) library, which
> provides a convenient way to implement associative arrays or hash
> tables.
It may not be true and doesn't apply to Emacs Lisp, though it may be same.
> In this case, the function `assoc` is used to search for an element
> in the associative array (or list) `ALIST`. The search is performed
> based on the value of `KEY`. If `KEY` matches the value (car) of any
> element in `ALIST`, the function returns the entire first element of
> that original list (cons cell).
That may bring more knowledge to user.
> The optional third argument `TESTFN` is a function that defines the
> equality test. By default, it is set to `equal`. If you provide a
> different function, `TESTFN` will be used instead of `equal` for the
> equality test between the car of an element in `ALIST` and `KEY`.
Aha and now we get to examples:
-------------------------------
Here's an example to illustrate its usage:
```lisp
(defparameter *alist* '((1 . "one") (2 . "two") (3 . "three")))
doesn't work, so let us say:
(defvar *alist* '((1 . "one") (2 . "two") (3 . "three")))
(assoc 2 *alist*) ; Returns (2 . "two")
(assoc 4 *alist*) ; Returns NIL, as 4 is not in the list
```
I think that example alone would help the user understand it better.
> In this example, `assoc` is called with `KEY` equal to 2. The function
> returns the cons cell `(2 . "two")`, which is the first element of the
> list in `ALIST` where the car matches `2`.
The description above helps user to understand.
The above exercise demonstrates that function descriptions can be
written in more understandable manner.
Why was LOGO invented? To help people understand programming better.
This concept, which involves deconstructing complex data into
manageable segments, must be employed for the purpose of facilitating
a wider comprehension among diverse audiences.
--
Jean Louis
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 22:42 ` Michael Heerdegen via Users list for the GNU Emacs text editor
@ 2025-02-06 8:42 ` Alfred M. Szmidt
0 siblings, 0 replies; 29+ messages in thread
From: Alfred M. Szmidt @ 2025-02-06 8:42 UTC (permalink / raw)
To: Michael Heerdegen; +Cc: help-gnu-emacs
> Return non-nil if KEY is equal to the car of an element of ALIST.
> The value is the first element of ALIST whose car equals KEY.
>
> which sounds strange to me (though English is not my first language, so
> there's that). tpeplt's proposal fixes that awkwardness perfectly.
It's a bit more precise in another aspect: `assoc' silently skips
non-cons elements. For example,
(assoc nil (list (cons 1 2) nil (cons 3 4)))
does not return non-nil although there actually is an "element whose car
equals KEY".
No there isn't. Compare with:
(assoc nil (list (cons 1 2) (cons nil 5) (cons 3 4)))
(assoc 5 (list (cons 1 2) 5 (cons 3 4)))
Just a very minor detail, though, and it's arguable whether the above
list "counts" as proper ALIST argument.
It does count, but your alist is does not have a element whos car
equals nil!
^ permalink raw reply [flat|nested] 29+ messages in thread
* Re: Improving language in documentation of assoc
2025-02-05 22:55 ` Heime via Users list for the GNU Emacs text editor
@ 2025-02-06 8:49 ` Eli Zaretskii
0 siblings, 0 replies; 29+ messages in thread
From: Eli Zaretskii @ 2025-02-06 8:49 UTC (permalink / raw)
To: help-gnu-emacs
> Date: Wed, 05 Feb 2025 22:55:32 +0000
> From: Heime <heimeborgia@protonmail.com>
> Cc: help-gnu-emacs@gnu.org
>
>
> On Thursday, February 6th, 2025 at 8:17 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>
> > > From: tpeplt@gmail.com
> > > Cc: Heime heimeborgia@protonmail.com
> > > Date: Wed, 05 Feb 2025 12:40:35 -0500
> > >
> > > The author of the docstring possibly thought that it was necessary to
> > > emphasize that the element of ALIST that was returned was the FIRST one
> > > found that matches, even though many (most?) readers would assume that
> > > to be the case.
> >
> >
> > No, that's just our usual documentation style, first to say something
> > general, then the details.
>
> Having mentioned apropos, I have been scrutinising the case where the first
> line would not be enough to extract information about what a function does
> well. Can such a case be handled if the information comes later. And if
> the docstring excessive, don't we run the risk of matching something that
> might not be valid.
When you find in the *Apropos* buffer a doc line that might match what
you want, you can see the full doc string by typing RET. Apropos
commands are a gate into showing documentation, but they show only the
first line so you could quickly skip what is definitely not relevant.
Therefore, the first line is not required to tell everything, only
enough to be considered as possibly relevant. (Of course, in the
simple cases, where we can say everything there, we do.) And false
positives are unavoidable in apropos commands, because they are for
the case where the user doesn't know well enough what he/she is after,
but only has a general idea.
^ permalink raw reply [flat|nested] 29+ messages in thread
end of thread, other threads:[~2025-02-06 8:49 UTC | newest]
Thread overview: 29+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-02-05 3:08 Improving language in documentation of assoc Heime via Users list for the GNU Emacs text editor
2025-02-05 3:31 ` Pierre Rouleau
2025-02-05 5:00 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 15:17 ` Jean Louis
2025-02-05 5:59 ` Yuri Khan
2025-02-05 6:13 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 14:07 ` Eli Zaretskii
2025-02-05 14:35 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 14:54 ` Alfred M. Szmidt
2025-02-05 15:27 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 14:37 ` Pierre Rouleau
2025-02-05 16:27 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 17:00 ` Eli Zaretskii
2025-02-05 17:38 ` Heime via Users list for the GNU Emacs text editor
2025-02-06 4:42 ` Jean Louis
2025-02-05 17:40 ` tpeplt
2025-02-05 18:10 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 19:30 ` Pierre Rouleau
2025-02-05 19:58 ` Alfred M. Szmidt
[not found] ` <CALTqLiZs7z24jA9TgDuAp+BdWUwCRzr9DpFhpEoP7tTAwzP-tA@mail.gmail.com>
2025-02-05 20:13 ` Fwd: " Pierre Rouleau
2025-02-05 20:18 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 20:24 ` Alfred M. Szmidt
2025-02-05 20:00 ` Heime via Users list for the GNU Emacs text editor
2025-02-05 19:28 ` mbork
2025-02-05 22:42 ` Michael Heerdegen via Users list for the GNU Emacs text editor
2025-02-06 8:42 ` Alfred M. Szmidt
2025-02-05 20:17 ` Eli Zaretskii
2025-02-05 22:55 ` Heime via Users list for the GNU Emacs text editor
2025-02-06 8:49 ` Eli Zaretskii
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.