Re: a property "definition-type" would help find macro-defined tests

[Stephen Gildea]

Eli Zaretskii <eliz@gnu.org> wrote:

>   The index entry should be only at the place of the main description of
>   the symbol property, if there is such a place.  Duplicate index
>   entries are not a good thing....

Okay, I understand the user experience you're trying to create.

I still find we need more index entries, but not as many as I thought.

Here's the latest version of the indexing updates.

The most notable change here is that I moved the index of
'interactive-form' from node "Interactive Call" to "Using
Interactive", which I thought gave a more detailed explanation.

 < Stephen

diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 24b4e892024..acd55fcbb81 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -535,6 +535,7 @@ Standard Properties
 Do not set them directly; they are managed by @code{defcustom} and
 related functions.  @xref{Variable Definitions}.
 
+@cindex @code{definition-name} (symbol property)
 @item definition-name
 This property is used to find the definition of a symbol in the source
 code, when it might be hard to find the definition by textual search
@@ -565,10 +566,27 @@ Standard Properties
 length for the named history list variable.  @xref{Minibuffer
 History}.
 
+@cindex @code{important-return-value} (symbol property)
+@item important-return-value
+A non-@code{nil} value makes the byte compiler warn about code that
+calls the named function without using its returned value.  This is
+useful for functions where doing so is likely to be a mistake.
+This property is normally added to a function with @code{declare}
+(@pxref{Declare Form}).
+
 @item interactive-form
 The value is an interactive form for the named function.  Normally,
 you should not set this directly; use the @code{interactive} special
-form instead.  @xref{Interactive Call}.
+form instead.  @xref{Using Interactive}.
+
+@item interactive-only
+If the value is non-@code{nil}, the named function should not be called
+from Lisp.  The value is an error string or the function to call
+instead.  @xref{Defining Commands}.
+
+@item menu-alias
+If non-nil, this symbol is an alias menu entry, and its own key binding
+should not be shown.  @xref{Alias Menu Items}.
 
 @item menu-enable
 The value is an expression for determining whether the named menu item
@@ -578,6 +596,11 @@ Standard Properties
 If the value is @code{special}, the named major mode is special.
 @xref{Major Mode Conventions}.
 
+@item ignored-mouse-command
+@itemx mouse-1-menu-command
+These properties affect how commands bound to @code{down-mouse-1} behave.
+@xref{Touchscreen Events}.
+
 @item permanent-local
 If the value is non-@code{nil}, the named variable is a buffer-local
 variable whose value should not be reset when changing major modes.
@@ -588,18 +611,20 @@ Standard Properties
 deleted from the local value of a hook variable when changing major
 modes.  @xref{Setting Hooks}.
 
+@cindex @code{pure} (symbol property)
 @item pure
-@cindex @code{pure} property
 If the value is non-@code{nil}, the named function is considered to be
 pure (@pxref{What Is a Function}).  Calls with constant arguments can
 be evaluated at compile time.  This may shift run time errors to
-compile time.  Not to be confused with pure storage (@pxref{Pure
-Storage}).
+compile time.  This property is normally added to a function with
+@code{declare} (@pxref{Declare Form}).  Not to be confused with pure
+storage (@pxref{Pure Storage}).
 
 @item risky-local-variable
 If the value is non-@code{nil}, the named variable is considered risky
 as a file-local variable.  @xref{File Local Variables}.
 
+@cindex @code{safe-function} (symbol property)
 @item safe-function
 If the value is non-@code{nil}, the named function is considered
 generally safe for evaluation.  @xref{Function Safety}.
@@ -610,25 +635,18 @@ Standard Properties
 
 @item safe-local-variable
 The value specifies a function for determining safe file-local values
-for the named variable.  @xref{File Local Variables}.  Since this
-value is consulted when loading files, the function should be
-efficient and should ideally not lead to loading any libraries to
-determine the safeness (e.g., it should not be an autoloaded function).
+for the named variable.  @xref{File Local Variables}.
 
+@cindex @code{side-effect-free} (symbol property)
 @item side-effect-free
-@cindex @code{side-effect-free} property
 A non-@code{nil} value indicates that the named function is free of
 side effects (@pxref{What Is a Function}), so the byte compiler may
 ignore a call whose value is unused.  If the property's value is
 @code{error-free}, the byte compiler may even delete such unused
 calls.  In addition to byte compiler optimizations, this property is
 also used for determining function safety (@pxref{Function Safety}).
-
-@item important-return-value
-@cindex @code{important-return-value} property
-A non-@code{nil} value makes the byte compiler warn about code that
-calls the named function without using its returned value.  This is
-useful for functions where doing so is likely to be a mistake.
+This property is normally added to a function with
+@code{declare} (@pxref{Declare Form}).
 
 @item undo-inhibit-region
 If non-@code{nil}, the named function prevents the @code{undo} operation
