Doc edits re uniquify

* doc/emacs/buffers.texi (Uniquify): Copyedits.

* doc/emacs/files.texi (Visiting): Update for uniquify changes.

* doc/lispref/files.texi (Subroutines of Visiting): Mention uniquify.

* doc/misc/vip.texi (Files): Defer to Emacs manual for uniquify details.

* lisp/bookmark.el (bookmark-load): Doc fix.

* lisp/uniquify.el (uniquify-buffer-name-style): Doc fix.

* lisp/files.el: Comment.

* etc/NEWS: Related edit.

7 files changed, 29 insertions, 22 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index f277526aea6..8f10c90dc07 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,5 +1,8 @@
 2014-06-08  Glenn Morris  <rgm@gnu.org>
 
+        * buffers.texi (Uniquify): Copyedits.
+        * files.texi (Visiting): Update for uniquify changes.
+
         * dired.texi (Marks vs Flags):
         * rmail.texi (Rmail Scrolling): Markup fixes re SPC.
 
diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index 89b56da7723..54a84989e2e 100644
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -608,20 +608,16 @@ convenient to switch between buffers.
 @cindex unique buffer names
 @cindex directories in buffer names
   When several buffers visit identically-named files, Emacs must give
-the buffers distinct names.  The default method
-(@code{uniquify-buffer-name-style} set to
-@code{post-forward-angle-brackets}) for making buffer names unique
-adds @samp{<dir1>}, @samp{<dir2>}, etc.@: to the end of the buffer
-names, where @file{dir1} and @file{dir2} are the minimal parts of the
-leading directories needed to make the buffer name unique.  For
-example, if you have files @file{/foo/bar/mumble/name} and
-@file{/baz/quux/mumble/name} visited, their buffers will be named
-@samp{name<bar/mumble>} and @samp{name<quux/mumble>} correspondingly.
+the buffers distinct names.  The default method adds a suffix based on
+the names of the directories that contain the files.  For example, if
+you visit files @file{/foo/bar/mumble/name} and
+@file{/baz/quux/mumble/name} at the same time, their buffers will be
+named @samp{name<bar/mumble>} and @samp{name<quux/mumble>}, respectively.
+Emacs adds as many directory parts as are needed to make a unique name.
 
 @vindex uniquify-buffer-name-style
-  There are several styles to make buffer names unique.  To select
-one, customize the variable @code{uniquify-buffer-name-style}
-(@pxref{Easy Customization}).
+  You can choose from several different styles for constructing unique
+buffer names, by customizing the option @code{uniquify-buffer-name-style}.
 
   The @code{forward} naming method includes part of the file's
 directory name at the beginning of the buffer name; using this method,
@@ -631,8 +627,8 @@ buffers visiting the files @file{/u/rms/tmp/Makefile} and
 
   In contrast, the @code{post-forward} naming method would call the
 buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}.  The default
-method @code{post-forward-angle-brackets} is like @code{post-forward}
-except that it prepends the unique path in angle brackets.  The
+method @code{post-forward-angle-brackets} is like @code{post-forward},
+except that it encloses the unique path in angle brackets.  The
 @code{reverse} naming method would call them @samp{Makefile\tmp} and
 @samp{Makefile\zaphod}.  The nontrivial difference between
 @code{post-forward} and @code{reverse} occurs when just one directory
@@ -641,8 +637,7 @@ the directory names in reverse order, so that @file{/top/middle/file}
 becomes @samp{file\middle\top}, while @code{post-forward} puts them in
 forward order after the file name, as in @samp{file|top/middle}.  If
 @code{uniquify-buffer-name-style} is set to @code{nil}, the buffer
