(Major Mode Conventions): Mention third way to set up Imenu.

(Imenu): A number of small fixes.
Delete documentation of internal variable imenu--index-alist.
Document the return value format of imenu-create-index-function
functions.

2 files changed, 67 insertions, 43 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index ebaaec22bb7..234133c78e2 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,12 @@
+2003-10-03  Lute Kamstra  <Lute.Kamstra@cwi.nl>
+
+        * modes.texi (Major Mode Conventions): Mention third way to set up
+        Imenu.
+        (Imenu): A number of small fixes.
+        Delete documentation of internal variable imenu--index-alist.
+        Document the return value format of imenu-create-index-function
+        functions.
+
 2003-09-30  Richard M. Stallman  <rms@gnu.org>
 
         * processes.texi (Network): Say what stopped datagram connections do.
diff --git a/lispref/modes.texi b/lispref/modes.texi
index b346dad99cc..fb287b162b8 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -236,7 +236,9 @@ setting up a buffer-local value for the variable
 @item
 The mode should specify how Imenu should find the definitions or
 sections of a buffer, by setting up a buffer-local value for the
-variable @code{imenu-generic-expression} or
+variable @code{imenu-generic-expression}, for the pair of variables
+@code{imenu-prev-index-position-function} and
+@code{imenu-extract-index-name-function}, or for the variable
 @code{imenu-create-index-function} (@pxref{Imenu}).
 
 @item
@@ -1702,12 +1704,12 @@ particular major mode.
 @code{imenu-generic-expression}:
 
 @defvar imenu-generic-expression
-This variable, if non-@code{nil}, specifies regular expressions for
-finding definitions for Imenu.  In the simplest case, elements should
-look like this:
+This variable, if non-@code{nil}, is a list that specifies regular
+expressions for finding definitions for Imenu.  Simple elements of
+@code{imenu-generic-expression} look like this:
 
 @example
-(@var{menu-title} @var{regexp} @var{subexp})
+(@var{menu-title} @var{regexp} @var{index})
 @end example
 
 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
@@ -1717,10 +1719,10 @@ for this element should go in a submenu of the buffer index;
 in the top level of the buffer index.
 
 The second item in the list, @var{regexp}, is a regular expression
-(@pxref{Regular Expressions}); anything in the buffer that it matches is
-considered a definition, something to mention in the buffer index.  The
-third item, @var{subexp}, indicates which subexpression in @var{regexp}
-matches the definition's name.
+(@pxref{Regular Expressions}); anything in the buffer that it matches
+is considered a definition, something to mention in the buffer index.
+The third item, @var{index}, is a non-negative integer that indicates
+which subexpression in @var{regexp} matches the definition's name.
 
 An element can also look like this:
 
@@ -1728,11 +1730,13 @@ An element can also look like this:
 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
 @end example
 
-Each match for this element creates a special index item which, if
-selected by the user, calls @var{function} with arguments consisting of
-the item name, the buffer position, and @var{arguments}.
+Like in the previous case, each match for this element creates an
+index item.  However, if this index item is selected by the user, it
+calls @var{function} with arguments consisting of the item name, the
+buffer position, and @var{arguments}.
 
-For Emacs Lisp mode, @var{pattern} could look like this:
+For Emacs Lisp mode, @code{imenu-generic-expression} could look like
+this:
 
 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
 @example
@@ -1756,9 +1760,10 @@ Setting this variable makes it buffer-local in the current buffer.
 @end defvar
 
 @defvar imenu-case-fold-search
-This variable controls whether matching against
-@var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
-means matching should ignore case.
+This variable controls whether matching against the regular
+expressions in the value of @code{imenu-generic-expression} is
+case-sensitive: @code{t}, the default, means matching should ignore
+case.
 
 Setting this variable makes it buffer-local in the current buffer.
 @end defvar
@@ -1786,11 +1791,11 @@ For example, Fortran mode uses it this way:
 (setq imenu-syntax-alist '(("_$" . "w")))
 @end example
 
-The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
-instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this technique may be
-inconvenient when the mode needs to limit the initial character
-of a name to a smaller set of characters than are allowed in the rest
-of a name.
+The @code{imenu-generic-expression} regular expressions can then use
+@samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this
+technique may be inconvenient when the mode needs to limit the initial
+character of a name to a smaller set of characters than are allowed in
+the rest of a name.
 
 Setting this variable makes it buffer-local in the current buffer.
 @end defvar
@@ -1823,37 +1828,47 @@ Setting this variable makes it buffer-local in the current buffer.
 variable @code{imenu-create-index-function}:
 
 @defvar imenu-create-index-function
-This variable specifies the function to use for creating a buffer index.
-The function should take no arguments, and return an index for the
-current buffer.  It is called within @code{save-excursion}, so where it
-leaves point makes no difference.
+This variable specifies the function to use for creating a buffer
+index.  The function should take no arguments, and return an index
+alist for the current buffer.  It is called within
+@code{save-excursion}, so where it leaves point makes no difference.
 
-The default value is a function that uses
-@code{imenu-generic-expression} to produce the index alist.  If you
-specify a different function, then @code{imenu-generic-expression} is
-not used.
+The index alist can have three types of elements.  Simple elements
+look like this:
 
-Setting this variable makes it buffer-local in the current buffer.
-@end defvar
+@example
+(@var{index-name} . @var{index-position})
+@end example
+
+Selecting a simple element has the effect of moving to position
+@var{index-position} in the buffer.  Special elements look like this:
 
-@defvar imenu-index-alist
-This variable holds the index alist for the current buffer.
-Setting it makes it buffer-local in the current buffer.
+@example
+(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
+@end example
 
-Simple elements in the alist look like @code{(@var{index-name}
-. @var{index-position})}.  Selecting a simple element has the effect of
-moving to position @var{index-position} in the buffer.
+Selecting a special element performs:
+
+@example
+(funcall @var{function} 
+         @var{index-name} @var{index-position} @var{arguments}@dots{})
+@end example
 
-Special elements look like @code{(@var{index-name} @var{position}
-@var{function} @var{arguments}@dots{})}.  Selecting a special element
-performs
+A nested sub-alist element looks like this:
 
 @example
-(funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})
+(@var{index-name} @var{sub-alist})
 @end example
 
-A nested sub-alist element looks like @code{(@var{index-name}
-@var{sub-alist})}.
+It creates a submenu specified by @var{sub-alist}.
+
+The default value of @code{imenu-create-index-function} is a function
+that uses @code{imenu-prev-index-position-function} and
+@code{imenu-extract-index-name-function} to produce the index alist.
+However, if either of these two variables is @code{nil}, the default
+function uses @code{imenu-generic-expression} instead.
+
+Setting this variable makes it buffer-local in the current buffer.
 @end defvar
 
 @node Font Lock Mode