\input texinfo @c -*-texinfo-*- @comment %**start of header @setfilename ../info/emacs-xtra @settitle Specialized Emacs Features @syncodeindex fn cp @syncodeindex vr cp @syncodeindex ky cp @comment %**end of header @copying This manual describes specialized features of Emacs. Copyright (C) 2004 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License'' in the Emacs manual. (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.'' This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license. @end quotation @end copying @dircategory Emacs @direntry * Emacs-Xtra: (emacs-xtra). Specialized Emacs features. @end direntry @titlepage @title Specialized Emacs Features @page @vskip 0pt plus 1filll @insertcopying @end titlepage @contents @ifnottex @node Top @top Specialized Emacs Features @insertcopying @end ifnottex @menu * Introduction:: What documentation belongs here? * Autorevert:: Auto Reverting non-file buffers. * Subdir switches:: Subdirectory switches in Dired. * Index:: @end menu @node Introduction @unnumbered Introduction This manual contains detailed information about various features that are too specialized to be included in the Emacs manual. It is intended to be readable by anyone having a basic knowledge of Emacs. However, certain sections may be intended for a more specialized audience, such as Elisp authors. This should be clearly pointed out at the beginning of these sections. This manual is intended as a complement, rather than an alternative, to other ways to gain a more detailed knowledge of Emacs than the Emacs manual can provide, such as browsing packages using @kbd{C-h p}, accessing mode documentation using @kbd{C-h m} and browsing user options using Custom. Also, certain packages, or collections of related features, have their own manuals. The present manual is mainly intended to be a collection of smaller specialized features, too small to get their own manual. Sections intended specifically for Elisp programmers can follow the style of the Elisp manual. Other sections should follow the style of the Emacs manual. @node Autorevert @chapter Auto Reverting non-file Buffers Normally Global Auto Revert Mode only reverts file buffers. There are two ways to auto-revert certain non-file buffers: enabling Auto Revert Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting @code{global-auto-revert-non-file-buffers} to @code{t}. The latter enables Auto Reverting for all types of buffers for which it is implemented, that is, for the types of buffers listed in the menu below. Like file buffers, non-file buffers should normally not revert while you are working on them, or while they contain information that might get lost after reverting. Therefore, they do not revert if they are ``modified''. This can get tricky, because deciding when a non-file buffer should be marked modified is usually more difficult than for file buffers. Another tricky detail is that, for efficiency reasons, Auto Revert often does not try to detect all possible changes in the buffer, only changes that are ``major'' or easy to detect. Hence, enabling auto-reverting for a non-file buffer does not always guarantee that all information in the buffer is up to date and does not necessarily make manual reverts useless. At the other extreme, certain buffers automatically auto-revert every @code{auto-revert-interval} seconds. (This currently only applies to the Buffer Menu.) In this case, Auto Revert does not print any messages while reverting, even when @code{auto-revert-verbose} is non-@code{nil}. The details depend on the particular types of buffers and are explained in the corresponding sections. @menu * Auto Reverting the Buffer Menu:: * Auto Reverting Dired:: * Supporting additional buffers:: @end menu @node Auto Reverting the Buffer Menu @section Auto Reverting the Buffer Menu If auto-reverting of non-file buffers is enabled, the Buffer Menu automatically reverts every @code{auto-revert-interval} seconds, whether there is a need for it or not. (It would probably take longer to check whether there is a need than to actually revert.) If the Buffer Menu inappropriately gets marked modified, just revert it manually using @kbd{g} and auto-reverting will resume. However, if you marked certain buffers to get deleted or to be displayed, you have to be careful, because reverting erases all marks. The fact that adding marks sets the buffer's modified flag prevents Auto Revert from automatically erasing the marks. @node Auto Reverting Dired @section Auto Reverting Dired buffers Auto-reverting Dired buffers currently works on GNU or Unix style operating systems. It may not work satisfactorily on some other systems. Dired buffers only auto-revert when the file list of the buffer's main directory changes. They do not auto-revert when information about a particular file changes or when inserted subdirectories change. To be sure that @emph{all} listed information is up to date, you have to manually revert using @kbd{g}, @emph{even} if auto-reverting is enabled in the Dired buffer. Sometimes, you might get the impression that modifying or saving files listed in the main directory actually does cause auto-reverting. This is because making changes to a file, or saving it, very often causes changes in the directory itself, for instance, through backup files or auto-save files. However, this is not guaranteed. If the Dired buffer is marked modified and there are no changes you want to protect, then most of the time you can make auto-reverting resume by manually reverting the buffer using @kbd{g}. There is one exception. If you flag or mark files, you can safely revert the buffer. This will not erase the flags or marks (unless the marked file has been deleted, of course). However, the buffer will stay modified, even after reverting, and auto-reverting will not resume. This is because, if you flag or mark files, you may be working on the buffer and you might not want the buffer to change without warning. If you want auto-reverting to resume in the presence of marks and flags, mark the buffer non-modified using @kbd{M-~}. However, adding, deleting or changing marks or flags will mark it modified again. Remote Dired buffers are not auto-reverted. Neither are Dired buffers for which you used shell wildcards or file arguments to list only some of the files. @samp{*Find*} and @samp{*Locate*} buffers do not auto-revert either. @node Supporting additional buffers @section Adding Support for Auto-Reverting additional Buffers. This section is intended for Elisp programmers who would like to add support for auto-reverting new types of buffers. To support auto-reverting the buffer must first of all have a @code{revert-buffer-function}. @xref{Definition of revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. In addition, it @emph{must} have a @code{buffer-stale-function}. @defvar buffer-stale-function The value of this variable is a function to check whether a non-file buffer needs reverting. This should be a function with one optional argument @var{noconfirm}. The function should return non-@code{nil} if the buffer should be reverted. The buffer is current when this function is called. While this function is mainly intended for use in auto-reverting, it could be used for other purposes as well. For instance, if auto-reverting is not enabled, it could be used to warn the user that the buffer needs reverting. The idea behind the @var{noconfirm} argument is that it should be @code{t} if the buffer is going to be reverted without asking the user and @code{nil} if the function is just going to be used to warn the user that the buffer is out of date. In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. If the function is only going to be used for auto-reverting, you can ignore the @var{noconfirm} argument. If you just want to automatically auto-revert every @code{auto-revert-interval} seconds, use: @example (set (make-local-variable 'buffer-stale-function) #'(lambda (&optional noconfirm) 'fast)) @end example @noindent in the buffer's mode function. The special return value @samp{fast} tells the caller that the need for reverting was not checked, but that reverting the buffer is fast. It also tells Auto Revert not to print any revert messages, even if @code{auto-revert-verbose} is non-@code{nil}. This is important, as getting revert messages every @code{auto-revert-interval} seconds can be very annoying. The information provided by this return value could also be useful if the function is consulted for purposes other than auto-reverting. @end defvar Once the buffer has a @code{revert-buffer-function} and a @code{buffer-stale-function}, several problems usually remain. The buffer will only auto-revert if it is marked unmodified. Hence, you will have to make sure that various functions mark the buffer modified if and only if either the buffer contains information that might be lost by reverting or there is reason to believe that the user might be inconvenienced by auto-reverting, because he is actively working on the buffer. The user can always override this by manually adjusting the modified status of the buffer. To support this, calling the @code{revert-buffer-function} on a buffer that is marked unmodified should always keep the buffer marked unmodified. It is important to assure that point does not continuously jump around as a consequence of auto-reverting. Of course, moving point might be inevitable if the buffer radically changes. You should make sure that the @code{revert-buffer-function} does not print messages that unnecessarily duplicate Auto Revert's own messages if @code{auto-revert-verbose} is @code{t} and effectively override a @code{nil} value for @code{auto-revert-verbose}. Hence, adapting a mode for auto-reverting often involves getting rid of such messages. This is especially important for buffers that automatically auto-revert every @code{auto-revert-interval} seconds. Also, you may want to update the documentation string of @code{global-auto-revert-non-file-buffers}. @ifinfo Finally, you should add a node to this chapter's menu. This node @end ifinfo @ifnotinfo Finally, you should add a section to this chapter. This section @end ifnotinfo should at the very least make clear whether enabling auto-reverting for the buffer reliably assures that all information in the buffer is completely up to date (or will be after @code{auto-revert-interval} seconds). @node Subdir switches @chapter Subdirectory Switches in Dired You can insert subdirectories with specified @code{ls} switches in Dired buffers, using @kbd{C-u i}. You can change the @code{ls} switches of an already inserted subdirectory using @kbd{C-u l}. In Emacs versions 21.4 and later, Dired remembers the switches, so that reverting the buffer will not change them back to the main directory's switches. Deleting a subdirectory forgets about its switches. Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) to reinsert or delete subdirectories, that were inserted with explicit switches, can bypass Dired's machinery for remembering (or forgetting) switches. Deleting a subdirectory using @code{dired-undo} does not forget its switches. When later reinserted using @kbd{i}, it will be reinserted using its old switches. Using @code{dired-undo} to reinsert a subdirectory that was deleted using the regular Dired commands (not @code{dired-undo}) will originally insert it with its old switches. However, reverting the buffer will relist it using the buffer's default switches. If any of this yields problems, you can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. Dired does not remember the @code{R} switch. Inserting a subdirectory with switches that include the @code{R} switch is equivalent with inserting each of its subdirectories using all remaining switches. For instance, updating or killing a subdirectory that was inserted with the @code{R} switch will not update or kill its subdirectories. The buffer's default switches do not affect subdirectories that were inserted using explicitly specified switches. In particular, commands such as @kbd{s}, that change the buffer's switches do not affect such subdirectories. (They do affect subdirectories without explicitly assigned switches, however.) You can make Dired forget about all subdirectory switches and relist all subdirectories with the buffer's default switches using @kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. @node Index @unnumbered Index @printindex cp @bye @ignore arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49 @end ignore