changeset 38739:7055d897b6bb

Many minor cleanups.

--- a/man/files.texi	Wed Aug 08 23:19:49 2001 +0000
+++ b/man/files.texi	Wed Aug 08 23:28:08 2001 +0000
@@ -46,10 +46,10 @@
   Most Emacs commands that operate on a file require you to specify the
 file name.  (Saving and reverting are exceptions; the buffer knows which
 file name to use for them.)  You enter the file name using the
-minibuffer (@pxref{Minibuffer}).  @dfn{Completion} is available, to make
-it easier to specify long file names.  @xref{Completion}.  When
+minibuffer (@pxref{Minibuffer}).  @dfn{Completion} is available
+(@pxref{Completion}) to make it easier to specify long file names.  When
 completing file names, Emacs ignores those whose file-name extensions
-appear in the variable @code{completion-ignored-extensions}, see
+appear in the variable @code{completion-ignored-extensions}; see
 @ref{Completion Options}.
 
   For most operations, there is a @dfn{default file name} which is used
@@ -79,7 +79,7 @@
 directory, and the command @kbd{M-x cd} sets it (to a value read using
 the minibuffer).  A buffer's default directory changes only when the
 @code{cd} command is used.  A file-visiting buffer's default directory
-is initialized to the directory of the file that is visited there.  If
+is initialized to the directory of the file that is visited in that buffer.  If
 you create a buffer with @kbd{C-x b}, its default directory is copied
 from that of the buffer that was current at the time.
 
@@ -162,15 +162,16 @@
 
 @cindex files, visiting and saving
 @cindex saving files
-  @dfn{Visiting} a file means copying its contents into an Emacs buffer
-so you can edit them.  Emacs makes a new buffer for each file that you
-visit.  We say that this buffer is visiting the file that it was created
-to hold.  Emacs constructs the buffer name from the file name by
-throwing away the directory, keeping just the name proper.  For example,
-a file named @file{/usr/rms/emacs.tex} would get a buffer named
-@samp{emacs.tex}.  If there is already a buffer with that name, a unique
-name is constructed by appending @samp{<2>}, @samp{<3>}, and so on, using
-the lowest number that makes a name that is not already in use.
+  @dfn{Visiting} a file means copying its contents into an Emacs
+buffer so you can edit them.  Emacs makes a new buffer for each file
+that you visit.  We often say that this buffer ``is visiting'' that
+file, or that the buffer's ``visited file'' is that file.  Emacs
+constructs the buffer name from the file name by throwing away the
+directory, keeping just the name proper.  For example, a file named
+@file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}.
+If there is already a buffer with that name, Emacs constructs a unique
+name---the normal method is to append @samp{<2>}, @samp{<3>}, and so
+on, but you can select other methods (@pxref{Uniquify}).
 
   Each window's mode line shows the name of the buffer that is being displayed
 in that window, so you can always tell what buffer you are editing.
@@ -259,8 +260,8 @@
 @cindex wildcard characters in file names
 @vindex find-file-wildcards
   If the file name you specify contains shell-style wildcard characters,
-Emacs visits all the files that match it.  Wildcards comprise @samp{?},
-@samp{*} and @samp{[@dots{}]} sequences.  @xref{Quoted File Names}, for
+Emacs visits all the files that match it.  Wildcards include @samp{?},
+@samp{*}, and @samp{[@dots{}]} sequences.  @xref{Quoted File Names}, for
 information on how to visit a file whose name actually contains wildcard
 characters.  You can disable the wildcard feature by customizing
 @code{find-file-wildcards}.
@@ -328,12 +329,11 @@
 normal hook, and the name ends in @samp{-hooks} rather than @samp{-hook}
 to indicate that fact.
 
-  Any visiting of a file, whether extant or not, expects
-@code{find-file-hooks} to contain a list of functions, and calls them
-all, one by one, with no arguments.  This variable is really a normal
-hook, but it has an abnormal name for historical compatibility.  In the
-case of a nonexistent file, the @code{find-file-not-found-hooks} are run
-first.  @xref{Hooks}.
+  Successful visiting of any file, whether existing or not, calls the
+functions in the list @code{find-file-hooks}, with no arguments.
+This variable is really a normal hook, but it has an abnormal name for
+historical compatibility.  In the case of a nonexistent file, the
+@code{find-file-not-found-hooks} are run first.  @xref{Hooks}.
 
   There are several ways to specify automatically the major mode for
 editing the file (@pxref{Choosing Modes}), and to specify local
