From c7143e7017b732e93d4074da970cd2ef45791362 Mon Sep 17 00:00:00 2001
From: Kaushal Modi <kaushal.modi@gmail.com>
Date: Mon, 27 Nov 2017 11:46:54 -0500
Subject: [PATCH] Update documentation about .dir-locals-2.el

* lisp/files.el: Remove unused constant `dir-locals-file-2'.
* lisp/files.el(dir-locals-file):
* doc/lispref/variables.texi (Directory Local Variables): Mention
  ".dir-locals-2.el".

(https://lists.gnu.org/r/emacs-devel/2017-11/msg00649.html)
---
 doc/lispref/variables.texi | 29 +++++++++++++++++------------
 etc/NEWS                   |  2 +-
 lisp/files.el              | 18 +++++++++---------
 3 files changed, 27 insertions(+), 22 deletions(-)

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index a871352b00..c14a440cbf 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1911,18 +1911,23 @@ Directory Local Variables
 @defvr Constant dir-locals-file
 This constant is the name of the file where Emacs expects to find the
 directory-local variables.  The name of the file is
-@file{.dir-locals.el}@footnote{
-The MS-DOS version of Emacs uses @file{_dir-locals.el} instead, due to
-limitations of the DOS filesystems.
-}.  A file by that name in a directory causes Emacs to apply its
-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
-specifies local variables as a specially formatted list; see
-@ref{Directory Variables, , Per-directory Local Variables, emacs, The
-GNU Emacs Manual}, for more details.
+@file{.dir-locals.el}@footnote{ The MS-DOS version of Emacs uses
+@file{_dir-locals.el} instead, due to limitations of the DOS
+filesystems.  }.  A file by that name in a directory causes Emacs to
+apply its 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.  This constant is also used to derive the name of a
+second dir-locals file @file{.dir-locals-2.el}.  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.
 @end defvr
 
 @defun hack-dir-local-variables
diff --git a/etc/NEWS b/etc/NEWS
index f7a9feb6e4..4ccf468693 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 d8b38a9f16..16fa4b8c52 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -3905,16 +3905,16 @@ dir-locals-file
   "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).  This second file name is
+derived by appending \"-2\" to the file name component without
+extension in `dir-locals-file'.  For example, if the value of
+`dir-locals-file' is \".dir-locals.el\", 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)
-- 
2.15.0

