4 files changed, 84 insertions, 66 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index 25909586102..6077deea9bb 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,23 @@
+2005-05-29  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * modes.texi (Major Mode Conventions): A derived mode only needs
+        to put the call to the parent mode inside `delay-mode-hooks'.
+
+2005-05-29  Richard M. Stallman  <rms@gnu.org>
+
+        * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook is
+        new, and what that implies.  Clarify.
+
+        * files.texi (Locating Files): Clean up the text.
+
+        * frames.texi (Window Frame Parameters): Document user-size.
+        Shorten entry for top by referring to left.
+
+2005-05-26  Richard M. Stallman  <rms@gnu.org>
+
+        * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook
+        is new, and what the implications are.  Other clarifications.
+
 2005-05-24  Richard M. Stallman  <rms@gnu.org>
 
         * frames.texi (Dialog Boxes): Minor fixes.
diff --git a/lispref/files.texi b/lispref/files.texi
index 25c4dfeb0d0..766220aa882 100644
--- a/lispref/files.texi
+++ b/lispref/files.texi
@@ -1261,36 +1261,36 @@ is on file system number -32252.
 @cindex locate files
 @cindex find files
 
-  Sometimes, you need to find a file that could reside in one of the
-standard directories.  One example is when you need to look for a
-program's executable file, e.g., to find out whether a given program
-is installed on the user's system.  Another example is the search for
+  This section explains how to search for a file in a list of
+directories.  One example is when you need to look for a program's
+executable file, e.g., to find out whether a given program is
+installed on the user's system.  Another example is the search for
 Lisp libraries (@pxref{Library Search}).  Such searches generally need
-to try several alternative file name extensions, in addition to
-looking in every standard directory where the file could be found.
-Emacs provides a function for such a generalized search for a file.
+to try various possible file name extensions, in addition to various
+possible directories.  Emacs provides a function for such a
+generalized search for a file.
 
 @defun locate-file filename path &optional suffixes predicate
-This function searches for the file whose name is @var{filename} in
-a list of directories given by @var{path}.  If it finds the file, it
-returns its full @dfn{absolute file name} (@pxref{Relative File
-Names}); if the file is not found, the function returns @code{nil}.
+This function searches for a file whose name is @var{filename} in a
+list of directories given by @var{path}, trying the suffixes in
+@var{suffixes}.  If it finds such a file, it returns the full
+@dfn{absolute file name} of the file (@pxref{Relative File Names});
+otherwise it returns @code{nil}.
 
 The optional argument @var{suffixes} gives the list of file-name
-suffixes to append to @var{filename} when searching.  If
-@var{suffixes} is @code{nil}, it's equivalent to passing a list with a
-single element that is an empty string @code{""}.
-
-Typical values of @var{path} are @code{exec-path} (@pxref{Subprocess
+suffixes to append to @var{filename} when searching.
+@code{locate-file} tries each possible directory with each of these
+suffixes.  If @var{suffixes} is @code{nil}, or @code{("")}, then there
+are no suffixes, and @var{filename} is used only as-is.  Typical
+values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
+Creation, exec-suffixes}) and @code{load-suffixes} (@pxref{Library
+Search, load-suffixes}).
+
+Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
 Creation, exec-path}) when looking for executable programs or
 @code{load-path} (@pxref{Library Search, load-path}) when looking for
-Lisp files.  Use @code{("/")} to disable the path search (e.g., if
-@var{filename} already includes the leading directories), but still
-try the extensions in @var{suffixes}.
-
-Typical values of @var{suffixes} are @code{exec-suffixes}
-(@pxref{Subprocess Creation, exec-suffixes}) and @code{load-suffixes}
-(@pxref{Library Search, load-suffixes}).
+Lisp files.  If @var{filename} is absolute, @var{path} has no effect,
+but the suffixes in @var{suffixes} are still tried.
 
 The optional argument @var{predicate}, if non-@code{nil}, specifies
 the predicate function to use for testing whether a candidate file is
@@ -1316,7 +1316,6 @@ in @code{exec-path} and tries all the file-name extensions in
 @code{exec-suffixes}.
 @end defun
 
-
 @node Changing Files
 @section Changing File Names and Attributes
 @cindex renaming files
diff --git a/lispref/frames.texi b/lispref/frames.texi
index 77694c87130..ffcc16f6289 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -362,20 +362,8 @@ non-@code{nil} value for the @code{user-position} parameter as well.
 
 @item top
 The screen position of the top edge, in pixels, with respect to the
-top edge of the screen.  The value may be a positive number @var{pos},
-or a list of the form @code{(+ @var{pos})} which permits specifying a
-negative @var{pos} value.
-
-A negative number @minus{}@var{pos}, or a list of the form @code{(-
-@var{pos})}, actually specifies the position of the bottom edge of the
-window with respect to the bottom edge of the screen.  A positive value
-of @var{pos} counts toward the top.  @strong{Reminder:} if the
-parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
-positive.
-
-Some window managers ignore program-specified positions.  If you want to
-be sure the position you specify is not ignored, specify a
-non-@code{nil} value for the @code{user-position} parameter as well.
+top edge of the screen.  It works just like @code{left}, except vertically
+instead of horizontally.
 
 @item icon-left
 The screen position of the left edge @emph{of the frame's icon}, in
@@ -418,6 +406,11 @@ pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
 The width of the frame contents, in characters.  (To get the height in
 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
 
+@item user-size
+This does for the size parameters @code{height} and @code{width} what
+the @code{user-position} parameter (see above) does for the position
+parameters @code{top} and @code{left}.
+
 @item fullscreen
 Specify that width, height or both shall be set to the size of the screen.
 The value @code{fullwidth} specifies that width shall be the size of the
diff --git a/lispref/modes.texi b/lispref/modes.texi
index 61bc878b581..f8c1ae82a4e 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -437,10 +437,8 @@ The major mode command may start by calling some other major mode
 command (called the @dfn{parent mode}) and then alter some of its
 settings.  A mode that does this is called a @dfn{derived mode}.  The
 recommended way to define one is to use @code{define-derived-mode},
-but this is not required.  Such a mode should use
-@code{delay-mode-hooks} around its entire body (including the call to
-the parent mode command) @emph{except} for the final call to
-@code{run-mode-hooks}, which runs the derived mode's hook.  (Using
+but this is not required.  Such a mode should call the parent mode
+command inside a @code{delay-mode-hooks} form.  (Using
 @code{define-derived-mode} does this automatically.)  @xref{Derived
 Modes}, and @ref{Mode Hooks}.
 
@@ -1117,7 +1115,7 @@ it runs the mode hook variable @code{@var{mode}-hook}.
 @node Mode Hooks
 @subsection Mode Hooks
 
-The two last things a major mode function does is to run its mode
+  The two last things a major mode function should do is run its mode
 hook and finally the mode independent normal hook
 @code{after-change-major-mode-hook}.  If the major mode is a derived
 mode, that is if it calls another major mode (the parent mode) in its
@@ -1125,45 +1123,53 @@ body, then the parent's mode hook is run just before the derived
 mode's hook.  Neither the parent's mode hook nor
 @code{after-change-major-mode-hook} are run at the end of the actual
 call to the parent mode.  This applies recursively if the parent mode
-has itself a parent.  That is, the mode hooks of all major modes called
-directly or indirectly by the major mode function are all run in
-sequence at the end, just before @code{after-change-major-mode-hook}.
-
-If you are customizing a major mode, rather than defining one, the
-above is all you need to know about the hooks run at the end of a
-major mode.  This also applies if you use @code{define-derived-mode}
-to define a major mode, because that macro will automatically
-implement the above for you.
-
-Programmers wishing to define a major mode without using
-@code{define-derived-mode}, should make sure that their major mode
-follows the above conventions.  @xref{Major Mode Conventions}, for how
-this should be accomplished.  Below, we give some implementation
-details.
+has itself a parent.  That is, the mode hooks of all major modes
+called directly or indirectly by the major mode function are all run
+in sequence at the end, just before
+@code{after-change-major-mode-hook}.
+
+  These conventions are new in Emacs 22, and some major modes
+implemented by users do not follow them yet.  So if you put a function
+onto @code{after-change-major-mode-hook}, keep in mind that some modes
+will fail to run it.  If a user complains about that, you can respond,
+``That major mode fails to follow Emacs conventions, and that's why it
+fails to work.  Please fix the major mode.''  In most cases, that is
+good enough, so go ahead and use @code{after-change-major-mode-hook}.
+However, if a certain feature needs to be completely reliable,
+it should not use @code{after-change-major-mode-hook} as of yet.
+
+  When you defined a major mode using @code{define-derived-mode}, it
+automatically makes sure these conventions are followed.  If you
+define a major mode ``from scratch'', not using
+@code{define-derived-mode}, make sure the major mode command follows
+these and other conventions.  @xref{Major Mode Conventions}.  You use
+these functions to do it properly.
 
 @defun run-mode-hooks &rest hookvars
 Major modes should run their mode hook using this function.  It is
-similar to @code{run-hooks} (@pxref{Hooks}), but if run inside a
-@code{delay-mode-hooks} form, this function does not run any hooks.
-Instead, it arranges for @var{hookvars} to be run at a later call to
-the function.  Otherwise, @code{run-mode-hooks} runs any delayed hooks
-in order, then @var{hookvars} and finally
+similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
 @code{after-change-major-mode-hook}.
+
+When the call to this function is dynamically inside a
+@code{delay-mode-hooks} form, this function does not run any hooks.
+Instead, it arranges for the next call to @code{run-mode-hooks} to run
+@var{hookvars}.
 @end defun
 
 @defmac delay-mode-hooks body...
 This macro executes @var{body} like @code{progn}, but all calls to
 @code{run-mode-hooks} inside @var{body} delay running their hooks.
 They will be run by the first call to @code{run-mode-hooks} after exit
-from @code{delay-mode-hooks}.
+from @code{delay-mode-hooks}.  This is the proper way for a major mode
+command to invoke its parent mode.
 @end defmac
 
 @defvar after-change-major-mode-hook
 Every major mode function should run this normal hook at its very end.
 It normally does not need to do so explicitly.  Indeed, a major mode
 function should normally run its mode hook with @code{run-mode-hooks}
-as the very last thing it does and @code{run-mode-hooks} runs
-@code{after-change-major-mode-hook} at its very end.
+as the very last thing it does, and the last thing
+@code{run-mode-hooks} does is run @code{after-change-major-mode-hook}.
 @end defvar
 
 @node Minor Modes