From 7e984384a516082244e2ef0d2a27ad08bcaba1a3 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Tue, 11 Mar 2025 14:35:48 +0800
Subject: [PATCH] Correct some outdated docs for hack-local-variables

* doc/lispref/variables.texi (File Local Variables):
<hack-local-variables>: Say that it applies directory-local
variables too.  Add a cross-reference.
(Directory Local Variables): Document dir-local-variables-alist.
* lisp/files.el (hack-local-variables): Say that it always puts
into effect directory-local variables.

(cherry picked from commit 202910460538401ec585e9be80c05adb55279573)
---
 doc/lispref/variables.texi | 32 +++++++++++++++++++++++++-------
 lisp/files.el              |  8 +++++---
 2 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index daece2d3a79..75042237ab2 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -2015,14 +2015,21 @@ function does not look for the @samp{mode:} local variable in the
 @w{@samp{-*-}} line.  @code{set-auto-mode} does that, also taking
 @code{enable-local-variables} into account (@pxref{Auto Major Mode}).
 
-This function works by walking the alist stored in
-@code{file-local-variables-alist} and applying each local variable in
-turn.  It calls @code{before-hack-local-variables-hook} and
+This function also puts into effect directory-local variables as
+specified in @file{.dir-locals.el}.  If the buffer is not visiting any
+file, then the directory-local variables that apply are those which
+would be applicable to files in the @code{default-directory}
+(@pxref{Directory Local Variables}).
+
+This function works by walking the alists stored in
+@code{file-local-variables-alist} and @code{dir-local-variables-alist}
+and applying each local variable in turn.  It calls
+@code{before-hack-local-variables-hook} and
 @code{hack-local-variables-hook} before and after applying the
-variables, respectively.  It only calls the before-hook if the alist
-is non-@code{nil}; it always calls the other hook.  This
-function ignores a @samp{mode} element if it specifies the same major
-mode as the buffer already has.
+variables, respectively.  It only calls the before-hook if
+@code{file-local-variables-alist} is non-@code{nil}; it always calls the
+other hook.  This function ignores a @samp{mode} element if it specifies
+the same major mode as the buffer already has.
 
 If the optional argument @var{handle-mode} is @code{t}, then all this
 function does is return a symbol specifying the major mode, if the
@@ -2295,6 +2302,17 @@ modification times of the associated directory local variables file
 updates this list.
 @end defvar
 
+@defvar dir-local-variables-alist
+This buffer-local variable holds the alist of directory-local variable
+settings.  Each element of the alist is of the form @w{@code{(@var{var}
+. @var{value})}}, where @var{var} is a symbol of the local variable and
+@var{value} is its value (this is the same structure as that of
+@code{file-local-variables-alist}, @pxref{File Local Variables}).  When
+Emacs visits a file, it collects all the directory-local variables into
+this alist, and then the @code{hack-local-variables} function applies
+them one by one (again, @pxref{File Local Variables}).
+@end defvar
+
 @defvar hack-dir-local-get-variables-functions
 This special hook holds the functions that gather the directory-local
 variables to use for a given buffer.  By default it contains just the
diff --git a/lisp/files.el b/lisp/files.el
index bc8712fc920..ba4df859ac3 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -4248,10 +4248,12 @@ DIR-NAME is the name of the associated directory.  Otherwise it is nil."
 
 (defun hack-local-variables (&optional handle-mode inhibit-locals)
   "Parse and put into effect this buffer's local variables spec.
-For buffers visiting files, also puts into effect directory-local
-variables.
+Also puts into effect directory-local variables.
+For buffers not visiting files, apply the directory-local variables that
+would be applicable to files in `default-directory'.
 
-Uses `hack-local-variables-apply' to apply the variables.
+Uses `hack-local-variables-apply' and `hack-dir-local-variables'
+to apply the variables.
 
 If `enable-local-variables' or `local-enable-local-variables' is
 nil, or INHIBIT-LOCALS is non-nil, this function disregards all
-- 
2.39.5