5 files changed, 75 insertions, 55 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index a374272135f..4825f08979f 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,14 @@
+2011-01-08  Chong Yidong  <cyd@stupidchicken.com>
+
+        * files.texi (File Aliases): Move directory-abbrev-alist doc from Lisp
+        manual.  Explain why directory-abbrev-alist elements should be anchored
+        (Bug#7777).
+
+2011-01-07  Eli Zaretskii  <eliz@gnu.org>
+
+        * msdog.texi (Windows Startup): Correct inaccurate description of
+        differences between emacsclient.exe and emacsclientw.exe.
+
 2010-12-30  Chong Yidong  <cyd@stupidchicken.com>
 
         * rmail.texi (Rmail Display): Edit for grammar and conciseness.
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
 
diff --git a/doc/emacs/msdog.texi b/doc/emacs/msdog.texi
index 514ef956dc3..caa1bbccd19 100644
--- a/doc/emacs/msdog.texi
+++ b/doc/emacs/msdog.texi
@@ -90,20 +90,24 @@ Via the Emacs client program, @file{emacsclient.exe} or
 programs, and to reuse a running Emacs process for serving editing
 jobs required by other programs.  @xref{Emacs Server}.  The difference
 between @file{emacsclient.exe} and @file{emacsclientw.exe} is that the
-former waits for Emacs to signal that the editing job is finished,
-while the latter does not wait.  Which one of them to use in each case
-depends on the expectations of the program that needs editing
-services.  If the program will use the edited files, it needs to wait
-for Emacs, so you should use @file{emacsclient.exe}.  By contrast, if
-the results of editing are not needed by the invoking program, you
-will be better off using @file{emacsclientw.exe}.  A notable situation
-where you would want @file{emacsclientw.exe} is when you right-click
-on a file in the Windows Explorer and select ``Open With'' from the
-pop-up menu.  Use the @samp{--alternate-editor=} or @samp{-a} options
-if Emacs might not be running (or not running as a server) when
-@command{emacsclient} is invoked---that will always give you an
-editor.  When invoked via @command{emacsclient}, Emacs will start in
-the current directory of the program that invoked
+former is a console program, while the latter is a Windows GUI
+program.  Both programs wait for Emacs to signal that the editing job
+is finished, before they exit and return control to the program that
+invoked them.  Which one of them to use in each case depends on the
+expectations of the program that needs editing services.  If that
+program is itself a console (text-mode) program, you should use
+@file{emacsclient.exe}, so that any of its messages and prompts appear
+in the same command window as those of the invoking program.  By
+contrast, if the invoking program is a GUI program, you will be better
+off using @file{emacsclientw.exe}, because @file{emacsclient.exe} will
+pop up a command window if it is invoked from a GUI program.  A
+notable situation where you would want @file{emacsclientw.exe} is when
+you right-click on a file in the Windows Explorer and select ``Open
+With'' from the pop-up menu.  Use the @samp{--alternate-editor=} or
+@samp{-a} options if Emacs might not be running (or not running as a
+server) when @command{emacsclient} is invoked---that will always give
+you an editor.  When invoked via @command{emacsclient}, Emacs will
+start in the current directory of the program that invoked
 @command{emacsclient}.
 @end enumerate
 
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 1cff2853a27..e1180124c05 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,13 @@
+2011-01-08  Chong Yidong  <cyd@stupidchicken.com>
+
+        * files.texi (Directory Names): Move directory-abbrev-alist doc to
+        Emacs manual.
+
+2011-01-07  Eli Zaretskii  <eliz@gnu.org>
+
+        * files.texi (Directory Names): Explain why FROM in
+        directory-abbrev-alist should begin with \`.  (Bug#7777)
+
 2010-12-25  Eli Zaretskii  <eliz@gnu.org>
 
         * modes.texi (Emulating Mode Line): Fix last change.
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index c2e057783c5..1f66da98347 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1920,51 +1920,22 @@ Don't try concatenating a slash by hand, as in
 because this is not portable.  Always use
 @code{file-name-as-directory}.
 
-@cindex directory name abbreviation
-  Directory name abbreviations are useful for directories that are
-normally accessed through symbolic links.  Sometimes the users recognize
-primarily the link's name as ``the name'' of the directory, and find it
-annoying to see the directory's ``real'' name.  If you define the link
-name as an abbreviation for the ``real'' name, Emacs shows users the
-abbreviation instead.
-
-@defopt directory-abbrev-alist
-The variable @code{directory-abbrev-alist} contains an alist of
-abbreviations to use for file directories.  Each element has the form
-@code{(@var{from} . @var{to})}, and says to replace @var{from} with
-@var{to} when it appears in a directory name.  The @var{from} string is
-actually a regular expression; it should always start with @samp{\`}.
-The @var{to} string should be an ordinary absolute directory name.  Do
-not use @samp{~} to stand for a home directory in that string.  The
-function @code{abbreviate-file-name} performs these substitutions.
-
-You can set this variable in @file{site-init.el} to describe the
-abbreviations appropriate for your site.
-
-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/gp" . "/gp")
- ("\\`/home/gd" . "/gd"))
-@end example
-@end defopt
-
   To convert a directory name to its abbreviation, use this
 function:
 
 @defun abbreviate-file-name filename
 @anchor{Definition of abbreviate-file-name}
-This function applies abbreviations from @code{directory-abbrev-alist}
-to its argument, and also substitutes @samp{~} for the user's home
-directory if the argument names a file in the home directory or one of
-its subdirectories.  (If the home directory is a root directory, it is
-not replaced with @samp{~}, because this does not make the result
-shorter on many systems.)  You can use it for directory names and for
-file names, because it recognizes abbreviations even as part of the
-name.
+This function returns an abbreviated form of @var{filename}.  It
+applies the abbreviations specified in @code{directory-abbrev-alist}
+(@pxref{File Aliases,,File Aliases, emacs, The GNU Emacs Manual}),
+then substitutes @samp{~} for the user's home directory if the
+argument names a file in the home directory or one of its
+subdirectories.  If the home directory is a root directory, it is not
+replaced with @samp{~}, because this does not make the result shorter
+on many systems.
+
+You can use this function for directory names and for file names,
+because it recognizes abbreviations even as part of the name.
 @end defun
 
 @node File Name Expansion