Improve documentation of directory-local variables

* lisp/files.el (hack-local-variables, normal-mode)
(after-find-file, find-file-hook): Mention directory-local
variables in the doc strings.  Suggested by Marcin Borkowski
<mbork@mbork.pl>.

* doc/emacs/custom.texi (File Variables, Directory Variables):
Clarify that directory-local variables are overridden by
file-local ones.

2 files changed, 16 insertions, 4 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 141fa045b63..b93009ad216 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1059,6 +1059,10 @@ local variable specifications; it automatically makes these variables
 local to the buffer, and sets them to the values specified in the
 file.
 
+  File local variables override directory local variables
+(@pxref{Directory Variables}), if any are specified for a file's
+directory.
+
 @menu
 * Specifying File Variables:: Specifying file local variables.
 * Safe File Variables::       Making sure file local variables are safe.
@@ -1309,7 +1313,12 @@ confirmation about processing @code{eval} variables.
   Sometimes, you may wish to define the same set of local variables to
 all the files in a certain directory and its subdirectories, such as
 the directory tree of a large software project.  This can be
-accomplished with @dfn{directory-local variables}.
+accomplished with @dfn{directory-local variables}.  File local
+variables override directory local variables, so if some of the files
+in a directory need specialized settings, you can specify the settings
+for the majority of the directory's files in directory variables, and
+then define file local variables in a few files which need the general
+settings overridden.
 
 @cindex @file{.dir-locals.el} file
   The usual way to define directory-local variables is to put a file
diff --git a/lisp/files.el b/lisp/files.el
index 4eb1560a20d..a3e72e2ce9c 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -493,7 +493,8 @@ The functions are called in the order given until one of them returns non-nil.")
 (defcustom find-file-hook nil
   "List of functions to be called after a buffer is loaded from a file.
 The buffer's local variables (if any) will have been processed before the
-functions are called."
+functions are called.  This includes directory-local variables, if any,
+for the file's directory."
   :group 'find-file
   :type 'hook
   :options '(auto-insert)
@@ -2369,7 +2370,7 @@ the file contents into it using `insert-file-contents-literally'."
                                   _after-find-file-from-revert-buffer
                                   nomodes)
   "Called after finding a file and by the default revert function.
-Sets buffer mode, parses local variables.
+Sets buffer mode, parses file-local and directory-local variables.
 Optional args ERROR, WARN, and NOAUTO: ERROR non-nil means there was an
 error in reading the file.  WARN non-nil means warn if there
 exists an auto-save file more recent than the visited file.
@@ -2454,7 +2455,7 @@ unless NOMODES is non-nil."
 
 (defun normal-mode (&optional find-file)
   "Choose the major mode for this buffer automatically.
-Also sets up any specified local variables of the file.
+Also sets up any specified local variables of the file or its directory.
 Uses the visited file name, the -*- line, and the local variables spec.
 
 This function is called automatically from `find-file'.  In that case,
@@ -3485,6 +3486,8 @@ DIR-NAME is the name of the associated directory.  Otherwise it is nil."
 
 (defun hack-local-variables (&optional handle-mode)
   "Parse and put into effect this buffer's local variables spec.
+For buffers visitying files, also puts into effect directory-local
+variables.
 Uses `hack-local-variables-apply' to apply the variables.
 
 If HANDLE-MODE is nil, we apply all the specified local