@comment %**end of header
@copying
-This file describes specialized features of Emacs.
+This manual describes specialized features of Emacs.
-Copyright (C) 2004
-Free Software Foundation, Inc.
+Copyright @copyright{} 2004, 2005, 2006 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
+under the terms of the GNU Free Documentation License, Version 1.2 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
@end ifnottex
@menu
-* Introduction:: What documentation belongs here?
-* Autorevert:: Auto Reverting non-file buffers.
-* Subdir switches:: Subdirectory switches in Dired.
+* Introduction:: What documentation belongs here?
+@iftex
+* Picture Mode:: Editing pictures made up of characters using
+ the quarter-plane screen model.
+
+* Autorevert:: Auto Reverting non-file buffers.
+* Subdir Switches:: Subdirectory switches in Dired.
+* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
+* Emerge:: A convenient way of merging two versions of a program.
+* Advanced VC Usage:: Advanced VC (version control) features.
+* Fortran:: Fortran mode and its special features.
+* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}).
+@end iftex
* Index::
@end menu
@unnumbered Introduction
This manual contains detailed information about various features that
-are too specialized to be included in the Emacs manual. It is
+are too specialized to be included in the printed 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.
+Certain packages, or collections of related features, have their own
+manuals, separate from the main Emacs User's manual. This manual is
+intended as a complement, rather than an alternative, to reading those
+additional manuals; in a nutshell, it is a collection of smaller
+specialized features, too small or too obscure to justify 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
+@iftex
+@c ``Picture Mode'' is a chapter, not a section, so it's outside @raisesections.
+@include picture-xtra.texi
-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.
+@raisesections
+@include arevert-xtra.texi
-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.
+@include dired-xtra.texi
-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.
+@include cal-xtra.texi
-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}.
+@include emerge-xtra.texi
-The details depend on the particular types of buffers and are
-explained in the corresponding sections.
+@include vc-xtra.texi
-@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.
-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.
-
-@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}.
+@include fortran-xtra.texi
-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.)
+@include msdog-xtra.texi
-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.
+@lowersections
+@end iftex
@node Index
@unnumbered Index