bug#37925: 26.3; Elisp manual: add index entry for sets/kinds of variables

[Drew Adams]

> > Please consider adding index entries that correspond directly to
> > these node names.  A user should be able to do, for example (and
> > preferably with or without the hyphen):
> >
> >   i mode-line variables
> >
> > Today that's not possible.
> 
> Yes, it is possible today, because each variable is indexed by its
> name.  So, for example "i mode-line TAB" will show the list of all the
> variables (and some other related topics as well).

That's not the "it" that I said is not possible.
That's an way to find something different:
information about a specific variable, known or
recognized as such.

> In general, the technique of working with index entries that I
> recommend is to try the text you thought about initially, in this case
> "mode-line variables", and if that doesn't bring anything useful,
> remove some text from the end and try again, with TAB.  (That is
> assuming the above text is something you really thought about in some
> real-life use case, and not a synthetic example of no practical
> importance.)

You're missing the point, I think.  You focus on
`mode-line' because each of the mode-line variables
has prefix `mode-line' in its name.  That's not true
of some of the other kinds of variables covered (by
kind) in nodes: list, generalized, constant, output...

Some come close, and TAB with just the first part
would suffice for them.  Others do not - `list',
for example.

Please read the bug title (and body).  It's about
the nodes for different "sets/kinds of variables".
It's not just about mode-line variables.

Not only that.  If you're interested in knowing
about mode-line variables, and you don't know
what they are, or even if there are any, their
individual names as entries won't help you much,
because the names aren't identified in the index
entries as _variable_ names.

In a real (e.g. book) index, an entry such as
`mode-line-remote' would be followed by
", variable".  That's done for entry
`mode-line-format, a frame parameter'.  But it's
not done for `mode-line-format' (a variable).

Beyond all of that, it's not obvious that there
even are nodes that talk about particular kinds
of variables.

Part of this problem would be alleviated by
having index entries that start with `variable'
for the various kinds covered by their own nodes:

variables, list
variables, completion
variables, generalized
...

These are the only index entries that start with
`variable':

variable
variable aliases
variable definition
variable descriptions 
variable limit error
variable watchpoints
variable with constant value 
variable write debugging
variable, buffer-local
variable-documentation property 
variable-width spaces

Those don't take you to a node that covers
variables of a given kind, except for
`variable with a constant value' and
`variable, buffer-local'.

> Please consider describing use cases where the name of the variable,
> or the results of TAB as above, will not let the user arrive to the
> place where he or she needs to be.  Otherwise, what you ask for is to
> provide one more index entry that begins like many others we already
> have and points to the same place, something that is not useful, and
> we therefore avoid it.

See above.  For example, `i list TAB' will
not show you anything that suggests a node
about list variables.  It won't get you to
node `List Variables'.

And no, entries such as what I suggest do
not "begin like many others we already have
and point to the same place".  See above.

If there's already an entry that does that,
then no entry need be added for it.  That's
the case for buffer-local variables: we have
entries `variable, buffer-local' and
`buffer-local variables'.  It's not the case
in general.

And BTW, we have these entries, which go to
3 different nodes.  They're not distinguished
at the level of entries (except for the 2nd
one).

buffer-local variables
buffer-local variables in modes
buffer-local-variables

It would be clearer if the last one were
called `buffer-local-variables, function'.