Commit 99d8aedf authored by Glenn Morris's avatar Glenn Morris

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.
parent b6542afe
2014-06-08 Glenn Morris <rgm@gnu.org> 2014-06-08 Glenn Morris <rgm@gnu.org>
* buffers.texi (Uniquify): Copyedits.
* files.texi (Visiting): Update for uniquify changes.
* dired.texi (Marks vs Flags): * dired.texi (Marks vs Flags):
* rmail.texi (Rmail Scrolling): Markup fixes re SPC. * rmail.texi (Rmail Scrolling): Markup fixes re SPC.
......
...@@ -608,20 +608,16 @@ convenient to switch between buffers. ...@@ -608,20 +608,16 @@ convenient to switch between buffers.
@cindex unique buffer names @cindex unique buffer names
@cindex directories in buffer names @cindex directories in buffer names
When several buffers visit identically-named files, Emacs must give When several buffers visit identically-named files, Emacs must give
the buffers distinct names. The default method the buffers distinct names. The default method adds a suffix based on
(@code{uniquify-buffer-name-style} set to the names of the directories that contain the files. For example, if
@code{post-forward-angle-brackets}) for making buffer names unique you visit files @file{/foo/bar/mumble/name} and
adds @samp{<dir1>}, @samp{<dir2>}, etc.@: to the end of the buffer @file{/baz/quux/mumble/name} at the same time, their buffers will be
names, where @file{dir1} and @file{dir2} are the minimal parts of the named @samp{name<bar/mumble>} and @samp{name<quux/mumble>}, respectively.
leading directories needed to make the buffer name unique. For Emacs adds as many directory parts as are needed to make a unique name.
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.
@vindex uniquify-buffer-name-style @vindex uniquify-buffer-name-style
There are several styles to make buffer names unique. To select You can choose from several different styles for constructing unique
one, customize the variable @code{uniquify-buffer-name-style} buffer names, by customizing the option @code{uniquify-buffer-name-style}.
(@pxref{Easy Customization}).
The @code{forward} naming method includes part of the file's The @code{forward} naming method includes part of the file's
directory name at the beginning of the buffer name; using this method, 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 ...@@ -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 In contrast, the @code{post-forward} naming method would call the
buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}. The default buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}. The default
method @code{post-forward-angle-brackets} is like @code{post-forward} method @code{post-forward-angle-brackets} is like @code{post-forward},
except that it prepends the unique path in angle brackets. The except that it encloses the unique path in angle brackets. The
@code{reverse} naming method would call them @samp{Makefile\tmp} and @code{reverse} naming method would call them @samp{Makefile\tmp} and
@samp{Makefile\zaphod}. The nontrivial difference between @samp{Makefile\zaphod}. The nontrivial difference between
@code{post-forward} and @code{reverse} occurs when just one directory @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} ...@@ -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 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 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 @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 names simply get @samp{<2>}, @samp{<3>}, etc. appended.
default behavior in Emacs versions up to 24.4.
Which rule to follow for putting the directory names in the buffer 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 name is not very important if you are going to @emph{look} at the
......
...@@ -171,9 +171,9 @@ the mode line (@pxref{Mode Line}). Emacs normally constructs the ...@@ -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 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 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, named @samp{emacs.tex}. If there is already a buffer with that name,
Emacs constructs a unique name; the normal method is to append Emacs constructs a unique name; the normal method is to add a suffix
@samp{<2>}, @samp{<3>}, and so on, but you can select other methods. based on the directory name (e.g., @samp{<rms>}, @samp{<tmp>},
@xref{Uniquify}. and so on), but you can select other methods. @xref{Uniquify}.
@cindex creating files @cindex creating files
To create a new file, just visit it using the same command, @kbd{C-x To create a new file, just visit it using the same command, @kbd{C-x
......
2014-06-08 Glenn Morris <rgm@gnu.org> 2014-06-08 Glenn Morris <rgm@gnu.org>
* files.texi (Subroutines of Visiting): Mention uniquify.
* numbers.texi (Comparison of Numbers): Copyedits. * numbers.texi (Comparison of Numbers): Copyedits.
2014-06-06 Glenn Morris <rgm@gnu.org> 2014-06-06 Glenn Morris <rgm@gnu.org>
......
...@@ -254,11 +254,16 @@ is permanent local, so it is unaffected by changes of major modes. ...@@ -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} which are sometimes useful in user Lisp code: @code{create-file-buffer}
and @code{after-find-file}. This section explains how to use them. 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 @defun create-file-buffer filename
This function creates a suitably named buffer for visiting This function creates a suitably named buffer for visiting
@var{filename}, and returns it. It uses @var{filename} (sans directory) @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 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}. @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} @strong{Please note:} @code{create-file-buffer} does @emph{not}
associate the new buffer with a file and does not select the buffer. associate the new buffer with a file and does not select the buffer.
......
2014-06-08 Glenn Morris <rgm@gnu.org> 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. * info.texi (Help-Small-Screen): Clarify details of S-SPC.
(Help-Small-Screen, Help-]): Do not mention S-SPC. (Help-Small-Screen, Help-]): Do not mention S-SPC.
(Emacs Info Variables): Markup fix. (Emacs Info Variables): Markup fix.
......
...@@ -895,9 +895,9 @@ just type @samp{vip.el} followed by @key{RET}. If the file @file{vip.el} ...@@ -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, 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 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 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 unique, Emacs may add a suffix (@pxref{Uniquify,,,
the buffer name. As the @dfn{file name completion} is provided here, you emacs, The GNU Emacs Manual}). As @dfn{file name completion} is provided here, you
can sometime save typing. For instance, suppose there is only one file in the 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}. 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 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} @samp{vip.el}. Thus, in this case, you just have to type @kbd{v v @key{TAB}
......
...@@ -402,6 +402,10 @@ conventions. To use it, add it to the `fill-nobreak-predicate' hook. ...@@ -402,6 +402,10 @@ conventions. To use it, add it to the `fill-nobreak-predicate' hook.
+++ +++
** Uniquify is enabled by default, with `post-forward-angle-brackets' style. ** 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. ** New command `C-x SPC' (`rectangle-mark-mode') makes a rectangular region.
......
2014-06-08 Glenn Morris <rgm@gnu.org>
* bookmark.el (bookmark-load):
* uniquify.el (uniquify-buffer-name-style): Doc fixes.
2014-06-06 Juri Linkov <juri@jurta.org> 2014-06-06 Juri Linkov <juri@jurta.org>
* desktop.el: Activate auto-saving on window configuration changes. * desktop.el: Activate auto-saving on window configuration changes.
......
...@@ -1420,8 +1420,7 @@ explicitly. ...@@ -1420,8 +1420,7 @@ explicitly.
If you load a file containing bookmarks with the same names as If you load a file containing bookmarks with the same names as
bookmarks already present in your Emacs, the new bookmarks will get bookmarks already present in your Emacs, the new bookmarks will get
unique numeric suffixes \"<2>\", \"<3>\", ... following the same unique numeric suffixes \"<2>\", \"<3>\", etc."
method buffers use to resolve name collisions."
(interactive (interactive
(list (read-file-name (list (read-file-name
(format "Load bookmarks from: (%s) " (format "Load bookmarks from: (%s) "
......
...@@ -1654,6 +1654,8 @@ killed." ...@@ -1654,6 +1654,8 @@ killed."
(let (kill-buffer-query-functions kill-buffer-hook) (let (kill-buffer-query-functions kill-buffer-hook)
(kill-buffer obuf)))))) (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) (defun create-file-buffer (filename)
"Create a suitably named buffer for visiting FILENAME, and return it. "Create a suitably named buffer for visiting FILENAME, and return it.
FILENAME (sans directory) is used unchanged if that name is free; FILENAME (sans directory) is used unchanged if that name is free;
......
...@@ -26,7 +26,7 @@ ...@@ -26,7 +26,7 @@
;;; Commentary: ;;; 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 ;; 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 ;; that behavior, for buffers visiting files and dired buffers, with a
;; uniquification that adds parts of the file name until the buffer names ;; uniquification that adds parts of the file name until the buffer names
...@@ -94,23 +94,27 @@ ...@@ -94,23 +94,27 @@
(defcustom uniquify-buffer-name-style 'post-forward-angle-brackets (defcustom uniquify-buffer-name-style 'post-forward-angle-brackets
"If non-nil, buffer names are uniquified with parts of directory name. "How to construct unique buffer names for files with the same base name.
The value determines the buffer name style and is one of `forward', The value can be one of: `forward', `reverse', `post-forward',
`reverse', `post-forward', or `post-forward-angle-brackets'. `post-forward-angle-brackets', or nil.
For example, files `/foo/bar/mumble/name' and `/baz/quux/mumble/name'
For example, the files `/foo/bar/mumble/name' and `/baz/quux/mumble/name'
would have the following buffer names in the various styles: would have the following buffer names in the various styles:
forward bar/mumble/name quux/mumble/name
reverse name\\mumble\\bar name\\mumble\\quux forward bar/mumble/name quux/mumble/name
post-forward name|bar/mumble name|quux/mumble reverse name\\mumble\\bar name\\mumble\\quux
post-forward-angle-brackets name<bar/mumble> name<quux/mumble> post-forward name|bar/mumble name|quux/mumble
nil name name<2> post-forward-angle-brackets name<bar/mumble> name<quux/mumble>
Of course, the \"mumble\" part may be stripped as well, depending on the setting nil name name<2>
of `uniquify-strip-common-suffix'."
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) :type '(radio (const forward)
(const reverse) (const reverse)
(const post-forward) (const post-forward)
(const post-forward-angle-brackets) (const post-forward-angle-brackets)
(const :tag "standard Emacs behavior (nil)" nil)) (const :tag "numeric suffixes" nil))
:version "24.4" :version "24.4"
:require 'uniquify :require 'uniquify
:group 'uniquify) :group 'uniquify)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment