New .texi file

[Luc Teirlinck <teirllm@dms.auburn.edu>]

I would want to include the .texi file below in emacs/man, together
with a bunch of minor supporting changes.  I could install all of this
if it seems OK.

The direct motivation for the .texi file below was to document
auto-reverting of non-file buffers, both for end users and for people
wanting to enable auto-reverting for additional types of buffers.

For both purposes, I want to use the Texinfo format.  Docstrings,
`Commentary' sections and the like have their limitations.  The stuff
is too big for the docstring of `global-auto-revert-non-file-buffers'.
So I wanted a .texi file with a hyperlink from the docstring.  On the
other hand, the stuff is too small for a separate manual.

I have seen other people struggle with similar problems.  Usually they
want stuff documented in the Emacs manual and are told that it already
is too big.  Proposed solutions like having two Emacs manuals, one
smaller printed version and one larger online version seem very
unattractive to me.

So what about a separate .texi file for a variety of stuff that does
not fit in the Emacs manual and is too small for its own manual?
Hyperlinks can be made to it from docstrings, Custom buffers, as well
as from the Emacs and Elisp manuals and it can be referenced from
`Commentary' sections of packages, even though these do not support
hyperlinks as such.  Also, users could quickly browse the file to see
if there is anything of interest to them that they might want to read
in full detail.

The file below currently documents one second feature, subdirectories
with non-default switches in Dired.  This is intended a an example of
a smaller, one node feature description.  More features could be added
later as additional nodes in the main menu.

I do not know whether `buffer-stale-function', documented in the file
below, should actually be documented in the Elisp manual.  If it would
be, then its documentation in the file below could be replaced with a
hyperlink to the Elisp manual.

The file requires the following anchor in backups.texi:

===File ~/backups-diff======================================
*** backups.texi	02 Apr 2004 21:07:22 -0600	1.27
--- backups.texi	12 Jun 2004 15:20:19 -0500	
***************
*** 712,717 ****
--- 712,718 ----
    Some major modes customize @code{revert-buffer} by making
  buffer-local bindings for these variables:
  
+ @anchor{Definition of revert-buffer-function}
  @defvar revert-buffer-function
  The value of this variable is the function to use to revert this
  buffer.  If non-@code{nil}, it should be a function with two optional
============================================================

Here is the main file:

===File ~/emacs-x.texi======================================
\input texinfo    @c -*-texinfo-*-
@comment %**start of header
@setfilename ../info/emacs-x
@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-X: (emacs-x).   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::               Subdir 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,
one 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.

One 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, one should add a node to this chapter's menu.  This node
@end ifinfo
@ifnotinfo
Finally, one 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 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 default switches using
@kbd{M-x dired-reset-subdir-switches}.  This also reverts the Dired buffer.

@node Index
@unnumbered Index

@printindex cp

@bye
============================================================

Here is an hyperlink to the file.  Additional hyperlinks to the file
could be useful.

===File ~/autorevert-diff===================================
*** autorevert.el	30 May 2004 16:30:46 -0500	1.31
--- autorevert.el	12 Jun 2004 16:24:43 -0500	
***************
*** 185,191 ****
  buffer needs updating may be imperfect, due to efficiency
  considerations, and may not take all information listed in the
  buffer into account.  Hence, a non-nil value for this option does
! not necessarily make manual updates useless for non-file buffers."
    :group 'auto-revert
    :type 'boolean)
  
--- 185,194 ----
  buffer needs updating may be imperfect, due to efficiency
  considerations, and may not take all information listed in the
  buffer into account.  Hence, a non-nil value for this option does