@@ -347,14 +347,14 @@
 
 @table @kbd
 @item C-x C-s
-Save the current buffer in its visited file (@code{save-buffer}).
+Save the current buffer in its visited file on disk (@code{save-buffer}).
 @item C-x s
 Save any or all buffers in their visited files (@code{save-some-buffers}).
 @item M-~
 Forget that the current buffer has been changed (@code{not-modified}).
 With prefix argument (@kbd{C-u}), mark the current buffer as changed.
 @item C-x C-w
-Save the current buffer in a specified file (@code{write-file}).
+Save the current buffer as a specified file name (@code{write-file}).
 @item M-x set-visited-file-name
 Change the file name under which the current buffer will be saved.
 @end table
@@ -430,12 +430,12 @@
 @findex set-visited-file-name
   @kbd{M-x set-visited-file-name} alters the name of the file that the
 current buffer is visiting.  It reads the new file name using the
-minibuffer.  Then it specifies the visited file name and changes the
-buffer name correspondingly (as long as the new name is not in use).
-@code{set-visited-file-name} does not save the buffer in the newly
-visited file; it just alters the records inside Emacs in case you do
-save later.  It also marks the buffer as ``modified'' so that @kbd{C-x
-C-s} in that buffer @emph{will} save.
+minibuffer.  Then it marks the buffer as visiting that file name, and
+changes the buffer name correspondingly.  @code{set-visited-file-name}
+does not save the buffer in the newly visited file; it just alters the
+records inside Emacs in case you do save later.  It also marks the
+buffer as ``modified'' so that @kbd{C-x C-s} in that buffer
+@emph{will} save.
 
 @kindex C-x C-w
 @findex write-file
@@ -446,7 +446,7 @@
 same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
 buffer as visiting that file, and saves it there.  The default file name in
 a buffer that is not visiting a file is made by combining the buffer name
-with the buffer's default directory.
+with the buffer's default directory (@pxref{File Names}).
 
   If the new file name implies a major mode, then @kbd{C-x C-w} switches
 to that major mode, in most cases.  The command
@@ -521,8 +521,8 @@
 into a backup file if you save the buffer again.  @kbd{C-u C-u C-x C-s}
 saves the buffer, but first makes the previous file contents into a new
 backup file.  @kbd{C-u C-u C-u C-x C-s} does both things: it makes a
-backup from the previous contents and arranges to make another from the
-newly saved contents, if you save again.
+backup from the previous contents, and arranges to make another from the
+newly saved contents if you save again.
 
 @menu
 * Names: Backup Names.		How backup files are named;
@@ -610,17 +610,19 @@
 @vindex kept-new-versions
   The two variables @code{kept-old-versions} and
 @code{kept-new-versions} control this deletion.  Their values are,
-respectively, the number of oldest (lowest-numbered) backups to keep and
-the number of newest (highest-numbered) ones to keep, each time a new
-backup is made.  Recall that these values are used just after a new
-backup version is made; that newly made backup is included in the count
-in @code{kept-new-versions}.  By default, both variables are 2.
+respectively, the number of oldest (lowest-numbered) backups to keep
+and the number of newest (highest-numbered) ones to keep, each time a
+new backup is made.  The backups in the middle (excluding those oldest
+and newest) are the excess middle versions---those backups are
+deleted.  These variables' values are used when it is time to delete
+excess versions, just after a new backup version is made; the newly
+made backup is included in the count in @code{kept-new-versions}.  By
+default, both variables are 2.
 
 @vindex delete-old-versions
-  If @code{delete-old-versions} is non-@code{nil}, the excess
-middle versions are deleted without a murmur.  If it is @code{nil}, the
-default, then you are asked whether the excess middle versions should
-really be deleted.
+  If @code{delete-old-versions} is non-@code{nil}, Emacs deletes the
+excess backup files silently.  If it is @code{nil}, the default, Emacs
+asks you whether it should delete the excess backup versions.
 
   Dired's @kbd{.} (Period) command can also be used to delete old versions.
 @xref{Dired Deletion}.
@@ -628,12 +630,13 @@
 @node Backup Copying
 @subsubsection Copying vs.@: Renaming
 
