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

[Stephen Gildea]

Eli Zaretskii <eliz@gnu.org> wrote:

>   Thanks.  A few remaining nits below.
>   ...

I will fix these items and commit the result.

But first ...

>   I think all these index entries should use "symbol property" instead
>   of the more general "property", to distinguish them from other kinds
>   of properties we have in Emacs.

Some of these symbol properties are missing index entries at
the point of their main discussion, or they have an entry with
a different format.  Adding or changing index entries in the
list of standard properties then creates a separate index
entry, bloating the index and making it more confusing to use.
I also discovered some symbol properties that were missing an
entry in this list.

I took it on myself to fix these discrepancies.

This is getting to be a bigger change, so I want to make it a
separate commit.  Here is what it looks like.

 < Stephen

diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 24b4e892024..5d5804179d3 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -509,32 +509,43 @@ Standard Properties
 symbol; similarly for ``the named variable'' etc.
 
 @table @code
+@cindex @code{:advertised-binding} (symbol property)
 @item :advertised-binding
 This property value specifies the preferred key binding, when showing
 documentation, for the named function.  @xref{Keys in Documentation}.
 
+@cindex @code{char-table-extra-slots} (symbol property)
 @item char-table-extra-slots
 The value, if non-@code{nil}, specifies the number of extra slots in
 the named char-table type.  @xref{Char-Tables}.
 
+@cindex @code{customized-face} (face symbol property)
 @item customized-face
+@cindex @code{face-defface-spec} (face symbol property)
 @itemx face-defface-spec
+@cindex @code{saved-face} (face symbol property)
 @itemx saved-face
+@cindex @code{theme-face} (face symbol property)
 @itemx theme-face
 These properties are used to record a face's standard, saved,
 customized, and themed face specs.  Do not set them directly; they are
 managed by @code{defface} and related functions.  @xref{Defining
 Faces}.
 
+@cindex @code{customized-value} (symbol property)
 @item customized-value
+@cindex @code{saved-value} (symbol property)
 @itemx saved-value
+@cindex @code{standard-value} (symbol property)
 @itemx standard-value
+@cindex @code{theme-value} (symbol property)
 @itemx theme-value
 These properties are used to record a customizable variable's standard
 value, saved value, customized-but-unsaved value, and themed values.
 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
@@ -552,62 +563,92 @@ Standard Properties
 of a symbol via a button in the @file{*Help*} buffer where the
 symbol's documentation is shown.
 
+@cindex @code{disabled} (symbol property)
 @item disabled
 If the value is non-@code{nil}, the named function is disabled as a
 command.  @xref{Disabling Commands}.
 
+@cindex @code{face-documentation} (face symbol property)
 @item face-documentation
 The value stores the documentation string of the named face.  This is
 set automatically by @code{defface}.  @xref{Defining Faces}.
 
+@cindex @code{history-length} (symbol property)
 @item history-length
 The value, if non-@code{nil}, specifies the maximum minibuffer history
 length for the named history list variable.  @xref{Minibuffer
 History}.
 
+@cindex @code{interactive-form} (symbol property)
 @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}.
 
+@cindex @code{interactive-only} (symbol property)
+@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}.
+
+@cindex @code{menu-alias} (symbol property)
+@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}.
+
+@cindex @code{menu-enable} (symbol property)
 @item menu-enable
 The value is an expression for determining whether the named menu item
 should be enabled in menus.  @xref{Simple Menu Items}.
 
+@cindex @code{mode-class} (symbol property)
 @item mode-class
 If the value is @code{special}, the named major mode is special.
 @xref{Major Mode Conventions}.
 
+@cindex @code{ignored-mouse-command} (symbol property)
+@item ignored-mouse-command
+@cindex @code{mouse-1-menu-command} (symbol property)
+@itemx mouse-1-menu-command
+These properties affect how commands bound to @code{down-mouse-1} behave.
+@xref{Touchscreen Events}.
+
+@cindex @code{permanent-local} (symbol property)
 @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.
 @xref{Creating Buffer-Local}.
 