! not necessarily make manual updates useless for non-file buffers.
! 
! To find out to which buffers this option currently applies, as
! well as for further details, see Info node `(emacs-x)Autorevert'."
    :group 'auto-revert
    :type 'boolean)
  
============================================================

Installing the file through the Emacs distribution also requires
adding the line:

* Emacs-X: (emacs-x).   Specialized Emacs features.

to emacs/info/dir and the following patches to Makefile.in and
man/Makefile.in:

===File ~/Makefile.in-diff==================================
*** Makefile.in	11 Jun 2004 15:08:27 -0500	1.291
--- Makefile.in	12 Jun 2004 12:05:20 -0500	
***************
*** 474,480 ****
  	      chmod a+r ${infodir}/dir); \
  	   fi; \
  	   cd ${srcdir}/info ; \
! 	   for f in ada-mode* autotype* calc* ccmode* cl* dired-x* ebrowse* ediff* efaq* eintr* elisp* emacs* eshell* eudc* forms* gnus* idlwave* info* message* mh-e* pcl-cvs* reftex* sc* ses* speedbar* tramp* vip* widget* woman* smtpmail*; do \
  	     (cd $${thisdir}; \
  	      ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
  	      chmod a+r ${infodir}/$$f); \
--- 474,480 ----
  	      chmod a+r ${infodir}/dir); \
  	   fi; \
  	   cd ${srcdir}/info ; \
! 	   for f in ada-mode* autotype* calc* ccmode* cl* dired-x* ebrowse* ediff* efaq* eintr* elisp* emacs* emacs-x* eshell* eudc* forms* gnus* idlwave* info* message* mh-e* pcl-cvs* reftex* sc* ses* speedbar* tramp* vip* widget* woman* smtpmail*; do \
  	     (cd $${thisdir}; \
  	      ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
  	      chmod a+r ${infodir}/$$f); \
***************
*** 484,490 ****
  	thisdir=`/bin/pwd`; \
  	if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
  	then \
! 	  for f in ada-mode autotype calc ccmode cl dired-x ebrowse ediff efaq elisp eintr emacs emacs-mime eshell eudc forms gnus idlwave info message mh-e pcl-cvs reftex sc ses speedbar tramp vip viper widget woman smtpmail; do \
  	    (cd $${thisdir}; \
  	     ${INSTALL_INFO} --info-dir=${infodir} ${infodir}/$$f); \
  	  done; \
--- 484,490 ----
  	thisdir=`/bin/pwd`; \
  	if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
  	then \
! 	  for f in ada-mode autotype calc ccmode cl dired-x ebrowse ediff efaq elisp eintr emacs emacs-mime emacs-x eshell eudc forms gnus idlwave info message mh-e pcl-cvs reftex sc ses speedbar tramp vip viper widget woman smtpmail; do \
  	    (cd $${thisdir}; \
  	     ${INSTALL_INFO} --info-dir=${infodir} ${infodir}/$$f); \
  	  done; \
***************
*** 550,556 ****
  	done
  	(cd ${archlibdir} && rm -f fns-*)
  	-rm -rf ${libexecdir}/emacs/${version}
! 	(cd ${infodir} && rm -f cl* ada-mode* autotype* calc* ccmode* ebrowse* efaq* eintr elisp* eshell* eudc* idlwave* message* pcl-cvs* reftex* speedbar* tramp* widget* woman* dired-x* ediff* emacs* forms* gnus* info* mh-e* sc* ses* vip* smtpmail*)
  	(cd ${man1dir}  && rm -f emacs${manext} emacsclient${manext} etags${manext} ctags${manext})
  	(cd ${bindir}  && rm -f $(EMACSFULL) $(EMACS))
  
--- 550,556 ----
  	done
  	(cd ${archlibdir} && rm -f fns-*)
  	-rm -rf ${libexecdir}/emacs/${version}
! 	(cd ${infodir} && rm -f cl* ada-mode* autotype* calc* ccmode* ebrowse* efaq* eintr elisp* eshell* eudc* idlwave* message* pcl-cvs* reftex* speedbar* tramp* widget* woman* dired-x* ediff* emacs* emacs-x* forms* gnus* info* mh-e* sc* ses* vip* smtpmail*)
  	(cd ${man1dir}  && rm -f emacs${manext} emacsclient${manext} etags${manext} ctags${manext})
  	(cd ${bindir}  && rm -f $(EMACSFULL) $(EMACS))
  
============================================================

===File ~/man-Makefile.in-diff==============================
*** Makefile.in	11 Jun 2004 15:10:03 -0500	1.54
--- Makefile.in	12 Jun 2004 14:00:25 -0500	
***************
*** 33,39 ****
  
  # The makeinfo program is part of the Texinfo distribution.
  MAKEINFO = makeinfo
! INFO_TARGETS = ../info/emacs ../info/ccmode ../info/cl \
  	        ../info/dired-x ../info/ediff ../info/forms ../info/gnus \
  		../info/info ../info/message ../info/mh-e ../info/reftex \
  		../info/sc ../info/vip ../info/viper ../info/widget \
--- 33,39 ----
  
  # The makeinfo program is part of the Texinfo distribution.
  MAKEINFO = makeinfo
! INFO_TARGETS = ../info/emacs ../info/emacs-x ../info/ccmode ../info/cl \
  	        ../info/dired-x ../info/ediff ../info/forms ../info/gnus \
  		../info/info ../info/message ../info/mh-e ../info/reftex \
  		../info/sc ../info/vip ../info/viper ../info/widget \
***************
*** 42,48 ****
  		../info/woman ../info/emacs-mime ../info/eshell \
  		../info/speedbar ../info/tramp ../info/ses ../info/smtpmail \
  		../info/flymake
! DVI_TARGETS = 	emacs.dvi calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \
  		 ediff.dvi forms.dvi gnus.dvi message.dvi mh-e.dvi \
  		 reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \
  		 ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \
--- 42,48 ----
  		../info/woman ../info/emacs-mime ../info/eshell \
  		../info/speedbar ../info/tramp ../info/ses ../info/smtpmail \
  		../info/flymake
! DVI_TARGETS = 	emacs.dvi emacs-x.dvi calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \
  		 ediff.dvi forms.dvi gnus.dvi message.dvi mh-e.dvi \
  		 reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \
  		 ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \
***************
*** 174,179 ****
--- 174,184 ----
  ediff.dvi: ediff.texi
  	$(ENVADD) $(TEXI2DVI) ${srcdir}/ediff.texi
  
+ ../info/emacs-x: emacs-x.texi
+ 	cd $(srcdir); $(MAKEINFO) emacs-x.texi
+ emacs-x.dvi: emacs-x.texi
+ 	$(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-x.texi
+ 
  ../info/forms: forms.texi
  	cd $(srcdir); $(MAKEINFO) forms.texi
  forms.dvi: forms.texi
============================================================