[Emacs-diffs] emacs-24 r117227: Doc edits re uniquify

[Glenn Morris]

------------------------------------------------------------
revno: 117227
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Sun 2014-06-08 00:41:27 -0700
message:
  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.
modified:
  doc/emacs/ChangeLog            changelog-20091113204419-o5vbwnq5f7feedwu-6227
  doc/emacs/buffers.texi         
buffers.texi-20091113204419-o5vbwnq5f7feedwu-6234
  doc/emacs/files.texi           files.texi-20091113204419-o5vbwnq5f7feedwu-6249
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/files.texi         files.texi-20091113204419-o5vbwnq5f7feedwu-6179
  doc/misc/ChangeLog             changelog-20091113204419-o5vbwnq5f7feedwu-6331
  doc/misc/vip.texi              vip.texi-20091113204419-o5vbwnq5f7feedwu-6327
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/bookmark.el               bookmark.el-20091113204419-o5vbwnq5f7feedwu-621
  lisp/files.el                  files.el-20091113204419-o5vbwnq5f7feedwu-265
  lisp/uniquify.el               uniquify.el-20091113204419-o5vbwnq5f7feedwu-956

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2014-06-08 06:57:15 +0000
+++ b/doc/emacs/ChangeLog       2014-06-08 07:41:27 +0000
@@ -1,5 +1,8 @@
 2014-06-08  Glenn Morris  <address@hidden>
 
+       * buffers.texi (Uniquify): Copyedits.
+       * files.texi (Visiting): Update for uniquify changes.
+
        * dired.texi (Marks vs Flags):
        * rmail.texi (Rmail Scrolling): Markup fixes re SPC.
 

=== modified file 'doc/emacs/buffers.texi'
--- a/doc/emacs/buffers.texi    2014-04-29 15:17:02 +0000
+++ b/doc/emacs/buffers.texi    2014-06-08 07:41:27 +0000
@@ -608,20 +608,16 @@
 @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
address@hidden) 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
address@hidden/baz/quux/mumble/name} visited, their buffers will be named
address@hidden<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
address@hidden/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 @@
 
   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 @@
 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

=== modified file 'doc/emacs/files.texi'
--- a/doc/emacs/files.texi      2014-04-29 14:45:24 +0000
+++ b/doc/emacs/files.texi      2014-06-08 07:41:27 +0000
@@ -171,9 +171,9 @@
 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
address@hidden<2>}, @samp{<3>}, and so on, but you can select other methods.
address@hidden
+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

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-06-08 00:51:10 +0000
+++ b/doc/lispref/ChangeLog     2014-06-08 07:41:27 +0000
@@ -1,5 +1,7 @@
 2014-06-08  Glenn Morris  <address@hidden>
 
+       * files.texi (Subroutines of Visiting): Mention uniquify.
+
        * numbers.texi (Comparison of Numbers): Copyedits.
 
 2014-06-06  Glenn Morris  <address@hidden>

=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi    2014-03-25 16:08:45 +0000
+++ b/doc/lispref/files.texi    2014-06-08 07:41:27 +0000
@@ -254,11 +254,16 @@
 which are sometimes useful in user Lisp code: @code{create-file-buffer}
 and @code{after-find-file}.  This section explains how to use them.
 
address@hidden FIXME This does not describe the default behavior, because
address@hidden uniquify is enabled by default and advises this function.
address@hidden 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.

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2014-06-08 07:00:20 +0000
+++ b/doc/misc/ChangeLog        2014-06-08 07:41:27 +0000
@@ -1,5 +1,7 @@
 2014-06-08  Glenn Morris  <address@hidden>
 
+       * 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.

=== modified file 'doc/misc/vip.texi'
--- a/doc/misc/vip.texi 2014-05-07 17:34:53 +0000
+++ b/doc/misc/vip.texi 2014-06-08 07:41:27 +0000
@@ -895,9 +895,9 @@
 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}

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-06-06 06:45:16 +0000
+++ b/etc/NEWS  2014-06-08 07:41:27 +0000
@@ -402,6 +402,10 @@
 
 +++
 ** Uniquify is enabled by default, with `post-forward-angle-brackets' style.
+In other words, if you visit two files that have the same base name,
+then rather than creating buffers basename and basename<2>,
+Emacs uses basename<dirA> and basename<dirB>.  To change this,
+customize `uniquify-buffer-name-style'.  Set it to nil for the old behavior.
 
 +++
 ** New command `C-x SPC' (`rectangle-mark-mode') makes a rectangular region.

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-06-06 23:38:40 +0000
+++ b/lisp/ChangeLog    2014-06-08 07:41:27 +0000
@@ -1,3 +1,8 @@
+2014-06-08  Glenn Morris  <address@hidden>
+
+       * bookmark.el (bookmark-load):
+       * uniquify.el (uniquify-buffer-name-style): Doc fixes.
+
 2014-06-06  Juri Linkov  <address@hidden>
 
        * desktop.el: Activate auto-saving on window configuration changes.