-  Backup files can be made by copying the old file or by renaming it.  This
-makes a difference when the old file has multiple names.  If the old file
-is renamed into the backup file, then the alternate names become names for
-the backup file.  If the old file is copied instead, then the alternate
-names remain names for the file that you are editing, and the contents
-accessed by those names will be the new contents.
+  Backup files can be made by copying the old file or by renaming it.
+This makes a difference when the old file has multiple names (hard
+links).  If the old file is renamed into the backup file, then the
+alternate names become names for the backup file.  If the old file is
+copied instead, then the alternate names remain names for the file
+that you are editing, and the contents accessed by those names will be
+the new contents.
 
   The method of making a backup file may also affect the file's owner
 and group.  If copying is used, these do not change.  If renaming is used,
@@ -718,8 +721,9 @@
 @item p
 Proceed.  Go ahead and edit the file despite its being locked by someone else.
 @item q
-Quit.  This causes an error (@code{file-locked}) and the modification you
-were trying to make in the buffer does not actually take place.
+Quit.  This causes an error (@code{file-locked}), and the buffer
+contents remain unchanged---the modification you were trying to make
+does not actually take place.
 @end table
 
   Note that locking works on the basis of a file name; if a file has
@@ -946,9 +950,11 @@
 auto-save}.
 
 @vindex auto-save-visited-file-name
-  If you want auto-saving to be done in the visited file, set the variable
-@code{auto-save-visited-file-name} to be non-@code{nil}.  In this mode,
-there is really no difference between auto-saving and explicit saving.
+  If you want auto-saving to be done in the visited file rather than
+in a separate auto-save file, set the variable
+@code{auto-save-visited-file-name} to a non-@code{nil} value.  In this
+mode, there is no real difference between auto-saving and explicit
+saving.
 
 @vindex delete-auto-save-files
   A buffer's auto-save file is deleted when you save the buffer in its
@@ -1344,7 +1350,7 @@
 @itemize @bullet
 @item
 If the file is modified (or locked), you can specify the version
-number to use for the new verion that you check-in.  This is one way
+number to use for the new version that you check in.  This is one way
 to create a new branch (@pxref{Branches}).
 
 @item
@@ -1358,7 +1364,7 @@
 @item
 Instead of the version number, you can also specify the name of a
 version control system.  This is useful when one file is being managed
-with two version control systems at the same time file (@pxref{Local
+with two version control systems at the same time (@pxref{Local
 Version Control}).
 @end itemize
 
@@ -1412,7 +1418,7 @@
 
 @findex vc-version-other-window
 @kindex C-x v ~
-  To examine an old version in toto, visit the file and then type
+  To examine an old version in its entirety, visit the file and then type
 @kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}).
 This puts the text of version @var{version} in a file named
 @file{@var{filename}.~@var{version}~}, and visits it in its own buffer
@@ -1438,14 +1444,17 @@
 file, this command compares the two specified versions of all registered
 files in that directory and its subdirectories.
 
-@vindex diff-switches
 @vindex vc-diff-switches
+@vindex vc-rcs-diff-switches
   @kbd{C-x v =} works by running a variant of the @code{diff} utility
-designed to work with the version control system in use.  Emacs passes
-the contents of the variable @code{diff-switches} to it; you can
-specify comparison options for version control in
-@code{vc-diff-switches}, and there are similar variables for each
-specific system---@code{vc-rcs-diff-switches}, and so on.
+designed to work with the version control system in use.  When you
+invoke @code{diff} this way, in addition to the options specified by
+@code{diff-switches} (@pxref{Comparing files}), it receives those
+specified by @code{vc-diff-switches}, plus those specified for the
+specific back end by @code{vc-@var{backend}-diff-switches}.  For
+instance, when the version control back end is RCS, @code{diff} uses
+the options in @code{vc-rcs-diff-switches}.  The
+@samp{vc@dots{}diff-switches} variables are @code{nil} by default.
 
   Unlike the @kbd{M-x diff} command, @kbd{C-x v =} does not try to
 locate the changes in the old and new versions.  This is because
@@ -1457,10 +1466,12 @@
 @kindex C-x v g
   For CVS-controlled files, you can display the result of the CVS
 annotate command, using colors to enhance the visual appearance.  Use
-the command @kbd{M-x vc-annotate} to do this.  Red means new, blue means
-old, and intermediate colors indicate intermediate ages.  A prefix
-argument @var{n} specifies a stretch factor for the time scale; it makes
-each color cover a period @var{n} times as long.
+the command @kbd{M-x vc-annotate} to do this.  Red means new, blue
+means old, and intermediate colors indicate intermediate ages.  By
+default, the time scale is 360 days, so that everything more than one
+year old is shown in blue.  Giving a prefix argument @var{n} to this
+command multiplies the time scale by @var{n}, so that all text over
+@var{n} years old is shown in blue.
 
 @node Secondary VC Commands
 @subsection The Secondary Commands of VC
