bug#7385: 24.0.50; Please index defcustom type constructs

bug#7385: 24.0.50; Please index defcustom type constructs

[Drew Adams]

emacs -Q
 
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.
 
This should be done at least for those constructs whose names are
unambiguously type constructs (e.g. `choice', `radio, and
`coding-system', but perhaps not `sexp', `cons', and `vector').
This applies also to keywords such as :match-alternatives.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2010-11-09 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'
 

bug#7385: 24.0.50; Please index defcustom type constructs

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 12 Nov 2010 08:29:18 -0800
> Cc: 
> 
> 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.  If you already know that you are
looking for restricted-sexp, you can use `s restricted-sexp RET'.
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.

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.

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.

bug#7385: 24.0.50; Please index defcustom type constructs

[Stefan Monnier]

> 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.

> This should be done at least for those constructs whose names are
> unambiguously type constructs (e.g. `choice', `radio, and
> `coding-system', but perhaps not `sexp', `cons', and `vector').
> This applies also to keywords such as :match-alternatives.
 
That would make sense, indeed.  Same for :keywords (e.g. those used in
menu-item).  It would probably need to be a new index, tho.


        Stefan

bug#7385: 24.0.50; Please index defcustom type constructs

[MON KEY]

>> Indexing is mainly for readers who do NOT know what they are after.

> 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.

There can not be just _one_ phrase.
Nor can there be an index for every word in the manual.
What is needed is a separate "site map" -- a hyper-manual,
a kind of conceptual topology... Enter Baudrillard:

 Today abstraction is no longer that of the map, the double, the
 mirror, or the concept. Simulation is no longer that of a
 territory, a referential being or substance. It is the generation
 by models of a real without origin or reality: A hyperreal. The
 territory no longer precedes the map, nor does it survive it. It
 is nevertheless the map that precedes the territory - precession
 of simulacra - that engenders the territory.

 "Simulacra & Simulation" 1994, p. 1

Witness `mon-help-*-blub' (of which these are legion):

(documentation 'mon-help-custom-keywords)

mon-help-custom-keywords is an interactive compiled Lisp function in
`mon-doc-help-utils.el'.

(mon-help-custom-keywords &optional insertp intrp)

Keywords used with defcustom, degroup, customize facilities.

;; :CUSTOM-COMMON-KEYWORDS
:link
                 ¦ (custom-manual        "(info-node)Section")
                 ¦ (info-link            "(info-node)Section")
                 ¦ (url-link              <STRING>)
                 ¦ (emacs-commentary-link <STRING>)
                 ¦ (emacs-library-link    <STRING>)
                 ¦ (file-link             <STRING>)
                 ¦ (function-link         <STRING>)
                 ¦ (file-link             <STRING>)
                 ¦ (variable-link         <VARIABLE>)
                 ¦ (custom-group-link     <SYMBOL>)

:tag             <STRING>
:group           <SYMBOL>
:load            <STRING>
:require         <SYMBOL>
:version         <STRING>
:prefix          <STRING>              ; :NOTE `defgroup' only
:package-version (<SYMBOL> . <STRING>)

;; :DEFCUSTOM-KEYWORDS
:options         <LIST>
:set             <SYMBOL>
:get             <SYMBOL>
:risky           <PROPERTY-VALUE>
:safe            <PROPERTY-VALUE>
:set-after       <SYMBOL>
:intialize       <SYMBOL>
                 ¦ `custom-initialize-set'
                 ¦ `custom-initialize-default'
                 ¦ `custom-initialize-reset'
                 ¦ `custom-initialize-changed'
                 ¦ `custom-initialize-safe-set'
                 ¦ `custom-initialize-safe-default'

;; :CUSTOM-TYPES-SIMPLE
:type            <TYPE>
                 ¦ sexp           <FORM>
                 ¦ integer        <INTEGER>
                 ¦ number         <NUMBER>
                 ¦ float          <FLOAT>
                 ¦ symbol         <SYMBOL>
                 ¦ string         <STRING>
                 ¦ regexp         <STRING>
                 ¦ character      <CHAR-CODE>
                 ¦ file           <STRING>
                 ¦ directory      <STRING>
                 ¦ hook           <LIST>
                 ¦ alist          <CONSED-LIST>
                 ¦ plist          <KEY-VALUE-PAIR>
                 ¦ function       <SYMBOL>
                 ¦ variable       <SYMBOL>
                 ¦ face           <SYMBOL>
                 ¦ boolean        <T-OR-NIL>
                 ¦ coding-system  <SYMBOL>
                 ¦ color          <STRING>|<RGB-HEX-VALUE>

;; :CUSTOM-TYPES-CONSTRUCTORS
list             <ELT-TYPES>
group            <ELT-TYPES>
vector           <ELT-TYPES>
radio            <ELT-TYPES>
choice           <ALT-TYPES>
const            <VAL-TYPEs>
other            <VAL-TYPES>
function-item    <FUNCTION>
cons             (<CAR-TYPE> <CDR-TYPE>)

;; :CUTSOM-USAGE
An alist of conses uses this form:

 :type '(alist :key-type integer :value-type string)

An alist that is not a cons uses one of the forms:

 :type '(repeat (group integer string))

 :type '(repeat (list integer string))

To link to a URL do:

 :link '(url-link :tag "A search-engine" "http://www.google.com")

To link to a file do:

 :link '(file-link :tag "an interesting file" "~/.emacs")

To link to an existing file of emacs lisp source code do:

 :link '(emacs-library-link  "subr.el")

:SEE info node `(elisp)Common Keywords'

:SEE info node `(elisp)Customization Types'

:SEE-ALSO `mon-help-widgets', `mon-help-easy-menu', `mon-help-plist-functions',
`mon-help-color-chart', `mon-help-key-functions', `mon-help-package-keywords',
`mon-help-faces', `mon-help-faces-basic', `mon-help-faces-themes',
`mon-help-eieio-defclass'.
►►►


Such handlists exist because I routinely can't find what I am looking
for in the manual.
It is impossible to keep all of  _Emacs_ top of mind.
Users should not be expected to know what they do not know they don't know.

---
/s_P\

bug#7385: 24.0.50; Please index defcustom type constructs

[Eli Zaretskii]

> Date: Sat, 13 Nov 2010 02:47:14 -0500
> From: MON KEY <monkey@sandpframing.com>
> Cc: Drew Adams <drew.adams@oracle.com>, Eli Zaretskii <eliz@gnu.org>
> 
> >> Indexing is mainly for readers who do NOT know what they are after.
> 
> > 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.
> 
> There can not be just _one_ phrase.

Right, I meant "phrases", of course.

bug#7385: 24.0.50; Please index defcustom type constructs

[Eli Zaretskii]

> Date: Sat, 13 Nov 2010 02:47:14 -0500
> From: MON KEY <monkey@sandpframing.com>
> Cc: Drew Adams <drew.adams@oracle.com>, Eli Zaretskii <eliz@gnu.org>
> 
> Such handlists exist because I routinely can't find what I am looking
> for in the manual.

Please report every one of them as a documentation bug.

> Users should not be expected to know what they do not know they don't know.

Of course not.  That's the main reason for indexing.  If you cannot
find something using appropriate phrases, it's a sign that the
indexing needs to be improved.

bug#7385: 24.0.50; Please index defcustom type constructs

[MON KEY]

On Sat, Nov 13, 2010 at 3:09 AM, Eli Zaretskii <eliz@gnu.org> wrote:

>> Such handlists exist because I routinely can't find what I am looking
>> for in the manual.
>
> Please report every one of them as a documentation bug.
>

I prob. should have qualified the above.
To be clear, what I meant to communicate was this:

 I routinely have trouble knowing what to look for and where to do it
 when I can't immediately find something in the manuals.

Indeed, FTMP the manuals _do_ provide the information one requires.
It just isn't always easily at hand.

I don't think this constitutes a bug. Do you?

--
/s_P\

bug#7385: 24.0.50; Please index defcustom type constructs

[Eli Zaretskii]

> Date: Sat, 13 Nov 2010 03:39:19 -0500
> From: MON KEY <monkey@sandpframing.com>
> Cc: 7385@debbugs.gnu.org, Drew Adams <drew.adams@oracle.com>
> 
> On Sat, Nov 13, 2010 at 3:09 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >> Such handlists exist because I routinely can't find what I am looking
> >> for in the manual.
> >
> > Please report every one of them as a documentation bug.
> >
> 
> I prob. should have qualified the above.
> To be clear, what I meant to communicate was this:
> 
>  I routinely have trouble knowing what to look for and where to do it
>  when I can't immediately find something in the manuals.
> 
> Indeed, FTMP the manuals _do_ provide the information one requires.
> It just isn't always easily at hand.
> 
> I don't think this constitutes a bug. Do you?

It could be.  Here's how to know: Whenever you are looking for some
issue, think about a word or a phrase of several words, which would
(in your opinion) be appropriate as index entries, or parts of index
entries, for that issue.  Then try these words/phrases with the `i'
command.  If they don't get you to the section of the manual where the
issue is described, submit a docs bug report and be sure to mention
the phrases you used to search.

TIA

bug#7385: 24.0.50; Please index defcustom type constructs

[Lars Ingebrigtsen]

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

> 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.
>
> This should be done at least for those constructs whose names are
> unambiguously type constructs (e.g. `choice', `radio, and
> `coding-system', but perhaps not `sexp', `cons', and `vector').
> This applies also to keywords such as :match-alternatives.

I've now added concept index entries to the first three types.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no