bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives

bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives

[Drew Adams]

(elisp) Common Keywords should be indexed for each of the LINK-DATA
alternatives: `custom-manual', `info-link', `url-link',
`emacs-commentary-link', `emacs-library-link', `file-link',
`function-link', `variable-link', and `custom-group-link'.

In GNU Emacs 24.0.94.1 (i386-mingw-nt5.1.2600)
 of 2012-03-19 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'
 

bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives

[Chong Yidong]

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

> (elisp) Common Keywords should be indexed for each of the LINK-DATA
> alternatives: `custom-manual', `info-link', `url-link',
> `emacs-commentary-link', `emacs-library-link', `file-link',
> `function-link', `variable-link', and `custom-group-link'.

No.  That makes no sense---there's already an index entry for adding
links to custom docs.  I don't want to pollute the index with entries
listing every possible value for what's just a keyword.  (Though I
eagerly await the coming long-form article arguing against this.)

bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives

[Drew Adams]

> > (elisp) Common Keywords should be indexed for each of the LINK-DATA
> > alternatives: `custom-manual', `info-link', `url-link',
> > `emacs-commentary-link', `emacs-library-link', `file-link',
> > `function-link', `variable-link', and `custom-group-link'.
> 
> No.  That makes no sense---there's already an index entry for adding
> links to custom docs.  I don't want to pollute the index with entries
> listing every possible value for what's just a keyword.  (Though I
> eagerly await the coming long-form article arguing against this.)

These are reference entries.  No different from indexing individual function
names or individual button properties.

We don't use the argument that just because there is an index entry for the
general topic of Apropos in the Emacs manual there should not also be entries
for the individual apropos commands.  Etc.

bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 10 Apr 2012 23:27:43 -0700
> Cc: 11178@debbugs.gnu.org
> 
> > > (elisp) Common Keywords should be indexed for each of the LINK-DATA
> > > alternatives: `custom-manual', `info-link', `url-link',
> > > `emacs-commentary-link', `emacs-library-link', `file-link',
> > > `function-link', `variable-link', and `custom-group-link'.
> > 
> > No.  That makes no sense---there's already an index entry for adding
> > links to custom docs.  I don't want to pollute the index with entries
> > listing every possible value for what's just a keyword.  (Though I
> > eagerly await the coming long-form article arguing against this.)
> 
> These are reference entries.  No different from indexing individual function
> names or individual button properties.

Perhaps adding two more index entries, something like

  @cindex links to documentation for customization items
  @cindex customization items, links to documentation

would do the job.  Currently, I see only one index entry there:

  @kindex link@r{, customization keyword}

which IMO is not enough for when the reader wants to find information
about adding links to the docs.  The existing index entry only covers
efficiently the case when the reader is specifically looking for the
'link' keyword and already knows what that's used for.

bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives

[Drew Adams]

> > These are reference entries.  No different from indexing 
> > individual function names or individual button properties.
> 
> Perhaps adding two more index entries, something like
> 
>   @cindex links to documentation for customization items
>   @cindex customization items, links to documentation
> 
> would do the job.  Currently, I see only one index entry there:
> 
>   @kindex link@r{, customization keyword}
> 
> which IMO is not enough for when the reader wants to find information
> about adding links to the docs.  The existing index entry only covers
> efficiently the case when the reader is specifically looking for the
> 'link' keyword and already knows what that's used for.

What Eli says is also pertinent.  But independent.

Again, you are talking about indexing _topics_.  I am talking about _reference_
index entries.

If a user wants to look up the particular button property `follow-link', she
does `i follow-link' and Bob's an uncle.

This is about looking up a particular :link alternative, such as
`emacs-commentary-link'.  It is not about looking up the topic of "links to
documentation for customization items".

bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <cyd@gnu.org>, <11178@debbugs.gnu.org>
> Date: Wed, 11 Apr 2012 10:37:39 -0700
> 
> > > These are reference entries.  No different from indexing 
> > > individual function names or individual button properties.
> > 
> > Perhaps adding two more index entries, something like
> > 
> >   @cindex links to documentation for customization items
> >   @cindex customization items, links to documentation
> > 
> > would do the job.  Currently, I see only one index entry there:
> > 
> >   @kindex link@r{, customization keyword}
> > 
> > which IMO is not enough for when the reader wants to find information
> > about adding links to the docs.  The existing index entry only covers
> > efficiently the case when the reader is specifically looking for the
> > 'link' keyword and already knows what that's used for.
> 
> What Eli says is also pertinent.  But independent.
> 
> Again, you are talking about indexing _topics_.  I am talking about _reference_
> index entries.

We've been through this before, Drew, and we already established that
your views about indexing are not shared.  Bringing that up again
won't change that.

> If a user wants to look up the particular button property `follow-link', she
> does `i follow-link' and Bob's an uncle.

She can also do 'i link TAB', see "link, customization keyword" and
Bob's her uncle.  IOW, if she already knows she's after follow-link,
she'll have no trouble finding it.

bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives

[Drew Adams]

> > Again, you are talking about indexing _topics_.  I am 
> > talking about _reference_ index entries.
> 
> We've been through this before, Drew, and we already established that
> your views about indexing are not shared.  Bringing that up again
> won't change that.

There you go again, Eli, generalizing and ad hominem ad nauseum.

Apparently "my views" related to this bug report _are_ shared when it comes to
button properties, functions, etc. - those are all indexed individually by name.

You just do not agree that link alternatives should be handled the same way.  It
would be fair enough to say that (we can disagree), but you do not.  

Instead, you cast this as being about some purported general "view" of mine.
No, it's about the question posed by the bug report: indexing the individual
link alternatives, which are specific Emacs-Lisp symbols/sexps.

As for "bringing it up again won't change that": Again, you are generalizing,
caricaturing, and ignoring the particular request.  I have never before brought
up this request.

And I understood as soon as Yidong said "That makes no sense" that the request
would likely not be fulfilled.  His reason, that there was already a topic entry
for adding links to custom docs, does not at all address the need expressed -
this bug report.  Your independent request for adding more topic entries does
not address it either.

So I explained the difference, using a particular button property (_not_ the
topic of button properties) as an example of how we do typically DTRT.
Functions that are mentioned in the manual are indexed under their names, in
addition to being indirectly indexed via topics where they are mentioned.
Likewise button properties and other entities.  Not so link alternatives.  

That is this bug.  It has nothing to do with wanting more topic entries about
links or linking.
 
> > If a user wants to look up the particular button property 
> > `follow-link', she does `i follow-link' and Bob's an uncle.
> >
> > This is about looking up a particular :link alternative,
> > such as `emacs-commentary-link'.  It is not about looking
> > up the topic of "links to documentation for customization items".
> 
> She can also do 'i link TAB', see "link, customization keyword" and
> Bob's her uncle.  IOW, if she already knows she's after follow-link,
> she'll have no trouble finding it.

Still missing the point, Eli.  `follow-link' is the example of a case where we
do DTRT: the `follow-link' button property is indexed as such, not only
indirectly via topics (such as "button properties") where it is mentioned.

It's about indexing the particular, literal reference term: `follow-link' in the
case of the button property (done), and `emacs-commentary-link' in the case of
the link alternative (not done).