Implement CLASH_DETECTION for MS-Windows.

[gnu-emacs] / doc / emacs / files.texi

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index b0d4e130c67c0bb128f5dedf376275fbf6412eaf..1f78747eaa6fbcdcccb98f6d8b9cf2ec7aec23fd 100644 (file)
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1,8 +1,8 @@
 @c This is part of the Emacs manual.
 @c This is part of the Emacs manual.

-@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012
-@c   Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2013 Free Software
+@c Foundation, Inc.

 @c See file emacs.texi for copying conditions.
 @c See file emacs.texi for copying conditions.

-@node Files, Buffers, Keyboard Macros, Top
+@node Files

 @chapter File Handling
 @cindex files
 
 @chapter File Handling
 @cindex files
 


@@ -72,7 +72,7 @@ directory into the minibuffer as the initial contents.  You can
 inhibit this insertion by changing the variable
 @code{insert-default-directory} to @code{nil} (@pxref{Minibuffer
 File}).  Regardless, Emacs always assumes that any relative file name
 inhibit this insertion by changing the variable
 @code{insert-default-directory} to @code{nil} (@pxref{Minibuffer
 File}).  Regardless, Emacs always assumes that any relative file name

-is relative to the default directory, e.g. entering a file name
+is relative to the default directory, e.g., entering a file name

 without a directory specifies a file in the default directory.
 
 @findex cd
 without a directory specifies a file in the default directory.
 
 @findex cd


@@ -97,7 +97,7 @@ minibuffer, with a directory omitted, specifies the file
 
   When typing a file name into the minibuffer, you can make use of a
 couple of shortcuts: a double slash is interpreted as ``ignore
 
   When typing a file name into the minibuffer, you can make use of a
 couple of shortcuts: a double slash is interpreted as ``ignore

-everything before the second slash in the pair,'' and @samp{~/} is
+everything before the second slash in the pair'', and @samp{~/} is

 interpreted as your home directory.  @xref{Minibuffer File}.
 
 @cindex environment variables in file names
 interpreted as your home directory.  @xref{Minibuffer File}.
 
 @cindex environment variables in file names


@@ -246,7 +246,7 @@ Archives}, for more about these features.
 or that is marked read-only, Emacs makes the buffer read-only too, so
 that you won't go ahead and make changes that you'll have trouble
 saving afterward.  You can make the buffer writable with @kbd{C-x C-q}
 or that is marked read-only, Emacs makes the buffer read-only too, so
 that you won't go ahead and make changes that you'll have trouble
 saving afterward.  You can make the buffer writable with @kbd{C-x C-q}

-(@code{toggle-read-only}).  @xref{Misc Buffer}.
+(@code{read-only-mode}).  @xref{Misc Buffer}.

 
 @kindex C-x C-r
 @findex find-file-read-only
 
 @kindex C-x C-r
 @findex find-file-read-only


@@ -734,10 +734,15 @@ file.
 @cindex locking files
   When you make the first modification in an Emacs buffer that is
 visiting a file, Emacs records that the file is @dfn{locked} by you.
 @cindex locking files
   When you make the first modification in an Emacs buffer that is
 visiting a file, Emacs records that the file is @dfn{locked} by you.

-(It does this by creating a specially-named symbolic link in the same
-directory.)  Emacs removes the lock when you save the changes.  The
-idea is that the file is locked whenever an Emacs buffer visiting it
-has unsaved changes.
+(It does this by creating a specially-named symbolic link or regular
+file with special contents in the same directory.)  Emacs removes the
+lock when you save the changes.  The idea is that the file is locked
+whenever an Emacs buffer visiting it has unsaved changes.
+
+@vindex create-lockfiles
+  You can prevent the creation of lock files by setting the variable
+@code{create-lockfiles} to @code{nil}.  @strong{Caution:} by
+doing so you will lose the benefits that this feature provides.

 
 @cindex collision
   If you begin to modify the buffer while the visited file is locked by
 
 @cindex collision
   If you begin to modify the buffer while the visited file is locked by


@@ -768,15 +773,15 @@ spurious, just use @kbd{p} to tell Emacs to go ahead anyway.
 multiple names, Emacs does not prevent two users from editing it
 simultaneously under different names.
 
 multiple names, Emacs does not prevent two users from editing it
 simultaneously under different names.
 

