emacs-27 524441d: Improve wording in the ELisp manual

[Eli Zaretskii]

branch: emacs-27
commit 524441d6b3f1da298a048862d330258eebca1118
Author: Richard Stallman <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve wording in the ELisp manual
    
    * doc/lispref/modes.texi (Setting Hooks): Improve and clarify
    wording.  (Bug#38818)
---
 doc/lispref/modes.texi | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 7354eb1..b52871e 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -135,13 +135,26 @@ non-@code{nil} value, it returns that value; otherwise it 
returns
 @node Setting Hooks
 @subsection Setting Hooks
 
-  Here's an example that uses a mode hook to turn on Auto Fill mode when
-in Lisp Interaction mode:
+  Here's an example that adds a funtion to a mode hook to turn
+on Auto Fill mode when in Lisp Interaction mode:
 
 @example
 (add-hook 'lisp-interaction-mode-hook 'auto-fill-mode)
 @end example
 
+  The value of a hook variable should be a list of functions.  You can
+manipulate that list using the normal Lisp facilities, but the modular
+way is to use the functions @code{add-hook} and @code{remove-hook},
+defined below.  They take care to handle some unusual situations and
+avoid problems.
+
+  It works to put a @code{lambda}-expression function on a hook, but
+we recommend avoiding this because it can lead to confusion.  If you
+add the same @code{lambda}-expression a second time but write it
+slightly differently, you will get two equivalent but distinct
+functions on the hook.  If you then remove one of them, the other will
+still be on it.
+
 @defun add-hook hook function &optional depth local
 This function is the handy way to add function @var{function} to hook
 variable @var{hook}.  You can use it for abnormal hooks as well as for