@@ -1818,9 +1829,9 @@
 regardless of whether you have already changed the file yourself.
 
   You can also enter a branch number or a pair of version numbers in
-the minibuffer.  Then @kbd{C-x v m} finds the changes from that branch,
-or between the two versions you specified, and merges them into the
-current version of the current file.
+the minibuffer.  Then @kbd{C-x v m} finds the changes from that
+branch, or the differences between the two versions you specified, and
+merges them into the current version of the current file.
 
   As an example, suppose that you have finished a certain feature on
 branch 1.3.1.  In the meantime, development on the trunk has proceeded
@@ -1870,7 +1881,8 @@
 @cindex vc-resolve-conflicts
   Then you can resolve the conflicts by editing the file manually.  Or
 you can type @code{M-x vc-resolve-conflicts} after visiting the file.
-This starts an Ediff session, as described above.
+This starts an Ediff session, as described above.  Don't forget to
+check in the merged version afterwards.
 
 @node Multi-User Branching
 @subsubsection Multi-User Branching
@@ -2334,9 +2346,9 @@
 make VC behave correctly (@pxref{Multi-User Branching}).
 
   Searching for version headers is controlled by the variable
-@code{vc-consult-headers}.  If it is non-@code{nil}, Emacs searches for
-headers to determine the version number you are editing.  Setting it to
-@code{nil} disables this feature.
+@code{vc-consult-headers}.  If it is non-@code{nil} (the default),
+Emacs searches for headers to determine the version number you are
+editing.  Setting it to @code{nil} disables this feature.
 
 @kindex C-x v h
 @findex vc-insert-headers
@@ -2360,10 +2372,12 @@
 each string in the list is inserted as a separate header on a line of
 its own.
 
-  It is often necessary to use ``superfluous'' backslashes when writing
-the strings that you put in this variable.  This is to prevent the
-string in the constant from being interpreted as a header itself if the
-Emacs Lisp file containing it is maintained with version control.
+  It is often necessary to use ``superfluous'' backslashes when
+writing the strings that you put in this variable.  For instance, you
+might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}.  The extra
+backslash prevents the string constant from being interpreted as a
+header, if the Emacs Lisp file containing it is maintained with
+version control.
 
 @vindex vc-comment-alist
   Each header is inserted surrounded by tabs, inside comment delimiters,
@@ -2649,9 +2663,10 @@
 @findex diff
 @vindex diff-switches
   The command @kbd{M-x diff} compares two files, displaying the
-differences in an Emacs buffer named @samp{*diff*}.  It works by running
-the @code{diff} program, using options taken from the variable
-@code{diff-switches}, whose value should be a string.
+differences in an Emacs buffer named @samp{*diff*}.  It works by
+running the @code{diff} program, using options taken from the variable
+@code{diff-switches}.  The value of @code{diff-switches} should be a
+string; the default is @code{"-c"} to specify a context diff.
 
   The buffer @samp{*diff*} has Compilation mode as its major mode, so
 you can use @kbd{C-x `} to visit successive changed locations in the two
@@ -2731,10 +2746,11 @@
   A related command, @kbd{M-x view-buffer}, views a buffer already present
 in Emacs.  @xref{Misc Buffer}.
 
+@kindex C-x i
 @findex insert-file
-  @kbd{M-x insert-file} inserts a copy of the contents of the specified
-file into the current buffer at point, leaving point unchanged before the
-contents and the mark after them.
+  @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the
+contents of the specified file into the current buffer at point,
+leaving point unchanged before the contents and the mark after them.
 
 @findex write-region
   @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
@@ -2750,15 +2766,17 @@
 
 @findex rename-file
   @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
-the minibuffer, then renames file @var{old} as @var{new}.  If a file named
+the minibuffer, then renames file @var{old} as @var{new}.  If the file name
 @var{new} already exists, you must confirm with @kbd{yes} or renaming is not
 done; this is because renaming causes the old meaning of the name @var{new}
 to be lost.  If @var{old} and @var{new} are on different file systems, the
 file @var{old} is copied and deleted.
 
 @findex add-name-to-file
+@cindex hard links (creation)
   The similar command @kbd{M-x add-name-to-file} is used to add an
 additional name to an existing file without removing its old name.
+The new name is created as a ``hard link'' to the existing file.
 The new name must belong on the same file system that the file is on.
 On Windows, this command works only if the file resides in an NTFS
 file system.  On MS-DOS, it works by copying the file.