From: Stephen Gildea Date: Mon, 13 Jan 2025 04:13:08 +0000 (-0800) Subject: Lisp Reference Manual: Index standard symbol properties. X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=3b3de5da3a854b25952951f222d284e796fad113;p=emacs.git 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)". (cherry picked from commit c98d9e8bf58c75e3ed6c7d2f9c5e63fc17bf9cf7) --- diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index b4d020b2425..b7f7035c1ad 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -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 @@ -2122,7 +2121,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 @@ -2159,7 +2158,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 @@ -4472,7 +4471,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 diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index b5a4c965fe9..09c05fa18c6 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -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 diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 89c1d15bc6f..3354094487d 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -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 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 @@ 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 diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 363ff40fb0c..aea6f330966 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -567,6 +567,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 diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index b7efe93c044..962a2b63d5d 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -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 diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index acbac1635fd..3745d7695dc 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -1626,6 +1626,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 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 @@ 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 diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 09b06aeca6e..cf76463c148 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1524,7 +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 -@vindex undo-inhibit-region +@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 @@ 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