bug#7385: 24.0.50; Please index defcustom type constructs

[Drew Adams]

> > In the Elisp manual, you should be able to do `i 
> > restricted-sexp RET' to go to the section that explains
> > that defcustom type construct.  Likewise
> > for the other type constructs.
> 
> Such indexing is not useful, IMO.

Well you are wrong. ;-)

Going directly to a :type construct entry such as `choice' or `restricted-sexp'
is no different from going directly to a function entry such as `cons' or
`fceiling', or a variable entry such as `obarray' or
`split-string-default-separators'.

Indexing of such distinguished names is important whether the name is commonly
or rarely used in the manual.  It gives you direct lookup.  

Obviously, if a term is commonly used, then index lookup gives a greater
advantage over brute search than if the term is rarely used.  But the criterion
for indexing a term is whether it is a distinguised name (or it relates to an
important concept).  The criterion is not the frequency with which it appears in
the manual.

In a manual that serves as a reference (and the Elisp manual does that, even
though it also provides some user-guide features), the distinguished names it
documents should be indexed.  In Emacs Lisp, this includes constants such as
keywords and other defcustom constructs that are described in the manual.

> If you already know that you are looking for restricted-sexp,
> you can use `s restricted-sexp RET'.

And if you already know that you are looking for `fceiling' you can use `s
fceiling'.  So what?  Searching through a manual is no substitute for indexing.
That is just a cop-out - let them eat cake.

Predefined names, whether of functions, variables, keymap constructs, font-lock
constructs, or defcustom constructs, should be indexed.

There is no substitute for being able to go directly to the description of the
`choice' defcustom entry.  Try searching for `choice' and see how long it takes
you to get to the right node.  G'head, try it.

> With such a specialized string, chances that you will get too many
> false hits are nil.  Alternatively, go to the chapter and look through
> its sections.
> 
> Indexing is mainly for readers who do NOT know what they are after.

Nonsense - nothing could be more backward.

Following that logic we should remove the key, option, command, and variable
indexes from the Emacs manual, and we should remove the function index entries
from the Elisp manual.  If you know you are after function `cons' or `eq' then
just search the manual for it - why should we index it?  Riiight.

If you know you are after the description of function `eq' then you _should_ be
able to use `i eq RET' to get there directly.  And, thank goodness, you can.

The fact that something is in the index recognizes and advertizes it as a
distinguished name (or as an important concept) that is documented in the
manual.  These constructs are distinguished names in Elisp, and they are
documented in the manual.  They deserve to be indexed.

Also, being able to complete your input against index entries is a significant
aid.  This is all the more important with non-trivial (i.e., not just prefix)
completion (e.g. substring/regexp completion, partial completion).  Search is
simply no substitute for index access.
 
> It would be much more useful if you (or someone else) could come up
> with some phrase that could be on the reader's mind when she is after
> these features.  Currently, the section where they are documented has
> only one index entry: "composite types (customization)".  Suggestions
> for more are most welcome.

I've made plenty of suggestions regarding index access to the defcustom
sections.  The most important one is to enable indexing of keywords such as
`:type' (including the colon).  You rejected that as an implementation
impossibility, so users have to settle for matching workaround entries such as
`type, defcustom keyword'.

If you really want to improve index access to sections about the defcustom
constructs, then please work on figuring out how to index keywords (including
the `:').

Keywords are important distinguished words in Emacs Lisp, hence the name
"keyword".  This indexing suggestion applies not only to defcustom keywords but
also to all the others that are documented.

If you want to see how important keywords are in the Elisp manual, just start
searching from the beginning using `C-M-s :[a-z]'.

I would also suggest that we have separate indexes for the Elisp manual, just as
we have for the Emacs manual: keywords, variables, commands, other functions,
etc.