More updates for Buffers and Files chapters of Lisp manual.
* doc/emacs/buffers.texi (Creating Buffers): Clarify that generate-new-buffer uses generate-new-buffer-names. (Killing Buffers): Remove bogus example duplicating buffer-live-p. * doc/emacs/files.texi (Directory Names): Index entry for file name abbreviations. (Relative File Names, File Name Expansion): Refer to it. (Locating Files): Move locate-user-emacs-file documentation to Standard File Names. (Standard File Names): Add locate-user-emacs-file; update examples.
This commit is contained in:
Chong Yidong
parent
9c62cd0479
commit
431ee44bbe
4 changed files with 114 additions and 111 deletions
|
|
@ -185,7 +185,7 @@ advice.texi cyd
|
|||
anti.texi
|
||||
back.texi
|
||||
backups.texi cyd
|
||||
buffers.texi
|
||||
buffers.texi cyd
|
||||
commands.texi cyd
|
||||
compile.texi cyd
|
||||
control.texi cyd
|
||||
|
|
|
|||
|
|
@ -1,3 +1,15 @@
|
|||
2012-02-27 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* buffers.texi (Creating Buffers): Clarify that
|
||||
generate-new-buffer uses generate-new-buffer-names.
|
||||
(Killing Buffers): Remove bogus example duplicating buffer-live-p.
|
||||
|
||||
* files.texi (Directory Names): Index entry for file name abbreviations.
|
||||
(Relative File Names, File Name Expansion): Refer to it.
|
||||
(Locating Files): Move locate-user-emacs-file documentation to
|
||||
Standard File Names.
|
||||
(Standard File Names): Add locate-user-emacs-file; update examples.
|
||||
|
||||
2012-02-26 Michael Albinus <michael.albinus@gmx.de>
|
||||
|
||||
* files.texi (Magic File Names): Add files-equal-p and file-subdir-of-p.
|
||||
|
|
|
|||
|
|
@ -417,7 +417,7 @@ This buffer-local variable holds the abbreviated truename of the file
|
|||
visited in the current buffer, or @code{nil} if no file is visited.
|
||||
It is a permanent local, unaffected by
|
||||
@code{kill-all-local-variables}. @xref{Truenames}, and
|
||||
@ref{Definition of abbreviate-file-name}.
|
||||
@ref{abbreviate-file-name}.
|
||||
@end defvar
|
||||
|
||||
@defvar buffer-file-number
|
||||
|
|
@ -502,9 +502,8 @@ buffer's recorded last file modification time as reported by
|
|||
last file modification time, after which @code{visited-file-modtime}
|
||||
returns zero.
|
||||
|
||||
@c Wordy to avoid overfull hbox. --rjc 16mar92
|
||||
When the function @code{set-visited-file-name} is called interactively, it
|
||||
prompts for @var{filename} in the minibuffer.
|
||||
When the function @code{set-visited-file-name} is called
|
||||
interactively, it prompts for @var{filename} in the minibuffer.
|
||||
@end deffn
|
||||
|
||||
@defvar list-buffers-directory
|
||||
|
|
@ -913,7 +912,7 @@ To replace a buffer in all the windows that display it, use
|
|||
This command switches to the last buffer in the local buffer list of
|
||||
the selected frame. More precisely, it calls the function
|
||||
@code{switch-to-buffer} (@pxref{Switching Buffers}), to display the
|
||||
buffer returned by @code{last-buffer}, see above, in the selected
|
||||
buffer returned by @code{last-buffer} (see above), in the selected
|
||||
window.
|
||||
@end deffn
|
||||
|
||||
|
|
@ -959,11 +958,12 @@ buffer initially disables undo information recording (@pxref{Undo}).
|
|||
|
||||
@defun generate-new-buffer name
|
||||
This function returns a newly created, empty buffer, but does not make
|
||||
it current. If there is no buffer named @var{name}, then that is the
|
||||
name of the new buffer. If that name is in use, this function adds
|
||||
suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an
|
||||
integer. It tries successive integers starting with 2 until it finds an
|
||||
available name.
|
||||
it current. The name of the buffer is generated by passing @var{name}
|
||||
to the function @code{generate-new-buffer-name} (@pxref{Buffer
|
||||
Names}). Thus, if there is no buffer named @var{name}, then that is
|
||||
the name of the new buffer; if that name is in use, a suffix of the
|
||||
form @samp{<@var{n}>}, where @var{n} is an integer, is appended to
|
||||
@var{name}.
|
||||
|
||||
An error is signaled if @var{name} is not a string.
|
||||
|
||||
|
|
@ -985,9 +985,6 @@ An error is signaled if @var{name} is not a string.
|
|||
The major mode for the new buffer is set to Fundamental mode. The default
|
||||
value of the variable @code{major-mode} is handled at a higher level.
|
||||
@xref{Auto Major Mode}.
|
||||
|
||||
See the related function @code{generate-new-buffer-name} in @ref{Buffer
|
||||
Names}.
|
||||
@end defun
|
||||
|
||||
@node Killing Buffers
|
||||
|
|
@ -1005,25 +1002,26 @@ their identity, however; if you kill two distinct buffers, they remain
|
|||
distinct according to @code{eq} although both are dead.
|
||||
|
||||
If you kill a buffer that is current or displayed in a window, Emacs
|
||||
automatically selects or displays some other buffer instead. This means
|
||||
that killing a buffer can in general change the current buffer.
|
||||
Therefore, when you kill a buffer, you should also take the precautions
|
||||
automatically selects or displays some other buffer instead. This
|
||||
means that killing a buffer can change the current buffer. Therefore,
|
||||
when you kill a buffer, you should also take the precautions
|
||||
associated with changing the current buffer (unless you happen to know
|
||||
that the buffer being killed isn't current). @xref{Current Buffer}.
|
||||
|
||||
If you kill a buffer that is the base buffer of one or more indirect
|
||||
buffers, the indirect buffers are automatically killed as well.
|
||||
@iftex
|
||||
buffers,
|
||||
@end iftex
|
||||
@ifnottex
|
||||
buffers (@pxref{Indirect Buffers}),
|
||||
@end ifnottex
|
||||
the indirect buffers are automatically killed as well.
|
||||
|
||||
The @code{buffer-name} of a killed buffer is @code{nil}. You can use
|
||||
this feature to test whether a buffer has been killed:
|
||||
|
||||
@example
|
||||
@group
|
||||
(defun buffer-killed-p (buffer)
|
||||
"Return t if BUFFER is killed."
|
||||
(not (buffer-name buffer)))
|
||||
@end group
|
||||
@end example
|
||||
@cindex live buffer
|
||||
The @code{buffer-name} of a buffer is @code{nil} if, and only if,
|
||||
the buffer is killed. A buffer that has not been killed is called a
|
||||
@dfn{live} buffer. To test whether a buffer is live or killed, use
|
||||
the function @code{buffer-live-p} (see below).
|
||||
|
||||
@deffn Command kill-buffer &optional buffer-or-name
|
||||
This function kills the buffer @var{buffer-or-name}, freeing all its
|
||||
|
|
@ -1032,9 +1030,8 @@ memory for other uses or to be returned to the operating system. If
|
|||
buffer.
|
||||
|
||||
Any processes that have this buffer as the @code{process-buffer} are
|
||||
sent the @code{SIGHUP} signal, which normally causes them to terminate.
|
||||
(The basic meaning of @code{SIGHUP} is that a dialup line has been
|
||||
disconnected.) @xref{Signals to Processes}.
|
||||
sent the @code{SIGHUP} (``hangup'') signal, which normally causes them
|
||||
to terminate. @xref{Signals to Processes}.
|
||||
|
||||
If the buffer is visiting a file and contains unsaved changes,
|
||||
@code{kill-buffer} asks the user to confirm before the buffer is killed.
|
||||
|
|
@ -1099,8 +1096,8 @@ automatically becomes buffer-local when set for any reason.
|
|||
@end defvar
|
||||
|
||||
@defun buffer-live-p object
|
||||
This function returns @code{t} if @var{object} is a buffer which has
|
||||
not been killed, @code{nil} otherwise.
|
||||
This function returns @code{t} if @var{object} is a live buffer (a
|
||||
buffer which has not been killed), @code{nil} otherwise.
|
||||
@end defun
|
||||
|
||||
@node Indirect Buffers
|
||||
|
|
|
|||
|
|
@ -1360,8 +1360,10 @@ support, then the return value is @code{(nil nil nil nil)}.
|
|||
|
||||
This section explains how to search for a file in a list of
|
||||
directories (a @dfn{path}), or for an executable file in the standard
|
||||
list of executable file directories, or for an Emacs-specific user
|
||||
configuration file.
|
||||
list of executable file directories.
|
||||
|
||||
To search for a user-specific configuration file, @xref{Standard
|
||||
File Names}, for the @code{locate-user-emacs-file} function.
|
||||
|
||||
@defun locate-file filename path &optional suffixes predicate
|
||||
This function searches for a file whose name is @var{filename} in a
|
||||
|
|
@ -1408,32 +1410,6 @@ in @code{exec-path}, and tries all the file-name extensions in
|
|||
@code{exec-suffixes} (@pxref{Subprocess Creation}).
|
||||
@end defun
|
||||
|
||||
@defun locate-user-emacs-file base-name &optional old-name
|
||||
This function returns an absolute file name for an Emacs-specific
|
||||
configuration or data file. The argument @file{base-name} should be a
|
||||
relative file name. The return value is the absolute name of a file
|
||||
in the directory specified by @code{user-emacs-directory}; if that
|
||||
directory does not exist, this function creates it.
|
||||
|
||||
If the optional argument @var{old-name} is non-@code{nil}, it
|
||||
specifies a file in the user's home directory,
|
||||
@file{~/@var{old-name}}. If such a file exists, the return value is
|
||||
the absolute name of that file, instead of the file specified by
|
||||
@var{base-name}. This argument is intended to be used by Emacs
|
||||
packages to provide backward compatibility. For instance, prior to
|
||||
the introduction of @code{user-emacs-directory}, the abbrev file was
|
||||
located in @file{~/.abbrev_defs}, so the definition of
|
||||
@code{abbrev-file-name} is
|
||||
|
||||
@example
|
||||
(defcustom abbrev-file-name
|
||||
(locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
|
||||
"Default name of file from which to read abbrevs."
|
||||
@dots{}
|
||||
:type 'file)
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@node Changing Files
|
||||
@section Changing File Names and Attributes
|
||||
@c @cindex renaming files Duplicates rename-file
|
||||
|
|
@ -1880,14 +1856,15 @@ not an extension.
|
|||
|
||||
All the directories in the file system form a tree starting at the
|
||||
root directory. A file name can specify all the directory names
|
||||
starting from the root of the tree; then it is called an @dfn{absolute}
|
||||
file name. Or it can specify the position of the file in the tree
|
||||
relative to a default directory; then it is called a @dfn{relative} file
|
||||
name. On Unix and GNU/Linux, an absolute file name starts with a slash
|
||||
or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
|
||||
MS-Windows, an absolute file name starts with a slash or a backslash, or
|
||||
with a drive specification @samp{@var{x}:/}, where @var{x} is the
|
||||
@dfn{drive letter}.
|
||||
starting from the root of the tree; then it is called an
|
||||
@dfn{absolute} file name. Or it can specify the position of the file
|
||||
in the tree relative to a default directory; then it is called a
|
||||
@dfn{relative} file name. On Unix and GNU/Linux, an absolute file
|
||||
name starts with a @samp{/} or a @samp{~}
|
||||
(@pxref{abbreviate-file-name}), and a relative one does not. On
|
||||
MS-DOS and MS-Windows, an absolute file name starts with a slash or a
|
||||
backslash, or with a drive specification @samp{@var{x}:/}, where
|
||||
@var{x} is the @dfn{drive letter}.
|
||||
|
||||
@defun file-name-absolute-p filename
|
||||
This function returns @code{t} if file @var{filename} is an absolute
|
||||
|
|
@ -2023,8 +2000,10 @@ because this is not portable. Always use
|
|||
To convert a directory name to its abbreviation, use this
|
||||
function:
|
||||
|
||||
@cindex file name abbreviations
|
||||
@cindex abbreviated file names
|
||||
@defun abbreviate-file-name filename
|
||||
@anchor{Definition of abbreviate-file-name}
|
||||
@anchor{abbreviate-file-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}),
|
||||
|
|
@ -2042,11 +2021,15 @@ because it recognizes abbreviations even as part of the name.
|
|||
@subsection Functions that Expand Filenames
|
||||
@cindex expansion of file names
|
||||
|
||||
@dfn{Expansion} of a file name means converting a relative file name
|
||||
to an absolute one. Since this is done relative to a default directory,
|
||||
you must specify the default directory name as well as the file name to
|
||||
be expanded. Expansion also simplifies file names by eliminating
|
||||
redundancies such as @file{./} and @file{@var{name}/../}.
|
||||
@dfn{Expanding} a file name means converting a relative file name to
|
||||
an absolute one. Since this is done relative to a default directory,
|
||||
you must specify the default directory name as well as the file name
|
||||
to be expanded. It also involves expanding abbreviations like
|
||||
@file{~/}
|
||||
@ifnottex
|
||||
(@pxref{abbreviate-file-name}),
|
||||
@end ifnottex
|
||||
and eliminating redundancies like @file{./} and @file{@var{name}/../}.
|
||||
|
||||
@defun expand-file-name filename &optional directory
|
||||
This function converts @var{filename} to an absolute file name. If
|
||||
|
|
@ -2411,49 +2394,60 @@ filter out a directory named @file{foo.elc}.
|
|||
@node Standard File Names
|
||||
@subsection Standard File Names
|
||||
|
||||
Most of the file names used in Lisp programs are entered by the user.
|
||||
But occasionally a Lisp program needs to specify a standard file name
|
||||
for a particular use---typically, to hold customization information
|
||||
about each user. For example, abbrev definitions are stored (by
|
||||
default) in the file @file{~/.abbrev_defs}; the @code{completion}
|
||||
package stores completions in the file @file{~/.completions}. These are
|
||||
two of the many standard file names used by parts of Emacs for certain
|
||||
purposes.
|
||||
Sometimes, an Emacs Lisp program needs to specify a standard file
|
||||
name for a particular use---typically, to hold configuration data
|
||||
specified by the current user. Usually, such files should be located
|
||||
in the directory specified by @code{user-emacs-directory}, which is
|
||||
@file{~/.emacs.d} by default (@pxref{Init File}). For example, abbrev
|
||||
definitions are stored by default in @file{~/.emacs.d/abbrev_defs}.
|
||||
The easiest way to specify such a file name is to use the function
|
||||
@code{locate-user-emacs-file}.
|
||||
|
||||
Various operating systems have their own conventions for valid file
|
||||
names and for which file names to use for user profile data. A Lisp
|
||||
program which reads a file using a standard file name ought to use, on
|
||||
each type of system, a file name suitable for that system. The function
|
||||
@code{convert-standard-filename} makes this easy to do.
|
||||
@defun locate-user-emacs-file base-name &optional old-name
|
||||
This function returns an absolute file name for an Emacs-specific
|
||||
configuration or data file. The argument @file{base-name} should be a
|
||||
relative file name. The return value is the absolute name of a file
|
||||
in the directory specified by @code{user-emacs-directory}; if that
|
||||
directory does not exist, this function creates it.
|
||||
|
||||
@defun convert-standard-filename filename
|
||||
This function alters the file name @var{filename} to fit the conventions
|
||||
of the operating system in use, and returns the result as a new string.
|
||||
@end defun
|
||||
|
||||
The recommended way to specify a standard file name in a Lisp program
|
||||
is to choose a name which fits the conventions of GNU and Unix systems,
|
||||
usually with a nondirectory part that starts with a period, and pass it
|
||||
to @code{convert-standard-filename} instead of using it directly. Here
|
||||
is an example from the @code{completion} package:
|
||||
If the optional argument @var{old-name} is non-@code{nil}, it
|
||||
specifies a file in the user's home directory,
|
||||
@file{~/@var{old-name}}. If such a file exists, the return value is
|
||||
the absolute name of that file, instead of the file specified by
|
||||
@var{base-name}. This argument is intended to be used by Emacs
|
||||
packages to provide backward compatibility. For instance, prior to
|
||||
the introduction of @code{user-emacs-directory}, the abbrev file was
|
||||
located in @file{~/.abbrev_defs}. Here is the definition of
|
||||
@code{abbrev-file-name}:
|
||||
|
||||
@example
|
||||
(defvar save-completions-file-name
|
||||
(convert-standard-filename "~/.completions")
|
||||
"*The file name to save completions to.")
|
||||
(defcustom abbrev-file-name
|
||||
(locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
|
||||
"Default name of file from which to read abbrevs."
|
||||
@dots{}
|
||||
:type 'file)
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
On GNU and Unix systems, and on some other systems as well,
|
||||
@code{convert-standard-filename} returns its argument unchanged. On
|
||||
some other systems, it alters the name to fit the system's conventions.
|
||||
A lower-level function for standardizing file names, which
|
||||
@code{locate-user-emacs-file} uses as a subroutine, is
|
||||
@code{convert-standard-filename}.
|
||||
|
||||
For example, on MS-DOS the alterations made by this function include
|
||||
converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
|
||||
middle of the name to @samp{.} if there is no other @samp{.}, inserting
|
||||
a @samp{.} after eight characters if there is none, and truncating to
|
||||
three characters after the @samp{.}. (It makes other changes as well.)
|
||||
Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
|
||||
@file{.completions} becomes @file{_complet.ion}.
|
||||
@defun convert-standard-filename filename
|
||||
This function returns a file name based on @var{filename}, which fits
|
||||
the conventions of the current operating system.
|
||||
|
||||
On GNU and Unix systems, this simply returns @var{filename}. On other
|
||||
operating systems, it may enforce system-specific file name
|
||||
conventions; for example, on MS-DOS this function performs a variety
|
||||
of changes to enforce MS-DOS file name limitations, including
|
||||
converting any leading @samp{.} to @samp{_} and truncating to three
|
||||
characters after the @samp{.}.
|
||||
|
||||
The recommended way to use this function is to specify a name which
|
||||
fits the conventions of GNU and Unix systems, and pass it to
|
||||
@code{convert-standard-filename}.
|
||||
@end defun
|
||||
|
||||
@node Contents of Directories
|
||||
@section Contents of Directories
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue