]> code.delx.au - gnu-emacs/blobdiff - doc/emacs/files.texi
Document Image Mode's new animation features.
[gnu-emacs] / doc / emacs / files.texi
index 36cd3658e2df5595b4ab0d2f696e3e3aed9d921f..449ad9f2aa16e69f3477aced5b43ad8b4446b9c0 100644 (file)
@@ -1,6 +1,6 @@
 @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-2014 Free Software
+@c Foundation, Inc.
 @c See file emacs.texi for copying conditions.
 @node Files
 @chapter File Handling
@@ -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
-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
@@ -286,6 +286,10 @@ exception, dropping a file into a window displaying a Dired buffer
 moves or copies the file into the displayed directory.  For details,
 see @ref{Drag and Drop}, and @ref{Misc Dired Features}.
 
+  On text-mode terminals and on graphical displays when Emacs was
+built without a GUI toolkit, you can visit files via the menu-bar
+``File'' menu, which has a ``Visit New File'' item.
+
   Each time you visit a file, Emacs automatically scans its contents
 to detect what character encoding and end-of-line convention it uses,
 and converts these to Emacs's internal encoding and end-of-line
@@ -705,13 +709,27 @@ setting the latter variable, you can control how these modes handle
 final newlines.
 
 @vindex write-region-inhibit-fsync
-  When Emacs saves a file, it invokes the @code{fsync} system call to
-force the data immediately out to disk.  This is important for safety
-if the system crashes or in case of power outage.  However, it can be
-disruptive on laptops using power saving, as it may force a disk
-spin-up each time you save a file.  If you accept an increased risk of
-data loss, you can set @code{write-region-inhibit-fsync} to a
-non-@code{nil} value to disable the synchronization.
+  Normally, when a program writes a file, the operating system briefly
+caches the file's data in main memory before committing the data to
+disk.  This can greatly improve performance; for example, when running
+on laptops, it can avoid a disk spin-up each time a file is written.
+However, it risks data loss if the operating system crashes before
+committing the cache to disk.
+
+  To lessen this risk, Emacs can invoke the @code{fsync} system call
+after saving a file.  Using @code{fsync} does not eliminate the risk
+of data loss, partly because many systems do not implement
+@code{fsync} properly, and partly because Emacs's file-saving
+procedure typically relies also on directory updates that might not
+survive a crash even if @code{fsync} works properly.
+
+  The @code{write-region-inhibit-fsync} variable controls whether
+Emacs invokes @code{fsync} after saving a file.  The variable's
+default value is @code{nil} when Emacs is interactive, and @code{t}
+when Emacs runs in batch mode.
+
+  Emacs never uses @code{fsync} when writing auto-save files, as these
+files might lose data anyway.
 
 @node Interlocking
 @subsection Protection against Simultaneous Editing
@@ -734,10 +752,10 @@ 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.
-(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
@@ -773,15 +791,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.
 
-  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
@@ -1071,7 +1089,7 @@ of data with the command @kbd{M-x recover-file @key{RET} @var{file}
 restores the contents from its auto-save file @file{#@var{file}#}.
 You can then save with @kbd{C-x C-s} to put the recovered text into
 @var{file} itself.  For example, to recover file @file{foo.c} from its
-auto-save file @file{#foo.c#}, do:@refill
+auto-save file @file{#foo.c#}, do:
 
 @example
 M-x recover-file @key{RET} foo.c @key{RET}
@@ -1253,9 +1271,12 @@ minibuffer, and displays the differences between the two files in a
 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,
-Comparing and Merging Files}, for more information about the
-@command{diff} program.
+@code{"-c"} to specify a context diff.
+@c Note that the actual name of the info file is diffutils.info,
+@c but it adds a dir entry for diff too.
+@c On older systems, only "info diff" works, not "info diffutils".
+@xref{Top,, Diff, diff, Comparing and Merging Files}, for more
+information about the @command{diff} program.
 
   The output of the @code{diff} command is shown using a major mode
 called Diff mode.  @xref{Diff Mode}.
@@ -1341,7 +1362,7 @@ 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
-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}.
 
@@ -1398,6 +1419,7 @@ In a multi-file patch, kill the current file part.
 
 @item C-c C-a
 @findex diff-apply-hunk
+@cindex patches, applying
 Apply this hunk to its target file (@code{diff-apply-hunk}).  With a
 prefix argument of @kbd{C-u}, revert this hunk.
 
@@ -1470,11 +1492,22 @@ name from the patch itself.  This is useful for making log entries for
 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
@@ -1911,10 +1944,9 @@ point.  Partial Completion mode offers other features extending
 
 @findex image-mode
 @findex image-toggle-display
-@findex image-toggle-animation
+@findex image-next-file
+@findex image-previous-file
 @cindex images, viewing
-@cindex image animation
-@cindex animated images
   Visiting image files automatically selects Image mode.  In this
 major mode, you can type @kbd{C-c C-c} (@code{image-toggle-display})
 to toggle between displaying the file as an image in the Emacs buffer,
@@ -1923,11 +1955,33 @@ Displaying the file as an image works only if Emacs is compiled with
 support for displaying such images.  If the displayed image is wider
 or taller than the frame, the usual point motion keys (@kbd{C-f},
 @kbd{C-p}, and so forth) cause different parts of the image to be
-displayed.  If the image can be animated, the command @kbd{RET}
+displayed.  You can press @kbd{n} (@code{image-next-file}) and @kbd{p}
+(@code{image-previous-file}) to visit the next image file and the
+previous image file in the same directory, respectively.
+
+@findex image-toggle-animation
+@findex image-next-frame
+@findex image-previous-frame
+@findex image-goto-frame
+@findex image-increase-speed
+@findex image-decrease-speed
+@findex image-reset-speed
+@findex image-reverse-speed
+@vindex image-animate-loop
+@cindex image animation
+@cindex animated images
+  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}.  With @kbd{f} (@code{image-next-frame}) and @kbd{b}
+(@code{image-previous-frame}) you can step through the individual
+frames.  Both commands accept a numeric prefix to step through several
+frames at once.  You can go to a specific frame with @kbd{F}
+(@code{image-goto-frame}).  The speed of the animation can be
+increased by pressing @kbd{a +} (@code{image-increase-speed}) and
+decreased by pressing @kbd{a -} (@code{image-decrease-speed}).  With
+@kbd{a r} (@code{image-reverse-speed}) the speed is reversed.  You can
+reset the speed with @kbd{a 0} (@code{image-reset-speed}).
 
 @cindex ImageMagick support
 @vindex imagemagick-enabled-types
@@ -1937,7 +1991,7 @@ 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
+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
@@ -1955,6 +2009,7 @@ thumbnails.  @xref{Image-Dired}.
 @node Filesets
 @section Filesets
 @cindex filesets
+@cindex sets of files
 
 @findex filesets-init
   If you regularly edit a certain group of files, you can define them