X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/9d6b4d53469a9ffd67bd770fabc6fe254e35c21d..343a2aefb528ce3c978ba2145705b9e37bfbe02a:/doc/emacs/files.texi diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 0d38728f7c..1f78747eaa 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1,8 +1,8 @@ @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. -@node Files, Buffers, Keyboard Macros, Top +@node 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 -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 @@ -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 -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 @@ -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} -(@code{toggle-read-only}). @xref{Misc Buffer}. +(@code{read-only-mode}). @xref{Misc Buffer}. @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. -(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 @@ -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. - 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 @@ -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 -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 @@ -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 - 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 @@ -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 -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, @@ -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 -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}. - 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}. @@ -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 - 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 @@ -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 -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 @@ -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 -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 @@ -1911,27 +1926,41 @@ point. Partial Completion mode offers other features extending @cindex images, viewing @cindex image animation @cindex animated images - Visiting image files automatically selects Image mode. This major -mode allows you to toggle between displaying the file as an image in -the Emacs buffer, and displaying its underlying text representation, -using the command @kbd{C-c C-c} (@code{image-toggle-display}). This -works only when Emacs can display the specific image type@footnote{If -your Emacs was compiled with ImageMagick support, then after using -@code{imagemagick-register-types}, you can view in Image mode any -image type that ImageMagick supports; @pxref{ImageMagick Images,,, -elisp, The Emacs Lisp Reference Manual}}. If the displayed image is wider + 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, +and displaying its underlying text (or raw byte) representation. +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, then the command @kbd{RET} -(@code{image-toggle-animation}), will start (or stop) animating it. +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 animated GIF files -(@pxref{Animated Images,,, elisp, The Emacs Lisp Reference Manual}). +non-@code{nil}. + +@cindex ImageMagick support +@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 - See also the Image-Dired package (@pxref{Image-Dired}) for viewing -images as thumbnails. + The Image-Dired package can also be used to view images as +thumbnails. @xref{Image-Dired}. @node Filesets @section Filesets