Subject: Re: bug#76912: 31.0.50; hack-local-variables docstring inaccurate about directory-local variables

From: Eli Zaretskii <[email-masked]>
Date: Tue, 11 Mar 2025 15:12:29 +0200

> From: Sean Whitton <[email-masked]>
> Cc: [email-masked]
> Date: Tue, 11 Mar 2025 14:36:07 +0800
> 
> > It would be good to document which directory is used for non-file
> > buffers, btw.
> 
> How's this -- targeting the emacs-30 branch.

Thanks, a few comments below.

> --- a/doc/lispref/modes.texi
> +++ b/doc/lispref/modes.texi
> @@ -546,7 +546,7 @@ Major Mode Conventions
>  @code{@var{modename}-mode-hook}.  The very last thing the major mode command
>  should do is to call @code{run-mode-hooks}.  This runs the normal
>  hook @code{change-major-mode-after-body-hook}, the mode hook, the
> -function @code{hack-local-variables} (when the buffer is visiting a file),
> +function @code{hack-local-variables},

This hunk doesn't seem to be correct.  From run-mode-hooks:

    (if (buffer-file-name)
        (with-demoted-errors "File local-variables error: %s"
          (hack-local-variables 'no-mode)))

> @@ -1124,10 +1124,9 @@ Mode Hooks
>  Major modes should run their mode hook using this function.  It is
>  similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
>  @code{change-major-mode-after-body-hook}, @code{hack-local-variables}
> -(when the buffer is visiting a file) (@pxref{File Local Variables}),
> -and @code{after-change-major-mode-hook}.  The last thing it does is to
> -evaluate any @code{:after-hook} forms declared by parent modes
> -(@pxref{Derived Modes}).
> +(@pxref{File Local Variables}), and @code{after-change-major-mode-hook}.
> +The last thing it does is to evaluate any @code{:after-hook} forms
> +declared by parent modes (@pxref{Derived Modes}).

Likewise here.

> --- a/doc/lispref/variables.texi
> +++ b/doc/lispref/variables.texi
> @@ -2014,14 +2014,20 @@ File Local Variables
>  @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}.

Please add here a cross-reference to "Directory Local Variables".

> +@defvar dir-local-variables-alist
> +This buffer-local variable holds the alist of directory-local variable
> +settings.  Its elements have the same structure as those of
> +@code{file-local-variables-alist}.  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.
> +@end defvar

Should this be in the next node, "Directory Local Variables", with
only a cross-reference to there in "File Local Variables"?

> --- a/lisp/files.el
> +++ b/lisp/files.el
> @@ -4163,8 +4163,9 @@ hack-local-variables--warned-lexical
>  
>  (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'.

I'd mention hack-dir-local-variables here.