@@ -638,7 +656,7 @@ Standard Properties
 @item variable-documentation
 If non-@code{nil}, this specifies the named variable's documentation
 string.  This is set automatically by @code{defvar} and related
-functions.  @xref{Defining Faces}.
+functions.  @xref{Documentation Basics}.
 @end table
 
 @node Shorthands
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 7cc32a7fdb3..9fe8b4b9e21 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -122,14 +122,13 @@ Defining Commands
 be called interactively.  The argument of the @code{interactive} form
 specifies how the arguments for an interactive call should be read.
 
-@cindex @code{interactive-form} property
   Alternatively, an @code{interactive} form may be specified in a
 function symbol's @code{interactive-form} property.  A non-@code{nil}
 value for this property takes precedence over any @code{interactive}
 form in the function body itself.  This feature is seldom used.
 
 @anchor{The interactive-only property}
-@cindex @code{interactive-only} property
+@cindex @code{interactive-only} (symbol property)
   Sometimes, a function is only intended to be called interactively,
 never directly from Lisp.  In that case, give the function a
 non-@code{nil} @code{interactive-only} property, either directly
@@ -174,7 +173,7 @@ Using Interactive
 then the caller supplies the arguments and @var{arg-descriptor} has no
 effect.
 
-@cindex @code{interactive-form}, symbol property
+@cindex @code{interactive-form} (symbol property)
 The @code{interactive} form must be located at top-level in the
 function body, or in the function symbol's @code{interactive-form}
 property (@pxref{Symbol Properties}).  It has its effect because the
@@ -2124,7 +2123,7 @@ Touchscreen Events
 translation'', and produces a simple correspondence between touchpoint
 motion and mouse motion.
 