-  A lock file cannot be written in some circumstances, e.g. if Emacs
-lacks the system permissions or the system does not support symbolic
-links.  In these cases, Emacs can still detect the collision when you
-try to save a file, by checking the file's last-modification date.  If
-the file has changed since the last time Emacs visited or saved it,
-that implies that changes have been made in some other way, and will
-be lost if Emacs proceeds with saving.  Emacs then displays a warning
-message and asks for confirmation before saving; answer @kbd{yes} to
-save, and @kbd{no} or @kbd{C-g} cancel the save.
+  A lock file cannot be written in some circumstances, e.g., if Emacs
+lacks the system permissions or cannot create lock files for some
+other reason.  In these cases, Emacs can still detect the collision
+when you try to save a file, by checking the file's last-modification
+date.  If the file has changed since the last time Emacs visited or
+saved it, that implies that changes have been made in some other way,
+and will be lost if Emacs proceeds with saving.  Emacs then displays a
+warning message and asks for confirmation before saving; answer
+@kbd{yes} to save, and @kbd{no} or @kbd{C-g} cancel the save.

 
   If you are notified that simultaneous editing has already taken
 place, one way to compare the buffer to its file is the @kbd{M-x
 
   If you are notified that simultaneous editing has already taken
 place, one way to compare the buffer to its file is the @kbd{M-x


@@ -976,7 +981,7 @@ are not visiting files are auto-saved only if you request it explicitly;
 when they are auto-saved, the auto-save file name is made by appending
 @samp{#} to the front and rear of buffer name, then
 adding digits and letters at the end for uniqueness.  For
 when they are auto-saved, the auto-save file name is made by appending
 @samp{#} to the front and rear of buffer name, then
 adding digits and letters at the end for uniqueness.  For

-example, the @samp{*mail*} buffer in which you compose messages to be
+example, the @file{*mail*} buffer in which you compose messages to be

 sent might be auto-saved in a file named @file{#*mail*#704juu}.  Auto-save file
 names are made this way unless you reprogram parts of Emacs to do
 something different (the functions @code{make-auto-save-file-name} and
 sent might be auto-saved in a file named @file{#*mail*#704juu}.  Auto-save file
 names are made this way unless you reprogram parts of Emacs to do
 something different (the functions @code{make-auto-save-file-name} and


@@ -1096,11 +1101,11 @@ recover are present in Emacs buffers.  You should then save them.  Only
 this---saving them---updates the files themselves.
 
 @vindex auto-save-list-file-prefix
 this---saving them---updates the files themselves.
 
 @vindex auto-save-list-file-prefix

-  Emacs records information about interrupted sessions for later
-recovery in files named @file{.saves-@var{pid}-@var{hostname}} in the
-directory @file{~/.emacs.d/auto-save-list/}.  This directory is
-determined by the variable @code{auto-save-list-file-prefix}.  If you
-set @code{auto-save-list-file-prefix} to @code{nil}, sessions are not
+  Emacs records information about interrupted sessions in files named
+@file{.saves-@var{pid}-@var{hostname}} in the directory
+@file{~/.emacs.d/auto-save-list/}.  This directory is determined by
+the variable @code{auto-save-list-file-prefix}.  If you set
+@code{auto-save-list-file-prefix} to @code{nil}, sessions are not

 recorded for recovery.
 
 @node File Aliases
 recorded for recovery.
 
 @node File Aliases


@@ -1245,7 +1250,7 @@ for more information about using the Trash.
 @vindex diff-switches
   The command @kbd{M-x diff} prompts for two file names, using the
 minibuffer, and displays the differences between the two files in a
 @vindex diff-switches
   The command @kbd{M-x diff} prompts for two file names, using the
 minibuffer, and displays the differences between the two files in a

-buffer named @samp{*diff*}.  This works by running the @command{diff}
+buffer named @file{*diff*}.  This works by running the @command{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.  @xref{Top,, Diff, 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.  @xref{Top,, Diff, diff,


@@ -1336,11 +1341,11 @@ contents of the hunk.
   You can edit a Diff mode buffer like any other buffer.  (If it is
 read-only, you need to make it writable first.  @xref{Misc Buffer}.)
 Whenever you change a hunk, Diff mode attempts to automatically
   You can edit a Diff mode buffer like any other buffer.  (If it is
 read-only, you need to make it writable first.  @xref{Misc Buffer}.)
 Whenever you change a hunk, Diff mode attempts to automatically

-correct the line numbers in the hunk headers, to ensure that the diff
+correct the line numbers in the hunk headers, to ensure that the patch

 remains ``correct''.  To disable automatic line number correction,
 change the variable @code{diff-update-on-the-fly} to @code{nil}.
 
 remains ``correct''.  To disable automatic line number correction,
 change the variable @code{diff-update-on-the-fly} to @code{nil}.
 

-  Diff mode treats each hunk as an ``error message,'' similar to
+  Diff mode treats each hunk as an ``error message'', similar to

 Compilation mode.  Thus, you can use commands such as @kbd{C-x '} to
 visit the corresponding source locations.  @xref{Compilation Mode}.
 
 Compilation mode.  Thus, you can use commands such as @kbd{C-x '} to
 visit the corresponding source locations.  @xref{Compilation Mode}.
 


@@ -1465,11 +1470,22 @@ name from the patch itself.  This is useful for making log entries for
 functions that are deleted by the patch.
 @end table
 
 functions that are deleted by the patch.
 @end table
 

-  By default, Diff mode highlights trailing whitespace on modified
-lines, so that they are more obvious.  This is done by enabling
-Whitespace mode in the Diff buffer (@pxref{Useless Whitespace}).  Diff
-mode buffers are set up so that Whitespace mode avoids highlighting
-trailing whitespace occurring in the diff context.
+@c Trailing whitespace is NOT shown by default.
+@c Emacs's dir-locals file enables this (for some reason).
+@cindex trailing whitespace, in patches
+@findex diff-delete-trailing-whitespace
+  Patches sometimes include trailing whitespace on modified lines, as
+an unintentional and undesired change.  There are two ways to deal
+with this problem.  Firstly, if you enable Whitespace mode in a Diff
+buffer (@pxref{Useless Whitespace}), it automatically highlights
+trailing whitespace in modified lines.  Secondly, you can use the
+command @kbd{M-x diff-delete-trailing-whitespace}, which searches for
+trailing whitespace in the lines modified by the patch, and removes
+that whitespace in both the patch and the patched source file(s).
+This command does not save the modifications that it makes, so you can
+decide whether to save the changes (the list of modified files is
+displayed in the echo area).  With a prefix argument, it tries to
+modify the original source files rather than the patched source files.

 
 @node Misc File Ops
 @section Miscellaneous File Operations
 
 @node Misc File Ops
 @section Miscellaneous File Operations


@@ -1559,9 +1575,8 @@ open file @var{linkname} will refer to whatever file is named
 @var{target} at the time the opening is done, or will get an error if
 the name @var{target} is nonexistent at that time.  This command does
 not expand the argument @var{target}, so that it allows you to specify
 @var{target} at the time the opening is done, or will get an error if
 the name @var{target} is nonexistent at that time.  This command does
 not expand the argument @var{target}, so that it allows you to specify

-a relative name as the target of the link.  Not all systems support
-symbolic links; on systems that don't support them, this command is
-not defined.
+a relative name as the target of the link.  On MS-Windows, this
+command works only on MS Windows Vista and later.

 
 @kindex C-x i
 @findex insert-file
 
 @kindex C-x i
 @findex insert-file


@@ -1853,7 +1868,7 @@ When typing a file name in the minibuffer, @kbd{C-@key{tab}}
 (@code{file-cache-minibuffer-complete}) completes it using the file
 name cache.  If you repeat @kbd{C-@key{tab}}, that cycles through the
 possible completions of what you had originally typed.  (However, note
 (@code{file-cache-minibuffer-complete}) completes it using the file
 name cache.  If you repeat @kbd{C-@key{tab}}, that cycles through the
 possible completions of what you had originally typed.  (However, note

-that the @kbd{C-@key{tab}} character cannot be typed on most text-only
+that the @kbd{C-@key{tab}} character cannot be typed on most text

 terminals.)
 
   The file name cache does not fill up automatically.  Instead, you
 terminals.)
 
   The file name cache does not fill up automatically.  Instead, you


@@ -1922,19 +1937,25 @@ or taller than the frame, the usual point motion keys (@kbd{C-f},
 displayed.  If the image can be animated, the command @kbd{RET}
 (@code{image-toggle-animation}) starts or stops the animation.
 Animation plays once, unless the option @code{image-animate-loop} is
 displayed.  If the image can be animated, the command @kbd{RET}
 (@code{image-toggle-animation}) starts or stops the animation.
 Animation plays once, unless the option @code{image-animate-loop} is

-non-@code{nil}.  Currently, Emacs only supports animation in GIF
-files.
+non-@code{nil}.

 
 @cindex ImageMagick support
 
 @cindex ImageMagick support

-  If your Emacs was compiled with ImageMagick support, it is possible
-to view a much wider variety of image types in Image mode, by
-rendering the images via ImageMagick.  However, this feature is
-currently disabled by default.  To enable it, add the following line
-to your init file:
-
-@example
-(imagemagick-register-types)
-@end example
+@vindex imagemagick-enabled-types
+@vindex imagemagick-types-inhibit
+  If Emacs was compiled with support for the ImageMagick library, it
+can use ImageMagick to render a wide variety of images.  The variable
+@code{imagemagick-enabled-types} lists the image types that Emacs may
+render using ImageMagick; each element in the list should be an
+internal ImageMagick name for an image type, as a symbol or an
+equivalent string (e.g., @code{BMP} for @file{.bmp} images).  To
+enable ImageMagick for all possible image types, change
+@code{imagemagick-enabled-types} to @code{t}.  The variable
+@code{imagemagick-types-inhibit} lists the image types which should
+never be rendered using ImageMagick, regardless of the value of
+@code{imagemagick-enabled-types} (the default list includes types like
+@code{C} and @code{HTML}, which ImageMagick can render as an ``image''
+but Emacs should not).  To disable ImageMagick entirely, change
+@code{imagemagick-types-inhibit} to @code{t}.

 
 @findex thumbs-mode
 @findex mode, thumbs
 
 @findex thumbs-mode
 @findex mode, thumbs