Make set-auto-mode respect mode: entries at the end of the file (bug#8586)

* lisp/files.el (set-auto-mode):
Also respect mode: entries at the end of the file.

* doc/lispref/modes.texi (Auto Major Mode):
Update for set-auto-mode changes.

* doc/emacs/custom.texi (Specifying File Variables):
Major modes no longer need come first.

* etc/NEWS: Mention this.

1 files changed, 8 insertions, 11 deletions

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 609c713194..29041151e5 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -583,12 +583,9 @@ 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 the default value of @code{major-mode}
-(see below).
+The function calls @code{set-auto-mode} to choose a major mode.  If it
+does not specify a mode, the buffer stays in the major mode determined
+by the default value of @code{major-mode} (see below).
 
 @cindex file mode specification error
 @code{normal-mode} uses @code{condition-case} around the call to the
@@ -600,15 +597,15 @@ mode specification error},  followed by the original error message.
 @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
+the @w{@samp{-*-}} line, on any @samp{mode:} local variable near the
+end of a file, 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.
+Major Modes are Chosen, emacs, The GNU Emacs Manual}. 
 If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
-does not check the @w{@samp{-*-}} line for a mode tag either.
+does not check the @w{@samp{-*-}} line, or near the end of the file,
+for any mode tag.
 
 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