-names simply get a @samp{<2>} etc. prepended.  This used to be the
-default behavior in Emacs versions up to 24.4.
+names simply get @samp{<2>}, @samp{<3>}, etc. appended.
 
   Which rule to follow for putting the directory names in the buffer
 name is not very important if you are going to @emph{look} at the
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 894e61d0f04..ee80c49af0b 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -171,9 +171,9 @@ the mode line (@pxref{Mode Line}).  Emacs normally constructs the
 buffer name from the file name, omitting the directory name.  For
 example, a file named @file{/usr/rms/emacs.tex} is visited in a buffer
 named @samp{emacs.tex}.  If there is already a buffer with that name,
-Emacs constructs a unique name; the normal method is to append
-@samp{<2>}, @samp{<3>}, and so on, but you can select other methods.
-@xref{Uniquify}.
+Emacs constructs a unique name; the normal method is to add a suffix
+based on the directory name (e.g., @samp{<rms>}, @samp{<tmp>},
+and so on), but you can select other methods.  @xref{Uniquify}.
 
 @cindex creating files
   To create a new file, just visit it using the same command, @kbd{C-x
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 1a4c9c3a57c..aa5589e1c16 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,7 @@
 2014-06-08  Glenn Morris  <rgm@gnu.org>
 
+        * files.texi (Subroutines of Visiting): Mention uniquify.
+
         * numbers.texi (Comparison of Numbers): Copyedits.
 
 2014-06-06  Glenn Morris  <rgm@gnu.org>
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 278b49e51e0..b071c6a8f35 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -254,11 +254,16 @@ is permanent local, so it is unaffected by changes of major modes.
 which are sometimes useful in user Lisp code: @code{create-file-buffer}
 and @code{after-find-file}.  This section explains how to use them.
 
+@c FIXME This does not describe the default behavior, because
+@c uniquify is enabled by default and advises this function.
+@c This is confusing.  uniquify should be folded into the function proper.
 @defun create-file-buffer filename
 This function creates a suitably named buffer for visiting
 @var{filename}, and returns it.  It uses @var{filename} (sans directory)
 as the name if that name is free; otherwise, it appends a string such as
 @samp{<2>} to get an unused name.  See also @ref{Creating Buffers}.
+Note that the @file{uniquify} library affects the result of this
+function.  @xref{Uniquify,,, emacs, The GNU Emacs Manual}.
 
 @strong{Please note:} @code{create-file-buffer} does @emph{not}
 associate the new buffer with a file and does not select the buffer.
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 6ddf4266db8..8e9eb83ca03 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,5 +1,7 @@
 2014-06-08  Glenn Morris  <rgm@gnu.org>
 
+        * vip.texi (Files): Defer to Emacs manual for uniquify details.
+
         * info.texi (Help-Small-Screen): Clarify details of S-SPC.
         (Help-Small-Screen, Help-]): Do not mention S-SPC.
         (Emacs Info Variables): Markup fix.
diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi
index 193d50f3a46..e11a5eb4c8b 100644
--- a/doc/misc/vip.texi
+++ b/doc/misc/vip.texi
@@ -895,9 +895,9 @@ just type @samp{vip.el} followed by @key{RET}.  If the file @file{vip.el}
 already exists in the directory, Emacs will visit that file, and if not,
 the file will be created.  Emacs will use the file name (@file{vip.el}, in
 this case) as the name of the buffer visiting the file.  In order to make
-the buffer name unique, Emacs may append @samp{<2>}, @samp{<3>} etc., to
-the buffer name.  As the @dfn{file name completion} is provided here, you
-can sometime save typing.  For instance, suppose there is only one file in the
+the buffer name unique, Emacs may add a suffix (@pxref{Uniquify,,,
+emacs, The GNU Emacs Manual}).  As @dfn{file name completion} is provided here, you
+can sometimes save typing.  For instance, suppose there is only one file in the
 default directory whose name starts with @samp{v}, that is @samp{vip.el}.
 Then if you just type @kbd{v @key{TAB}} then it will be completed to
 @samp{vip.el}.  Thus, in this case, you just have to type @kbd{v v @key{TAB}