# HG changeset patch # User Luc Teirlinck # Date 1087332924 0 # Node ID 23a626038a46146b40d5ddc9d59b8cc9cb9165de # Parent 6fbabfb26a3c464776974d6a2739f6b6443db5f7 New file. diff -r 6fbabfb26a3c -r 23a626038a46 man/emacs-xtra.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/emacs-xtra.texi Tue Jun 15 20:55:24 2004 +0000 @@ -0,0 +1,294 @@ +\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 file 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. + +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 only works satisfactorily on +GNU/Linux and Unix style operating 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, then, unlike for the Buffer +Menu, 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. +This information could 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. + +@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}. + +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