bug#8900: 24.0.50; please index mentioned coding systems in Emacs manual

[Drew Adams]

> > I disagree.  These are real, implementation, user-visible, 
> > runtime names.  This is just like indexing command names
> > or variable names or package names.  The exact name should
> > appear in the index.
> 
> Not true, at least not until we have a detailed documentation of each
> encoding there.  The absolute majority of coding-systems is not
> documented in the manual, so there's no real place to put the index
> entries.  I'm not sure there's something intelligent to tell about
> these encodings in the manual, either.

Doesn't matter that we don't have detailed doc about these.  Certainly doesn't
matter that we don't have detailed doc about *each* coding system.

The fact is that the manual provides some information about these particular
coding systems.  They should be indexed so users can easily find that
information.

An index does not refer only to "detailed documentation" about terms.  It refers
to terms that we think a user is likely to look for in the book.  It is often
the case that a term is indexed that is only mentioned in the book.

What is important is whether a user might want to look it up, not how much the
book goes into detail about it.  The book might even state in some context "this
book does not cover XYZ", and `XYZ' might still be appropriate as an index entry
- precisely to get you to that information, however negative and incomplete.

> > Consider, for instance, the use case that brought this to 
> > my attention:
> 
> You cannot assume that every symbol appears in the manual.

What makes you think I make such an assumption?  Far from it.

You have knee-jerk repeated that several times over the past - it seems to be
your mantra whenever indexing comes up.  Just a straw man - no one here is
assuming any such thing.

Certainly it is _not_ the case that every symbol _should_ appear in the manual.
Far from it.  The vast majority of symbols should _not_.

In any case, this is not about whether some given term should appear in the
manual.  This is about whether some particular terms that _do_ appear in the
manual should be indexed.

> So this feature can never work reliably, only ad-hoc.

Wrong.  "This feature" is to provide a link in *Help* (in this case, for
`describe-coding-system XYZ') to search the manuals for a corresponding index
entry.  That works 100% reliably.

"This feature" also includes an option for those who prefer that a link to
search the manuals not be added unless there are in fact index entries for the
subject term in the manuals to be searched.  And that option also lets users
choose which manuals are to be searched.

But regardless of the option value, clicking the `manuals' link will always
correctly search the specified manuals and produce a virtual index if the
subject term is found.  100% reliable.

> You should be prepared for the situation where the manual
> doesn't have this in its index, and handle that gracefully.

See above.  And see the emacs-devel thread where the feature was described.  Or
see the source code that implements it - either the submitted patch or the cited
library, help-fns+.el.

And independently of this feature, a user can _already_ create a virtual index
(which is what this feature creates automatically when you click the `manuals'
link).  Doing that should find a particular coding system that is discussed in
the manual.

If the manual had nothing to say about these coding systems then they would not
be there and would not be indexed.