GNU bug report logs - #76912
31.0.50; hack-local-variables docstring inaccurate about directory-local variables

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 76912 in the body.
You can then email your comments to 76912 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: bug-gnu-emacs <at> gnu.org
Subject: 31.0.50; hack-local-variables docstring inaccurate about
 directory-local variables
Date: Mon, 10 Mar 2025 16:58:28 +0800

Hello,

We have:

    (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.

but this second sentence is wrong -- buffers not visiting files get
them, too.  For example

- emacs -Q
- C-x v d ~/src/emacs/trunk/ RET
- C-h v fill-column RET
=> local value of 72, from our .dir-locals.el, but VC-Dir is not a
   file-visiting buffer.

I think this is not a bug in the implementation and the docstring just
needs changing.  Would someone kindly confirm?

-- 
Sean Whitton

Message #8 received at 76912 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: 76912 <at> debbugs.gnu.org
Subject: Re: bug#76912: 31.0.50;
 hack-local-variables docstring inaccurate about directory-local
 variables
Date: Mon, 10 Mar 2025 18:51:53 +0200

> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Date: Mon, 10 Mar 2025 16:58:28 +0800
> 
> We have:
> 
>     (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.
> 
> but this second sentence is wrong -- buffers not visiting files get
> them, too.  For example
> 
> - emacs -Q
> - C-x v d ~/src/emacs/trunk/ RET
> - C-h v fill-column RET
> => local value of 72, from our .dir-locals.el, but VC-Dir is not a
>    file-visiting buffer.
> 
> I think this is not a bug in the implementation and the docstring just
> needs changing.  Would someone kindly confirm?

The code clearly calls hack-dir-local-variables, and has been doing so
since 2008, AFAICT.  As usual, we changed the code, but failed pt
update the doc string.

Note that the ELisp manual keeps silence about this aspect of
hack-local-variables.

It would be good to document which directory is used for non-file
buffers, btw.

Message #13 received at 76912 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76912 <at> debbugs.gnu.org
Subject: Re: bug#76912: 31.0.50; hack-local-variables docstring inaccurate
 about directory-local variables
Date: Tue, 11 Mar 2025 12:36:13 +0800

Hello,

On Mon 10 Mar 2025 at 06:51pm +02, Eli Zaretskii wrote:

> The code clearly calls hack-dir-local-variables, and has been doing so
> since 2008, AFAICT.  As usual, we changed the code, but failed pt
> update the doc string.
>
> Note that the ELisp manual keeps silence about this aspect of
> hack-local-variables.
>
> It would be good to document which directory is used for non-file
> buffers, btw.

Okay, thanks for confirming, I will fix the docstring and manual.

-- 
Sean Whitton

Message #16 received at 76912 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76912 <at> debbugs.gnu.org
Subject: Re: bug#76912: 31.0.50; hack-local-variables docstring inaccurate
 about directory-local variables
Date: Tue, 11 Mar 2025 14:36:07 +0800

[Message part 1 (text/plain, inline)]

Hello,

On Mon 10 Mar 2025 at 06:51pm +02, Eli Zaretskii wrote:

> The code clearly calls hack-dir-local-variables, and has been doing so
> since 2008, AFAICT.  As usual, we changed the code, but failed pt
> update the doc string.
>
> Note that the ELisp manual keeps silence about this aspect of
> hack-local-variables.
>
> It would be good to document which directory is used for non-file
> buffers, btw.

How's this -- targeting the emacs-30 branch.

-- 
Sean Whitton

[0001-Correct-some-outdated-docs-for-hack-local-variables.patch (text/x-diff, attachment)]

Message #19 received at 76912 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: 76912 <at> debbugs.gnu.org
Subject: Re: bug#76912: 31.0.50; hack-local-variables docstring inaccurate
 about directory-local variables
Date: Tue, 11 Mar 2025 15:12:29 +0200

> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Cc: 76912 <at> debbugs.gnu.org
> 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.

Message #24 received at 76912-done <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76912-done <at> debbugs.gnu.org
Subject: Re: bug#76912: 31.0.50; hack-local-variables docstring inaccurate
 about directory-local variables
Date: Wed, 12 Mar 2025 10:06:06 +0800

Hello,

On Tue 11 Mar 2025 at 03:12pm +02, Eli Zaretskii wrote:

>> From: Sean Whitton <spwhitton <at> spwhitton.name>
>> Cc: 76912 <at> debbugs.gnu.org
>> 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.

Thanks, changed all those and installed.

I'm very glad you checked the modes.texi changes.

-- 
Sean Whitton

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.