Commit 431ee44b authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent 9c62cd04
......@@ -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
......
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.
The @code{buffer-name} of a killed buffer is @code{nil}. You can use
this feature to test whether a buffer has been killed:
@iftex
buffers,
@end iftex
@ifnottex
buffers (@pxref{Indirect Buffers}),
@end ifnottex
the indirect buffers are automatically killed as well.
@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.
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.
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}.
@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
@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.
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.
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}.
A lower-level function for standardizing file names, which
@code{locate-user-emacs-file} uses as a subroutine, is
@code{convert-standard-filename}.
@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
......
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