[Emacs-diffs] Changes to emacs/man/emacs-xtra.texi [lexbind]

[Miles Bader]

Index: emacs/man/emacs-xtra.texi
diff -c /dev/null emacs/man/emacs-xtra.texi:1.5.4.1
*** /dev/null   Tue Jul  6 10:18:17 2004
--- emacs/man/emacs-xtra.texi   Tue Jul  6 10:17:14 2004
***************
*** 0 ****
--- 1,313 ----
+ \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
+ address@hidden
+ 
+ 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 address@hidden
+ 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 address@hidden  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}.
+ 
+ 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