-@cindex @code{ignored-mouse-command}, a symbol property
+@cindex @code{ignored-mouse-command} (symbol property)
 However, some commands bound to
 @code{down-mouse-1}--@code{mouse-drag-region}, for example--either
 conflict with defined touch screen gestures (such as ``long-press to
@@ -2161,7 +2160,7 @@ Touchscreen Events
 @code{read-key} expecting to receive @code{mouse-movement} and
 @code{drag-mouse-1} events.
 
-@cindex @code{mouse-1-menu-command}, a symbol property
+@cindex @code{mouse-1-menu-command} (symbol property)
 Since certain commands are also bound to @code{down-mouse-1} for the
 purpose of displaying pop-up menus, Emacs additionally behaves as
 illustrated in the last paragraph if @code{down-mouse-1} is bound to a
@@ -4488,7 +4487,7 @@ Disabling Commands
 which might be confusing to beginning users, to prevent them from using
 the commands by accident.
 
-@kindex disabled
+@cindex @code{disabled} (symbol property)
   The low-level mechanism for disabling a command is to put a
 non-@code{nil} @code{disabled} property on the Lisp symbol for the
 command.  These properties are normally set up by the user's
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 0a4be71a215..738fb29b6f7 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -511,6 +511,10 @@ Variable Definitions
 options not yet defined.
 @end defun
 
+@cindex @code{customized-value} (symbol property)
+@cindex @code{saved-value} (symbol property)
+@cindex @code{standard-value} (symbol property)
+@cindex @code{theme-value} (symbol property)
 Internally, @code{defcustom} uses the symbol property
 @code{standard-value} to record the expression for the standard value,
 @code{saved-value} to record the value saved by the user with the
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 810a7f042fa..f39ab3e4d05 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -60,7 +60,7 @@ Documentation Basics
 @code{function-documentation} property of a function name
 (@pxref{Accessing Documentation}).
 
-@cindex @code{variable-documentation} property
+@cindex @code{variable-documentation} (symbol property)
   In a variable definition (a @code{defvar} form), the documentation
 string is specified after the initial value.  @xref{Defining
 Variables}.  The string is stored in the variable's
@@ -388,6 +388,7 @@ Keys in Documentation
 this face to the produced string.
 
 @cindex advertised binding
+@cindex @code{:advertised-binding} (symbol property)
 If a command has multiple bindings, this function normally uses the
 first one it finds.  You can specify one particular key binding by
 assigning an @code{:advertised-binding} symbol property to the
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 56fd330a84d..7095942d7b2 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -2473,6 +2473,7 @@ Simple Menu Items
   If @var{real-binding} is @code{nil}, then @var{item-string} appears in
 the menu but cannot be selected.
 
+@cindex @code{menu-enable} (symbol property)
   If @var{real-binding} is a symbol and has a non-@code{nil}
 @code{menu-enable} property, that property is an expression that
 controls whether the menu item is enabled.  Every time the keymap is
@@ -2716,6 +2717,7 @@ Alias Menu Items
 (put 'make-writable 'menu-enable 'buffer-read-only)
 @end example
 
+@cindex @code{menu-alias} (symbol property)
 When using aliases in menus, often it is useful to display the
 equivalent key bindings for the real command name, not the aliases
 (which typically don't have any key bindings except for the menu
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index d8e34da8584..d8e7e6c2e76 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -671,6 +671,7 @@ Minibuffer History
 this variable to your own function which adds only some candidates, or
 some other values, to the ``future history''.
 
+@cindex @code{history-length} (symbol property)
   Emacs functions that add a new element to a history list can also
 delete old elements if the list gets too long.  The variable
 @code{history-length} specifies the maximum length for most history
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 710be4cd730..7c532002670 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -183,6 +183,7 @@ Setting Hooks
 If @var{function} is already present in @var{hook} (comparing using
 @code{equal}), then @code{add-hook} does not add it a second time.
 
+@cindex @code{permanent-local-hook} (symbol property)
 If @var{function} has a non-@code{nil} property
 @code{permanent-local-hook}, then @code{kill-all-local-variables} (or
 changing major modes) won't delete it from the hook variable's local
@@ -565,6 +566,8 @@ Major Mode Conventions
 this mode to any other major mode, this mode can set up a buffer-local
 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
 
+@cindex @code{mode-class} (symbol property)
+@cindex @code{special} modes
 @item
 If this mode is appropriate only for specially-prepared text produced by
 the mode itself (rather than by the user typing at the keyboard or by an
@@ -572,8 +575,6 @@ Major Mode Conventions
 property named @code{mode-class} with value @code{special}, put on as
 follows:
 
-@kindex mode-class @r{(property)}
-@cindex @code{special} modes
 @example
 (put 'funny-mode 'mode-class 'special)
 @end example
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 283dd1c9610..5588d32c5e9 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -1629,6 +1629,7 @@ Char-Tables
 @code{syntax-table} as the subtype.  The subtype can be queried using
 the function @code{char-table-subtype}, described below.
 
+@cindex @code{char-table-extra-slots} (symbol property)
 @item
 The subtype controls the number of @dfn{extra slots} in the
 char-table.  This number is specified by the subtype's
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 5e072b8697b..2d24436d214 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -1524,6 +1524,7 @@ Undo
 execution of @var{body} so that it can be undone as a single step.
 @end defmac
 
+@cindex @code{undo-inhibit-region} (symbol property)
 Some commands leave the region active after execution in such a way that
 it interferes with selective undo of that command.  To make @code{undo}
 ignore the active region when invoked immediately after such a command,
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index fed72235801..a2bb1834477 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1774,6 +1774,7 @@ Creating Buffer-Local
 @end defvar
 
 @cindex permanent local variable
+@cindex @code{permanent-local} (symbol property)
 A buffer-local variable is @dfn{permanent} if the variable name (a
 symbol) has a @code{permanent-local} property that is non-@code{nil}.
 Such variables are unaffected by @code{kill-all-local-variables}, and
@@ -2051,7 +2052,7 @@ File Local Variables
 @end defvar
 
 @cindex safe local variable
-@cindex @code{safe-local-variable}, property of variable
+@cindex @code{safe-local-variable} (symbol property)
   You can specify safe values for a variable with a
 @code{safe-local-variable} property.  The property has to be a
 function of one argument; any value is safe if the function returns
@@ -2061,6 +2062,11 @@ File Local Variables
 For boolean-valued variables that are safe, use @code{booleanp} as the
 property value.
 
+  Since the value of @code{safe-local-variable} is consulted when
+loading files, the function should be efficient and should ideally not
+lead to loading any libraries to determine the safeness (e.g., it should
+not be an autoloaded function).
+
   If you want to define @code{safe-local-variable} properties for
 variables defined in C source code, add the names and the properties
 of those variables to the list in the ``Safe local variables'' section
@@ -2118,7 +2124,7 @@ File Local Variables
 the value @var{val}, based on the above criteria.
 @end defun
 
-@c @cindex risky local variable   Duplicates risky-local-variable
+@cindex @code{risky-local-variable} (symbol property)
   Some variables are considered @dfn{risky}.  If a variable is risky,
 it is never entered automatically into
 @code{safe-local-variable-values}; Emacs always queries before setting
@@ -2167,6 +2173,7 @@ File Local Variables
 local variables list.
 @end defopt
 
+@cindex @code{safe-local-eval-function} (symbol property)
   If the expression is a function call and the function has a
 @code{safe-local-eval-function} property, the property value
 determines whether the expression is safe to evaluate.  The property