Re: Relics of removed dir-locals-file-2 feature in pretest

[Kaushal Modi <kaushal.modi@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2336 bytes --]

On Thu, Nov 23, 2017 at 3:09 PM Eli Zaretskii <eliz@gnu.org> wrote:

>
> 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?
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 3501 bytes --]