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:
parent
615f06ea53
commit
c98d9e8bf5
10 changed files with 62 additions and 27 deletions
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Add table
Reference in a new issue