Lisp Reference Manual: Index standard symbol properties.

* doc/lispref/symbols.texi (Standard Properties):
* doc/lispref/commands.texi:
* doc/lispref/customize.texi (Variable Definitions):
* doc/lispref/help.texi:
* doc/lispref/keymaps.texi:
* doc/lispref/minibuf.texi (Minibuffer History):
* doc/lispref/modes.texi (Setting Hooks):
* doc/lispref/sequences.texi (Char-Tables):
* doc/lispref/text.texi (Undo):
* doc/lispref/variables.texi: Each standard symbol property has exactly
one index entry, uniformly formatted as "(symbol property)".
This commit is contained in:
Stephen Gildea 2025-01-12 20:13:08 -08:00
parent 615f06ea53
commit c98d9e8bf5
10 changed files with 62 additions and 27 deletions

View file

@ -122,14 +122,13 @@ serves as a flag, telling the Emacs command loop that the function can
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 @@ A command may be called from Lisp programs like any other function, but
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 @@ been intercepted by another program.) This is dubbed ``simple
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 @@ non-@code{nil} value, as, for example, it may be by a caller of
@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 @@ confirmation before it can be executed. Disabling is used for 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

View file

@ -511,6 +511,10 @@ previously, Lisp programs can use this function to add values for user
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

View file

@ -60,7 +60,7 @@ Documentation}. You can also put function documentation in the
@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 @@ argument @var{no-face} is non-@code{nil}, the function doesn't add
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

View file

@ -2473,6 +2473,7 @@ is on that item in the same way as @code{help-echo} text properties
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 @@ items. Here's an example that makes two aliases for
(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

View file

@ -671,6 +671,7 @@ function, this automatic addition is disabled, and you can also set
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

View file

@ -183,6 +183,7 @@ adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
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 @@ If something special should be done if the user switches a buffer from
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 @@ external file), then the major mode command symbol should have a
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

View file

@ -1629,6 +1629,7 @@ as the subtype, and syntax tables are char-tables with
@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

View file

@ -535,6 +535,7 @@ 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
@ -565,10 +566,27 @@ The value, if non-@code{nil}, specifies the maximum minibuffer history
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 @@ should be enabled in menus. @xref{Simple Menu Items}.
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 @@ 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}).
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 @@ file-local evaluation forms. @xref{File Local Variables}.
@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 @@ immediately after the function. @xref{Undo}.
@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

View file

@ -1524,6 +1524,7 @@ This macro removes all the undo boundaries inserted during the
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,

View file

@ -1774,6 +1774,7 @@ subsequent major mode. @xref{Hooks}.
@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 stored in @code{file-local-variables-alist}.
@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 @@ variables have @code{safe-local-variable} properties; these include
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 @@ This function returns non-@code{nil} if it is safe to give @var{sym}
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 @@ evaluate when found in the @samp{Eval:} ``variable'' in a file
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