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}.
@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
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
resulting syntax table is stored in @code{font-lock-syntax-table}.
The fifth element, @var{syntax-begin}, specifies the value of
-@code{font-lock-beginning-of-syntax-function}.
+@code{font-lock-beginning-of-syntax-function}. We recommend setting
+this variable to @code{nil} and using @code{syntax-begin-function}
+instead.
All the remaining elements (if any) are collectively called
@var{other-vars}. Each of these elements should have the form
@code{font-lock-defaults}.
@end defvar
-@c ???
-@c The docstring says that font-lock-syntax-table is semi-obsolete.
-@c How the alternative should be used is not clear. --lute
-
@defvar font-lock-beginning-of-syntax-function
If this variable is non-@code{nil}, it should be a function to move
point back to a position that is syntactically at ``top level'' and
be outside a syntactic block), or @code{beginning-of-defun} for
programming modes, or @code{backward-paragraph} for textual modes.
-If the value is @code{nil}, the beginning of the buffer is used as a
-position outside of a syntactic block. This cannot be wrong, but it
-can be slow.
+If the value is @code{nil}, Font Lock uses
+@code{syntax-begin-function} to move back outside of any comment,
+string, or sexp. This variable is semi-obsolete; we recommend setting
+@code{syntax-begin-function} instead.
Specify this variable using @var{syntax-begin} in
@code{font-lock-defaults}.