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.

4 files changed, 115 insertions, 112 deletions

diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index 1401bad10d2..beb60eb93d6 100644
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -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
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 09a32de0547..a3ddc5b1cff 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -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.
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index c2e792cd585..125a886ecb2 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -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
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index bc62e9b1a49..cffaef37988 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -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