+@node Auto Major Mode
+@subsection How Emacs Chooses a Major Mode
+@cindex major mode, automatic selection
+
+ Based on information in the file name or in the file itself, Emacs
+automatically selects a major mode for the new buffer when a file is
+visited. It also processes local variables specified in the file text.
+
+@deffn Command fundamental-mode
+ Fundamental mode is a major mode that is not specialized for anything
+in particular. Other major modes are defined in effect by comparison
+with this one---their definitions say what to change, starting from
+Fundamental mode. The @code{fundamental-mode} function does @emph{not}
+run any mode hooks; you're not supposed to customize it. (If you want Emacs
+to behave differently in Fundamental mode, change the @emph{global}
+state of Emacs.)
+@end deffn
+
+@deffn Command normal-mode &optional find-file
+This function establishes the proper major mode and buffer-local variable
+bindings for the current buffer. First it calls @code{set-auto-mode}
+(see below), then it runs @code{hack-local-variables} to parse, and
+bind or evaluate as appropriate, the file's local variables
+(@pxref{File Local Variables}).
+
+If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
+@code{normal-mode} assumes that the @code{find-file} function is calling
+it. In this case, it may process local variables in the @samp{-*-}
+line or at the end of the file. The variable
+@code{enable-local-variables} controls whether to do so. @xref{File
+Variables, , Local Variables in Files, emacs, The GNU Emacs Manual},
+for the syntax of the local variables section of a file.
+
+If you run @code{normal-mode} interactively, the argument
+@var{find-file} is normally @code{nil}. In this case,
+@code{normal-mode} unconditionally processes any file local variables.
+
+If @code{normal-mode} processes the local variables list and this list
+specifies a major mode, that mode overrides any mode chosen by
+@code{set-auto-mode}. If neither @code{set-auto-mode} nor
+@code{hack-local-variables} specify a major mode, the buffer stays in
+the major mode determined by @code{default-major-mode} (see below).
+
+@cindex file mode specification error
+@code{normal-mode} uses @code{condition-case} around the call to the
+major mode function, so errors are caught and reported as a @samp{File
+mode specification error}, followed by the original error message.
+@end deffn
+
+@defun set-auto-mode &optional keep-mode-if-same
+@cindex visited file mode
+ This function selects the major mode that is appropriate for the
+current buffer. It bases its decision (in order of precedence) on
+the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using
+@code{interpreter-mode-alist}), on the text at the beginning of the
+buffer (using @code{magic-mode-alist}), and finally on the visited
+file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How
+Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this
+function does not look for the @samp{mode:} local variable near the
+end of a file; the @code{hack-local-variables} function does that.
+If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
+does not check the @w{@samp{-*-}} line for a mode tag either.
+
+If @var{keep-mode-if-same} is non-@code{nil}, this function does not
+call the mode command if the buffer is already in the proper major
+mode. For instance, @code{set-visited-file-name} sets this to
+@code{t} to avoid killing buffer local variables that the user may
+have set.
+@end defun
+
+@defopt default-major-mode
+This variable holds the default major mode for new buffers. The
+standard value is @code{fundamental-mode}.
+
+If the value of @code{default-major-mode} is @code{nil}, Emacs uses
+the (previously) current buffer's major mode as the default major mode
+of a new buffer. However, if that major mode symbol has a @code{mode-class}
+property with value @code{special}, then it is not used for new buffers;
+Fundamental mode is used instead. The modes that have this property are
+those such as Dired and Rmail that are useful only with text that has
+been specially prepared.
+@end defopt
+
+@defun set-buffer-major-mode buffer
+This function sets the major mode of @var{buffer} to the value of
+@code{default-major-mode}; if that variable is @code{nil}, it uses the
+current buffer's major mode (if that is suitable). As an exception,
+if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to
+@code{initial-major-mode}.
+
+The low-level primitives for creating buffers do not use this function,
+but medium-level commands such as @code{switch-to-buffer} and
+@code{find-file-noselect} use it whenever they create buffers.
+@end defun
+
+@defopt initial-major-mode
+@cindex @samp{*scratch*}
+The value of this variable determines the major mode of the initial
+@samp{*scratch*} buffer. The value should be a symbol that is a major
+mode command. The default value is @code{lisp-interaction-mode}.
+@end defopt
+
+@defvar interpreter-mode-alist
+This variable specifies major modes to use for scripts that specify a
+command interpreter in a @samp{#!} line. Its value is an alist with
+elements of the form @code{(@var{interpreter} . @var{mode})}; for
+example, @code{("perl" . perl-mode)} is one element present by
+default. The element says to use mode @var{mode} if the file
+specifies an interpreter which matches @var{interpreter}.
+@end defvar
+
+@defvar magic-mode-alist
+This variable's value is an alist with elements of the form
+@code{(@var{regexp} . @var{function})}, where @var{regexp} is a
+regular expression and @var{function} is a function or @code{nil}.
+After visiting a file, @code{set-auto-mode} calls @var{function} if
+the text at the beginning of the buffer matches @var{regexp} and
+@var{function} is non-@code{nil}; if @var{function} is @code{nil},
+@code{auto-mode-alist} gets to decide the mode.
+@end defvar
+
+@defvar file-start-mode-alist
+This works like @code{magic-mode-alist}, except that it is handled
+only if @code{auto-mode-alist} does not specify a mode for this file.
+@end defvar
+
+@defvar auto-mode-alist
+This variable contains an association list of file name patterns
+(regular expressions) and corresponding major mode commands. Usually,
+the file name patterns test for suffixes, such as @samp{.el} and
+@samp{.c}, but this need not be the case. An ordinary element of the
+alist looks like @code{(@var{regexp} . @var{mode-function})}.
+
+For example,
+
+@smallexample
+@group
+(("\\`/tmp/fol/" . text-mode)
+ ("\\.texinfo\\'" . texinfo-mode)
+ ("\\.texi\\'" . texinfo-mode)
+@end group
+@group
+ ("\\.el\\'" . emacs-lisp-mode)
+ ("\\.c\\'" . c-mode)
+ ("\\.h\\'" . c-mode)
+ @dots{})
+@end group
+@end smallexample
+
+When you visit a file whose expanded file name (@pxref{File Name
+Expansion}), with version numbers and backup suffixes removed using
+@code{file-name-sans-versions} (@pxref{File Name Components}), matches
+a @var{regexp}, @code{set-auto-mode} calls the corresponding
+@var{mode-function}. This feature enables Emacs to select the proper
+major mode for most files.
+
+If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
+@var{function} t)}, then after calling @var{function}, Emacs searches
+@code{auto-mode-alist} again for a match against the portion of the file
+name that did not match before. This feature is useful for
+uncompression packages: an entry of the form @code{("\\.gz\\'"
+@var{function} t)} can uncompress the file and then put the uncompressed
+file in the proper mode according to the name sans @samp{.gz}.
+
+Here is an example of how to prepend several pattern pairs to
+@code{auto-mode-alist}. (You might use this sort of expression in your
+init file.)
+
+@smallexample
+@group
+(setq auto-mode-alist
+ (append
+ ;; @r{File name (within directory) starts with a dot.}
+ '(("/\\.[^/]*\\'" . fundamental-mode)
+ ;; @r{File name has no dot.}
+ ("[^\\./]*\\'" . fundamental-mode)
+ ;; @r{File name ends in @samp{.C}.}
+ ("\\.C\\'" . c++-mode))
+ auto-mode-alist))
+@end group
+@end smallexample
+@end defvar
+
+@node Mode Help
+@subsection Getting Help about a Major Mode
+@cindex mode help
+@cindex help for major mode
+@cindex documentation for major mode
+
+ The @code{describe-mode} function is used to provide information
+about major modes. It is normally called with @kbd{C-h m}. The
+@code{describe-mode} function uses the value of @code{major-mode},
+which is why every major mode function needs to set the
+@code{major-mode} variable.
+
+@deffn Command describe-mode
+This function displays the documentation of the current major mode.
+
+The @code{describe-mode} function calls the @code{documentation}
+function using the value of @code{major-mode} as an argument. Thus, it
+displays the documentation string of the major mode function.
+(@xref{Accessing Documentation}.)
+@end deffn
+
+@defvar major-mode
+This buffer-local variable holds the symbol for the current buffer's
+major mode. This symbol should have a function definition that is the
+command to switch to that major mode. The @code{describe-mode}
+function uses the documentation string of the function as the
+documentation of the major mode.
+@end defvar
+
+@node Derived Modes
+@subsection Defining Derived Modes
+@cindex derived mode
+
+ It's often useful to define a new major mode in terms of an existing
+one. An easy way to do this is to use @code{define-derived-mode}.
+
+@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
+This construct defines @var{variant} as a major mode command, using
+@var{name} as the string form of the mode name. @var{variant} and
+@var{parent} should be unquoted symbols.
+
+The new command @var{variant} is defined to call the function
+@var{parent}, then override certain aspects of that parent mode:
+
+@itemize @bullet
+@item
+The new mode has its own sparse keymap, named
+@code{@var{variant}-map}. @code{define-derived-mode}
+makes the parent mode's keymap the parent of the new map, unless
+@code{@var{variant}-map} is already set and already has a parent.
+
+@item
+The new mode has its own syntax table, kept in the variable
+@code{@var{variant}-syntax-table}, unless you override this using the
+@code{:syntax-table} keyword (see below). @code{define-derived-mode}
+makes the parent mode's syntax-table the parent of
+@code{@var{variant}-syntax-table}, unless the latter is already set
+and already has a parent different from the standard syntax table.
+
+@item
+The new mode has its own abbrev table, kept in the variable
+@code{@var{variant}-abbrev-table}, unless you override this using the
+@code{:abbrev-table} keyword (see below).
+
+@item
+The new mode has its own mode hook, @code{@var{variant}-hook}. It
+runs this hook, after running the hooks of its ancestor modes, with
+@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
+@end itemize
+
+In addition, you can specify how to override other aspects of
+@var{parent} with @var{body}. The command @var{variant}
+evaluates the forms in @var{body} after setting up all its usual
+overrides, just before running the mode hooks.
+
+You can also specify @code{nil} for @var{parent}. This gives the new
+mode no parent. Then @code{define-derived-mode} behaves as described
+above, but, of course, omits all actions connected with @var{parent}.
+
+The argument @var{docstring} specifies the documentation string for
+the new mode. @code{define-derived-mode} adds some general
+information about the mode's hook, followed by the mode's keymap, at
+the end of this docstring. If you omit @var{docstring},
+@code{define-derived-mode} generates a documentation string.
+
+The @var{keyword-args} are pairs of keywords and values. The values
+are evaluated. The following keywords are currently supported:
+
+@table @code
+@item :syntax-table
+You can use this to explicitly specify a syntax table for the new
+mode. If you specify a @code{nil} value, the new mode uses the same
+syntax table as @var{parent}, or the standard syntax table if
+@var{parent} is @code{nil}. (Note that this does @emph{not} follow
+the convention used for non-keyword arguments that a @code{nil} value
+is equivalent with not specifying the argument.)
+
+@item :abbrev-table
+You can use this to explicitly specify an abbrev table for the new
+mode. If you specify a @code{nil} value, the new mode uses the same
+abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table}
+if @var{parent} is @code{nil}. (Again, a @code{nil} value is
+@emph{not} equivalent to not specifying this keyword.)
+
+@item :group
+If this is specified, the value should be the customization group for
+this mode. (Not all major modes have one.) Only the (still
+experimental and unadvertised) command @code{customize-mode} currently
+uses this. @code{define-derived-mode} does @emph{not} automatically
+define the specified customization group.
+@end table
+
+Here is a hypothetical example:
+
+@example
+(define-derived-mode hypertext-mode
+ text-mode "Hypertext"
+ "Major mode for hypertext.
+\\@{hypertext-mode-map@}"
+ (setq case-fold-search nil))
+
+(define-key hypertext-mode-map
+ [down-mouse-3] 'do-hyper-link)
+@end example
+
+Do not write an @code{interactive} spec in the definition;
+@code{define-derived-mode} does that automatically.
+@end defmac
+
+@node Generic Modes
+@subsection Generic Modes
+@cindex generic mode
+
+ @dfn{Generic modes} are simple major modes with basic support for
+comment syntax and Font Lock mode. To define a generic mode, use the
+macro @code{define-generic-mode}. See the file @file{generic-x.el}
+for some examples of the use of @code{define-generic-mode}.
+
+@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
+This macro defines a generic mode command named @var{mode} (a symbol,
+not quoted). The optional argument @var{docstring} is the
+documentation for the mode command. If you do not supply it,
+@code{define-generic-mode} generates one by default.
+
+The argument @var{comment-list} is a list in which each element is
+either a character, a string of one or two characters, or a cons cell.
+A character or a string is set up in the mode's syntax table as a
+``comment starter.'' If the entry is a cons cell, the @sc{car} is set
+up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
+(Use @code{nil} for the latter if you want comments to end at the end
+of the line.) Note that the syntax table mechanism has limitations
+about what comment starters and enders are actually possible.
+@xref{Syntax Tables}.
+
+The argument @var{keyword-list} is a list of keywords to highlight
+with @code{font-lock-keyword-face}. Each keyword should be a string.
+Meanwhile, @var{font-lock-list} is a list of additional expressions to
+highlight. Each element of this list should have the same form as an
+element of @code{font-lock-keywords}. @xref{Search-based
+Fontification}.
+
+The argument @var{auto-mode-list} is a list of regular expressions to
+add to the variable @code{auto-mode-alist}. They are added by the execution
+of the @code{define-generic-mode} form, not by expanding the macro call.
+
+Finally, @var{function-list} is a list of functions for the mode
+command to call for additional setup. It calls these functions just
+before it runs the mode hook variable @code{@var{mode}-hook}.
+@end defmac
+
+@node Mode Hooks
+@subsection Mode Hooks
+
+ Every major mode function should finish by running its mode hook and
+the mode-independent normal hook @code{after-change-major-mode-hook}.
+It does this by calling @code{run-mode-hooks}. If the major mode is a
+derived mode, that is if it calls another major mode (the parent mode)
+in its body, it should do this inside @code{delay-mode-hooks} so that
+the parent won't run these hooks itself. Instead, the derived mode's
+call to @code{run-mode-hooks} runs the parent's mode hook too.
+@xref{Major Mode Conventions}.
+
+ Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
+When user-implemented major modes have not been updated to use it,
+they won't entirely follow these conventions: they may run the
+parent's mode hook too early, or fail to run
+@code{after-change-major-mode-hook}. If you encounter such a major
+mode, please correct it to follow these conventions.
+
+ 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 ``by hand,'' not using @code{define-derived-mode},
+use the following functions to handle these conventions automatically.
+
+@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 it also runs
+@code{after-change-major-mode-hook}.
+
+When this function is called during the execution of a
+@code{delay-mode-hooks} form, it does not run the hooks immediately.
+Instead, it arranges for the next call to @code{run-mode-hooks} to run
+them.
+@end defun
+
+@defmac delay-mode-hooks body@dots{}
+When one major mode command calls another, it should do so inside of
+@code{delay-mode-hooks}.
+
+This macro executes @var{body}, but tells all @code{run-mode-hooks}
+calls during the execution of @var{body} to delay running their hooks.
+The hooks will actually run during the next call to
+@code{run-mode-hooks} after the end of the @code{delay-mode-hooks}
+construct.
+@end defmac
+
+@defvar after-change-major-mode-hook
+This is a normal hook run by @code{run-mode-hooks}. It is run at the
+very end of every properly-written major mode function.
+@end defvar
+