Reference to ‘alist’ in Emacs Lisp Manual without previous explanation

Reference to ‘alist’ in Emacs Lisp Manual without previous explanation

[Pankaj Jangid]

I am reading the Emacs Lisp Manual from beginning and
sequencially. Found reference to ‘alist’ in section 2.4.12 Hash Table
Type without any previous explanation.

Either a brief summary should be provided before this, probably near
2.4.6 Cons Cell and List Types or a cross-reference should be added.

Regards

-- Pankaj

Subject: Re: Reference to ‘alist’ in Emacs Lisp Manual without previous explanation

[Alfred M. Szmidt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 336 bytes --]


   I am reading the Emacs Lisp Manual from beginning and
   sequencially. Found reference to ‘alist’ in section 2.4.12 Hash Table
   Type without any previous explanation.

If you look up the term in the index, you will get the right result
for it.  "i alist RET" in the Info reader which goes the the overall
chapter on alists.

Re: Reference to ‘alist’ in Emacs Lisp Manual without previous explanation

[Eli Zaretskii]

> From: Pankaj Jangid <pankaj@codeisgreat.org>
> Date: Thu, 22 Oct 2020 11:10:21 +0530
> 
> I am reading the Emacs Lisp Manual from beginning and
> sequencially. Found reference to ‘alist’ in section 2.4.12 Hash Table
> Type without any previous explanation.
> 
> Either a brief summary should be provided before this, probably near
> 2.4.6 Cons Cell and List Types or a cross-reference should be added.

If you are reading the manual in order, you should have read 2.4.6.3
"Association List Type", where "alist" is explained, before you got to
2.4.12.  How come you didn't see that?

RE: Reference to ‘alist’ in Emacs Lisp Manual without previous explanation

[Drew Adams]

> > I am reading the Emacs Lisp Manual from beginning and
> > sequencially. Found reference to ‘alist’ in section 2.4.12 Hash Table
> > Type without any previous explanation.
> >
> > Either a brief summary should be provided before this, probably near
> > 2.4.6 Cons Cell and List Types or a cross-reference should be added.
> 
> If you are reading the manual in order, you should have read 2.4.6.3
> "Association List Type", where "alist" is explained, before you got to
> 2.4.12.  How come you didn't see that?

Yes, "if".  Aside from whether Pankaj should have
seen that:

People don't necessarily (or even often) read manuals
"in order".

Even when they do, it can help to put important terms
in a glossary, and add links from the glossary to
topics that also define, or otherwise expand on the
terms.

The Emacs manual has a glossary (`g glossary'), but
the Elisp manual doesn't.  It could have one too.

Links from occurrences to glossary entries (or if
no glossary, to a defining topic) can help.  E.g.,
put a glossary link on the first occurrence of a
term in a given topic, especially if understanding
the term is important to understanding that topic.

Re: Reference to ‘alist’ in Emacs Lisp Manual without previous explanation

[Pankaj Jangid]

Eli Zaretskii <eliz@gnu.org> writes:

>> sequencially. Found reference to ‘alist’ in section 2.4.12 Hash Table
>> Type without any previous explanation.
>> 
>> Either a brief summary should be provided before this, probably near
>> 2.4.6 Cons Cell and List Types or a cross-reference should be added.
>
> If you are reading the manual in order, you should have read 2.4.6.3
> "Association List Type", where "alist" is explained, before you got to
> 2.4.12.  How come you didn't see that?

I missed it completely while reading. Completely my fault. The manual is
absolute truth.

Re: Reference to ‘alist’ in Emacs Lisp Manual without previous explanation

[Eli Zaretskii]

> From: Pankaj Jangid <pankaj@codeisgreat.org>
> Cc: emacs-devel@gnu.org
> Date: Fri, 23 Oct 2020 12:52:48 +0530
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > If you are reading the manual in order, you should have read 2.4.6.3
> > "Association List Type", where "alist" is explained, before you got to
> > 2.4.12.  How come you didn't see that?
> 
> I missed it completely while reading. Completely my fault. The manual is
> absolute truth.

Maybe you could tell how you missed that, and it will help us make
this more prominent?

Re: Reference to ‘alist’ in Emacs Lisp Manual without previous explanation

[Pankaj Jangid]

Eli Zaretskii <eliz@gnu.org> writes:

>> > If you are reading the manual in order, you should have read 2.4.6.3
>> > "Association List Type", where "alist" is explained, before you got to
>> > 2.4.12.  How come you didn't see that?
>> 
>> I missed it completely while reading. Completely my fault. The manual is
>> absolute truth.
>
> Maybe you could tell how you missed that, and it will help us make
> this more prominent?

I tried to replay what I could have done, but could not find a way to
miss the topic. Usually, when I read sequencially, I use SPACE key to go
to next page. This cannot miss the section. And since this section
2.4.6.3 is at the same level as 2.4.6.2 I cannot miss it with ‘n’ as
well.

So, I guess, it just slipped from my mind.