[Emacs-diffs] /srv/bzr/emacs/trunk r107446: More updates for Buffers and Files chapters of Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 107446
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Mon 2012-02-27 15:26:13 +0800
message:
  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.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/buffers.texi
  doc/lispref/files.texi

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-02-25 20:59:46 +0000
+++ b/admin/FOR-RELEASE 2012-02-27 07:26:13 +0000
@@ -185,7 +185,7 @@
 anti.texi         
 back.texi
 backups.texi      cyd
-buffers.texi      
+buffers.texi      cyd
 commands.texi     cyd
 compile.texi      cyd
 control.texi      cyd

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-26 09:41:13 +0000
+++ b/doc/lispref/ChangeLog     2012-02-27 07:26:13 +0000
@@ -1,3 +1,15 @@
+2012-02-27  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * files.texi (Magic File Names): Add files-equal-p and file-subdir-of-p.

=== modified file 'doc/lispref/buffers.texi'
--- a/doc/lispref/buffers.texi  2012-01-19 07:21:25 +0000
+++ b/doc/lispref/buffers.texi  2012-02-27 07:26:13 +0000
@@ -417,7 +417,7 @@
 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
address@hidden of abbreviate-file-name}.
address@hidden
 @end defvar
 
 @defvar buffer-file-number
@@ -502,9 +502,8 @@
 last file modification time, after which @code{visited-file-modtime}
 returns zero.
 
address@hidden 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 @@
 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 @@
 
 @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
address@hidden
 
 An error is signaled if @var{name} is not a string.
 
@@ -985,9 +985,6 @@
 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 @@
 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:
-
address@hidden
address@hidden
-(defun buffer-killed-p (buffer)
-  "Return t if BUFFER is killed."
-  (not (buffer-name buffer)))
address@hidden group
address@hidden example
address@hidden
+buffers,
address@hidden iftex
address@hidden
+buffers (@pxref{Indirect Buffers}),
address@hidden ifnottex
+the indirect buffers are automatically killed as well.
+
address@hidden 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
address@hidden 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 @@
 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 @@
 @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

=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi    2012-02-26 09:41:13 +0000
+++ b/doc/lispref/files.texi    2012-02-27 07:26:13 +0000
@@ -1360,8 +1360,10 @@
 
   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 @@
 @code{exec-suffixes} (@pxref{Subprocess Creation}).
 @end defun
 
address@hidden 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 address@hidden, it
-specifies a file in the user's home directory,
address@hidden/@var{old-name}}.  If such a file exists, the return value is
-the absolute name of that file, instead of the file specified by
address@hidden  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
address@hidden is
-
address@hidden
-(defcustom abbrev-file-name
-  (locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
-  "Default name of file from which to read abbrevs."
-  @dots{}
-  :type 'file)
address@hidden example
address@hidden defun
-
 @node Changing Files
 @section Changing File Names and Attributes
 @c @cindex renaming files  Duplicates rename-file
@@ -1880,14 +1856,15 @@
 
   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 @address@hidden:/}, where @var{x} is the
address@hidden letter}.
+starting from the root of the tree; then it is called an
address@hidden file name.  Or it can specify the position of the file
+in the tree relative to a default directory; then it is called a
address@hidden 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 @address@hidden:/}, where
address@hidden 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 @@
   To convert a directory name to its abbreviation, use this
 function:
 
address@hidden file name abbreviations
address@hidden abbreviated file names
 @defun abbreviate-file-name filename
address@hidden of abbreviate-file-name}
address@hidden
 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 @@
 @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 @address@hidden/../}.
+  @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
address@hidden/}
address@hidden
+(@pxref{abbreviate-file-name}),
address@hidden ifnottex
+and eliminating redundancies like @file{./} and @address@hidden/../}.
 
 @defun expand-file-name filename &optional directory
 This function converts @var{filename} to an absolute file name.  If
@@ -2411,50 +2394,61 @@
 @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
address@hidden 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
address@hidden/.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
address@hidden
+
address@hidden 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 address@hidden, it
+specifies a file in the user's home directory,
address@hidden/@var{old-name}}.  If such a file exists, the return value is
+the absolute name of that file, instead of the file specified by
address@hidden  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
address@hidden:
+
address@hidden
+(defcustom abbrev-file-name
+  (locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
+  "Default name of file from which to read abbrevs."
+  @dots{}
+  :type 'file)
address@hidden example
address@hidden defun
+
+  A lower-level function for standardizing file names, which
address@hidden uses as a subroutine, is
address@hidden
 
 @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.
+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
address@hidden
 @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:
-
address@hidden
-(defvar save-completions-file-name
-        (convert-standard-filename "~/.completions")
-  "*The file name to save completions to.")
address@hidden example
-
-  On GNU and Unix systems, and on some other systems as well,
address@hidden 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
address@hidden becomes @file{_complet.ion}.
-
 @node Contents of Directories
 @section Contents of Directories
 @cindex directory-oriented functions