[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-29 0cb686ffb6: Document the 'definition-name' property.
From: |
Eli Zaretskii |
Subject: |
emacs-29 0cb686ffb6: Document the 'definition-name' property. |
Date: |
Sat, 7 Jan 2023 12:57:58 -0500 (EST) |
branch: emacs-29
commit 0cb686ffb6bbc017d3b71acbf40ed3e5c1a32863
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>
Document the 'definition-name' property.
* doc/lispref/symbols.texi (Standard Properties): Document
'definition-name'.
* doc/lispref/functions.texi (Defining Functions): Describe how to
use 'definition-name' when generating function definitions at run
time. (Bug#60568)
---
doc/lispref/functions.texi | 14 ++++++++++++++
doc/lispref/symbols.texi | 17 +++++++++++++++++
2 files changed, 31 insertions(+)
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 3a8eddb93e..f5572e447d 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -685,6 +685,20 @@ Here are some examples:
@end group
@end example
+@cindex defining functions dynamically
+Most Emacs functions are part of the source code of Lisp programs, and
+are defined when the Emacs Lisp reader reads the program source before
+executing it. However, you can also define functions dynamically at
+run time, e.g., by generating @code{defun} calls when your program's
+code is executed. If you do this, be aware that Emacs's Help
+commands, such as @kbd{C-h f}, which present in the @file{*Help*}
+buffer a button to jump to the function's definition, might be unable
+to find the source code because generating a function dynamically
+usually looks very different from the usual static calls to
+@code{defun}. You can make the job of finding the code which
+generates such functions easier by using the @code{definition-name}
+property, @pxref{Standard Properties}.
+
@cindex override existing functions
@cindex redefine existing functions
Be careful not to redefine existing functions unintentionally.
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 183367c0cd..5b53cbe310 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -555,6 +555,23 @@ 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}.
+@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
+of the source file. For example, a @code{define-derived-mode}
+(@pxref{Derived Modes}) might define a mode-specific function or a
+variable implicitly; or your Lisp program might generate a run-time
+call to @code{defun} to define a function (@pxref{Defining
+Functions}). In these and similar cases, the @code{definition-name}
+property of the symbol should be another symbol whose definition can
+be found by textual search and whose code defines the original symbol.
+In the example with @code{define-derived-mode}, the value of this
+property of the functions and variables it defines should be the mode
+symbol. The Emacs Help commands such as @kbd{C-h f} (@pxref{Help,,,
+emacs, The GNU Emacs Manual}) use this property to show the definition
+of a symbol via a button in the @file{*Help*} buffer where the
+symbol's documentation is shown.
+
@item disabled
If the value is non-@code{nil}, the named function is disabled as a
command. @xref{Disabling Commands}.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- emacs-29 0cb686ffb6: Document the 'definition-name' property.,
Eli Zaretskii <=