=== modified file 'lisp/bookmark.el'
--- a/lisp/bookmark.el  2014-01-01 07:43:34 +0000
+++ b/lisp/bookmark.el  2014-06-08 07:41:27 +0000
@@ -1420,8 +1420,7 @@
 
 If you load a file containing bookmarks with the same names as
 bookmarks already present in your Emacs, the new bookmarks will get
-unique numeric suffixes \"<2>\", \"<3>\", ... following the same
-method buffers use to resolve name collisions."
+unique numeric suffixes \"<2>\", \"<3>\", etc."
   (interactive
    (list (read-file-name
           (format "Load bookmarks from: (%s) "

=== modified file 'lisp/files.el'
--- a/lisp/files.el     2014-05-09 06:53:30 +0000
+++ b/lisp/files.el     2014-06-08 07:41:27 +0000
@@ -1654,6 +1654,8 @@
        (let (kill-buffer-query-functions kill-buffer-hook)
          (kill-buffer obuf))))))
 
+;; FIXME we really need to fold the uniquify stuff in here by default,
+;; not using advice, and add it to the doc string.
 (defun create-file-buffer (filename)
   "Create a suitably named buffer for visiting FILENAME, and return it.
 FILENAME (sans directory) is used unchanged if that name is free;

=== modified file 'lisp/uniquify.el'
--- a/lisp/uniquify.el  2014-02-10 01:34:22 +0000
+++ b/lisp/uniquify.el  2014-06-08 07:41:27 +0000
@@ -26,7 +26,7 @@
 
 ;;; Commentary:
 
-;; Emacs's standard method for making buffer names unique adds <2>, <3>,
+;; Emacs's traditional method for making buffer names unique adds <2>, <3>,
 ;; etc. to the end of (all but one of) the buffers.  This file replaces
 ;; that behavior, for buffers visiting files and dired buffers, with a
 ;; uniquification that adds parts of the file name until the buffer names
@@ -94,23 +94,27 @@
 
 
 (defcustom uniquify-buffer-name-style 'post-forward-angle-brackets
-  "If non-nil, buffer names are uniquified with parts of directory name.
-The value determines the buffer name style and is one of `forward',
-`reverse', `post-forward', or `post-forward-angle-brackets'.
-For example, files `/foo/bar/mumble/name' and `/baz/quux/mumble/name'
+  "How to construct unique buffer names for files with the same base name.
+The value can be one of: `forward', `reverse', `post-forward',
+`post-forward-angle-brackets', or nil.
+
+For example, the files `/foo/bar/mumble/name' and `/baz/quux/mumble/name'
 would have the following buffer names in the various styles:
-  forward        bar/mumble/name  quux/mumble/name
-  reverse        name\\mumble\\bar  name\\mumble\\quux
-  post-forward   name|bar/mumble  name|quux/mumble
-  post-forward-angle-brackets   name<bar/mumble>  name<quux/mumble>
-  nil            name  name<2>
-Of course, the \"mumble\" part may be stripped as well, depending on the 
setting
-of `uniquify-strip-common-suffix'."
+
+  forward                       bar/mumble/name    quux/mumble/name
+  reverse                       name\\mumble\\bar    name\\mumble\\quux
+  post-forward                  name|bar/mumble    name|quux/mumble
+  post-forward-angle-brackets   name<bar/mumble>   name<quux/mumble>
+  nil                           name               name<2>
+
+The \"mumble\" part may be stripped as well, depending on the
+setting of `uniquify-strip-common-suffix'.  For more options that
+you can set, browse the `uniquify' custom group."
   :type '(radio (const forward)
                (const reverse)
                (const post-forward)
                (const post-forward-angle-brackets)
-               (const :tag "standard Emacs behavior (nil)" nil))
+               (const :tag "numeric suffixes" nil))
   :version "24.4"
   :require 'uniquify
   :group 'uniquify)