+@cindex @code{permanent-local-hook} (symbol property)
 @item permanent-local-hook
 If the value is non-@code{nil}, the named function should not be
 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}).
 
+@cindex @code{risky-local-variable} (symbol property)
 @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}.
 
+@cindex @code{safe-local-eval-function} (symbol property)
 @item safe-local-eval-function
 If the value is non-@code{nil}, the named function is safe to call in
 file-local evaluation forms.  @xref{File Local Variables}.
 
+@cindex @code{safe-local-variable} (symbol property)
 @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
@@ -615,8 +656,8 @@ Standard Properties
 efficient and should ideally not lead to loading any libraries to
 determine the safeness (e.g., it should not be an autoloaded function).
 
+@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
@@ -624,21 +665,25 @@ Standard Properties
 calls.  In addition to byte compiler optimizations, this property is
 also used for determining function safety (@pxref{Function Safety}).
 
+@cindex @code{important-return-value} (symbol property)
 @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}).
 
+@cindex @code{undo-inhibit-region} (symbol property)
 @item undo-inhibit-region
 If non-@code{nil}, the named function prevents the @code{undo} operation
 from being restricted to the active region, if @code{undo} is invoked
 immediately after the function.  @xref{Undo}.
 
+@cindex @code{variable-documentation} (symbol property)
 @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..1d77c641362 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -122,14 +122,14 @@ 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
+@cindex @code{interactive-form} (symbol 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 +174,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
@@ -802,6 +802,7 @@ Interactive Call
 This function returns @code{t} if @var{object} is a command.
 Otherwise, it returns @code{nil}.
 
+@cindex @code{interactive-form} (symbol property)
 Commands include strings and vectors (which are treated as keyboard
 macros), lambda expressions that contain a top-level
 @code{interactive} form (@pxref{Using Interactive}), byte-code
@@ -2124,7 +2125,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 +2162,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 +4489,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/functions.texi b/doc/lispref/functions.texi
index c659ecaf3f8..50d605f52a1 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2695,17 +2695,20 @@ Declare Form
 Specify the arguments that should be stored for @code{repeat-command}.
 Each @var{arg} is on the form @code{@var{argument-name} @var{form}}.
 
+@cindex @code{pure} (symbol property)
 @item (pure @var{val})
 If @var{val} is non-@code{nil}, this function is @dfn{pure}
 (@pxref{What Is a Function}).  This is the same as the @code{pure}
 property of the function's symbol (@pxref{Standard Properties}).
 
+@cindex @code{side-effect-free} (symbol property)
 @item (side-effect-free @var{val})
 If @var{val} is non-@code{nil}, this function is free of side effects,
 so the byte compiler can ignore calls whose value is ignored.  This is
 the same as the @code{side-effect-free} property of the function's
 symbol, @pxref{Standard Properties}.
 
+@cindex @code{important-return-value} (symbol property)
 @item (important-return-value @var{val})
 If @var{val} is non-@code{nil}, the byte compiler will warn about
 calls to this function that do not use the returned value.  This is 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..394271a23cc 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
@@ -2204,6 +2205,7 @@ Mode Line Data
 There is one exception: if the value of @var{symbol} is a string, it is
 displayed verbatim: the @code{%}-constructs are not recognized.
 
+@cindex @code{risky-local-variable} (symbol property)
 Unless @var{symbol} is marked as risky (i.e., it has a
 non-@code{nil} @code{risky-local-variable} property), all text
 properties specified in @var{symbol}'s value are ignored.  This includes
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..56ef90bb55f 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1735,6 +1735,7 @@ Creating Buffer-Local
 @end deffn
 
 @cindex local variables, killed by major mode
+@cindex @code{permanent-local-hook} (symbol property)
 @defun kill-all-local-variables &optional kill-permanent
 This function eliminates all the buffer-local variable bindings of the
 current buffer.  As a result, the buffer will see the default values
@@ -1774,6 +1775,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 +2053,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
@@ -2118,7 +2120,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 +2169,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