1 files changed, 25 insertions, 1 deletions

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 4df81caa8f2..530c2bb94f7 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1158,7 +1158,6 @@ links point to directories.
 
 @vindex find-file-existing-other-name
 @vindex find-file-suppress-same-file-warnings
-
   Normally, if you visit a file which Emacs is already visiting under
 a different name, Emacs displays a message in the echo area and uses
 the existing buffer visiting that file.  This can happen on systems
@@ -1180,6 +1179,31 @@ then the file name recorded for a buffer is the file's @dfn{truename}
 than the name you specify.  Setting @code{find-file-visit-truename} also
 implies the effect of @code{find-file-existing-other-name}.
 
+@cindex directory name abbreviation
+@vindex directory-abbrev-alist
+  Sometimes, a directory is ordinarily accessed through a symbolic
+link, and you may want Emacs to preferentially display its ``linked''
+name instead of its truename.  To do this, customize the variable
+@code{directory-abbrev-alist}.  Each element in this list should have
+the form @code{(@var{from} . @var{to})}, which says to replace
+@var{from} with @var{to} when it appears in a directory name.  For
+this feature to work properly, @var{from} and @var{to} should point to
+the same file.  The @var{from} string is actually a regular expression
+(@pxref{Regexps}); it should always start with @samp{\`}, to avoid
+matching to an incorrect part of the original directory name.  The
+@var{to} string should be an ordinary absolute directory name.  Do not
+use @samp{~} to stand for a home directory in the @var{to} string;
+Emacs performs these substitutions separately.
+
+  Here's an example, from a system on which file system
+@file{/home/fsf} and so on are normally accessed through symbolic
+links named @file{/fsf} and so on.
+
+@example
+(("\\`/home/fsf" . "/fsf")
+ ("\\`/home/gd" . "/gd"))
+@end example
+
 @node Directories
 @section File Directories