[Emacs-diffs] emacs-26 0540df1: Update documentation of '.dir-locals-2.el'

[Eli Zaretskii]

branch: emacs-26
commit 0540df10e63ba624a775cfe1bba4124456591cf5
Author: Kaushal Modi <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Update documentation of '.dir-locals-2.el'
    
    See https://lists.gnu.org/r/emacs-devel/2017-11/msg00649.html
    for more details.
    * lisp/files.el (dir-locals-file-2): Remove unused constant.
    * lisp/files.el (dir-locals-file): Mention ".dir-locals-2.el" in
    the doc string.
    * doc/lispref/variables.texi (Directory Local Variables): Mention
    ".dir-locals-2.el".
    * etc/NEWS: Replace `dir-locals-file-2' mention with
    `dir-locals-file'.
---
 doc/lispref/variables.texi |  7 ++++++-
 etc/NEWS                   |  2 +-
 lisp/files.el              | 18 +++++++++---------
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index a871352..5bee0f9 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1919,7 +1919,12 @@ settings to any file in that directory or any of its 
subdirectories
 (optionally, you can exclude subdirectories; see below).
 If some of the subdirectories have their own @file{.dir-locals.el}
 files, Emacs uses the settings from the deepest file it finds starting
-from the file's directory and moving up the directory tree.  The file
+from the file's directory and moving up the directory tree.  This
+constant is also used to derive the name of a second dir-locals file
address@hidden  If this second dir-locals file is present,
+then that is loaded instead of @file{.dir-locals.el}.  This is useful
+when @file{.dir-locals.el} is under version control in a shared
+repository and cannot be used for personal customizations.  The file
 specifies local variables as a specially formatted list; see
 @ref{Directory Variables, , Per-directory Local Variables, emacs, The
 GNU Emacs Manual}, for more details.
diff --git a/etc/NEWS b/etc/NEWS
index f7a9feb..4ccf468 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -366,7 +366,7 @@ These local variables will thus not vanish on setting a 
major mode.
 
 +++
 ** A second dir-local file (.dir-locals-2.el) is now accepted.
-See the variable 'dir-locals-file-2' for more information.
+See the doc string of 'dir-locals-file' for more information.
 
 +++
 ** Connection-local variables can be used to specify local variables
diff --git a/lisp/files.el b/lisp/files.el
index d8b38a9..8021e1b 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -3905,16 +3905,16 @@ VARIABLES list of the class.  The list is processed in 
order.
   "File that contains directory-local variables.
 It has to be constant to enforce uniform values across different
 environments and users.
-See also `dir-locals-file-2', whose values override this one's.
-See Info node `(elisp)Directory Local Variables' for details.")
 
-(defconst dir-locals-file-2 ".dir-locals-2.el"
-  "File that contains directory-local variables.
-This essentially a second file that can be used like
-`dir-locals-file', so that users can have specify their personal
-dir-local variables even if the current directory already has a
-`dir-locals-file' that is shared with other users (such as in a
-git repository).
+A second dir-locals file can be used by a user to specify their
+personal dir-local variables even if the current directory
+already has a `dir-locals-file' that is shared with other
+users (such as in a git repository).  The name of this second
+file is derived by appending \"-2\" to the base name of
+`dir-locals-file'.  With the default value of `dir-locals-file',
+a \".dir-locals-2.el\" file in the same directory will override
+the \".dir-locals.el\".
+
 See Info node `(elisp)Directory Local Variables' for details.")
 
 (defun dir-locals--all-files (directory)