Subject: bug#7385: 24.0.50; Please index defcustom type constructs

From: MON KEY <[email-masked]>
Date: Sat, 13 Nov 2010 02:47:14 -0500

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