Which part of it is incorrect?
Let's say a user reads the NEWS and finds:
> * A second dir-local file (.dir-locals-2.el) is now accepted.
> See the variable 'dir-locals-file-2' for more information.
They do C-h v dir-locals-file-2 and read:
> This essentially a second file that can be used like `dir-locals-file', ..
That is incorrect! dir-locals-file-2 *cannot* be used like `dir-locals-file'! That variable is just declared but not used anywhere (why is it that only I think that that's a problem). A user can
Reading further in that docstring:
> See Info node `(elisp)Directory Local Variables' for details.
That node has no reference to dir-locals-file-2 variable or a mention of the feature that .dir-locals-2.el can be used to override .dir-local.el.
Also in the doc-string of dir-locals-file:
> See also `dir-locals-file-2', whose values override this one's.
No, it *does not*! dir-locals-file-2 is not used in any code.
Thank you for volunteering, but I'm not yet sure we should do that.
Please consider making this change.
From your earlier email (I missed replying to this part):
> We could remove the defconst, but just removing it is not enough,
> because that would also remove its doc string.
Why is that bad? That variable is anyways not used.. so what's the point of keeping docstring of an unused variable.
> So we will have to do
>
something else in order to keep that special file name documented
>
(e.g., so that "M-x apropos-documentation" would find it). I'm not
>
sure we should invest such an effort: after all, what's there does
>
work,
Why not just mention that a user can just add "-2" to (file-name-sans-extension dir-locals-file), and that file can be used to override dir-locals-file. Mention that in the dir-locals-file docstring and the (elisp)Directory Local Variables node.
> so why fix that which ain't broken?
The documentation is broken. It is incorrect, misleading.
And I am not just complaining, I am willing to provide a patch that removes that defconst and updates the dir-local-file doc-string and the manual to make this feature better discoverable. So why is that is problem? Why would you want the 26.1 release to go out with this misdocumented feature? What am I missing?