New file.

man/emacs-xtra.texi

@@ -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