From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Kaushal Modi Newsgroups: gmane.emacs.devel Subject: Re: Relics of removed dir-locals-file-2 feature in pretest Date: Mon, 27 Nov 2017 14:57:26 +0000 Message-ID: References: <833757cqy7.fsf@gnu.org> <83tvxmbat5.fsf@gnu.org> <83lgiyb801.fsf@gnu.org> <83d149at4o.fsf@gnu.org> <831skobvvw.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="94eb2c0309588be87a055ef81f70" X-Trace: blaine.gmane.org 1511794707 3270 195.159.176.226 (27 Nov 2017 14:58:27 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 27 Nov 2017 14:58:27 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Nov 27 15:58:22 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eJKrS-0000H2-M2 for ged-emacs-devel@m.gmane.org; Mon, 27 Nov 2017 15:58:19 +0100 Original-Received: from localhost ([::1]:33171 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eJKra-0002Gd-3r for ged-emacs-devel@m.gmane.org; Mon, 27 Nov 2017 09:58:26 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35634) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eJKqw-0002BL-7J for emacs-devel@gnu.org; Mon, 27 Nov 2017 09:57:47 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eJKqr-0004f5-Bz for emacs-devel@gnu.org; Mon, 27 Nov 2017 09:57:46 -0500 Original-Received: from mail-yw0-x231.google.com ([2607:f8b0:4002:c05::231]:43132) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eJKqp-0004cl-6o; Mon, 27 Nov 2017 09:57:39 -0500 Original-Received: by mail-yw0-x231.google.com with SMTP id s127so1765273ywb.10; Mon, 27 Nov 2017 06:57:38 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=OhuVrciMXq1D7g4ec8vjj3mGJJnFhQUsFr+oVb4MQws=; b=te8iEb/4K4/ooiFWHwvk5Ci+O5NTtxDeV7JRRAGUR5Nsee9DpZj7PL257UgCFuGceK S2uSDkSy53bpPSdF9pHXXdQCSOFv5bT/BmGn3rJK4ptxvDMpyO6Cb9VUTl1uiA7MzYUd AY9Aeqasn0E4UPmAoK2vOpbI+/aqF71Tc0h41wRhqTsq+kd4p9FXN9w0B988N5um9fqq 9+a+5hFVQZIV/j5mqfZ+m6iafLMUk7gFpXJSgZTybVQTIgPhS9BoR6fLhtZzvVOgr/eH qpT1a6u+/52iGoTqaHCtOaYV1BSnaDxFYCD8TUk6aB6YyBLPK1oH74bOxA3PdIxdAfWI lZDg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=OhuVrciMXq1D7g4ec8vjj3mGJJnFhQUsFr+oVb4MQws=; b=A6ADKcMNTlcgR2nkXCNpUijk3xF8FY01OGQhj60UsC/6yT/VUIkfZ8h+5en3D3Zqr/ x2R9XL5FIr6ZoDeJ5lrGTAh3DipoaxQkMAophfOYUd2NnMS/CwkO3z4HZdPPv4VLEkye zp4npU0s5Po5UPyEymTtJkU4IQBYAjO1ghRaVuqQOD8Um5xiGFfyKIETz5Xwc4zOgeU9 2XwRMqxe5imoscH25QzpAzAovvIz8hfRJKGawHwEO5k5tRmXDUksXipnErBrwoFAY6Ib fAxwIshV4v59RsGWtszCTUOTTXzPpCCm+COd95clfi4MBEs669j4X/dvPfAgSc8tdmli O7GQ== X-Gm-Message-State: AJaThX6/YQiTKtRrtEI/Ex1WbQhhQQvrB0y4Pm89z3vZ0fEFLb1oht9y Zg4C/H+X9GvP2yF7PeVReXcaPP+xN0MA3HZiVIM= X-Google-Smtp-Source: AGs4zMZUZe2OoCm7eo+TDaORRW4KAg5Qfk0SvlgyEwa5kZJpHMt/Qt3e2F52TcXjoVvfL0zJXUztCbuN6llbQ5l90Ww= X-Received: by 10.13.241.5 with SMTP id a5mr24137586ywf.427.1511794657714; Mon, 27 Nov 2017 06:57:37 -0800 (PST) In-Reply-To: <831skobvvw.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:4002:c05::231 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:220483 Archived-At: --94eb2c0309588be87a055ef81f70 Content-Type: text/plain; charset="UTF-8" On Thu, Nov 23, 2017 at 3:09 PM Eli Zaretskii 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 --94eb2c0309588be87a055ef81f70 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Thu, Nov 23= , 2017 at 3:09 PM Eli Zaretskii <eliz@gn= u.org> wrote:

Which part of it is incorrect?

Let'= s say a user reads the NEWS and finds:

> * A se= cond dir-local file (.dir-locals-2.el) is now accepted.
> See the var= iable 'dir-locals-file-2' for more information.

They do C-h v dir-locals-file-2 and read:

&g= t; This essentially a second file that can be used like `dir-locals-file= 9;, ..

That is incorrect! dir-locals-file-2 *canno= t* be used like `dir-locals-file'! That variable is just declared but n= ot used anywhere (why is it that only I think that that's a problem). A= user can

Reading further in that docstring:<= /div>

> See Info node `(elisp)Directory Local Variabl= es' 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.=C2=A0<= /div>

From your earlier email (I missed replying to this= part):

> We could remove the defconst, but jus= t removing it is not enough,
> because that would also remove its doc= string.=C2=A0

Why is that bad? That variable is a= nyways not used.. so what's the point of keeping docstring of an unused= variable.

> So we will have to do
&= gt;=20 something else in order to keep that special file name documented
>= =20 (e.g., so that "M-x apropos-documentation" would find it).=C2=A0 = I'm not
>=20 sure we should invest such an effort: after all, what's there does
&= gt;=20 work,

Why not just mention that a user can ju= st add "-2" to (file-name-sans-extension dir-locals-file), and th= at file can be used to override dir-locals-file. Mention that in the dir-lo= cals-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.<= /div>

And I am not just complaining, I am willing to pro= vide 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 t= hat is problem? Why would you want the 26.1 release to go out with this mis= documented feature? What am I missing?
--

Kaushal Modi

--94eb2c0309588be87a055ef81f70--