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

From: "Drew Adams" <[email-masked]>
Date: Fri, 1 Jul 2011 14:00:01 -0700

> > 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.
> 
> Well, in that case, we will have to disagree.

You need detailed doc about *each* coding system before you will index *any* of
them?

With that logic we should remove all entries from our `Variable', `Command', and
`Key' indexes, since we certainly do not provide documentation - let alone
"detailed documentation" - about all of them.

> Having index entries about something that isn't described
> is a Bad Thing.

"Described" is vague here, so it's hard to judge.  But you clarified earlier
that only "detailed documentation" counts for you.

We have similar index entries in the manuals.  Looking only at the first few
entries of the `Variable' index, check `blink-cursor-alist' and `auto-coding-*',
for instance.  There is no "detailed documentation" describing these variables.
There is only a general, cursory mention of what they are for.  And these are
not outliers/alone in this respect.

That is not a bug.  We still want to index these variables, IMO.  Not because we
necessarily provide their "detailed documentation" in this manual (we do _not_),
but because:

a. we say something about them that could be useful to a user (otherwise we
wouldn't mention them!), and

b. we think a user might want to look them up.

Those, not simply the degree of detail provided, are proper, user-oriented
criteria for indexing.

(Of course, if such a variable also had a more complete, detailed documentation
elsewhere in the manual, then that location would likely be indexed - either in
addition to or instead of the current location, depending on the context and the
specific content.)

I think those two criteria apply to the coding-system entries I submitted this
bug about.  You can disagree about that.  But I would hope that you would agree
about such criteria, whether or not you agree that they are satisfied in these
particular cases.

> > 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.
> 
> But there's no information to find.

Yes there is.  About the same degree of information as for our "descriptions" of
variables `blink-cursor-alist' and `auto-coding-alist' - more, in fact.  We say
what the undecided-* coding systems do wrt end-of-line conversion, and we
mention their aliases.

> > 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. 
> 
> Not in my book.

Whatever.  I do indexing for a living.  But it's `your book'.