mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-15 10:30:25 -08:00
Code Issues Projects Releases Wiki Activity

More updates for Buffers and Files chapters of Lisp manual.

Browse source 
* 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 2012-02-27 15:26:13 +08:00
parent 9c62cd0479
commit 431ee44bbe
4 changed files with 114 additions and 111 deletions
Download patch file Download diff file Expand all files Collapse all files

150
doc/lispref/files.texi
View file

@ -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