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.

1 files changed, 29 insertions, 32 deletions

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index c2e792cd58..125a886ecb 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