--- /dev/null
+1999-07-12 Richard Stallman <rms@gnu.org>
+
+ * Version 20.4 released.
+
+1999-02-22 Andreas Schwab <schwab@gnu.org>
+
+ * gnus.texi: Fix punctuation after @xref.
+
+1999-01-18 Eli Zaretskii <eliz@gnu.org>
+
+ * msdog.texi (MS-DOS and MULE): dos-unsupported-character-glyph is
+ a triangle by default, not a solid box.
+
+1999-01-17 Andrew Innes <andrewi@gnu.org>
+
+ * msdog.texi (MS-DOS Printing): Rewrite section.
+
+ * emacs.texi (Top): Include Windows 98 in the MS-DOS section.
+
+1998-12-04 Markus Rost <rost@delysid.gnu.org>
+
+ * Makefile.in (INFO_TARGETS): Delete customize.info.
+ (DVI_TARGETS): Delete customize.dvi.
+ (../info/customize, customize.dvi): Targets deleted.
+
+1998-11-18 Richard Stallman <rms@psilocin.ai.mit.edu>
+
+ * customize.texi: File deleted.
+
+1998-11-08 Eli Zaretskii <eliz@mescaline.gnu.org>
+
+ * frames.texi: Change @xref to @pxref and add comma after @xref.
+ * custom.texi (Locals): Likewise.
+ * programs.texi (Fortran Autofill): Likewise.
+ * text.texi (TeX Editing): Likewise.
+ * viper.texi: Likewise.
+
+1998-08-24 Andreas Schwab <schwab@delysid.gnu.org>
+
+ * reftex.texi: Fix info file name.
+
+ * forms.texi (Forms Commands): Change @item to @itemx for
+ secondary items.
+ * viper.texi (Groundwork): Likewise.
+ (Commands): Remove extra Top from @node.
+
+1998-08-19 Richard Stallman <rms@psilocin.ai.mit.edu>
+
+ * Version 20.3 released.
+
+1998-08-10 Carsten Dominik <cd@delysid.gnu.org>
+
+ * reftex.texi: Updated to the latest RefTeX version.
+
+1998-05-06 Richard Stallman <rms@psilocin.gnu.org>
+
+ * Makefile.in (EMACSSOURCES): Add mule.texi.
+ Add msdog.texi, ack.texi. Remove gnu1.texi.
+
+1998-04-06 Andreas Schwab <schwab@gnu.org>
+
+ * Makefile.in (ENVADD): Enviroment vars to pass to texi2dvi. Use
+ it in dvi targets.
+ (../etc/GNU): Change to $(srcdir) first.
+
+1998-03-11 Carsten Dominik <cd@delysid.gnu.org>
+
+ * reftex.texi Updated for RefTeX version 3.22.
+
+1998-02-08 Richard Stallman <rms@psilocin.gnu.org>
+
+ * Makefile.in (reftex.dvi, ../info/reftex): New targets.
+ (INFO_TARGETS, DVI_TARGETS): Add the new targets.
+
+1997-09-23 Paul Eggert <eggert@twinsun.com>
+
+ * Makefile.in: Merge changes mistakenly made to `Makefile'.
+ (INFO_TARGETS): Change ../info/custom to ../info/customize.
+ (../info/customize): Renamed from ../info/custom.
+ (../info/viper, viper.dvi): Remove dependency on viper-cmd.texi.
+
+1997-09-19 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
+
+ * Version 20.2 released.
+
+1997-09-15 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
+
+ * Version 20.1 released.
+
+1997-08-24 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
+
+ * Makefile (../info/customize, customize.dvi): New targets.
+ (INFO_TARGETS): Add ../info/customize.
+ (DVI_TARGETS): Add customize.dvi.
+
+1997-07-10 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
+
+ * Makefile (../info/viper, viper.dvi): Delete viper-cmd.texi dep.
+
+1996-08-11 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
+
+ * Version 19.33 released.
+
+1996-07-31 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
+
+ * Version 19.32 released.
+
+1996-06-27 Lars Magne Ingebrigtsen <larsi@ifi.uio.no>
+
+ * Makefile.in: Add rules for the Message manual.
+
+1996-06-26 Lars Magne Ingebrigtsen <larsi@ifi.uio.no>
+
+ * gnus.texi: New version.
+
+ * message.texi: New manual.
+
+1996-06-20 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
+
+ * Makefile.in (All info targets): cd $(srcdir) to do the work.
+
+1996-06-19 Richard Stallman <rms@psilocin.gnu.ai.mit.edu>
+
+ * Makefile.in (All info targets): Specify $(srcdir) in input files.
+ Specify -I option.
+ (All dvi targets): Set the TEXINPUTS variable.
+
+1996-05-25 Karl Heuer <kwzh@gnu.ai.mit.edu>
+
+ * Version 19.31 released.
+
+1996-01-07 Richard Stallman <rms@whiz-bang.gnu.ai.mit.edu>
+
+ * Makefile.in (../info/ccmode): Renamed from ../info/cc-mode.
+ (INFO_TARGETS): Use new name. This avoids name conflict on MSDOS.
+
+1995-11-29 Richard Stallman <rms@mole.gnu.ai.mit.edu>
+
+ * Makefile.in (../info/cc-mode, cc-mode.dvi): New targets.
+ (INFO_TARGETS): Add ../info/cc-mode.
+ (DVI_TARGETS): Add cc-mode.dvi.
+
+1995-11-24 Richard Stallman <rms@mole.gnu.ai.mit.edu>
+
+ * Version 19.30 released.
+
+1995-11-04 Lars Magne Ingebrigtsen <larsi@ifi.uio.no>
+
+ * gnus.texi: New file.
+
+1995-11-04 Erik Naggum <erik@naggum.no>
+
+ * gnus.texi: File deleted.
+
+1995-11-02 Stephen Gildea <gildea@x.org>
+
+ * mh-e.texi: "Function Index" -> "Command Index" to work with
+ Emacs 19.30 C-h C-k support of separately-documented commands.
+
+1995-06-26 Richard Stallman <rms@mole.gnu.ai.mit.edu>
+
+ * Makefile.in (../info/ediff, ediff.dvi): New targets.
+ (INFO_TARGETS, DVI_TARGETS): Add those new targets.
+
+1995-04-24 Richard Stallman <rms@mole.gnu.ai.mit.edu>
+
+ * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add viper targets.
+ (../info/viper, viper.dvi): New targets.
+
+1995-04-20 Kevin Rodgers <kevinr@ihs.com>
+
+ * dired-x.texi (Installation): Change the example to set
+ buffer-local variables like dired-omit-files-p in
+ dired-mode-hook.
+
+1995-04-17 Richard Stallman <rms@mole.gnu.ai.mit.edu>
+
+ * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add mh-e targets.
+ (../info/mh-e, mh-e.dvi): New targets.
+
+1995-02-07 Richard Stallman <rms@pogo.gnu.ai.mit.edu>
+
+ * Makefile.in (maintainer-clean): Renamed from realclean.
+
+1994-11-23 Richard Stallman <rms@mole.gnu.ai.mit.edu>
+
+ * Makefile.in: New file.
+ * Makefile: File deleted.
+
+1994-11-19 Richard Stallman <rms@mole.gnu.ai.mit.edu>
+
+ * Makefile (TEXINDEX_OBJS): Variable deleted.
+ (texindex, texindex.o, getopt.o): Rules deleted.
+ All deps on texindex deleted.
+ (distclean): Don't delete texindex.
+ (mostlyclean): Don't delete *.o.
+ * texindex.c, getopt.c: Files deleted.
+
+1994-09-07 Richard Stallman <rms@mole.gnu.ai.mit.edu>
+
+ * Version 19.26 released.
+
+1994-07-02 Richard Stallman (rms@gnu.ai.mit.edu)
+
+ * Makefile (EMACSSOURCES): Exclude undo.texi.
+
+1994-05-30 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Version 19.25 released.
+
+1994-05-23 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Version 19.24 released.
+
+1994-05-16 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Version 19.23 released.
+
+1994-04-17 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Makefile: Delete spurious tab.
+
+1994-02-16 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Makefile (.SUFFIXES): New rule.
+
+1994-01-15 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Makefile (dired-x.dvi, ../info/dired-x): New targets.
+ (INFO_TARGETS, DVI_TARGETS): Add the new targets.
+
+1994-01-08 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Makefile (../info/sc): Renamed frin sc.info.
+ (../info/cl): Likewise.
+ (INFO_TARGETS): Use new names.
+
+1993-12-04 Richard Stallman (rms@srarc2)
+
+ * getopt.c: New file.
+ * Makefile (TEXINDEX_OBJS): Use getopt.o in this dir, not ../lib-src.
+ (getopt.o): New rule.
+ (dvi): Don't depend on texindex.
+ (emacs.dvi, cl.dvi, forms.dvi, vip.dvi, gnus.dvi, sc.dvi):
+ Depend on texindex.
+
+1993-12-03 Richard Stallman (rms@srarc2)
+
+ * Makefile (../info/sc.info): Renamed from ../info/sc.
+ (TEXI2DVI): New variable.
+ (emacs.dvi, cl.dvi forms.dvi, sc.dvi, vip.dvi, gnus.dvi, info.dvi):
+ Add explicit commands.
+ (TEXINDEX_OBJS): Delete duplicate getopt.o.
+
+1993-11-27 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Version 19.22 released.
+
+1993-11-18 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Makefile (TEXINDEX_OBJS): Delete spurious period.
+
+1993-11-16 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Version 19.21 released.
+
+1993-11-15 Paul Eggert (eggert@twinsun.com)
+
+ * man/Makefile (../info/cl.info): Renamed from ../info/cl.
+
+1993-11-15 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Makefile (../etc/GNU): New target.
+ (EMACSSOURCES): Add gnu1.texi.
+
+1993-11-14 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Makefile (realclean): Don't delete the Info files.
+
+1993-10-25 Brian Fox (bfox@albert.gnu.ai.mit.edu)
+
+ * forms.texi: Fix forms.texi so that it will format correctly.
+ Added missing `@end iftex', fixed bad reference.
+
+ * info.texi, info-stn.texi: New files implement texinfo version of
+ `info' file.
+
+ * frames.texi (Creating Frames): Mention `C-x 5' instead of `C-x
+ 4' where appropriate.
+
+1993-10-20 Brian Fox (bfox@ai.mit.edu)
+
+ * Makefile: Fix targets for texindex, new info.texi files.
+ * info-stnd.texi: New file implements info for standalone info
+ reader.
+ * info.texi: Updated to include recent changes to "../info/info".
+ New source file for ../info/info; includes info-stnd.texi.
+
+ * texindex.c: Include "../src/config.h" if building in emacs.
+
+ * Makefile: Change all files to FILENAME.texi, force all targets
+ to be FILENAME, not FILENAME.info. This changes sc.texinfo,
+ vip.texinfo, forms.texinfo, cl.texinfo.
+ Add target to build texindex.c, defining `emacs'.
+
+ * forms.texi: Install new file to match version 2.3 of forms.el.
+
+1993-08-14 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Version 19.19 released.
+
+1993-08-10 Simon Leinen (simon@lia.di.epfl.ch)
+
+ * sc.texinfo: Fix info file name.
+
+ * Makefile (info): Added gnus and sc.
+ (dvi): Added gnus.dvi and sc.dvi.
+ (../info/sc, sc.dvi): New targets.
+
+1993-08-08 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Version 19.18 released.
+
+1993-07-20 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Makefile: Fix source file names of the separate manuals.
+ (gnus.dvi, ../info/gnus): New targets.
+
+1993-07-18 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * Version 19.17 released.
+
+1993-07-10 Richard Stallman (rms@mole.gnu.ai.mit.edu)
+
+ * split-man: Fix typos in last change.
+
+1993-07-06 Jim Blandy (jimb@geech.gnu.ai.mit.edu)
+
+ * Version 19.16 released.
+
+1993-06-19 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
+
+ * version 19.15 released.
+
+1993-06-18 Jim Blandy (jimb@geech.gnu.ai.mit.edu)
+
+ * Makefile (distclean): It's rm, not rf.
+
+1993-06-17 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
+
+ * Version 19.14 released.
+
+1993-06-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
+
+ * Makefile: New file.
+
+1993-06-08 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
+
+ * Version 19.13 released.
+
+1993-05-27 Jim Blandy (jimb@geech.gnu.ai.mit.edu)
+
+ * Version 19.9 released.
+
+1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
+
+ * Version 19.8 released.
+
+1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
+
+ * cmdargs.texi: Document the -i, -itype, and -iconic options.
+
+ * trouble.texi: It's `enable-flow-control-on', not
+ `evade-flow-control-on'.
+
+1993-05-24 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu)
+
+ * display.texi: Document standard-display-european.
+
+1993-05-22 Jim Blandy (jimb@geech.gnu.ai.mit.edu)
+
+ * Version 19.7 released.
+
+ * emacs.texi: Add a sentence to the top menu mentioning the
+ specific version of Emacs this manual applies to.
+
+1993-04-25 Eric S. Raymond (eric@mole.gnu.ai.mit.edu)
+
+ * basic.texi: Documented next-line-add-lines variable used to
+ implement down-arrow.
+
+ * killing.texi: Documented kill-whole-line.
+
+1993-04-18 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu)
+
+ * text.texi: Updated unix TeX ordering information.
+
+1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu)
+
+ * news.texi: Mentioned fill-rectangle in keybinding list.
+
+ * killing.texi: Documented fill-rectangle.
+
+1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu)
+
+ * vc.texi: Brought the docs up to date with VC 5.2.
+
+1992-01-10 Eric S. Raymond (eric@mole.gnu.ai.mit.edu)
+
+ * emacs.tex: Mentioned blackbox and gomoku under Amusements.
+ Assembler mode is now mentioned and appropriately
+ indexed under Programming Modes.
+
+1991-02-15 Robert J. Chassell (bob at wookumz.ai.mit.edu)
+
+ * emacs.tex: Updated TeX ordering information.
+
+1990-08-30 David Lawrence (tale at pogo.ai.mit.edu)
+
+ * gnus.texinfo: New file. Removed installation instructions.
+
+1990-06-26 David Lawrence (tale at geech)
+
+ * emacs.tex: Noted that completion-ignored-extensions is not used
+ to filter out names when all completions are displayed in
+ *Completions*.
+
+1990-05-25 Richard Stallman (rms at sugar-bombs.ai.mit.edu)
+
+ * texindex.tex: If USG, include sys/types.h and sys/fcntl.h.
+
+1990-03-21 Jim Kingdon (kingdon at pogo.ai.mit.edu)
+
+ * emacs.tex: Add @findex grep.
+
+1989-01-17 Robert J. Chassell (bob at rice-chex.ai.mit.edu)
+
+ * texinfo.tex: Changed spelling of `\sc' font to `\smallcaps' and
+ then defined `\sc' as the command for smallcaps in Texinfo. This
+ measns that the @sc command will produce small caps. bfox has
+ made the corresponding change to makeinfo and texinfm.el.
+
+1988-08-16 Robert J. Chassell (bob at frosted-flakes.ai.mit.edu)
+
+ * emacs.tex: Corrected two typos. No other changes before
+ Version 19 will be made.
+
+ * vip.texinfo: Removed menu entry Adding Lisp Code in node
+ Customization since the menu entry did not point to anything.
+ Also added an @finalout command to remove overfull hboxes from the
+ printed output.
+
+ * cl.texinfo: Added @bye, \input line and @settitle to file.
+ This file is clearly intended to be a chapter of some other work,
+ but the other work does not yet exist.
+
+1988-07-25 Robert J. Chassell (bob at frosted-flakes.ai.mit.edu)
+
+ * texinfo.texinfo: Three typos corrected.
+
+1988-05-23 Robert J. Chassell (bob at frosted-flakes.ai.mit.edu)
+
+ * emacs.tex: Update information for obtaining TeX distribution from the
+ University of Washington.
+
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Abbrevs, Picture, Building, Top
+@chapter Abbrevs
+@cindex abbrevs
+@cindex expansion (of abbrevs)
+
+ A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert
+it, into some different text. Abbrevs are defined by the user to expand
+in specific ways. For example, you might define @samp{foo} as an abbrev
+expanding to @samp{find outer otter}. Then you would be able to insert
+@samp{find outer otter } into the buffer by typing @kbd{f o o
+@key{SPC}}.
+
+ A second kind of abbreviation facility is called @dfn{dynamic abbrev
+expansion}. You use dynamic abbrev expansion with an explicit command
+to expand the letters in the buffer before point by looking for other
+words in the buffer that start with those letters. @xref{Dynamic
+Abbrevs}.
+
+@menu
+* Abbrev Concepts:: Fundamentals of defined abbrevs.
+* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
+* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
+* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
+* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
+* Dynamic Abbrevs:: Abbreviations for words already in the buffer.
+* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling.
+@end menu
+
+@node Abbrev Concepts
+@section Abbrev Concepts
+
+ An @dfn{abbrev} is a word which has been defined to @dfn{expand} into
+a specified @dfn{expansion}. When you insert a word-separator character
+following the abbrev, that expands the abbrev---replacing the abbrev
+with its expansion. For example, if @samp{foo} is defined as an abbrev
+expanding to @samp{find outer otter}, then you can insert @samp{find
+outer otter.} into the buffer by typing @kbd{f o o .}.
+
+@findex abbrev-mode
+@vindex abbrev-mode
+@cindex Abbrev mode
+@cindex mode, Abbrev
+ Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
+Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
+but they do not expand until Abbrev mode is enabled again. The command
+@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
+turns Abbrev mode on if the argument is positive, off otherwise.
+@xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is
+on when the variable is non-@code{nil}. The variable @code{abbrev-mode}
+automatically becomes local to the current buffer when it is set.
+
+ Abbrev definitions can be @dfn{mode-specific}---active only in one major
+mode. Abbrevs can also have @dfn{global} definitions that are active in
+all major modes. The same abbrev can have a global definition and various
+mode-specific definitions for different major modes. A mode-specific
+definition for the current major mode overrides a global definition.
+
+ Abbrevs can be defined interactively during the editing session. Lists
+of abbrev definitions can also be saved in files and reloaded in later
+sessions. Some users keep extensive lists of abbrevs that they load in
+every session.
+
+@node Defining Abbrevs
+@section Defining Abbrevs
+
+@table @kbd
+@item C-x a g
+Define an abbrev, using one or more words before point as its expansion
+(@code{add-global-abbrev}).
+@item C-x a l
+Similar, but define an abbrev specific to the current major mode
+(@code{add-mode-abbrev}).
+@item C-x a i g
+Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
+@item C-x a i l
+Define a word in the buffer as a mode-specific abbrev
+(@code{inverse-add-mode-abbrev}).
+@item M-x kill-all-abbrevs
+This command discards all abbrev definitions currently in effect,
+leaving a blank slate.
+@end table
+
+@kindex C-x a g
+@findex add-global-abbrev
+ The usual way to define an abbrev is to enter the text you want the
+abbrev to expand to, position point after it, and type @kbd{C-x a g}
+(@code{add-global-abbrev}). This reads the abbrev itself using the
+minibuffer, and then defines it as an abbrev for one or more words before
+point. Use a numeric argument to say how many words before point should be
+taken as the expansion. For example, to define the abbrev @samp{foo} as
+mentioned above, insert the text @samp{find outer otter} and then type
+@kbd{C-u 3 C-x a g f o o @key{RET}}.
+
+ An argument of zero to @kbd{C-x a g} means to use the contents of the
+region as the expansion of the abbrev being defined.
+
+@kindex C-x a l
+@findex add-mode-abbrev
+ The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but
+defines a mode-specific abbrev. Mode-specific abbrevs are active only in a
+particular major mode. @kbd{C-x a l} defines an abbrev for the major mode
+in effect at the time @kbd{C-x a l} is typed. The arguments work the same
+as for @kbd{C-x a g}.
+
+@kindex C-x a i g
+@findex inverse-add-global-abbrev
+@kindex C-x a i l
+@findex inverse-add-mode-abbrev
+ If the text already in the buffer is the abbrev, rather than its
+expansion, use command @kbd{C-x a i g}
+(@code{inverse-add-global-abbrev}) instead of @kbd{C-x a g}, or use
+@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x a
+l}. These commands are called ``inverse'' because they invert the
+meaning of the two text strings they use (one from the buffer and one
+read with the minibuffer).
+
+ To change the definition of an abbrev, just define a new definition.
+When the abbrev has a prior definition, the abbrev definition commands
+ask for confirmation for replacing it.
+
+ To remove an abbrev definition, give a negative argument to the abbrev
+definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}. The
+former removes a global definition, while the latter removes a
+mode-specific definition.
+
+@findex kill-all-abbrevs
+ @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there
+are, both global and local.
+
+@node Expanding Abbrevs
+@section Controlling Abbrev Expansion
+
+ An abbrev expands whenever it is present in the buffer just before
+point and you type a self-inserting whitespace or punctuation character
+(@key{SPC}, comma, etc.@:). More precisely, any character that is not a
+word constituent expands an abbrev, and any word-constituent character
+can be part of an abbrev. The most common way to use an abbrev is to
+insert it and then insert a punctuation character to expand it.
+
+@vindex abbrev-all-caps
+ Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
+outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
+@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
+variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first
+of the two expansions).
+
+ These commands are used to control abbrev expansion:
+
+@table @kbd
+@item M-'
+Separate a prefix from a following abbrev to be expanded
+(@code{abbrev-prefix-mark}).
+@item C-x a e
+@findex expand-abbrev
+Expand the abbrev before point (@code{expand-abbrev}).
+This is effective even when Abbrev mode is not enabled.
+@item M-x expand-region-abbrevs
+Expand some or all abbrevs found in the region.
+@end table
+
+@kindex M-'
+@findex abbrev-prefix-mark
+ You may wish to expand an abbrev with a prefix attached; for example,
+if @samp{cnst} expands into @samp{construction}, you might want to use
+it to enter @samp{reconstruction}. It does not work to type
+@kbd{recnst}, because that is not necessarily a defined abbrev. What
+you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in
+between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert
+@samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer to
+indicate that it has done its work. Then insert the abbrev @samp{cnst};
+the buffer now contains @samp{re-cnst}. Now insert a non-word character
+to expand the abbrev @samp{cnst} into @samp{construction}. This
+expansion step also deletes the hyphen that indicated @kbd{M-'} had been
+used. The result is the desired @samp{reconstruction}.
+
+ If you actually want the text of the abbrev in the buffer, rather than
+its expansion, you can accomplish this by inserting the following
+punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in
+the buffer.
+
+@findex unexpand-abbrev
+ If you expand an abbrev by mistake, you can undo the expansion and
+bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}).
+This also undoes the insertion of the non-word character that expanded
+the abbrev. If the result you want is the terminating non-word
+character plus the unexpanded abbrev, you must reinsert the terminating
+character, quoting it with @kbd{C-q}. You can also use the command
+@kbd{M-x unexpand-abbrev} to cancel the last expansion without
+deleting the terminating character.
+
+@findex expand-region-abbrevs
+ @kbd{M-x expand-region-abbrevs} searches through the region for defined
+abbrevs, and for each one found offers to replace it with its expansion.
+This command is useful if you have typed in text using abbrevs but forgot
+to turn on Abbrev mode first. It may also be useful together with a
+special set of abbrev definitions for making several global replacements at
+once. This command is effective even if Abbrev mode is not enabled.
+
+ Expanding an abbrev runs the hook @code{pre-abbrev-expand-hook}
+(@pxref{Hooks}).
+
+@need 1500
+@node Editing Abbrevs
+@section Examining and Editing Abbrevs
+
+@table @kbd
+@item M-x list-abbrevs
+Display a list of all abbrev definitions.
+@item M-x edit-abbrevs
+Edit a list of abbrevs; you can add, alter or remove definitions.
+@end table
+
+@findex list-abbrevs
+ The output from @kbd{M-x list-abbrevs} looks like this:
+
+@example
+(lisp-mode-abbrev-table)
+"dk" 0 "define-key"
+(global-abbrev-table)
+"dfn" 0 "definition"
+@end example
+
+@noindent
+(Some blank lines of no semantic significance, and some other abbrev
+tables, have been omitted.)
+
+ A line containing a name in parentheses is the header for abbrevs in a
+particular abbrev table; @code{global-abbrev-table} contains all the global
+abbrevs, and the other abbrev tables that are named after major modes
+contain the mode-specific abbrevs.
+
+ Within each abbrev table, each nonblank line defines one abbrev. The
+word at the beginning of the line is the abbrev. The number that
+follows is the number of times the abbrev has been expanded. Emacs
+keeps track of this to help you see which abbrevs you actually use, so
+that you can eliminate those that you don't use often. The string at
+the end of the line is the expansion.
+
+@findex edit-abbrevs
+@kindex C-c C-c @r{(Edit Abbrevs)}
+ @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev
+definitions by editing a list of them in an Emacs buffer. The list has
+the same format described above. The buffer of abbrevs is called
+@samp{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in
+this buffer to install the abbrev definitions as specified in the
+buffer---and delete any abbrev definitions not listed.
+
+ The command @code{edit-abbrevs} is actually the same as
+@code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*}
+whereas @code{list-abbrevs} merely displays it in another window.
+
+@node Saving Abbrevs
+@section Saving Abbrevs
+
+ These commands allow you to keep abbrev definitions between editing
+sessions.
+
+@table @kbd
+@item M-x write-abbrev-file @key{RET} @var{file} @key{RET}
+Write a file @var{file} describing all defined abbrevs.
+@item M-x read-abbrev-file @key{RET} @var{file} @key{RET}
+Read the file @var{file} and define abbrevs as specified therein.
+@item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET}
+Similar but do not display a message about what is going on.
+@item M-x define-abbrevs
+Define abbrevs from definitions in current buffer.
+@item M-x insert-abbrevs
+Insert all abbrevs and their expansions into current buffer.
+@end table
+
+@findex write-abbrev-file
+ @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and
+then writes a description of all current abbrev definitions into that
+file. This is used to save abbrev definitions for use in a later
+session. The text stored in the file is a series of Lisp expressions
+that, when executed, define the same abbrevs that you currently have.
+
+@findex read-abbrev-file
+@findex quietly-read-abbrev-file
+@vindex abbrev-file-name
+ @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and
+then reads the file, defining abbrevs according to the contents of the
+file. @kbd{M-x quietly-read-abbrev-file} is the same except that it
+does not display a message in the echo area saying that it is doing its
+work; it is actually useful primarily in the @file{.emacs} file. If an
+empty argument is given to either of these functions, they use the file
+name specified in the variable @code{abbrev-file-name}, which is by
+default @code{"~/.abbrev_defs"}.
+
+@vindex save-abbrevs
+ Emacs will offer to save abbrevs automatically if you have changed any of
+them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x
+C-c}). This feature can be inhibited by setting the variable
+@code{save-abbrevs} to @code{nil}.
+
+@findex insert-abbrevs
+@findex define-abbrevs
+ The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
+similar to the previous commands but work on text in an Emacs buffer.
+@kbd{M-x insert-abbrevs} inserts text into the current buffer before point,
+describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
+the entire current buffer and defines abbrevs accordingly.@refill
+
+@node Dynamic Abbrevs
+@section Dynamic Abbrev Expansion
+
+ The abbrev facility described above operates automatically as you insert
+text, but all abbrevs must be defined explicitly. By contrast,
+@dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined
+automatically from the contents of the buffer, but dynamic abbrev expansion
+happens only when you request it explicitly.
+
+@kindex M-/
+@kindex C-M-/
+@findex dabbrev-expand
+@findex dabbrev-completion
+@table @kbd
+@item M-/
+Expand the word in the buffer before point as a @dfn{dynamic abbrev},
+by searching in the buffer for words starting with that abbreviation
+(@code{dabbrev-expand}).
+
+@item C-M-/
+Complete the word before point as a dynamic abbrev
+(@code{dabbrev-completion}).
+@end table
+
+@vindex dabbrev-limit
+ For example, if the buffer contains @samp{does this follow } and you
+type @kbd{f o M-/}, the effect is to insert @samp{follow} because that
+is the last word in the buffer that starts with @samp{fo}. A numeric
+argument to @kbd{M-/} says to take the second, third, etc.@: distinct
+expansion found looking backward from point. Repeating @kbd{M-/}
+searches for an alternative expansion by looking farther back. After
+scanning all the text before point, it searches the text after point.
+The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far
+in the buffer to search for an expansion.
+
+@vindex dabbrev-check-all-buffers
+ After scanning the current buffer, @kbd{M-/} normally searches other
+buffers, unless you have set @code{dabbrev-check-all-buffers} to
+@code{nil}.
+
+ A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to
+search first for expansions after point, and second for expansions
+before point. If you repeat the @kbd{M-/} to look for another
+expansion, do not specify an argument. This tries all the expansions
+after point and then the expansions before point.
+
+ After you have expanded a dynamic abbrev, you can copy additional
+words that follow the expansion in its original context. Simply type
+@kbd{@key{SPC} M-/} for each word you want to copy. The spacing and
+punctuation between words is copied along with the words.
+
+ The command @kbd{C-M-/} (@code{dabbrev-completion}) performs
+completion of a dynamic abbreviation. Instead of trying the possible
+expansions one by one, it finds all of them, then inserts the text that
+they have in common. If they have nothing in common, @kbd{C-M-/}
+displays a list of completions, from which you can select a choice in
+the usual manner. @xref{Completion}.
+
+ Dynamic abbrev expansion is completely independent of Abbrev mode; the
+expansion of a word with @kbd{M-/} is completely independent of whether
+it has a definition as an ordinary abbrev.
+
+@node Dabbrev Customization
+@section Customizing Dynamic Abbreviation
+
+ Normally, dynamic abbrev expansion ignores case when searching for
+expansions. That is, the expansion need not agree in case with the word
+you are expanding.
+
+@vindex dabbrev-case-fold-search
+ This feature is controlled by the variable
+@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in
+this search; if @code{nil}, the word and the expansion must match in
+case. If the value of @code{dabbrev-case-fold-search} is
+@code{case-fold-search}, which is true by default, then the variable
+@code{case-fold-search} controls whether to ignore case while searching
+for expansions.
+
+@vindex dabbrev-case-replace
+ Normally, dynamic abbrev expansion preserves the case pattern @emph{of
+the abbrev you have typed}, by converting the expansion to that case
+pattern.
+
+@vindex dabbrev-case-fold-search
+ The variable @code{dabbrev-case-replace} controls whether to preserve
+the case pattern of the abbrev. If it is @code{t}, the abbrev's case
+pattern is preserved in most cases; if @code{nil}, the expansion is
+always copied verbatim. If the value of @code{dabbrev-case-replace} is
+@code{case-replace}, which is true by default, then the variable
+@code{case-replace} controls whether to copy the expansion verbatim.
+
+ However, if the expansion contains a complex mixed case pattern, and
+the abbrev matches this pattern as far as it goes, then the expansion is
+always copied verbatim, regardless of those variables. Thus, for
+example, if the buffer contains @code{variableWithSillyCasePattern}, and
+you type @kbd{v a M-/}, it copies the expansion verbatim including its
+case pattern.
+
+@vindex dabbrev-abbrev-char-regexp
+ The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil},
+controls which characters are considered part of a word, for dynamic expansion
+purposes. The regular expression must match just one character, never
+two or more. The same regular expression also determines which
+characters are part of an expansion. The value @code{nil} has a special
+meaning: abbreviations are made of word characters, but expansions are
+made of word and symbol characters.
+
+@vindex dabbrev-abbrev-skip-leading-regexp
+ In shell scripts and makefiles, a variable name is sometimes prefixed
+with @samp{$} and sometimes not. Major modes for this kind of text can
+customize dynamic abbreviation to handle optional prefixes by setting
+the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value
+should be a regular expression that matches the optional prefix that
+dynamic abbreviation should ignore.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1994, 1995, 1996, 1997, 1999 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Acknowledgments, Screen, Concept Index, Top
+@chapter Acknowledgments
+
+Many people have contributed code included in the Free Software
+Foundation's distribution of GNU Emacs. To show our appreciation for
+their public spirit, we list here those who have written substantial
+portions.
+
+@itemize @bullet
+@item
+Per Abrahamsen wrote the customization buffer facilities, as well as
+@file{double.el} for typing accented characters not normally available
+from the keyboard, @file{xt-mouse.el} which handles mouse commands
+through Xterm, and @file{cpp.el} which hides or highlights parts of C
+programs according to preprocessor conditionals.
+
+@item
+Jay K. Adams wrote @file{jka-compr.el}, providing automatic
+decompression and recompression for compressed files.
+
+@item
+Joe Arceneaux wrote the original text property implementation, and
+implemented support for X11.
+
+@item
+Boaz Ben-Zvi wrote @file{profile.el}, to time Emacs Lisp functions.
+
+@item
+Jim Blandy wrote Emacs 19's input system, brought its configuration and
+build process up to the GNU coding standards, and contributed to the
+frame support and multi-face support.
+
+@item
+Terrence M. Brannon wrote @file{landmark.el}, a neural-network robot
+that learns landmarks.
+
+@item
+Frank Bresz wrote @file{diff.el}, a program to display @code{diff}
+output.
+
+@item
+Peter Breton implemented @file{dirtrack} which does better tracking of
+directory changes in shell buffers, @file{filecache.el} which records
+which directories your files are in, @file{locate.el} which interfaces
+to the @code{locate} command, @file{net-utils.el}, and the ``generic
+mode'' feature.
+
+@item
+Kevin Broadey wrote @file{foldout.el}, providing folding extensions to
+Emacs's outline modes.
+
+@item
+Vincent Broman wrote @file{ada.el}, a mode for editing Ada code
+(since replaced by @file{ada-mode.el}).
+
+@item
+David M. Brown wrote @file{array.el}, for editing arrays and other
+tabular data.
+
+@item
+Bill Carpenter provided @file{feedmail.el}.
+
+@item
+Hans Chalupsky wrote @file{advice.el}, an overloading mechanism for
+Emacs Lisp functions, and @file{trace.el}, a tracing facility for Emacs
+Lisp.
+
+@item
+Bob Chassell wrote @file{texnfo-upd.el} and @file{makeinfo.el}, modes
+and utilities for working with Texinfo files.
+
+@item
+James Clark wrote @file{sgml-mode.el}, a mode for editing SGML
+documents, and contributed to Emacs's dumping procedures.
+
+@item
+Mike Clarkson wrote @file{edt.el}, an emulation of DEC's EDT editor.
+
+@item
+Glynn Clements provided @file{gamegrid.el} and a couple of games that
+use it, Snake and Tetris.
+
+@item
+Andrew Csillag wrote M4 mode (@file{m4-mode.el}).
+
+@item
+Doug Cutting and Jamie Zawinski wrote @file{disass.el}, a disassembler
+for compiled Emacs Lisp code.
+
+@item
+Michael DeCorte wrote @file{emacs.csh}, a C-shell script that starts a
+new Emacs job, or restarts a paused Emacs if one exists.
+
+@item
+Gary Delp wrote @file{mailpost.el}, an interface between RMAIL and the
+@file{/usr/uci/post} mailer.
+
+@item
+Matthieu Devin wrote @file{delsel.el}, a package to make newly-typed
+text replace the current selection.
+
+@item
+Eric Ding contributed @file{goto-addr.el},
+
+@item
+Carsten Dominik wrote @file{reftex.el}, a package for setting up
+labels and cross-references for La@TeX{}.
+
+@item
+Scott Draves wrote @file{tq.el}, help functions for maintaining
+transaction queues between Emacs and its subprocesses.
+
+@item
+Viktor Dukhovni wrote support for dumping under SunOS version 4.
+
+@item
+John Eaton co-wrote Octave mode (@file{octave.el} and related files).
+
+@item
+Rolf Ebert co-wrote Ada mode (@file{ada-mode.el}).
+
+@item
+Stephen Eglen implemented @file{mspools.el}, for use with Procmail,
+which tells you which mail folders have mail waiting in them, and
+@file{iswitchb.el}, a feature for incremental reading and completion of
+buffer names.
+
+@item
+@c iftex
+Torbj@"orn
+@c end iftex
+@c ifinfo
+@c Torbjorn
+@c end ifinfo
+Einarsson contributed F90 mode (@file{f90.el}).
+
+@item
+Tsugutomo Enami co-wrote the support for international character sets.
+
+@item
+Hans Henrik Eriksen wrote @file{simula.el}, a mode for editing SIMULA 87
+code.
+
+@item
+Michael Ernst wrote @file{reposition.el}, a command for recentering a
+function's source code and preceding comment on the screen.
+
+@item
+Ata Etemadi wrote @file{cdl.el}, functions for working with Common Data
+Language source code.
+
+@item
+Frederick Farnback implemented @file{morse.el}, which converts text to
+morse code.
+
+@item
+Fred Fish wrote the support for dumping COFF executable files.
+
+@item
+Karl Fogel wrote:
+@itemize @bullet
+@item
+@file{bookmark.el}, for creating named placeholders, saving them and
+jumping to them later,
+@item
+@file{mail-hist.el}, a history mechanism for outgoing mail messages, and
+@item
+@file{saveplace.el}, for preserving point's location in files between
+editing sessions.
+@end itemize
+
+@item
+Gary Foster wrote the emulation for CRiSP: @file{crisp.el} and
+@file{scroll-lock.el}.
+
+@item
+Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin, and
+@file{type-break.el}, which reminds you to take periodic breaks from
+typing. With Roland McGrath, he wrote @file{rsz-mini.el}, a minor mode
+to automatically resize the minibuffer to fit the text it contains.
+
+@item
+Keith Gabryelski wrote @file{hexl.el}, a mode for editing binary files.
+
+@item
+Kevin Gallagher rewrote and enhanced the EDT emulation, and wrote
+@file{flow-ctrl.el}, a package for coping with unsuppressible XON/XOFF
+flow control.
+
+@item
+Kevin Gallo added multiple-frame support for Windows NT.
+
+@item
+Howard Gayle wrote:
+@itemize @bullet
+@item
+the C and lisp code for display tables and case tables,
+@item
+@file{rot13.el}, a command to display the plaintext form of a buffer
+encoded with the Caesar cipher,
+@item
+much of the support for the ISO-8859 European character set (which
+includes @file{iso-ascii.el}, @file{iso-insert.el}, @file{iso-swed.el},
+@file{iso-syntax.el}, @file{iso-transl.el}, and @file{swedish.el}), and
+@item
+@file{vt100-led.el}, a package for controlling the LED's on
+VT100-compatible terminals.
+@end itemize
+
+@item
+Stephen Gildea made the Emacs quick reference card.
+
+@item
+David Gillespie wrote:
+@itemize @bullet
+@item
+Emacs 19's Common Lisp compatibility packages, replacing the old package
+by Cesar Augusto Quiroz Gonzalez,
+@item
+@file{complete.el}, a partial completion mechanism, and
+@item
+@file{edmacro.el}, a package for editing keyboard macros.
+@end itemize
+
+@item
+Bob Glickstein contributed the @file{sregex.el} feature.
+
+@item
+Boris Goldowsky wrote @file{avoid.el}, a package to keep the mouse
+cursor out of the way of the text cursor; @file{shadowfile.el}, a
+package for keeping identical copies of files in more than one place;
+@file{enriched.el}, a package for saving text properties in files;
+and @file{facemenu.el}, a package for specifying faces.
+
+@item
+Michelangelo Grigni wrote @file{ffap.el} which visits a file,
+taking the file name from the buffer.
+
+@item
+Odd Gripenstam wrote @file{dcl-mode.el}.
+
+@item
+Michael Gschwind wrote @file{iso-cvt.el}, a package to convert between
+the ISO 8859-1 character set and the notations for non-@code{ASCII}
+characters used by @TeX{} and net tradition.
+
+@item
+Henry Guillaume wrote @file{find-file.el}, a package to visit files
+related to the currently visited file.
+
+@item
+Doug Gwyn wrote the portable @code{alloca} implementation.
+
+@item
+Ken'ichi Handa implemented most of the support for international
+character sets.
+
+@item
+Chris Hanson wrote @file{netuname.el}, a package to use HP-UX's Remote
+File Access facility from Emacs.
+
+@item
+K. Shane Hartman wrote:
+@itemize @bullet
+@item
+@file{chistory.el} and @file{echistory.el}, packages for browsing
+command history lists,
+@item
+@file{electric.el} and @file{helper.el}, providing an alternative
+command loop and appropriate help facilities,
+@item
+@file{emacsbug.el}, a package for reporting Emacs bugs,
+@item
+@file{picture.el}, a mode for editing ASCII pictures, and
+@item
+@file{view.el}, a package for perusing files and buffers without editing
+them.
+@end itemize
+
+@item
+John Heidemann wrote @file{mouse-copy.el} and @file{mouse-drag.el},
+which provide alternative mouse-based editing and scrolling features.
+
+@item
+Markus Heritsch co-wrote Ada mode (@file{ada-mode.el}).
+
+@item
+Karl Heuer wrote the original blessmail script, implemented the
+@code{intangible} text property, and rearranged the structure of the
+@code{Lisp_Object} type to allow for more data bits.
+
+@item
+Manabu Higashida ported Emacs to the MS-DOS operating system.
+
+@item
+Anders Holst wrote @file{hippie-exp.el}, a versatile completion and
+expansion package.
+
+@item
+Kurt Hornik co-wrote Octave mode (@file{octave.el} and related files).
+
+@item
+Tom Houlder wrote @file{mantemp.el}, which generates manual C++ template
+instantiations.
+
+@item
+Lars Ingebrigtsen did a major redesign of the GNUS newsreader.
+
+@item
+Andrew Innes contributed extensively to the Windows NT support.
+
+@item
+Kyle Jones wrote @file{life.el}, a package to play Conway's ``life'' game,
+and @file{mldrag.el}, a package which allows the user to resize windows
+by dragging mode lines and vertical window separators with the mouse.
+
+@item
+Tomoji Kagatani implemented @file{smtpmail.el}, used for sending out
+mail with SMTP.
+
+@item
+David Kaufman wrote @file{yow.c}, an essential utility program for the
+hopelessly pinheaded.
+
+@item
+Henry Kautz wrote @file{bib-mode.el}, a mode for maintaining
+bibliography databases compatible with @code{refer} (the @code{troff}
+version) and @code{lookbib}, and @file{refbib.el}, a package to convert
+those databases to the format used by the LaTeX text formatting package.
+
+@item
+Howard Kaye wrote @file{sort.el}, commands to sort text in Emacs
+buffers.
+
+@item
+Michael Kifer wrote @file{ediff.el}, an interactive interface to the
+@code{diff} and @code{patch} programs, and Viper, the newest emulation
+for VI.
+
+@item
+Richard King wrote the first version of @file{userlock.el} and
+@file{filelock.c}, which provide simple support for multiple users
+editing the same file.
+@c We're not using his backquote.el any more.
+
+@item
+Larry K. Kolodney wrote @file{cvtmail.c}, a program to convert the mail
+directories used by Gosling Emacs into RMAIL format.
+
+@item
+Robert Krawitz wrote the original @file{xmenu.c}, part of Emacs's pop-up
+menu support.
+
+@item
+Sebastian Kremer wrote Emacs 19's @code{dired-mode}, with contributions
+by Lawrence R. Dodd.
+
+@item
+Geoff Kuenning wrote Emacs 19's @file{ispell.el}, based on work by Ken
+Stevens and others.
+
+@item
+David K@ringaccent{a}gedal wrote @file{tempo.el}, providing support for
+easy insertion of boilerplate text and other common constructions.
+
+@item
+Daniel LaLiberte wrote:
+@itemize @bullet
+@item
+@file{edebug.el}, a source-level debugger for Emacs Lisp,
+@item
+@file{cl-specs.el}, specifications to help @code{edebug} debug code
+written using David Gillespie's Common Lisp support,
+@item
+@file{cust-print.el}, a customizable package for printing lisp objects,
+@item
+@file{eval-reg.el}, a re-implementation of @code{eval-region} in Emacs
+Lisp, and
+@item
+@file{isearch.el}, Emacs 19's incremental search minor mode.
+@end itemize
+
+@item
+James R. Larus wrote @file{mh-e.el}, an interface to the MH mail system.
+
+@item
+Frederic Lepied contributed @file{expand.el}, which uses the abbrev
+mechanism for inserting programming constructs.
+
+@item
+Lars Lindberg wrote @file{msb.el}, which provides more flexible menus
+for buffer selection, and rewrote @file{dabbrev.el}.
+
+@item
+Eric Ludlam wrote the Speedbar package and @file{checkdoc.el}.
+
+@item
+Neil M. Mager wrote @file{appt.el}, functions to notify users of their
+appointments. It finds appointments recorded in the diary files
+generated by Edward M. Reingold's @code{calendar} package.
+
+@item
+Ken Manheimer wrote @file{allout.el}, a mode for manipulating and
+formatting outlines, and @file{icomplete.el}, which provides incremental
+completion feedback in the minibuffer.
+
+@item
+Bill Mann wrote @file{perl-mode.el}, a mode for editing Perl code.
+
+@item
+Brian Marick and Daniel LaLiberte wrote @file{hideif.el}, support for
+hiding selected code within C @code{#ifdef} clauses.
+
+@item
+Simon Marshall wrote:
+@itemize @bullet
+@item
+@file{fast-lock.el}, which caches the face data computed by Font Lock mode,
+@item
+@file{lazy-lock.el}, which delays fontification in Font Lock mode
+until text is actually displayed, and
+@item
+@file{regexp-opt.el}, which generates a regular expression from a list
+of strings.
+@end itemize
+
+@item
+Bengt Martensson, Mark Shapiro, Mike Newton, Aaron Larson, and Stefan
+Schoef, wrote @file{bibtex.el}, a mode for editing Bib@TeX{}
+bibliography files.
+
+@item
+Charlie Martin wrote @file{autoinsert.el}, which provides automatic
+mode-sensitive insertion of text into new files.
+
+@item
+Thomas May wrote @file{blackbox.el}, a version of the traditional
+blackbox game.
+
+@item
+Roland McGrath wrote:
+@itemize @bullet
+@item
+@file{compile.el}, a package for running compilations in a buffer, and
+then visiting the locations reported in error messages,
+@item
+@file{etags.el}, a package for jumping to function definitions and
+searching or replacing in all the files mentioned in a @file{TAGS} file,
+@item
+@file{find-dired.el}, for using @code{dired} commands on output from the
+@code{find} program, with Sebastian Kremer,
+@item
+@file{map-ynp.el}, a general purpose boolean question-asker,
+@item
+@file{autoload.el}, providing semi-automatic maintenance of autoload
+files, and
+@item
+@file{upd-copyr.el}, providing semi-automatic maintenance of copyright
+notices in source code.
+@end itemize
+
+@item
+David Megginson wrote @file{derived.el}, which allows one to define new
+major modes by inheriting key bindings and commands from existing major
+modes.
+
+@item
+Wayne Mesard wrote @file{hscroll.el} which does horizontal scrolling
+automatically.
+
+@item
+Richard Mlynarik wrote:
+@itemize @bullet
+@item
+@file{cl-indent.el}, a package for indenting Common Lisp code,
+@item
+@file{ebuff-menu.el}, an ``electric'' browser for buffer listings,
+@item
+@file{ehelp.el}, bindings for browsing help screens,
+@item
+@file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format,
+used in mail messages and news articles,
+@item
+@file{terminal.el}, a terminal emulator for Emacs subprocesses, and
+@item
+@file{yow.el}, an essential utility (try @kbd{M-x yow}).
+@end itemize
+
+@item
+Keith Moore wrote @file{aixcc.lex}, a pre-processor designed to help
+Emacs parse the error messages produced by the AIX C compiler.
+
+@item
+Erik Naggum wrote the time-conversion functions, and has tested the
+latest source code daily.
+
+@item
+Thomas Neumann and Eric Raymond wrote @file{makefile.el}, a mode for
+editing makefiles.
+
+@item
+Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation.
+
+@item
+Jeff Norden wrote @file{kermit.el}, a package to help the Kermit
+dialup communications program run comfortably in an Emacs shell buffer.
+
+@item
+Andrew Norman wrote @file{ange-ftp.el}, providing transparent FTP support.
+
+@item
+Jeff Peck wrote:
+@itemize @bullet
+@item
+@file{emacstool.c}, support for running Emacs under SunView/Sun Windows,
+@item
+@file{sun-curs.el}, cursor definitions for Sun Windows, and
+@item
+@file{sun-fns.el}, providing mouse support for Sun Windows.
+@end itemize
+
+@item
+Damon Anton Permezel wrote @file{hanoi.el}, an animated demonstration of
+the ``Towers of Hanoi'' puzzle.
+
+@item
+Jens Petersen wrote @file{find-func.el}, which makes it easy to find
+the source code for an Emacs Lisp function or variable.
+
+@item
+Daniel Pfeiffer wrote:
+@itemize @bullet
+@item
+@file{executable.el}
+@item
+@file{sh-script.el}, a mode for editing shell scripts,
+@item
+@file{skeleton.el}, implementing a concise language for writing
+statement skeletons, and
+@item
+@file{two-column.el}, a minor mode for simultaneous two-column editing.
+@end itemize
+
+@item
+Fred Pierresteguy and Paul Reilly made Emacs work with X Toolkit
+widgets.
+
+@item
+Christian Plaunt wrote @file{soundex.el}, an implementation of the
+Soundex algorithm for comparing English words by their pronunciation.
+
+@item
+Francesco A. Potorti wrote @file{cmacexp.el}, providing a command which
+runs the C preprocessor on a region of a file and displays the results.
+
+@item
+Michael D. Prange and Steven A. Wood wrote @file{fortran.el}, a mode for
+editing FORTRAN code.
+@c We're not distributing his tex-mode.el anymore; we're using Ed Reingold's.
+
+@item
+Ashwin Ram wrote @file{refer.el}, commands to look up references in
+bibliography files by keyword.
+
+@item
+Eric S. Raymond wrote:
+@itemize @bullet
+@item
+@file{vc.el}, an interface to the RCS and SCCS source code version
+control systems, with Paul Eggert,
+@item
+@file{gud.el}, a package for running source-level debuggers like GDB
+and SDB in Emacs,
+@item
+@file{asm-mode.el}, a mode for editing assembly language code,
+@item
+@file{cookie1.el}, support for ``fortune-cookie'' programs like
+@file{yow.el} and @file{spook.el},
+@item
+@file{finder.el}, a package for finding Emacs Lisp packages by keyword
+and topic,
+@item
+@file{lisp-mnt.el}, functions for working with the special headers used
+in Emacs Lisp library files, and
+@item
+code to set and make use of the @code{load-history} lisp variable, which
+records the source file from which each lisp function loaded into Emacs
+came.
+@end itemize
+
+@item
+Edward M. Reingold wrote the extensive calendar and diary support (try
+@kbd{M-x calendar}), with contributions from Stewart Clamen, Paul
+Eggert, and Lara Rios. Andy Oram contributed to its documentation.
+Reingold has also contributed to @file{tex-mode.el}, a mode for editing
+@TeX{} files, as have William F. Schelter, Dick King, Stephen Gildea,
+Michael Prange, and Jacob Gore.
+
+@item
+Rob Riepel contributed @file{tpu-edt.el} and its associated files,
+providing an emulation of the VMS TPU text editor emulating the VMS EDT
+editor, and @file{vt-control.el}, providing some control functions for
+the DEC VT line of terminals.
+
+@item
+Roland B. Roberts contributed much of the VMS support distributed with
+Emacs 19, along with Joseph M. Kelsey, and @file{vms-pmail.el}, support
+for using Emacs within VMS MAIL.
+
+@item
+John Robinson wrote @file{bg-mouse.el}, support for the mouse on the BBN
+Bitgraph terminal.
+
+@item
+Danny Roozendaal implemented @file{handwrite.el}, which converts text
+into ``handwriting.''
+
+@item
+William Rosenblatt wrote @file{float.el}, implementing a floating-point
+numeric type using Lisp cons cells and integers.
+
+@item
+Guillermo J. Rozas wrote @file{scheme.el}, a mode for editing Scheme
+code, and @file{fakemail.c}, an interface to the System V mailer.
+
+@item
+Ivar Rummelhoff provided @file{winner.el}, which records
+recent window configurations so you can move back to them.
+
+@item
+Wolfgang Rupprecht contributed Emacs 19's floating-point support
+(including @file{float-sup.el} and @file{floatfns.c}), and
+@file{sup-mouse.el}, support for the Supdup mouse on lisp machines.
+
+@item
+James B. Salem and Brewster Kahle wrote @file{completion.el}, providing
+dynamic word completion.
+
+@item
+Masahiko Sato wrote @file{vip.el}, an emulation of the VI editor.
+
+@item
+William Schelter wrote @file{telnet.el}, support for @code{telnet}
+sessions within Emacs.
+
+@item
+Ralph Schleicher contributed @file{battery.el}, a package for displaying
+laptop computer battery status, and @file{info-look.el}, a package for
+looking up Info documentation for symbols in the buffer.
+
+@item
+Gregor Schmid wrote @file{tcl.el}, a mode for editing Tcl/Tk scripts.
+
+@item
+Michael Schmidt and Tom Perrine wrote @file{modula2.el}, a mode for
+editing Modula-2 code, based on work by Mick Jordan and Peter Robinson.
+
+@item
+Ronald S. Schnell wrote @file{dunnet.el}, a text adventure game.
+
+@item
+Philippe Schnoebelen wrote @file{gomoku.el}, a Go Moku game played
+against Emacs, and @file{mpuz.el}, a multiplication puzzle.
+
+@item
+Randal Schwartz wrote @file{pp.el}, a pretty-printer for lisp objects.
+
+@item
+Manuel Serrano contributed the Flyspell package that does spell checking
+as you type.
+
+@item
+Stanislav Shalunov wrote @file{uce.el}, for responding to unsolicited
+commercial email.
+
+@item
+Richard Sharman contributed @file{hilit-chg.el}, which uses colors
+to inclidate recent editing changes.
+
+@item
+Olin Shivers wrote:
+@itemize @bullet
+@item
+@file{comint.el}, a library for modes running interactive command-line-
+oriented subprocesses,
+@item
+@file{cmuscheme.el}, for running inferior Scheme processes,
+@item
+@file{inf-lisp.el}, for running inferior Lisp process, and
+@item
+@file{shell.el}, for running inferior shells.
+@end itemize
+
+@item
+Sam Shteingold wrote @file{gulp.el}.
+
+@item
+Espen Skoglund wrote @file{pascal.el}, a mode for editing Pascal code.
+
+@item
+Rick Sladkey wrote @file{backquote.el}, a lisp macro for creating
+mostly-constant data.
+
+@item
+Lynn Slater wrote @file{help-macro.el}, a macro for writing interactive
+help for key bindings.
+
+@item
+Chris Smith wrote @file{icon.el}, a mode for editing Icon code.
+
+@item
+David Smith wrote @file{ielm.el}, a mode for interacting with the Emacs
+Lisp interpreter as a subprocess.
+
+@item
+Paul D. Smith wrote @file{snmp-mode.el}.
+
+@item
+William Sommerfeld wrote @file{scribe.el}, a mode for editing Scribe
+files, and @file{server.el}, a package allowing programs to send files
+to an extant Emacs job to be edited.
+
+@item
+Michael Staats wrote @file{pc-select.el}, which rebinds keys for
+selecting regions to follow many other systems.
+
+@item
+Ake Stenhoff and Lars Lindberg wrote @file{imenu.el}, a framework for
+browsing indices made from buffer contents.
+
+@item
+Peter Stephenson contributed @file{vcursor.el}, which implements a
+``virtual cursor'' that you can move with the keyboard and use for
+copying text.
+
+@item
+Sam Steingold wrote @file{midnight.el}.
+
+@item
+Jonathan Stigelman wrote @file{hilit19.el}, a package providing
+automatic highlighting in source code buffers, mail readers, and other
+contexts.
+
+@item
+Steve Strassman did not write @file{spook.el}, and even if he did, he
+really didn't mean for you to use it in an anarchistic way.
+
+@item
+Jens T. Berger Thielemann wrote @file{word-help.el}, which is
+part of the basis for @file{info-look.el}.
+
+@item
+Spencer Thomas wrote the original @file{dabbrev.el}, providing a command
+which completes the partial word before point, based on other nearby
+words for which it is a prefix. He also wrote the original dumping
+support.
+
+@item
+Jim Thompson wrote @file{ps-print.el}, which converts
+Emacs text to Postscript.
+
+@item
+Masanobu Umeda wrote:
+@itemize @bullet
+@item
+GNUS, a featureful reader for Usenet news,
+@item
+@file{prolog.el}, a mode for editing Prolog code,
+@item
+@file{rmailsort.el}, a package for sorting messages in RMAIL folders,
+@item
+@file{metamail.el}, an interface to the Metamail program,
+@item
+@file{tcp.el}, emulation of the @code{open-network-stream} function for
+some Emacs configurations which lack it, and
+@item
+@file{timezone.el}, providing functions for dealing with time zones.
+@end itemize
+
+@item
+Neil W. Van Dyke wrote @file{webjump.el}, a ``hot links'' package.
+
+@item
+Ulrik Vieth implemented @file{meta-mode.el}, for editing MetaFont code.
+
+@item
+Geoffrey Voelker wrote the Windows NT support.
+
+@item
+Johan Vromans wrote @file{forms.el} and its associated files, defining a
+mode for filling in forms, and @file{iso-acc.el}, a minor mode providing
+electric accent keys for text using the ISO-8859 character set.
+
+@item
+Barry Warsaw wrote:
+@itemize @bullet
+@item
+@file{assoc.el}, a set of utility functions for working with association
+lists,
+@item
+@file{cc-mode.el}, a major mode for editing C and C++ code, based on
+earlier work by Dave Detlefs, Stewart Clamen, and Richard Stallman,
+@item
+@file{elp.el}, a new profiler for Emacs Lisp programs.
+@item
+@file{man.el}, a mode for reading UNIX manual pages,
+@item
+@file{regi.el}, providing an AWK-like control structure for
+use in lisp programs, and
+@item
+@file{reporter.el}, providing customizable bug reporting for lisp
+packages.
+@item
+@file{supercite.el}, a minor mode for quoting sections of mail messages
+and news articles,
+@end itemize
+
+@item
+Morten Welinder wrote:
+@itemize @bullet
+@item
+@file{desktop.el}, facilities for saving some of Emacs's state between
+sessions,
+@item
+@file{s-region.el}, commands for setting the region using the shift key
+and motion commands, and
+@item
+@file{dos-fns.el}, functions for use under MS-DOS.
+@end itemize
+
+He also helped port Emacs to MS-DOS.
+
+@item
+Joseph Brian Wells wrote:
+@itemize @bullet
+@item
+@file{apropos.el}, a command to find commands, functions, and variables
+whose names contain matches for a regular expression,
+@item
+@file{resume.el}, support for processing command-line arguments after
+resuming a suspended Emacs job, and
+@item
+@file{mail-extr.el}, a package for extracting names and addresses from
+mail headers, with contributions from Jamie Zawinski.
+@end itemize
+
+@item
+Rodney Whitby and Reto Zimmermann wrote @file{vhdl-mode.el}.
+
+@item
+Ed Wilkinson wrote @file{b2m.c}, a program to convert mail files from
+RMAIL format to Unix @code{mbox} format.
+
+@item
+Mike Williams wrote @file{mouse-sel.el}, providing enhanced mouse
+selection, and @file{thingatpt.el}, a library of functions for finding
+the ``thing'' (word, line, s-expression) containing point.
+
+@item
+Dale R. Worley wrote @file{emerge.el}, a package for interactively
+merging two versions of a file.
+
+@item
+Tom Wurgler wrote @file{emacs-lock.el}, which makes it harder
+to exit with valuable buffers unsaved.
+
+@item
+Eli Zaretskii made many standard Emacs features work on MS-DOS.
+
+@item
+Jamie Zawinski wrote:
+@itemize @bullet
+@item
+Emacs 19's optimizing byte compiler, with Hallvard Furuseth,
+@item
+much of the support for faces and X selections,
+@item
+@file{mailabbrev.el}, a package providing automatic expansion of mail
+aliases, and
+@item
+@file{tar-mode.el}, providing simple viewing and editing commands for
+tar files.
+@end itemize
+
+@item
+Ian T. Zimmerman wrote @file{gametree.el}.
+
+@item
+Neal Ziring and Felix S. T. Wu wrote @file{vi.el}, an emulation of the
+VI text editor.
+@end itemize
+
+Others too numerous to mention have reported and fixed bugs, and added
+features to many parts of Emacs. We thank them for their generosity as
+well.
+
+This list intended to mention every contributor of a major package or
+feature we currently distribute; if you know of someone we have omitted,
+please report that as a manual bug.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1997, 1999 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+
+@node Antinews, MS-DOS, Command Arguments, Top
+@appendix Emacs 19 Antinews
+
+ For those users who live backwards in time, here is information about
+downgrading to Emacs version 19. We hope you will enjoy the greater
+simplicity that results from the absence of certain Emacs 20 features.
+
+@itemize @bullet
+@item
+The multibyte character and end-of-line conversion support have been
+eliminated entirely. (Some users consider this a tremendous
+improvement.) Character codes are limited to the range 0 through 255
+and files imported onto Unix-like systems may have a ^M at the end of
+each line to remind you to control MS-DOG type files.
+
+@item
+Fontsets, coding systems and input methods have been eliminated as well.
+
+@item
+The mode line normally displays the string @samp{Emacs}, in case you
+forget what editor you are using.
+
+@item
+Scroll bars always appear on the right-hand side of the window.
+This clearly separates them from the text in the window.
+
+@item
+The @kbd{M-x customize} feature has been replaced with a very simple
+feature, @kbd{M-x edit-options}. This shows you @emph{all} the user
+options right from the start, so you don't have to hunt for the ones you
+want. It also provides a few commands, such as @kbd{s} and @kbd{x}, to
+set a user option.
+
+@item
+The @key{DELETE} key does nothing special in Emacs 19 when you use it
+after selecting a region with the mouse. It does exactly the same thing
+in that situation as it does at all other times: delete one character
+backwards.
+
+@item
+@kbd{C-x C-w} no longer changes the major mode according to the new file
+name. If you want to change the mode, use @kbd{M-x normal-mode}.
+
+@item
+In Transient Mark mode, each window displays highlighting for the region
+as it exists in that window.
+
+@item
+Outline mode doesn't use overlay properties; instead, it hides a line by
+converting the preceding newline into code 015. Magically, however, if
+you save the file, the 015 character appears in the file as a newline.
+
+@item
+There is now a clever way you can activate the minibuffer recursively
+even if @code{enable-recursive-minibuffers} is @code{nil}. All you have
+to do is @emph{switch windows} to a non-minibuffer window, and then use a
+minibuffer command. You can pile up any number of minibuffer levels
+this way, but @kbd{M-x top-level} will get you out of all of them.
+
+@item
+We have removed the limit on the length of minibuffer history lists;
+they now contain all the minibuffer arguments you have used since the
+beginning of the session.
+
+@item
+Dynamic abbrev expansion now handles case conversion in a very simple
+and straightforward way. If you have requested preserving case, it
+always converts the entire expansion to the case pattern of the abbrev
+that you have typed in.
+
+@item
+The @code{compose-mail} command does not exist; @kbd{C-x m} now
+runs @code{mail} directly.
+
+@item
+There is no way to quote a file name with special characters in it.
+What you see is what you get: if the name looks remote, it is remote.
+
+@item
+@kbd{M-x grep-find} has been eliminated, because @code{grep} has never
+been lost.
+
+@ignore
+@item
+Truth in advertising: @kbd{M-x grep} by default uses @code{grep}, the
+whole @code{grep}, and nothing but the @code{grep}. If you want it to
+use @code{zgrep}, you'll have to edit the search command by hand.
+@end ignore
+
+@item
+Some Dired commands have been rearranged: two-character sequences
+have been replaced with quick single-character commands:
+
+@itemize @bullet
+@item
+For @code{dired-mark-executables}, type @kbd{*}.
+@item
+For @code{dired-mark-directories}, type @kbd{/}.
+@item
+For @code{dired-mark-symlinks}, type @kbd{@@}.
+@item
+For @code{dired-change-marks}, type @kbd{c}.
+@item
+For @code{dired-unmark-all-files}, type @kbd{C-M-?}.
+@item
+For @code{dired-unmark-all-marks}, type @kbd{C-M-? @key{RET}}.
+@end itemize
+
+But if you want to use @code{dired-flag-garbage-files}, @kbd{&}, you'll
+just have to stop living in the past.
+
+@item
+In C mode, you can now specify your preferred style for block comments.
+If you want to use the style
+
+@example
+/*
+blah
+blah
+*/
+@end example
+
+@noindent
+then you should set the variable @code{c-block-comments-indent-p} to
+@code{t}.
+
+@item
+To customize faces used by Font Lock mode, use the variable
+@code{font-lock-face-attributes}. See its documentation string for
+details.
+
+@item
+For efficiency, Font Lock mode now uses by default the minimum supported
+level of decoration for the selected major mode.
+
+@item
+If you kill a buffer, any registers holding saved positions in that
+buffer are changed to point into limbo.
+
+@item
+The function @code{set-frame-font} has been renamed to
+@code{set-default-font}.
+
+@item
+The variable @code{tex-main-file} doesn't exist. Of course, you can
+create the variable by setting it, but that won't do anything special.
+
+@item
+The @code{scroll-preserve-screen-position} variable has been eliminated;
+and so has the feature that it controls.
+
+@item
+We have eliminated the functions @code{add-untranslated-filesystem} and
+@code{remove-untranslated-filesystem}, and replaced them with a simpler
+function, @code{using-unix-filesystems}.
+
+@item
+To keep up with decreasing computer memory capacity, many other
+functions and files have been eliminated in Emacs 19. There's no need
+to mention them all here. If you try to use one of them, you'll get an
+error message to tell you that it is undefined or unbound.
+@end itemize
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Basic, Minibuffer, Exiting, Top
+@chapter Basic Editing Commands
+
+@kindex C-h t
+@findex help-with-tutorial
+ We now give the basics of how to enter text, make corrections, and
+save the text in a file. If this material is new to you, you might
+learn it more easily by running the Emacs learn-by-doing tutorial. To
+use the tutorial, run Emacs and type @kbd{Control-h t}
+(@code{help-with-tutorial}).
+
+ To clear the screen and redisplay, type @kbd{C-l} (@code{recenter}).
+
+@menu
+
+* Inserting Text:: Inserting text by simply typing it.
+* Moving Point:: How to move the cursor to the place where you want to
+ change something.
+* Erasing:: Deleting and killing text.
+* Undo:: Undoing recent changes in the text.
+* Files: Basic Files. Visiting, creating, and saving files.
+* Help: Basic Help. Asking what a character does.
+* Blank Lines:: Commands to make or delete blank lines.
+* Continuation Lines:: Lines too wide for the screen.
+* Position Info:: What page, line, row, or column is point on?
+* Arguments:: Numeric arguments for repeating a command.
+* Repeating:: A short-cut for repeating the previous command.
+@end menu
+
+@node Inserting Text
+@section Inserting Text
+
+@cindex insertion
+@cindex graphic characters
+ To insert printing characters into the text you are editing, just type
+them. This inserts the characters you type into the buffer at the
+cursor (that is, at @dfn{point}; @pxref{Point}). The cursor moves
+forward, and any text after the cursor moves forward too. If the text
+in the buffer is @samp{FOOBAR}, with the cursor before the @samp{B},
+then if you type @kbd{XX}, you get @samp{FOOXXBAR}, with the cursor
+still before the @samp{B}.
+
+ To @dfn{delete} text you have just inserted, use @key{DEL}. @key{DEL}
+deletes the character @emph{before} the cursor (not the one that the cursor
+is on top of or under; that is the character @var{after} the cursor). The
+cursor and all characters after it move backwards. Therefore, if you type
+a printing character and then type @key{DEL}, they cancel out.
+
+@kindex RET
+@cindex newline
+ To end a line and start typing a new one, type @key{RET}. This
+inserts a newline character in the buffer. If point is in the middle of
+a line, @key{RET} splits the line. Typing @key{DEL} when the cursor is
+at the beginning of a line deletes the preceding newline, thus joining
+the line with the preceding line.
+
+ Emacs can split lines automatically when they become too long, if you
+turn on a special minor mode called @dfn{Auto Fill} mode.
+@xref{Filling}, for how to use Auto Fill mode.
+
+ If you prefer to have text characters replace (overwrite) existing
+text rather than shove it to the right, you can enable Overwrite mode,
+a minor mode. @xref{Minor Modes}.
+
+@cindex quoting
+@kindex C-q
+@findex quoted-insert
+ Direct insertion works for printing characters and @key{SPC}, but other
+characters act as editing commands and do not insert themselves. If you
+need to insert a control character or a character whose code is above 200
+octal, you must @dfn{quote} it by typing the character @kbd{Control-q}
+(@code{quoted-insert}) first. (This character's name is normally written
+@kbd{C-q} for short.) There are two ways to use @kbd{C-q}:@refill
+
+@itemize @bullet
+@item
+@kbd{C-q} followed by any non-graphic character (even @kbd{C-g})
+inserts that character.
+
+@item
+@kbd{C-q} followed by a sequence of octal digits inserts the character
+with the specified octal character code. You can use any number of
+octal digits; any non-digit terminates the sequence. If the terminating
+character is @key{RET}, it serves only to terminate the sequence; any
+other non-digit is itself used as input after terminating the sequence.
+(The use of octal sequences is disabled in ordinary non-binary Overwrite
+mode, to give you a convenient way to insert a digit instead of
+overwriting with it.)
+@end itemize
+
+@noindent
+When multibyte characters are enabled, octal codes 0200 through 0377 are
+not valid as characters; if you specify a code in this range, @kbd{C-q}
+assumes that you intend to use some ISO Latin-@var{n} character set, and
+converts the specified code to the corresponding Emacs character code.
+@xref{Enabling Multibyte}. You select @emph{which} ISO Latin character
+set though your choice of language environment (@pxref{Language
+Environments}).
+
+@vindex read-quoted-char-radix
+To use decimal or hexadecimal instead of octal, set the variable
+@code{read-quoted-char-radix} to 10 or 16. If the radix is greater than
+10, some letters starting with @kbd{a} serve as part of a character
+code, just like digits.
+
+A numeric argument to @kbd{C-q} specifies how many copies of the
+quoted character should be inserted (@pxref{Arguments}).
+
+@findex newline
+@findex self-insert
+ Customization information: @key{DEL} in most modes runs the command
+@code{delete-backward-char}; @key{RET} runs the command @code{newline}, and
+self-inserting printing characters run the command @code{self-insert},
+which inserts whatever character was typed to invoke it. Some major modes
+rebind @key{DEL} to other commands.
+
+@node Moving Point
+@section Changing the Location of Point
+
+@cindex arrow keys
+@kindex LEFT
+@kindex RIGHT
+@kindex UP
+@kindex DOWN
+@cindex moving point
+@cindex movement
+@cindex cursor motion
+@cindex moving the cursor
+ To do more than insert characters, you have to know how to move point
+(@pxref{Point}). The simplest way to do this is with arrow keys, or by
+clicking the left mouse button where you want to move to.
+
+ There are also control and meta characters for cursor motion. Some
+are equivalent to the arrow keys (these date back to the days before
+terminals had arrow keys, and are usable on terminals which don't have
+them). Others do more sophisticated things.
+
+@kindex C-a
+@kindex C-e
+@kindex C-f
+@kindex C-b
+@kindex C-n
+@kindex C-p
+@kindex M->
+@kindex M-<
+@kindex M-r
+@findex beginning-of-line
+@findex end-of-line
+@findex forward-char
+@findex backward-char
+@findex next-line
+@findex previous-line
+@findex beginning-of-buffer
+@findex end-of-buffer
+@findex goto-char
+@findex goto-line
+@findex move-to-window-line
+@table @kbd
+@item C-a
+Move to the beginning of the line (@code{beginning-of-line}).
+@item C-e
+Move to the end of the line (@code{end-of-line}).
+@item C-f
+Move forward one character (@code{forward-char}).
+@item C-b
+Move backward one character (@code{backward-char}).
+@item M-f
+Move forward one word (@code{forward-word}).
+@item M-b
+Move backward one word (@code{backward-word}).
+@item C-n
+Move down one line, vertically (@code{next-line}). This command
+attempts to keep the horizontal position unchanged, so if you start in
+the middle of one line, you end in the middle of the next. When on
+the last line of text, @kbd{C-n} creates a new line and moves onto it.
+@item C-p
+Move up one line, vertically (@code{previous-line}).
+@item M-r
+Move point to left margin, vertically centered in the window
+(@code{move-to-window-line}). Text does not move on the screen.
+
+A numeric argument says which screen line to place point on. It counts
+screen lines down from the top of the window (zero for the top line). A
+negative argument counts lines from the bottom (@minus{}1 for the bottom
+line).
+@item M-<
+Move to the top of the buffer (@code{beginning-of-buffer}). With
+numeric argument @var{n}, move to @var{n}/10 of the way from the top.
+@xref{Arguments}, for more information on numeric arguments.@refill
+@item M->
+Move to the end of the buffer (@code{end-of-buffer}).
+@item M-x goto-char
+Read a number @var{n} and move point to buffer position @var{n}.
+Position 1 is the beginning of the buffer.
+@item M-x goto-line
+Read a number @var{n} and move point to line number @var{n}. Line 1
+is the beginning of the buffer.
+@item C-x C-n
+@findex set-goal-column
+@kindex C-x C-n
+Use the current column of point as the @dfn{semipermanent goal column} for
+@kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). Henceforth, those
+commands always move to this column in each line moved into, or as
+close as possible given the contents of the line. This goal column remains
+in effect until canceled.
+@item C-u C-x C-n
+Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} once
+again try to stick to a fixed horizontal position, as usual.
+@end table
+
+@vindex track-eol
+ If you set the variable @code{track-eol} to a non-@code{nil} value,
+then @kbd{C-n} and @kbd{C-p} when at the end of the starting line move
+to the end of another line. Normally, @code{track-eol} is @code{nil}.
+@xref{Variables}, for how to set variables such as @code{track-eol}.
+
+@vindex next-line-add-newlines
+ Normally, @kbd{C-n} on the last line of a buffer appends a newline to
+it. If the variable @code{next-line-add-newlines} is @code{nil}, then
+@kbd{C-n} gets an error instead (like @kbd{C-p} on the first line).
+
+@node Erasing
+@section Erasing Text
+
+@table @kbd
+@item @key{DEL}
+Delete the character before point (@code{delete-backward-char}).
+@item C-d
+Delete the character after point (@code{delete-char}).
+@item C-k
+Kill to the end of the line (@code{kill-line}).
+@item M-d
+Kill forward to the end of the next word (@code{kill-word}).
+@item M-@key{DEL}
+Kill back to the beginning of the previous word
+(@code{backward-kill-word}).
+@end table
+
+@cindex killing characters and lines
+@cindex deleting characters and lines
+@cindex erasing characters and lines
+ You already know about the @key{DEL} key which deletes the character
+before point (that is, before the cursor). Another key, @kbd{Control-d}
+(@kbd{C-d} for short), deletes the character after point (that is, the
+character that the cursor is on). This shifts the rest of the text on
+the line to the left. If you type @kbd{C-d} at the end of a line, it
+joins together that line and the next line.
+
+ To erase a larger amount of text, use the @kbd{C-k} key, which kills a
+line at a time. If you type @kbd{C-k} at the beginning or middle of a
+line, it kills all the text up to the end of the line. If you type
+@kbd{C-k} at the end of a line, it joins that line and the next line.
+
+ @xref{Killing}, for more flexible ways of killing text.
+
+@node Undo
+@section Undoing Changes
+@cindex undo
+@cindex changes, undoing
+
+ You can undo all the recent changes in the buffer text, up to a
+certain point. Each buffer records changes individually, and the undo
+command always applies to the current buffer. Usually each editing
+command makes a separate entry in the undo records, but some commands
+such as @code{query-replace} make many entries, and very simple commands
+such as self-inserting characters are often grouped to make undoing less
+tedious.
+
+@table @kbd
+@item C-x u
+Undo one batch of changes---usually, one command worth (@code{undo}).
+@item C-_
+The same.
+@item C-u C-x u
+Undo one batch of changes in the region.
+@end table
+
+@kindex C-x u
+@kindex C-_
+@findex undo
+ The command @kbd{C-x u} or @kbd{C-_} is how you undo. The first time
+you give this command, it undoes the last change. Point moves back to
+where it was before the command that made the change.
+
+ Consecutive repetitions of @kbd{C-_} or @kbd{C-x u} undo earlier and
+earlier changes, back to the limit of the undo information available.
+If all recorded changes have already been undone, the undo command
+prints an error message and does nothing.
+
+ Any command other than an undo command breaks the sequence of undo
+commands. Starting from that moment, the previous undo commands become
+ordinary changes that you can undo. Thus, to redo changes you have
+undone, type @kbd{C-f} or any other command that will harmlessly break
+the sequence of undoing, then type more undo commands.
+
+@cindex selective undo
+@kindex C-u C-x u
+ Ordinary undo applies to all changes made in the current buffer. You
+can also perform @dfn{selective undo}, limited to the current region.
+To do this, specify the region you want, then run the @code{undo}
+command with a prefix argument (the value does not matter): @kbd{C-u C-x
+u} or @kbd{C-u C-_}. This undoes the most recent change in the region.
+To undo further changes in the same region, repeat the @code{undo}
+command (no prefix argument is needed). In Transient Mark mode, any use
+of @code{undo} when there is an active region performs selective undo;
+you do not need a prefix argument.
+
+ If you notice that a buffer has been modified accidentally, the
+easiest way to recover is to type @kbd{C-_} repeatedly until the stars
+disappear from the front of the mode line. At this time, all the
+modifications you made have been canceled. Whenever an undo command
+makes the stars disappear from the mode line, it means that the buffer
+contents are the same as they were when the file was last read in or
+saved.
+
+ If you do not remember whether you changed the buffer deliberately,
+type @kbd{C-_} once. When you see the last change you made undone, you
+will see whether it was an intentional change. If it was an accident,
+leave it undone. If it was deliberate, redo the change as described
+above.
+
+ Not all buffers record undo information. Buffers whose names start with
+spaces don't; these buffers are used internally by Emacs and its extensions
+to hold text that users don't normally look at or edit.
+
+ You cannot undo mere cursor motion; only changes in the buffer
+contents save undo information. However, some cursor motion commands
+set the mark, so if you use these commands from time to time, you can
+move back to the neighborhoods you have moved through by popping the
+mark ring (@pxref{Mark Ring}).
+
+@vindex undo-limit
+@vindex undo-strong-limit
+@cindex undo limit
+ When the undo information for a buffer becomes too large, Emacs
+discards the oldest undo information from time to time (during garbage
+collection). You can specify how much undo information to keep by
+setting two variables: @code{undo-limit} and @code{undo-strong-limit}.
+Their values are expressed in units of bytes of space.
+
+ The variable @code{undo-limit} sets a soft limit: Emacs keeps undo
+data for enough commands to reach this size, and perhaps exceed it, but
+does not keep data for any earlier commands beyond that. Its default
+value is 20000. The variable @code{undo-strong-limit} sets a stricter
+limit: the command which pushes the size past this amount is itself
+forgotten. Its default value is 30000.
+
+ Regardless of the values of those variables, the most recent change is
+never discarded, so there is no danger that garbage collection occurring
+right after an unintentional large change might prevent you from undoing
+it.
+
+ The reason the @code{undo} command has two keys, @kbd{C-x u} and
+@kbd{C-_}, set up to run it is that it is worthy of a single-character
+key, but on some keyboards it is not obvious how to type @kbd{C-_}.
+@kbd{C-x u} is an alternative you can type straightforwardly on any
+terminal.
+
+@node Basic Files
+@section Files
+
+ The commands described above are sufficient for creating and altering
+text in an Emacs buffer; the more advanced Emacs commands just make
+things easier. But to keep any text permanently you must put it in a
+@dfn{file}. Files are named units of text which are stored by the
+operating system for you to retrieve later by name. To look at or use
+the contents of a file in any way, including editing the file with
+Emacs, you must specify the file name.
+
+ Consider a file named @file{/usr/rms/foo.c}. In Emacs, to begin editing
+this file, type
+
+@example
+C-x C-f /usr/rms/foo.c @key{RET}
+@end example
+
+@noindent
+Here the file name is given as an @dfn{argument} to the command @kbd{C-x
+C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to
+read the argument, and you type @key{RET} to terminate the argument
+(@pxref{Minibuffer}).@refill
+
+ Emacs obeys the command by @dfn{visiting} the file: creating a buffer,
+copying the contents of the file into the buffer, and then displaying
+the buffer for you to edit. If you alter the text, you can @dfn{save}
+the new text in the file by typing @kbd{C-x C-s} (@code{save-buffer}).
+This makes the changes permanent by copying the altered buffer contents
+back into the file @file{/usr/rms/foo.c}. Until you save, the changes
+exist only inside Emacs, and the file @file{foo.c} is unaltered.
+
+ To create a file, just visit the file with @kbd{C-x C-f} as if it
+already existed. This creates an empty buffer in which you can insert
+the text you want to put in the file. The file is actually created when
+you save this buffer with @kbd{C-x C-s}.
+
+ Of course, there is a lot more to learn about using files. @xref{Files}.
+
+@node Basic Help
+@section Help
+
+@cindex getting help with keys
+ If you forget what a key does, you can find out with the Help
+character, which is @kbd{C-h} (or @key{F1}, which is an alias for
+@kbd{C-h}). Type @kbd{C-h k} followed by the key you want to know
+about; for example, @kbd{C-h k C-n} tells you all about what @kbd{C-n}
+does. @kbd{C-h} is a prefix key; @kbd{C-h k} is just one of its
+subcommands (the command @code{describe-key}). The other subcommands of
+@kbd{C-h} provide different kinds of help. Type @kbd{C-h} twice to get
+a description of all the help facilities. @xref{Help}.@refill
+
+@node Blank Lines
+@section Blank Lines
+
+@cindex inserting blank lines
+@cindex deleting blank lines
+ Here are special commands and techniques for putting in and taking out
+blank lines.
+
+@c widecommands
+@table @kbd
+@item C-o
+Insert one or more blank lines after the cursor (@code{open-line}).
+@item C-x C-o
+Delete all but one of many consecutive blank lines
+(@code{delete-blank-lines}).
+@end table
+
+@kindex C-o
+@kindex C-x C-o
+@cindex blank lines
+@findex open-line
+@findex delete-blank-lines
+ When you want to insert a new line of text before an existing line, you
+can do it by typing the new line of text, followed by @key{RET}.
+However, it may be easier to see what you are doing if you first make a
+blank line and then insert the desired text into it. This is easy to do
+using the key @kbd{C-o} (@code{open-line}), which inserts a newline
+after point but leaves point in front of the newline. After @kbd{C-o},
+type the text for the new line. @kbd{C-o F O O} has the same effect as
+@w{@kbd{F O O @key{RET}}}, except for the final location of point.
+
+ You can make several blank lines by typing @kbd{C-o} several times, or
+by giving it a numeric argument to tell it how many blank lines to make.
+@xref{Arguments}, for how. If you have a fill prefix, then @kbd{C-o}
+command inserts the fill prefix on the new line, when you use it at the
+beginning of a line. @xref{Fill Prefix}.
+
+ The easy way to get rid of extra blank lines is with the command
+@kbd{C-x C-o} (@code{delete-blank-lines}). @kbd{C-x C-o} in a run of
+several blank lines deletes all but one of them. @kbd{C-x C-o} on a
+solitary blank line deletes that blank line. When point is on a
+nonblank line, @kbd{C-x C-o} deletes any blank lines following that
+nonblank line.
+
+@node Continuation Lines
+@section Continuation Lines
+
+@cindex continuation line
+@cindex wrapping
+@cindex line wrapping
+ If you add too many characters to one line without breaking it with
+@key{RET}, the line will grow to occupy two (or more) lines on the screen,
+with a @samp{\} at the extreme right margin of all but the last of them.
+The @samp{\} says that the following screen line is not really a distinct
+line in the text, but just the @dfn{continuation} of a line too long to fit
+the screen. Continuation is also called @dfn{line wrapping}.
+
+ Sometimes it is nice to have Emacs insert newlines automatically when
+a line gets too long. Continuation on the screen does not do that. Use
+Auto Fill mode (@pxref{Filling}) if that's what you want.
+
+@vindex truncate-lines
+@cindex truncation
+ As an alternative to continuation, Emacs can display long lines by
+@dfn{truncation}. This means that all the characters that do not fit in
+the width of the screen or window do not appear at all. They remain in
+the buffer, temporarily invisible. @samp{$} is used in the last column
+instead of @samp{\} to inform you that truncation is in effect.
+
+ Truncation instead of continuation happens whenever horizontal
+scrolling is in use, and optionally in all side-by-side windows
+(@pxref{Windows}). You can enable truncation for a particular buffer by
+setting the variable @code{truncate-lines} to non-@code{nil} in that
+buffer. (@xref{Variables}.) Altering the value of
+@code{truncate-lines} makes it local to the current buffer; until that
+time, the default value is in effect. The default is initially
+@code{nil}. @xref{Locals}.
+
+ @xref{Display Vars}, for additional variables that affect how text is
+displayed.
+
+@node Position Info
+@section Cursor Position Information
+
+ Here are commands to get information about the size and position of
+parts of the buffer, and to count lines.
+
+@table @kbd
+@item M-x what-page
+Print page number of point, and line number within page.
+@item M-x what-line
+Print line number of point in the buffer.
+@item M-x line-number-mode
+Toggle automatic display of current line number.
+@item M-=
+Print number of lines in the current region (@code{count-lines-region}).
+@xref{Mark}, for information about the region.
+@item C-x =
+Print character code of character after point, character position of
+point, and column of point (@code{what-cursor-position}).
+@end table
+
+@findex what-page
+@findex what-line
+@cindex line number commands
+@cindex location of point
+@cindex cursor location
+@cindex point location
+ There are two commands for working with line numbers. @kbd{M-x
+what-line} computes the current line number and displays it in the echo
+area. To go to a given line by number, use @kbd{M-x goto-line}; it
+prompts you for the number. These line numbers count from one at the
+beginning of the buffer.
+
+ You can also see the current line number in the mode line; @xref{Mode
+Line}. If you narrow the buffer, then the line number in the mode line
+is relative to the accessible portion (@pxref{Narrowing}). By contrast,
+@code{what-line} shows both the line number relative to the narrowed
+region and the line number relative to the whole buffer.
+
+ By contrast, @kbd{M-x what-page} counts pages from the beginning of
+the file, and counts lines within the page, printing both numbers.
+@xref{Pages}.
+
+@kindex M-=
+@findex count-lines-region
+ While on this subject, we might as well mention @kbd{M-=} (@code{count-lines-region}),
+which prints the number of lines in the region (@pxref{Mark}).
+@xref{Pages}, for the command @kbd{C-x l} which counts the lines in the
+current page.
+
+@kindex C-x =
+@findex what-cursor-position
+ The command @kbd{C-x =} (@code{what-cursor-position}) can be used to find out
+the column that the cursor is in, and other miscellaneous information about
+point. It prints a line in the echo area that looks like this:
+
+@smallexample
+Char: c (0143, 99, 0x63) point=21044 of 26883(78%) column 53
+@end smallexample
+
+@noindent
+(In fact, this is the output produced when point is before the
+@samp{column} in the example.)
+
+ The four values after @samp{Char:} describe the character that follows
+point, first by showing it and then by giving its character code in
+octal, decimal and hex. For a non-ASCII multibyte character, these are
+followed by @samp{ext} and the character's representation, in hex, in
+the buffer's coding system, if that coding system encodes the character
+safely and with a single byte (@pxref{Coding Systems}). If the
+character's encoding is longer than one byte, Emacs shows @samp{ext ...}.
+
+ @samp{point=} is followed by the position of point expressed as a character
+count. The front of the buffer counts as position 1, one character later
+as 2, and so on. The next, larger, number is the total number of characters
+in the buffer. Afterward in parentheses comes the position expressed as a
+percentage of the total size.
+
+ @samp{column} is followed by the horizontal position of point, in
+columns from the left edge of the window.
+
+ If the buffer has been narrowed, making some of the text at the
+beginning and the end temporarily inaccessible, @kbd{C-x =} prints
+additional text describing the currently accessible range. For example, it
+might display this:
+
+@smallexample
+Char: C (0103, 67, 0x43) point=252 of 889(28%) <231 - 599> column 0
+@end smallexample
+
+@noindent
+where the two extra numbers give the smallest and largest character
+position that point is allowed to assume. The characters between those
+two positions are the accessible ones. @xref{Narrowing}.
+
+ If point is at the end of the buffer (or the end of the accessible
+part), the @w{@kbd{C-x =}} output does not describe a character after
+point. The output might look like this:
+
+@smallexample
+point=26957 of 26956(100%) column 0
+@end smallexample
+
+ @w{@kbd{C-u C-x =}} displays additional information about a character,
+in place of the buffer coordinates and column: the character set name
+and the codes that identify the character within that character set;
+ASCII characters are identified as belonging to the @code{ASCII}
+character set. In addition, the full character encoding, even if it
+takes more than a single byte, is shown after @samp{ext}. Here's an
+example for a Latin-1 character A with a grave accent in a buffer whose
+coding system is iso-2022-7bit@footnote{On terminals that support
+Latin-1 characters, the character shown after @samp{Char:} is displayed
+as the actual glyph of A with grave accent.}:
+
+@example
+Char: @`A (04300, 2240, 0x8c0, ext ESC , A @@) (latin-iso8859-1 64)
+@end example
+
+@node Arguments
+@section Numeric Arguments
+@cindex numeric arguments
+@cindex prefix arguments
+@cindex arguments, numeric
+@cindex arguments, prefix
+
+ In mathematics and computer usage, the word @dfn{argument} means
+``data provided to a function or operation.'' You can give any Emacs
+command a @dfn{numeric argument} (also called a @dfn{prefix argument}).
+Some commands interpret the argument as a repetition count. For
+example, @kbd{C-f} with an argument of ten moves forward ten characters
+instead of one. With these commands, no argument is equivalent to an
+argument of one. Negative arguments tell most such commands to move or
+act in the opposite direction.
+
+@kindex M-1
+@kindex M-@t{-}
+@findex digit-argument
+@findex negative-argument
+ If your terminal keyboard has a @key{META} key, the easiest way to
+specify a numeric argument is to type digits and/or a minus sign while
+holding down the @key{META} key. For example,
+@example
+M-5 C-n
+@end example
+@noindent
+would move down five lines. The characters @kbd{Meta-1}, @kbd{Meta-2},
+and so on, as well as @kbd{Meta--}, do this because they are keys bound
+to commands (@code{digit-argument} and @code{negative-argument}) that
+are defined to contribute to an argument for the next command. Digits
+and @kbd{-} modified with Control, or Control and Meta, also specify
+numeric arguments.
+
+@kindex C-u
+@findex universal-argument
+ Another way of specifying an argument is to use the @kbd{C-u}
+(@code{universal-argument}) command followed by the digits of the
+argument. With @kbd{C-u}, you can type the argument digits without
+holding down modifier keys; @kbd{C-u} works on all terminals. To type a
+negative argument, type a minus sign after @kbd{C-u}. Just a minus sign
+without digits normally means @minus{}1.
+
+ @kbd{C-u} followed by a character which is neither a digit nor a minus
+sign has the special meaning of ``multiply by four.'' It multiplies the
+argument for the next command by four. @kbd{C-u} twice multiplies it by
+sixteen. Thus, @kbd{C-u C-u C-f} moves forward sixteen characters. This
+is a good way to move forward ``fast,'' since it moves about 1/5 of a line
+in the usual size screen. Other useful combinations are @kbd{C-u C-n},
+@kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u C-u
+C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four
+lines).@refill
+
+ Some commands care only about whether there is an argument, and not about
+its value. For example, the command @kbd{M-q} (@code{fill-paragraph}) with
+no argument fills text; with an argument, it justifies the text as well.
+(@xref{Filling}, for more information on @kbd{M-q}.) Plain @kbd{C-u} is a
+handy way of providing an argument for such commands.
+
+ Some commands use the value of the argument as a repeat count, but do
+something peculiar when there is no argument. For example, the command
+@kbd{C-k} (@code{kill-line}) with argument @var{n} kills @var{n} lines,
+including their terminating newlines. But @kbd{C-k} with no argument is
+special: it kills the text up to the next newline, or, if point is right at
+the end of the line, it kills the newline itself. Thus, two @kbd{C-k}
+commands with no arguments can kill a nonblank line, just like @kbd{C-k}
+with an argument of one. (@xref{Killing}, for more information on
+@kbd{C-k}.)@refill
+
+ A few commands treat a plain @kbd{C-u} differently from an ordinary
+argument. A few others may treat an argument of just a minus sign
+differently from an argument of @minus{}1. These unusual cases are
+described when they come up; they are always for reasons of convenience
+of use of the individual command.
+
+ You can use a numeric argument to insert multiple copies of a
+character. This is straightforward unless the character is a digit; for
+example, @kbd{C-u 6 4 a} inserts 64 copies of the character @samp{a}.
+But this does not work for inserting digits; @kbd{C-u 6 4 1} specifies
+an argument of 641, rather than inserting anything. To separate the
+digit to insert from the argument, type another @kbd{C-u}; for example,
+@kbd{C-u 6 4 C-u 1} does insert 64 copies of the character @samp{1}.
+
+ We use the term ``prefix argument'' as well as ``numeric argument'' to
+emphasize that you type the argument before the command, and to
+distinguish these arguments from minibuffer arguments that come after
+the command.
+
+@node Repeating
+@section Repeating a Command
+@cindex repeating a command
+
+@kindex C-x z
+@findex repeat
+ The command @kbd{C-x z} (@code{repeat}) provides another way to repeat
+an Emacs command many times. This command repeats the previous Emacs
+command, whatever that was. Repeating a command uses the same arguments
+that were used before; it does not read new arguments each time.
+
+ To repeat the command more than once, type additional @kbd{z}'s: each
+@kbd{z} repeats the command one more time. Repetition ends when you
+type a character other than @kbd{z}, or press a mouse button.
+
+ For example, suppose you type @kbd{C-u 2 0 C-d} to delete 20
+characters. You can repeat that command (including its argument) three
+additional times, to delete a total of 80 characters, by typing @kbd{C-x
+z z z}. The first @kbd{C-x z} repeats the command once, and each
+subsequent @kbd{z} repeats it once again.
+
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Buffers, Windows, Files, Top
+@chapter Using Multiple Buffers
+
+@cindex buffers
+ The text you are editing in Emacs resides in an object called a
+@dfn{buffer}. Each time you visit a file, a buffer is created to hold the
+file's text. Each time you invoke Dired, a buffer is created to hold the
+directory listing. If you send a message with @kbd{C-x m}, a buffer named
+@samp{*mail*} is used to hold the text of the message. When you ask for a
+command's documentation, that appears in a buffer called @samp{*Help*}.
+
+@cindex selected buffer
+@cindex current buffer
+ At any time, one and only one buffer is @dfn{selected}. It is also
+called the @dfn{current buffer}. Often we say that a command operates on
+``the buffer'' as if there were only one; but really this means that the
+command operates on the selected buffer (most commands do).
+
+ When Emacs has multiple windows, each window has a chosen buffer which
+is displayed there, but at any time only one of the windows is selected and
+its chosen buffer is the selected buffer. Each window's mode line displays
+the name of the buffer that the window is displaying (@pxref{Windows}).
+
+ Each buffer has a name, which can be of any length, and you can select
+any buffer by giving its name. Most buffers are made by visiting files,
+and their names are derived from the files' names. But you can also create
+an empty buffer with any name you want. A newly started Emacs has a buffer
+named @samp{*scratch*} which can be used for evaluating Lisp expressions in
+Emacs. The distinction between upper and lower case matters in buffer
+names.
+
+ Each buffer records individually what file it is visiting, whether it is
+modified, and what major mode and minor modes are in effect in it
+(@pxref{Major Modes}). Any Emacs variable can be made @dfn{local to} a
+particular buffer, meaning its value in that buffer can be different from
+the value in other buffers. @xref{Locals}.
+
+@menu
+* Select Buffer:: Creating a new buffer or reselecting an old one.
+* List Buffers:: Getting a list of buffers that exist.
+* Misc Buffer:: Renaming; changing read-onlyness; copying text.
+* Kill Buffer:: Killing buffers you no longer need.
+* Several Buffers:: How to go through the list of all buffers
+ and operate variously on several of them.
+* Indirect Buffers:: An indirect buffer shares the text of another buffer.
+@end menu
+
+@node Select Buffer
+@section Creating and Selecting Buffers
+@cindex change buffers
+@cindex switch buffers
+
+@table @kbd
+@item C-x b @var{buffer} @key{RET}
+Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
+@item C-x 4 b @var{buffer} @key{RET}
+Similar, but select @var{buffer} in another window
+(@code{switch-to-buffer-other-window}).
+@item C-x 5 b @var{buffer} @key{RET}
+Similar, but select @var{buffer} in a separate frame
+(@code{switch-to-buffer-other-frame}).
+@end table
+
+@kindex C-x 4 b
+@findex switch-to-buffer-other-window
+@kindex C-x 5 b
+@findex switch-to-buffer-other-frame
+@kindex C-x b
+@findex switch-to-buffer
+ To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
+@key{RET}}. This runs the command @code{switch-to-buffer} with argument
+@var{bufname}. You can use completion on an abbreviation for the buffer
+name you want (@pxref{Completion}). An empty argument to @kbd{C-x b}
+specifies the most recently selected buffer that is not displayed in any
+window.@refill
+
+ Most buffers are created by visiting files, or by Emacs commands that
+want to display some text, but you can also create a buffer explicitly
+by typing @kbd{C-x b @var{bufname} @key{RET}}. This makes a new, empty
+buffer that is not visiting any file, and selects it for editing. Such
+buffers are used for making notes to yourself. If you try to save one,
+you are asked for the file name to use. The new buffer's major mode is
+determined by the value of @code{default-major-mode} (@pxref{Major
+Modes}).
+
+ Note that @kbd{C-x C-f}, and any other command for visiting a file,
+can also be used to switch to an existing file-visiting buffer.
+@xref{Visiting}.
+
+ Emacs uses buffer names that start with a space for internal purposes.
+It treats these buffers specially in minor ways---for example, by
+default they do not record undo information. It is best to avoid using
+such buffer names yourself.
+
+@node List Buffers
+@section Listing Existing Buffers
+
+@table @kbd
+@item C-x C-b
+List the existing buffers (@code{list-buffers}).
+@end table
+
+@cindex listing current buffers
+@kindex C-x C-b
+@findex list-buffers
+ To display a list of all the buffers that exist, type @kbd{C-x C-b}.
+Each line in the list shows one buffer's name, major mode and visited
+file. The buffers are listed in the order that they were current; the
+buffers that were current most recently come first.
+
+ @samp{*} at the beginning of a line indicates the buffer is ``modified.''
+If several buffers are modified, it may be time to save some with @kbd{C-x s}
+(@pxref{Saving}). @samp{%} indicates a read-only buffer. @samp{.} marks the
+selected buffer. Here is an example of a buffer list:@refill
+
+@smallexample
+ MR Buffer Size Mode File
+ -- ------ ---- ---- ----
+.* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex
+ *Help* 1287 Fundamental
+ files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
+ % RMAIL 64042 RMAIL /u/rms/RMAIL
+ *% man 747 Dired /u2/emacs/man/
+ net.emacs 343885 Fundamental /u/rms/net.emacs
+ fileio.c 27691 C /u2/emacs/src/fileio.c
+ NEWS 67340 Text /u2/emacs/etc/NEWS
+ *scratch* 0 Lisp Interaction
+@end smallexample
+
+@noindent
+Note that the buffer @samp{*Help*} was made by a help request; it is not
+visiting any file. The buffer @code{man} was made by Dired on the
+directory @file{/u2/emacs/man/}.
+
+@need 2000
+@node Misc Buffer
+@section Miscellaneous Buffer Operations
+
+@table @kbd
+@item C-x C-q
+Toggle read-only status of buffer (@code{vc-toggle-read-only}).
+@item M-x rename-buffer @key{RET} @var{name} @key{RET}
+Change the name of the current buffer.
+@item M-x rename-uniquely
+Rename the current buffer by adding @samp{<@var{number}>} to the end.
+@item M-x view-buffer @key{RET} @var{buffer} @key{RET}
+Scroll through buffer @var{buffer}.
+@end table
+
+@kindex C-x C-q
+@findex vc-toggle-read-only
+@vindex buffer-read-only
+@cindex read-only buffer
+ A buffer can be @dfn{read-only}, which means that commands to change
+its contents are not allowed. The mode line indicates read-only buffers
+with @samp{%%} or @samp{%*} near the left margin. Read-only buffers are
+usually made by subsystems such as Dired and Rmail that have special
+commands to operate on the text; also by visiting a file whose access
+control says you cannot write it.
+
+ If you wish to make changes in a read-only buffer, use the command
+@kbd{C-x C-q} (@code{vc-toggle-read-only}). It makes a read-only buffer
+writable, and makes a writable buffer read-only. In most cases, this
+works by setting the variable @code{buffer-read-only}, which has a local
+value in each buffer and makes the buffer read-only if its value is
+non-@code{nil}. If the file is maintained with version control,
+@kbd{C-x C-q} works through the version control system to change the
+read-only status of the file as well as the buffer. @xref{Version
+Control}.
+
+@findex rename-buffer
+ @kbd{M-x rename-buffer} changes the name of the current buffer. Specify
+the new name as a minibuffer argument. There is no default. If you
+specify a name that is in use for some other buffer, an error happens and
+no renaming is done.
+
+ @kbd{M-x rename-uniquely} renames the current buffer to a similar name
+with a numeric suffix added to make it both different and unique. This
+command does not need an argument. It is useful for creating multiple
+shell buffers: if you rename the @samp{*Shell*} buffer, then do @kbd{M-x
+shell} again, it makes a new shell buffer named @samp{*Shell*};
+meanwhile, the old shell buffer continues to exist under its new name.
+This method is also good for mail buffers, compilation buffers, and most
+Emacs features that create special buffers with particular names.
+
+@findex view-buffer
+ @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc
+File Ops}) except that it examines an already existing Emacs buffer.
+View mode provides commands for scrolling through the buffer
+conveniently but not for changing it. When you exit View mode with
+@kbd{q}, that switches back to the buffer (and the position) which was
+previously displayed in the window. Alternatively, if you exit View
+mode with @kbd{e}, the buffer and the value of point that resulted from
+your perusal remain in effect.
+
+ The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer}
+can be used to copy text from one buffer to another. @xref{Accumulating
+Text}.@refill
+
+@node Kill Buffer
+@section Killing Buffers
+
+@cindex killing buffers
+ If you continue an Emacs session for a while, you may accumulate a
+large number of buffers. You may then find it convenient to @dfn{kill}
+the buffers you no longer need. On most operating systems, killing a
+buffer releases its space back to the operating system so that other
+programs can use it. Here are some commands for killing buffers:
+
+@c WideCommands
+@table @kbd
+@item C-x k @var{bufname} @key{RET}
+Kill buffer @var{bufname} (@code{kill-buffer}).
+@item M-x kill-some-buffers
+Offer to kill each buffer, one by one.
+@end table
+
+@findex kill-buffer
+@findex kill-some-buffers
+@kindex C-x k
+
+ @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you
+specify in the minibuffer. The default, used if you type just @key{RET}
+in the minibuffer, is to kill the current buffer. If you kill the
+current buffer, another buffer is selected; one that has been selected
+recently but does not appear in any window now. If you ask to kill a
+file-visiting buffer that is modified (has unsaved editing), then you
+must confirm with @kbd{yes} before the buffer is killed.
+
+ The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
+one. An answer of @kbd{y} means to kill the buffer. Killing the current
+buffer or a buffer containing unsaved changes selects a new buffer or asks
+for confirmation just like @code{kill-buffer}.
+
+ The buffer menu feature (@pxref{Several Buffers}) is also convenient
+for killing various buffers.
+
+@vindex kill-buffer-hook
+ If you want to do something special every time a buffer is killed, you
+can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}).
+
+@findex clean-buffer-list
+ If you run one Emacs session for a period of days, as many people do,
+it can fill up with buffers that you used several days ago. The command
+@kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills
+all the unmodified buffers that you have not used for a long time. An
+ordinary buffer is killed if it has not been displayed for three days;
+however, you can specify certain buffers that should never be killed
+automatically, and others that should be killed if they have been unused
+for a mere hour.
+
+@cindex Midnight mode
+@vindex midnight-mode
+@vindex midnight-hook
+ You can also have this buffer purging done for you, every day at
+midnight, by enabling Midnight mode. Midnight mode operates each day at
+midnight; at that time, it runs @code{clean-buffer-list}, or whichever
+functions you have placed in the normal hook @code{midnight-hook}
+(@pxref{Hooks}).
+
+ To enable Midnight mode, use the Customization buffer to set the
+variable @code{midnight-mode} to @code{t}. @xref{Easy Customization}.
+
+@node Several Buffers
+@section Operating on Several Buffers
+@cindex buffer menu
+
+ The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
+you to request operations on various Emacs buffers by editing an Emacs
+buffer containing a list of them. You can save buffers, kill them
+(here called @dfn{deleting} them, for consistency with Dired), or display
+them.
+
+@table @kbd
+@item M-x buffer-menu
+Begin editing a buffer listing all Emacs buffers.
+@end table
+
+@findex buffer-menu
+ The command @code{buffer-menu} writes a list of all Emacs buffers into
+the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
+mode. The buffer is read-only, and can be changed only through the
+special commands described in this section. The usual Emacs cursor
+motion commands can be used in the @samp{*Buffer List*} buffer. The
+following commands apply to the buffer described on the current line.
+
+@table @kbd
+@item d
+Request to delete (kill) the buffer, then move down. The request
+shows as a @samp{D} on the line, before the buffer name. Requested
+deletions take place when you type the @kbd{x} command.
+@item C-d
+Like @kbd{d} but move up afterwards instead of down.
+@item s
+Request to save the buffer. The request shows as an @samp{S} on the
+line. Requested saves take place when you type the @kbd{x} command.
+You may request both saving and deletion for the same buffer.
+@item x
+Perform previously requested deletions and saves.
+@item u
+Remove any request made for the current line, and move down.
+@item @key{DEL}
+Move to previous line and remove any request made for that line.
+@end table
+
+ The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
+flags also move down (or up) one line. They accept a numeric argument
+as a repeat count.
+
+ These commands operate immediately on the buffer listed on the current
+line:
+
+@table @kbd
+@item ~
+Mark the buffer ``unmodified.'' The command @kbd{~} does this
+immediately when you type it.
+@item %
+Toggle the buffer's read-only flag. The command @kbd{%} does
+this immediately when you type it.
+@item t
+Visit the buffer as a tags table. @xref{Select Tags Table}.
+@end table
+
+ There are also commands to select another buffer or buffers:
+
+@table @kbd
+@item q
+Quit the buffer menu---immediately display the most recent formerly
+visible buffer in its place.
+@item @key{RET}
+@itemx f
+Immediately select this line's buffer in place of the @samp{*Buffer
+List*} buffer.
+@item o
+Immediately select this line's buffer in another window as if by
+@kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible.
+@item C-o
+Immediately display this line's buffer in another window, but don't
+select the window.
+@item 1
+Immediately select this line's buffer in a full-screen window.
+@item 2
+Immediately set up two windows, with this line's buffer in one, and the
+previously selected buffer (aside from the buffer @samp{*Buffer List*})
+in the other.
+@item b
+Bury the buffer listed on this line.
+@item m
+Mark this line's buffer to be displayed in another window if you exit
+with the @kbd{v} command. The request shows as a @samp{>} at the
+beginning of the line. (A single buffer may not have both a delete
+request and a display request.)
+@item v
+Immediately select this line's buffer, and also display in other windows
+any buffers previously marked with the @kbd{m} command. If you have not
+marked any buffers, this command is equivalent to @kbd{1}.
+@end table
+
+ All that @code{buffer-menu} does directly is create and switch to a
+suitable buffer, and turn on Buffer Menu mode. Everything else
+described above is implemented by the special commands provided in
+Buffer Menu mode. One consequence of this is that you can switch from
+the @samp{*Buffer List*} buffer to another Emacs buffer, and edit there.
+You can reselect the @samp{*Buffer List*} buffer later, to perform the
+operations already requested, or you can kill it, or pay no further
+attention to it.
+
+ The only difference between @code{buffer-menu} and @code{list-buffers}
+is that @code{buffer-menu} switches to the @samp{*Buffer List*} buffer
+in the selected window; @code{list-buffers} displays it in another
+window. If you run @code{list-buffers} (that is, type @kbd{C-x C-b})
+and select the buffer list manually, you can use all of the commands
+described here.
+
+ The buffer @samp{*Buffer List*} is not updated automatically when
+buffers are created and killed; its contents are just text. If you have
+created, deleted or renamed buffers, the way to update @samp{*Buffer
+List*} to show what you have done is to type @kbd{g}
+(@code{revert-buffer}) or repeat the @code{buffer-menu} command.
+
+@node Indirect Buffers
+@section Indirect Buffers
+@cindex indirect buffer
+@cindex base buffer
+
+ An @dfn{indirect buffer} shares the text of some other buffer, which
+is called the @dfn{base buffer} of the indirect buffer. In some ways it
+is the analogue, for buffers, of a symbolic link between files.
+
+@table @kbd
+@findex make-indirect-buffer
+@item M-x make-indirect-buffer @var{base-buffer} @key{RET} @var{indirect-name} @key{RET}
+Create an indirect buffer named @var{indirect-name} whose base buffer
+is @var{base-buffer}.
+@end table
+
+ The text of the indirect buffer is always identical to the text of its
+base buffer; changes made by editing either one are visible immediately
+in the other. But in all other respects, the indirect buffer and its
+base buffer are completely separate. They have different names,
+different values of point, different narrowing, different markers,
+different major modes, and different local variables.
+
+ An indirect buffer cannot visit a file, but its base buffer can. If
+you try to save the indirect buffer, that actually works by saving the
+base buffer. Killing the base buffer effectively kills the indirect
+buffer, but killing an indirect buffer has no effect on its base buffer.
+
+ One way to use indirect buffers is to display multiple views of an
+outline. @xref{Outline Views}.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Building, Abbrevs, Programs, Top
+@chapter Compiling and Testing Programs
+@cindex building programs
+@cindex program building
+@cindex running Lisp functions
+
+ The previous chapter discusses the Emacs commands that are useful for
+making changes in programs. This chapter deals with commands that assist
+in the larger process of developing and maintaining programs.
+
+@menu
+* Compilation:: Compiling programs in languages other
+ than Lisp (C, Pascal, etc.).
+* Grep Searching:: Running grep as if it were a compiler.
+* Compilation Mode:: The mode for visiting compiler errors.
+* Compilation Shell:: Customizing your shell properly
+ for use in the compilation buffer.
+* Debuggers:: Running symbolic debuggers for non-Lisp programs.
+* Executing Lisp:: Various modes for editing Lisp programs,
+ with different facilities for running
+ the Lisp programs.
+* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
+* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
+* Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
+* External Lisp:: Communicating through Emacs with a separate Lisp.
+@end menu
+
+@node Compilation
+@section Running Compilations under Emacs
+@cindex inferior process
+@cindex make
+@cindex compilation errors
+@cindex error log
+
+ Emacs can run compilers for noninteractive languages such as C and
+Fortran as inferior processes, feeding the error log into an Emacs buffer.
+It can also parse the error messages and show you the source lines where
+compilation errors occurred.
+
+@table @kbd
+@item M-x compile
+Run a compiler asynchronously under Emacs, with error messages to
+@samp{*compilation*} buffer.
+@item M-x grep
+Run @code{grep} asynchronously under Emacs, with matching lines
+listed in the buffer named @samp{*grep*}.
+@item M-x grep-find
+Run @code{grep} via @code{find}, with user-specified arguments, and
+collect output in the buffer named @samp{*grep*}.
+@item M-x kill-compilation
+@itemx M-x kill-grep
+Kill the running compilation or @code{grep} subprocess.
+@end table
+
+@findex compile
+ To run @code{make} or another compilation command, do @kbd{M-x
+compile}. This command reads a shell command line using the minibuffer,
+and then executes the command in an inferior shell, putting output in
+the buffer named @samp{*compilation*}. The current buffer's default
+directory is used as the working directory for the execution of the
+command; normally, therefore, the compilation happens in this
+directory.
+
+@vindex compile-command
+ When the shell command line is read, the minibuffer appears containing
+a default command line, which is the command you used the last time you
+did @kbd{M-x compile}. If you type just @key{RET}, the same command
+line is used again. For the first @kbd{M-x compile}, the default is
+@samp{make -k}. The default compilation command comes from the variable
+@code{compile-command}; if the appropriate compilation command for a
+file is something other than @samp{make -k}, it can be useful for the
+file to specify a local value for @code{compile-command} (@pxref{File
+Variables}).
+
+ Starting a compilation displays the buffer @samp{*compilation*} in
+another window but does not select it. The buffer's mode line tells you
+whether compilation is finished, with the word @samp{run} or @samp{exit}
+inside the parentheses. You do not have to keep this buffer visible;
+compilation continues in any case. While a compilation is going on, the
+string @samp{Compiling} appears in the mode lines of all windows. When
+this string disappears, the compilation is finished.
+
+ If you want to watch the compilation transcript as it appears, switch
+to the @samp{*compilation*} buffer and move point to the end of the
+buffer. When point is at the end, new compilation output is inserted
+above point, which remains at the end. If point is not at the end of
+the buffer, it remains fixed while more compilation output is added at
+the end of the buffer.
+
+@vindex compilation-scroll-output
+ If you set the variable @code{compilation-scroll-output} to a
+non-@code{nil} value, then the compilation buffer always scrolls to
+follow output as it comes in.
+
+@findex kill-compilation
+ To kill the compilation process, do @kbd{M-x kill-compilation}. When
+the compiler process terminates, the mode line of the
+@samp{*compilation*} buffer changes to say @samp{signal} instead of
+@samp{run}. Starting a new compilation also kills any running
+compilation, as only one can exist at any time. However, @kbd{M-x
+compile} asks for confirmation before actually killing a compilation
+that is running.
+
+@node Grep Searching
+@section Searching with Grep under Emacs
+
+@findex grep
+ Just as you can run a compiler from Emacs and then visit the lines
+where there were compilation errors, you can also run @code{grep} and
+then visit the lines on which matches were found. This works by
+treating the matches reported by @code{grep} as if they were ``errors.''
+
+ To do this, type @kbd{M-x grep}, then enter a command line that
+specifies how to run @code{grep}. Use the same arguments you would give
+@code{grep} when running it normally: a @code{grep}-style regexp
+(usually in single-quotes to quote the shell's special characters)
+followed by file names, which may use wildcards. The output from
+@code{grep} goes in the @samp{*grep*} buffer. You can find the
+corresponding lines in the original files using @kbd{C-x `} and
+@key{RET}, as with compilation errors.
+
+ If you specify a prefix argument for @kbd{M-x grep}, it figures out
+the tag (@pxref{Tags}) around point, and puts that into the default
+@code{grep} command.
+
+@findex grep-find
+ The command @kbd{M-x grep-find} is similar to @kbd{M-x grep}, but it
+supplies a different initial default for the command---one that runs
+both @code{find} and @code{grep}, so as to search every file in a
+directory tree. See also the @code{find-grep-dired} command,
+in @ref{Dired and Find}.
+
+@node Compilation Mode
+@section Compilation Mode
+
+@findex compile-goto-error
+@cindex Compilation mode
+@cindex mode, Compilation
+ The @samp{*compilation*} buffer uses a special major mode, Compilation
+mode, whose main feature is to provide a convenient way to look at the
+source line where the error happened.
+
+@table @kbd
+@item C-x `
+Visit the locus of the next compiler error message or @code{grep} match.
+@item @key{RET}
+Visit the locus of the error message that point is on.
+This command is used in the compilation buffer.
+@item Mouse-2
+Visit the locus of the error message that you click on.
+@end table
+
+@kindex C-x `
+@findex next-error
+ You can visit the source for any particular error message by moving
+point in @samp{*compilation*} to that error message and typing @key{RET}
+(@code{compile-goto-error}). Or click @kbd{Mouse-2} on the error message;
+you need not switch to the @samp{*compilation*} buffer first.
+
+ To parse the compiler error messages sequentially, type @kbd{C-x `}
+(@code{next-error}). The character following the @kbd{C-x} is the
+backquote or ``grave accent,'' not the single-quote. This command is
+available in all buffers, not just in @samp{*compilation*}; it displays
+the next error message at the top of one window and source location of
+the error in another window.
+
+ The first time @kbd{C-x `} is used after the start of a compilation,
+it moves to the first error's location. Subsequent uses of @kbd{C-x `}
+advance down to subsequent errors. If you visit a specific error
+message with @key{RET} or @kbd{Mouse-2}, subsequent @kbd{C-x `}
+commands advance from there. When @kbd{C-x `} gets to the end of the
+buffer and finds no more error messages to visit, it fails and signals
+an Emacs error.
+
+ @kbd{C-u C-x `} starts scanning from the beginning of the compilation
+buffer. This is one way to process the same set of errors again.
+
+ Compilation mode also redefines the keys @key{SPC} and @key{DEL} to
+scroll by screenfuls, and @kbd{M-n} and @kbd{M-p} to move to the next or
+previous error message. You can also use @kbd{M-@{} and @kbd{M-@}} to
+move up or down to an error message for a different source file.
+
+ The features of Compilation mode are also available in a minor mode
+called Compilation Minor mode. This lets you parse error messages in
+any buffer, not just a normal compilation output buffer. Type @kbd{M-x
+compilation-minor-mode} to enable the minor mode. This defines the keys
+@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode.
+
+ Compilation minor mode works in any buffer, as long as the contents
+are in a format that it understands. In an Rlogin buffer (@pxref{Remote
+Host}), Compilation minor mode automatically accesses remote source
+files by FTP (@pxref{File Names}).
+
+@node Compilation Shell
+@section Subshells for Compilation
+
+ Emacs uses a shell to run the compilation command, but specifies
+the option for a noninteractive shell. This means, in particular, that
+the shell should start with no prompt. If you find your usual shell
+prompt making an unsightly appearance in the @samp{*compilation*}
+buffer, it means you have made a mistake in your shell's init file by
+setting the prompt unconditionally. (This init file's name may be
+@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or various
+other things, depending on the shell you use.) The shell init file
+should set the prompt only if there already is a prompt. In csh, here
+is how to do it:
+
+@example
+if ($?prompt) set prompt = @dots{}
+@end example
+
+@noindent
+And here's how to do it in bash:
+
+@example
+if [ "$@{PS1+set@}" = set ]
+then PS1=@dots{}
+fi
+@end example
+
+ There may well be other things that your shell's init file
+ought to do only for an interactive shell. You can use the same
+method to conditionalize them.
+
+ The MS-DOS ``operating system'' does not support asynchronous
+subprocesses; to work around this lack, @kbd{M-x compile} runs the
+compilation command synchronously on MS-DOS. As a consequence, you must
+wait until the command finishes before you can do anything else in
+Emacs. @xref{MS-DOS}.
+
+@node Debuggers
+@section Running Debuggers Under Emacs
+@cindex debuggers
+@cindex GUD library
+@cindex GDB
+@cindex DBX
+@cindex SDB
+@cindex XDB
+@cindex Perldb
+@cindex JDB
+@cindex PDB
+
+@c Do you believe in GUD?
+The GUD (Grand Unified Debugger) library provides an interface to
+various symbolic debuggers from within Emacs. We recommend the debugger
+GDB, which is free software, but you can also run DBX, SDB or XDB if you
+have them. GUD can also serve as an interface to the Perl's debugging
+mode, the Python debugger PDB, and to JDB, the Java Debugger.
+
+@menu
+* Starting GUD:: How to start a debugger subprocess.
+* Debugger Operation:: Connection between the debugger and source buffers.
+* Commands of GUD:: Key bindings for common commands.
+* GUD Customization:: Defining your own commands for GUD.
+@end menu
+
+@node Starting GUD
+@subsection Starting GUD
+
+ There are several commands for starting a debugger, each corresponding
+to a particular debugger program.
+
+@table @kbd
+@item M-x gdb @key{RET} @var{file} @key{RET}
+@findex gdb
+Run GDB as a subprocess of Emacs. This command creates a buffer for
+input and output to GDB, and switches to it. If a GDB buffer already
+exists, it just switches to that buffer.
+
+@item M-x dbx @key{RET} @var{file} @key{RET}
+@findex dbx
+Similar, but run DBX instead of GDB.
+
+@item M-x xdb @key{RET} @var{file} @key{RET}
+@findex xdb
+@vindex gud-xdb-directories
+Similar, but run XDB instead of GDB. Use the variable
+@code{gud-xdb-directories} to specify directories to search for source
+files.
+
+@item M-x sdb @key{RET} @var{file} @key{RET}
+@findex sdb
+Similar, but run SDB instead of GDB.
+
+ Some versions of SDB do not mention source file names in their
+messages. When you use them, you need to have a valid tags table
+(@pxref{Tags}) in order for GUD to find functions in the source code.
+If you have not visited a tags table or the tags table doesn't list one
+of the functions, you get a message saying @samp{The sdb support
+requires a valid tags table to work}. If this happens, generate a valid
+tags table in the working directory and try again.
+
+@item M-x perldb @key{RET} @var{file} @key{RET}
+@findex perldb
+Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
+
+@item M-x jdb @key{RET} @var{file} @key{RET}
+@findex jdb
+Run the Java debugger to debug @var{file}.
+
+@item M-x pdb @key{RET} @var{file} @key{RET}
+@findex pdb
+Run the Python debugger to debug @var{file}.
+@end table
+
+ Each of these commands takes one argument: a command line to invoke
+the debugger. In the simplest case, specify just the name of the
+executable file you want to debug. You may also use options that the
+debugger supports. However, shell wildcards and variables are not
+allowed. GUD assumes that the first argument not starting with a
+@samp{-} is the executable file name.
+
+ Emacs can only run one debugger process at a time.
+
+@node Debugger Operation
+@subsection Debugger Operation
+
+ When you run a debugger with GUD, the debugger uses an Emacs buffer
+for its ordinary input and output. This is called the GUD buffer. The
+debugger displays the source files of the program by visiting them in
+Emacs buffers. An arrow (@samp{=>}) in one of these buffers indicates
+the current execution line. Moving point in this buffer does not move
+the arrow.
+
+ You can start editing these source files at any time in the buffers
+that were made to display them. The arrow is not part of the file's
+text; it appears only on the screen. If you do modify a source file,
+keep in mind that inserting or deleting lines will throw off the arrow's
+positioning; GUD has no way of figuring out which line corresponded
+before your changes to the line number in a debugger message. Also,
+you'll typically have to recompile and restart the program for your
+changes to be reflected in the debugger's tables.
+
+ If you wish, you can control your debugger process entirely through the
+debugger buffer, which uses a variant of Shell mode. All the usual
+commands for your debugger are available, and you can use the Shell mode
+history commands to repeat them. @xref{Shell Mode}.
+
+@node Commands of GUD
+@subsection Commands of GUD
+
+ The GUD interaction buffer uses a variant of Shell mode, so the
+commands of Shell mode are available (@pxref{Shell Mode}). GUD mode
+also provides commands for setting and clearing breakpoints, for
+selecting stack frames, and for stepping through the program. These
+commands are available both in the GUD buffer and globally, but with
+different key bindings.
+
+ The breakpoint commands are usually used in source file buffers,
+because that is the way to specify where to set or clear the breakpoint.
+Here's the global command to set a breakpoint:
+
+@table @kbd
+@item C-x @key{SPC}
+@kindex C-x SPC
+Set a breakpoint on the source line that point is on.
+@end table
+
+@kindex C-x C-a @r{(GUD)}
+ Here are the other special commands provided by GUD. The keys
+starting with @kbd{C-c} are available only in the GUD interaction
+buffer. The key bindings that start with @kbd{C-x C-a} are available in
+the GUD interaction buffer and also in source files.
+
+@table @kbd
+@item C-c C-l
+@kindex C-c C-l @r{(GUD)}
+@itemx C-x C-a C-l
+@findex gud-refresh
+Display in another window the last line referred to in the GUD
+buffer (that is, the line indicated in the last location message).
+This runs the command @code{gud-refresh}.
+
+@item C-c C-s
+@kindex C-c C-s @r{(GUD)}
+@itemx C-x C-a C-s
+@findex gud-step
+Execute a single line of code (@code{gud-step}). If the line contains
+a function call, execution stops after entering the called function.
+
+@item C-c C-n
+@kindex C-c C-n @r{(GUD)}
+@itemx C-x C-a C-n
+@findex gud-next
+Execute a single line of code, stepping across entire function calls
+at full speed (@code{gud-next}).
+
+@item C-c C-i
+@kindex C-c C-i @r{(GUD)}
+@itemx C-x C-a C-i
+@findex gud-stepi
+Execute a single machine instruction (@code{gud-stepi}).
+
+@need 3000
+@item C-c C-r
+@kindex C-c C-r @r{(GUD)}
+@itemx C-x C-a C-r
+@findex gud-cont
+Continue execution without specifying any stopping point. The program
+will run until it hits a breakpoint, terminates, or gets a signal that
+the debugger is checking for (@code{gud-cont}).
+
+@need 1000
+@item C-c C-d
+@kindex C-c C-d @r{(GUD)}
+@itemx C-x C-a C-d
+@findex gud-remove
+Delete the breakpoint(s) on the current source line, if any
+(@code{gud-remove}). If you use this command in the GUD interaction
+buffer, it applies to the line where the program last stopped.
+
+@item C-c C-t
+@kindex C-c C-t @r{(GUD)}
+@itemx C-x C-a C-t
+@findex gud-tbreak
+Set a temporary breakpoint on the current source line, if any.
+If you use this command in the GUD interaction buffer,
+it applies to the line where the program last stopped.
+@end table
+
+ The above commands are common to all supported debuggers. If you are
+using GDB or (some versions of) DBX, these additional commands are available:
+
+@table @kbd
+@item C-c <
+@kindex C-c < @r{(GUD)}
+@itemx C-x C-a <
+@findex gud-up
+Select the next enclosing stack frame (@code{gud-up}). This is
+equivalent to the @samp{up} command.
+
+@item C-c >
+@kindex C-c > @r{(GUD)}
+@itemx C-x C-a >
+@findex gud-down
+Select the next inner stack frame (@code{gud-down}). This is
+equivalent to the @samp{down} command.
+@end table
+
+ If you are using GDB, these additional key bindings are available:
+
+@table @kbd
+@item @key{TAB}
+@kindex TAB @r{(GUD)}
+@findex gud-gdb-complete-command
+With GDB, complete a symbol name (@code{gud-gdb-complete-command}).
+This key is available only in the GUD interaction buffer, and requires
+GDB versions 4.13 and later.
+
+@item C-c C-f
+@kindex C-c C-f @r{(GUD)}
+@itemx C-x C-a C-f
+@findex gud-finish
+Run the program until the selected stack frame returns (or until it
+stops for some other reason).
+@end table
+
+ These commands interpret a numeric argument as a repeat count, when
+that makes sense.
+
+ Because @key{TAB} serves as a completion command, you can't use it to
+enter a tab as input to the program you are debugging with GDB.
+Instead, type @kbd{C-q @key{TAB}} to enter a tab.
+
+@node GUD Customization
+@subsection GUD Customization
+
+@vindex gdb-mode-hook
+@vindex dbx-mode-hook
+@vindex sdb-mode-hook
+@vindex xdb-mode-hook
+@vindex perldb-mode-hook
+@vindex pdb-mode-hook
+@vindex jdb-mode-hook
+ On startup, GUD runs one of the following hooks: @code{gdb-mode-hook},
+if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;
+@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you
+are using XDB; @code{perldb-mode-hook}, for Perl debugging mode;
+@code{jdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can
+use these hooks to define custom key bindings for the debugger
+interaction buffer. @xref{Hooks}.
+
+ Here is a convenient way to define a command that sends a particular
+command string to the debugger, and set up a key binding for it in the
+debugger interaction buffer:
+
+@findex gud-def
+@example
+(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})
+@end example
+
+ This defines a command named @var{function} which sends
+@var{cmdstring} to the debugger process, and gives it the documentation
+string @var{docstring}. You can use the command thus defined in any
+buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds
+the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to
+@kbd{C-x C-a @var{binding}} generally.
+
+ The command string @var{cmdstring} may contain certain
+@samp{%}-sequences that stand for data to be filled in at the time
+@var{function} is called:
+
+@table @samp
+@item %f
+The name of the current source file. If the current buffer is the GUD
+buffer, then the ``current source file'' is the file that the program
+stopped in.
+@c This said, ``the name of the file the program counter was in at the last breakpoint.''
+@c But I suspect it is really the last stop file.
+
+@item %l
+The number of the current source line. If the current buffer is the GUD
+buffer, then the ``current source line'' is the line that the program
+stopped in.
+
+@item %e
+The text of the C lvalue or function-call expression at or adjacent to point.
+
+@item %a
+The text of the hexadecimal address at or adjacent to point.
+
+@item %p
+The numeric argument of the called function, as a decimal number. If
+the command is used without a numeric argument, @samp{%p} stands for the
+empty string.
+
+If you don't use @samp{%p} in the command string, the command you define
+ignores any numeric argument.
+@end table
+
+@node Executing Lisp
+@section Executing Lisp Expressions
+
+ Emacs has several different major modes for Lisp and Scheme. They are
+the same in terms of editing commands, but differ in the commands for
+executing Lisp expressions. Each mode has its own purpose.
+
+@table @asis
+@item Emacs-Lisp mode
+The mode for editing source files of programs to run in Emacs Lisp.
+This mode defines @kbd{C-M-x} to evaluate the current defun.
+@xref{Lisp Libraries}.
+@item Lisp Interaction mode
+The mode for an interactive session with Emacs Lisp. It defines
+@kbd{C-j} to evaluate the sexp before point and insert its value in the
+buffer. @xref{Lisp Interaction}.
+@item Lisp mode
+The mode for editing source files of programs that run in Lisps other
+than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun
+to an inferior Lisp process. @xref{External Lisp}.
+@item Inferior Lisp mode
+The mode for an interactive session with an inferior Lisp process.
+This mode combines the special features of Lisp mode and Shell mode
+(@pxref{Shell Mode}).
+@item Scheme mode
+Like Lisp mode but for Scheme programs.
+@item Inferior Scheme mode
+The mode for an interactive session with an inferior Scheme process.
+@end table
+
+ Most editing commands for working with Lisp programs are in fact
+available globally. @xref{Programs}.
+
+@node Lisp Libraries
+@section Libraries of Lisp Code for Emacs
+@cindex libraries
+@cindex loading Lisp code
+
+ Lisp code for Emacs editing commands is stored in files whose names
+conventionally end in @file{.el}. This ending tells Emacs to edit them in
+Emacs-Lisp mode (@pxref{Executing Lisp}).
+
+@findex load-file
+ To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This
+command reads a file name using the minibuffer and then executes the
+contents of that file as Lisp code. It is not necessary to visit the
+file first; in any case, this command reads the file as found on disk,
+not text in an Emacs buffer.
+
+@findex load
+@findex load-library
+ Once a file of Lisp code is installed in the Emacs Lisp library
+directories, users can load it using @kbd{M-x load-library}. Programs can
+load it by calling @code{load-library}, or with @code{load}, a more primitive
+function that is similar but accepts some additional arguments.
+
+ @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
+searches a sequence of directories and tries three file names in each
+directory. Suppose your argument is @var{lib}; the three names are
+@file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just
+@file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention
+the result of compiling @file{@var{lib}.el}; it is better to load the
+compiled file, since it will load and run faster.
+
+ If @code{load-library} finds that @file{@var{lib}.el} is newer than
+@file{@var{lib}.elc} file, it prints a warning, because it's likely that
+somebody made changes to the @file{.el} file and forgot to recompile
+it.
+
+ Because the argument to @code{load-library} is usually not in itself
+a valid file name, file name completion is not available. Indeed, when
+using this command, you usually do not know exactly what file name
+will be used.
+
+@vindex load-path
+ The sequence of directories searched by @kbd{M-x load-library} is
+specified by the variable @code{load-path}, a list of strings that are
+directory names. The default value of the list contains the directory where
+the Lisp code for Emacs itself is stored. If you have libraries of
+your own, put them in a single directory and add that directory
+to @code{load-path}. @code{nil} in this list stands for the current default
+directory, but it is probably not a good idea to put @code{nil} in the
+list. If you find yourself wishing that @code{nil} were in the list,
+most likely what you really want to do is use @kbd{M-x load-file}
+this once.
+
+@cindex autoload
+ Often you do not have to give any command to load a library, because
+the commands defined in the library are set up to @dfn{autoload} that
+library. Trying to run any of those commands calls @code{load} to load
+the library; this replaces the autoload definitions with the real ones
+from the library.
+
+@cindex byte code
+ Emacs Lisp code can be compiled into byte-code which loads faster,
+takes up less space when loaded, and executes faster. @xref{Byte
+Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}.
+By convention, the compiled code for a library goes in a separate file
+whose name consists of the library source file with @samp{c} appended.
+Thus, the compiled code for @file{foo.el} goes in @file{foo.elc}.
+That's why @code{load-library} searches for @samp{.elc} files first.
+
+@node Lisp Eval
+@section Evaluating Emacs-Lisp Expressions
+@cindex Emacs-Lisp mode
+@cindex mode, Emacs-Lisp
+
+@findex emacs-lisp-mode
+ Lisp programs intended to be run in Emacs should be edited in
+Emacs-Lisp mode; this happens automatically for file names ending in
+@file{.el}. By contrast, Lisp mode itself is used for editing Lisp
+programs intended for other Lisp systems. To switch to Emacs-Lisp mode
+explicitly, use the command @kbd{M-x emacs-lisp-mode}.
+
+ For testing of Lisp programs to run in Emacs, it is often useful to
+evaluate part of the program as it is found in the Emacs buffer. For
+example, after changing the text of a Lisp function definition,
+evaluating the definition installs the change for future calls to the
+function. Evaluation of Lisp expressions is also useful in any kind of
+editing, for invoking noninteractive functions (functions that are
+not commands).
+
+@table @kbd
+@item M-:
+Read a single Lisp expression in the minibuffer, evaluate it, and print
+the value in the echo area (@code{eval-expression}).
+@item C-x C-e
+Evaluate the Lisp expression before point, and print the value in the
+echo area (@code{eval-last-sexp}).
+@item C-M-x
+Evaluate the defun containing or after point, and print the value in
+the echo area (@code{eval-defun}).
+@item M-x eval-region
+Evaluate all the Lisp expressions in the region.
+@item M-x eval-current-buffer
+Evaluate all the Lisp expressions in the buffer.
+@end table
+
+@kindex M-:
+@findex eval-expression
+ @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating
+a Lisp expression interactively. It reads the expression using the
+minibuffer, so you can execute any expression on a buffer regardless of
+what the buffer contains. When the expression is evaluated, the current
+buffer is once again the buffer that was current when @kbd{M-:} was
+typed.
+
+@kindex C-M-x @r{(Emacs-Lisp mode)}
+@findex eval-defun
+ In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command
+@code{eval-defun}, which parses the defun containing or following point
+as a Lisp expression and evaluates it. The value is printed in the echo
+area. This command is convenient for installing in the Lisp environment
+changes that you have just made in the text of a function definition.
+
+ @kbd{C-M-x} treats @code{defvar} expressions specially. Normally,
+evaluating a @code{defvar} expression does nothing if the variable it
+defines already has a value. But @kbd{C-M-x} unconditionally resets the
+variable to the initial value specified in the @code{defvar} expression.
+This special feature is convenient for debugging Lisp programs.
+
+@kindex C-x C-e
+@findex eval-last-sexp
+ The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp
+expression preceding point in the buffer, and displays the value in the
+echo area. It is available in all major modes, not just Emacs-Lisp
+mode. It does not treat @code{defvar} specially.
+
+ If @kbd{C-M-x}, @kbd{C-x C-e}, or @kbd{M-:} is given a numeric
+argument, it inserts the value into the current buffer at point, rather
+than displaying it in the echo area. The argument's value does not
+matter.
+
+@findex eval-region
+@findex eval-current-buffer
+ The most general command for evaluating Lisp expressions from a buffer
+is @code{eval-region}. @kbd{M-x eval-region} parses the text of the
+region as one or more Lisp expressions, evaluating them one by one.
+@kbd{M-x eval-current-buffer} is similar but evaluates the entire
+buffer. This is a reasonable way to install the contents of a file of
+Lisp code that you are just ready to test. Later, as you find bugs and
+change individual functions, use @kbd{C-M-x} on each function that you
+change. This keeps the Lisp world in step with the source file.
+
+@node Lisp Interaction
+@section Lisp Interaction Buffers
+
+ The buffer @samp{*scratch*} which is selected when Emacs starts up is
+provided for evaluating Lisp expressions interactively inside Emacs.
+
+ The simplest way to use the @samp{*scratch*} buffer is to insert Lisp
+expressions and type @kbd{C-j} after each expression. This command
+reads the Lisp expression before point, evaluates it, and inserts the
+value in printed representation before point. The result is a complete
+typescript of the expressions you have evaluated and their values.
+
+ The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
+is the same as Emacs-Lisp mode except for the binding of @kbd{C-j}.
+
+@findex lisp-interaction-mode
+ The rationale for this feature is that Emacs must have a buffer when
+it starts up, but that buffer is not useful for editing files since a
+new buffer is made for every file that you visit. The Lisp interpreter
+typescript is the most useful thing I can think of for the initial
+buffer to do. Type @kbd{M-x lisp-interaction-mode} to put the current
+buffer in Lisp Interaction mode.
+
+@findex ielm
+ An alternative way of evaluating Emacs Lisp expressions interactively
+is to use Inferior Emacs-Lisp mode, which provides an interface rather
+like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp
+expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer
+which uses this mode.
+
+@node External Lisp
+@section Running an External Lisp
+
+ Emacs has facilities for running programs in other Lisp systems. You can
+run a Lisp process as an inferior of Emacs, and pass expressions to it to
+be evaluated. You can also pass changed function definitions directly from
+the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
+process.
+
+@findex run-lisp
+@vindex inferior-lisp-program
+@kindex C-x C-z
+ To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs
+the program named @code{lisp}, the same program you would run by typing
+@code{lisp} as a shell command, with both input and output going through
+an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal
+output'' from Lisp will go into the buffer, advancing point, and any
+``terminal input'' for Lisp comes from text in the buffer. (You can
+change the name of the Lisp executable file by setting the variable
+@code{inferior-lisp-program}.)
+
+ To give input to Lisp, go to the end of the buffer and type the input,
+terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp
+mode, which combines the special characteristics of Lisp mode with most
+of the features of Shell mode (@pxref{Shell Mode}). The definition of
+@key{RET} to send a line to a subprocess is one of the features of Shell
+mode.
+
+@findex lisp-mode
+ For the source files of programs to run in external Lisps, use Lisp
+mode. This mode can be selected with @kbd{M-x lisp-mode}, and is used
+automatically for files whose names end in @file{.l}, @file{.lsp}, or
+@file{.lisp}, as most Lisp systems usually expect.
+
+@kindex C-M-x @r{(Lisp mode)}
+@findex lisp-eval-defun
+ When you edit a function in a Lisp program you are running, the easiest
+way to send the changed definition to the inferior Lisp process is the key
+@kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun},
+which finds the defun around or following point and sends it as input to
+the Lisp process. (Emacs can send input to any inferior process regardless
+of what buffer is current.)
+
+ Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs
+to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
+programs to be run in Emacs): in both modes it has the effect of installing
+the function definition that point is in, but the way of doing so is
+different according to where the relevant Lisp environment is found.
+@xref{Executing Lisp}.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Calendar/Diary, Gnus, Dired, Top
+@chapter The Calendar and the Diary
+@cindex calendar
+@findex calendar
+
+ Emacs provides the functions of a desk calendar, with a diary of
+planned or past events. To enter the calendar, type @kbd{M-x calendar};
+this displays a three-month calendar centered on the current month, with
+point on the current date. With a numeric argument, as in @kbd{C-u M-x
+calendar}, it prompts you for the month and year to be the center of the
+three-month calendar. The calendar uses its own buffer, whose major
+mode is Calendar mode.
+
+ @kbd{Mouse-2} in the calendar brings up a menu of operations on a
+particular date; @kbd{C-Mouse-3} brings up a menu of commonly used
+calendar features that are independent of any particular date. To exit
+the calendar, type @kbd{q}. @xref{Calendar, Customizing the Calendar
+and Diary,, elisp, The Emacs Lisp Reference Manual}, for customization
+information about the calendar and diary.
+
+@menu
+* Calendar Motion:: Moving through the calendar; selecting a date.
+* Scroll Calendar:: Bringing earlier or later months onto the screen.
+* Counting Days:: How many days are there between two dates?
+* General Calendar:: Exiting or recomputing the calendar.
+* LaTeX Calendar:: Print a calendar using LaTeX.
+* Holidays:: Displaying dates of holidays.
+* Sunrise/Sunset:: Displaying local times of sunrise and sunset.
+* Lunar Phases:: Displaying phases of the moon.
+* Other Calendars:: Converting dates to other calendar systems.
+* Diary:: Displaying events from your diary.
+* Appointments:: Reminders when it's time to do something.
+* Daylight Savings:: How to specify when daylight savings time is active.
+@end menu
+
+@node Calendar Motion
+@section Movement in the Calendar
+
+@cindex moving inside the calendar
+ Calendar mode lets you move through the calendar in logical units of
+time such as days, weeks, months, and years. If you move outside the
+three months originally displayed, the calendar display ``scrolls''
+automatically through time to make the selected date visible. Moving to
+a date lets you view its holidays or diary entries, or convert it to other
+calendars; moving longer time periods is also useful simply to scroll the
+calendar.
+
+@menu
+* Calendar Unit Motion:: Moving by days, weeks, months, and years.
+* Move to Beginning or End:: Moving to start/end of weeks, months, and years.
+* Specified Dates:: Moving to the current date or another
+ specific date.
+@end menu
+
+@node Calendar Unit Motion
+@subsection Motion by Standard Lengths of Time
+
+ The commands for movement in the calendar buffer parallel the
+commands for movement in text. You can move forward and backward by
+days, weeks, months, and years.
+
+@table @kbd
+@item C-f
+Move point one day forward (@code{calendar-forward-day}).
+@item C-b
+Move point one day backward (@code{calendar-backward-day}).
+@item C-n
+Move point one week forward (@code{calendar-forward-week}).
+@item C-p
+Move point one week backward (@code{calendar-backward-week}).
+@item M-@}
+Move point one month forward (@code{calendar-forward-month}).
+@item M-@{
+Move point one month backward (@code{calendar-backward-month}).
+@item C-x ]
+Move point one year forward (@code{calendar-forward-year}).
+@item C-x [
+Move point one year backward (@code{calendar-backward-year}).
+@end table
+
+@kindex C-f @r{(Calendar mode)}
+@findex calendar-forward-day
+@kindex C-b @r{(Calendar mode)}
+@findex calendar-backward-day
+@kindex C-n @r{(Calendar mode)}
+@findex calendar-forward-week
+@kindex C-p @r{(Calendar mode)}
+@findex calendar-backward-week
+ The day and week commands are natural analogues of the usual Emacs
+commands for moving by characters and by lines. Just as @kbd{C-n}
+usually moves to the same column in the following line, in Calendar
+mode it moves to the same day in the following week. And @kbd{C-p}
+moves to the same day in the previous week.
+
+ The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and
+@kbd{C-p}, just as they normally are in other modes.
+
+@kindex M-@} @r{(Calendar mode)}
+@findex calendar-forward-month
+@kindex M-@{ @r{(Calendar mode)}
+@findex calendar-backward-month
+@kindex C-x ] @r{(Calendar mode)}
+@findex calendar-forward-year
+@kindex C-x [ @r{(Calendar mode)}
+@findex calendar-forward-year
+ The commands for motion by months and years work like those for
+weeks, but move a larger distance. The month commands @kbd{M-@}} and
+@kbd{M-@{} move forward or backward by an entire month's time. The
+year commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a
+whole year.
+
+ The easiest way to remember these commands is to consider months and
+years analogous to paragraphs and pages of text, respectively. But the
+commands themselves are not quite analogous. The ordinary Emacs paragraph
+commands move to the beginning or end of a paragraph, whereas these month
+and year commands move by an entire month or an entire year, which usually
+involves skipping across the end of a month or year.
+
+ All these commands accept a numeric argument as a repeat count.
+For convenience, the digit keys and the minus sign specify numeric
+arguments in Calendar mode even without the Meta modifier. For example,
+@kbd{100 C-f} moves point 100 days forward from its present location.
+
+@node Move to Beginning or End
+@subsection Beginning or End of Week, Month or Year
+
+ A week (or month, or year) is not just a quantity of days; we think of
+weeks (months, years) as starting on particular dates. So Calendar mode
+provides commands to move to the beginning or end of a week, month or
+year:
+
+@table @kbd
+@kindex C-a @r{(Calendar mode)}
+@findex calendar-beginning-of-week
+@item C-a
+Move point to start of week (@code{calendar-beginning-of-week}).
+@kindex C-e @r{(Calendar mode)}
+@findex calendar-end-of-week
+@item C-e
+Move point to end of week (@code{calendar-end-of-week}).
+@kindex M-a @r{(Calendar mode)}
+@findex calendar-beginning-of-month
+@item M-a
+Move point to start of month (@code{calendar-beginning-of-month}).
+@kindex M-e @r{(Calendar mode)}
+@findex calendar-end-of-month
+@item M-e
+Move point to end of month (@code{calendar-end-of-month}).
+@kindex M-< @r{(Calendar mode)}
+@findex calendar-beginning-of-year
+@item M-<
+Move point to start of year (@code{calendar-beginning-of-year}).
+@kindex M-> @r{(Calendar mode)}
+@findex calendar-end-of-year
+@item M->
+Move point to end of year (@code{calendar-end-of-year}).
+@end table
+
+ These commands also take numeric arguments as repeat counts, with the
+repeat count indicating how many weeks, months, or years to move
+backward or forward.
+
+@vindex calendar-week-start-day
+@cindex weeks, which day they start on
+@cindex calendar, first day of week
+ By default, weeks begin on Sunday. To make them begin on Monday
+instead, set the variable @code{calendar-week-start-day} to 1.
+
+@node Specified Dates
+@subsection Specified Dates
+
+ Calendar mode provides commands for moving to a particular date
+specified in various ways.
+
+@table @kbd
+@item g d
+Move point to specified date (@code{calendar-goto-date}).
+@item o
+Center calendar around specified month (@code{calendar-other-month}).
+@item .
+Move point to today's date (@code{calendar-goto-today}).
+@end table
+
+@kindex g d @r{(Calendar mode)}
+@findex calendar-goto-date
+ @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day
+of the month, and then moves to that date. Because the calendar includes all
+dates from the beginning of the current era, you must type the year in its
+entirety; that is, type @samp{1990}, not @samp{90}.
+
+@kindex o @r{(Calendar mode)}
+@findex calendar-other-month
+ @kbd{o} (@code{calendar-other-month}) prompts for a month and year,
+then centers the three-month calendar around that month.
+
+@kindex . @r{(Calendar mode)}
+@findex calendar-goto-today
+ You can return to today's date with @kbd{.}@:
+(@code{calendar-goto-today}).
+
+@node Scroll Calendar
+@section Scrolling in the Calendar
+
+@cindex scrolling in the calendar
+ The calendar display scrolls automatically through time when you move out
+of the visible portion. You can also scroll it manually. Imagine that the
+calendar window contains a long strip of paper with the months on it.
+Scrolling it means moving the strip so that new months become visible in
+the window.
+
+@table @kbd
+@item C-x <
+Scroll calendar one month forward (@code{scroll-calendar-left}).
+@item C-x >
+Scroll calendar one month backward (@code{scroll-calendar-right}).
+@item C-v
+@itemx @key{NEXT}
+Scroll calendar three months forward
+(@code{scroll-calendar-left-three-months}).
+@item M-v
+@itemx @key{PRIOR}
+Scroll calendar three months backward
+(@code{scroll-calendar-right-three-months}).
+@end table
+
+@kindex C-x < @r{(Calendar mode)}
+@findex scroll-calendar-left
+@kindex C-x > @r{(Calendar mode)}
+@findex scroll-calendar-right
+ The most basic calendar scroll commands scroll by one month at a
+time. This means that there are two months of overlap between the
+display before the command and the display after. @kbd{C-x <} scrolls
+the calendar contents one month to the left; that is, it moves the
+display forward in time. @kbd{C-x >} scrolls the contents to the
+right, which moves backwards in time.
+
+@kindex C-v @r{(Calendar mode)}
+@findex scroll-calendar-left-three-months
+@kindex M-v @r{(Calendar mode)}
+@findex scroll-calendar-right-three-months
+ The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire
+``screenful''---three months---in analogy with the usual meaning of
+these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes
+earlier dates visible. These commands take a numeric argument as a
+repeat count; in particular, since @kbd{C-u} multiplies the next command
+by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and
+typing @kbd{C-u M-v} scrolls the calendar backward by a year.
+
+ The function keys @key{NEXT} and @key{PRIOR} are equivalent to
+@kbd{C-v} and @kbd{M-v}, just as they are in other modes.
+
+@node Counting Days
+@section Counting Days
+
+@table @kbd
+@item M-=
+Display the number of days in the current region
+(@code{calendar-count-days-region}).
+@end table
+
+@kindex M-= @r{(Calendar mode)}
+@findex calendar-count-days-region
+ To determine the number of days in the region, type @kbd{M-=}
+(@code{calendar-count-days-region}). The numbers of days printed is
+@emph{inclusive}; that is, it includes the days specified by mark and
+point.
+
+@node General Calendar
+@section Miscellaneous Calendar Commands
+
+@table @kbd
+@item p d
+Display day-in-year (@code{calendar-print-day-of-year}).
+@item C-c C-l
+Regenerate the calendar window (@code{redraw-calendar}).
+@item SPC
+Scroll the next window (@code{scroll-other-window}).
+@item q
+Exit from calendar (@code{exit-calendar}).
+@end table
+
+@kindex p d @r{(Calendar mode)}
+@cindex day of year
+@findex calendar-print-day-of-year
+ To print the number of days elapsed since the start of the year, or
+the number of days remaining in the year, type the @kbd{p d} command
+(@code{calendar-print-day-of-year}). This displays both of those
+numbers in the echo area. The number of days elapsed includes the
+selected date. The number of days remaining does not include that
+date.
+
+@kindex C-c C-l @r{(Calendar mode)}
+@findex redraw-calendar
+ If the calendar window text gets corrupted, type @kbd{C-c C-l}
+(@code{redraw-calendar}) to redraw it. (This can only happen if you use
+non-Calendar-mode editing commands.)
+
+@kindex SPC @r{(Calendar mode)}
+ In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window})
+to scroll the other window. This is handy when you display a list of
+holidays or diary entries in another window.
+
+@kindex q @r{(Calendar mode)}
+@findex exit-calendar
+ To exit from the calendar, type @kbd{q} (@code{exit-calendar}). This
+buries all buffers related to the calendar, selecting other buffers.
+(If a frame contains a dedicated calendar window, exiting from the
+calendar iconifies that frame.)
+
+@node LaTeX Calendar
+@section LaTeX Calendar
+@cindex calendar and La@TeX{}
+
+ The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that
+prints as a calendar. Depending on the command you use, the printed
+calendar covers the day, week, month or year that point is in.
+
+@kindex t @r{(Calendar mode)}
+@table @kbd
+@item t m
+Generate a one-month calendar (@code{cal-tex-cursor-month}).
+@item t M
+Generate a sideways-printing one-month calendar
+(@code{cal-tex-cursor-month-landscape}).
+@item t d
+Generate a one-day calendar
+(@code{cal-tex-cursor-day}).
+@item t w 1
+Generate a one-page calendar for one week
+(@code{cal-tex-cursor-week}).
+@item t w 2
+Generate a two-page calendar for one week
+(@code{cal-tex-cursor-week2}).
+@item t w 3
+Generate an ISO-style calendar for one week
+(@code{cal-tex-cursor-week-iso}).
+@item t w 4
+Generate a calendar for one Monday-starting week
+(@code{cal-tex-cursor-week-monday}).
+@item t f w
+Generate a Filofax-style two-weeks-at-a-glance calendar
+(@code{cal-tex-cursor-filofax-2week}).
+@item t f W
+Generate a Filofax-style one-week-at-a-glance calendar
+(@code{cal-tex-cursor-filofax-week}).
+@item t y
+Generate a calendar for one year
+(@code{cal-tex-cursor-year}).
+@item t Y
+Generate a sideways-printing calendar for one year
+(@code{cal-tex-cursor-year-landscape}).
+@item t f y
+Generate a Filofax-style calendar for one year
+(@code{cal-tex-cursor-filofax-year}).
+@end table
+
+ Some of these commands print the calendar sideways (in ``landscape
+mode''), so it can be wider than it is long. Some of them use Filofax
+paper size (3.75in x 6.75in). All of these commands accept a prefix
+argument which specifies how many days, weeks, months or years to print
+(starting always with the selected one).
+
+ If the variable @code{cal-tex-holidays} is non-@code{nil} (the default),
+then the printed calendars show the holidays in @code{calendar-holidays}.
+If the variable @code{cal-tex-diary} is non-@code{nil} (the default is
+@code{nil}), diary entries are included also (in weekly and monthly
+calendars only). If the variable @code{cal-tex-rules} is non-@code{nil}
+(the default is @code{nil}), the calendar styles with sufficient room
+have ruled pages.
+
+@node Holidays
+@section Holidays
+@cindex holidays
+
+ The Emacs calendar knows about all major and many minor holidays,
+and can display them.
+
+@table @kbd
+@item h
+Display holidays for the selected date
+(@code{calendar-cursor-holidays}).
+@item Mouse-2 Holidays
+Display any holidays for the date you click on.
+@item x
+Mark holidays in the calendar window (@code{mark-calendar-holidays}).
+@item u
+Unmark calendar window (@code{calendar-unmark}).
+@item a
+List all holidays for the displayed three months in another window
+(@code{list-calendar-holidays}).
+@item M-x holidays
+List all holidays for three months around today's date in another
+window.
+@item M-x list-holidays
+List holidays in another window for a specified range of years.
+@end table
+
+@kindex h @r{(Calendar mode)}
+@findex calendar-cursor-holidays
+ To see if any holidays fall on a given date, position point on that
+date in the calendar window and use the @kbd{h} command. Alternatively,
+click on that date with @kbd{Mouse-2} and then choose @kbd{Holidays}
+from the menu that appears. Either way, this displays the holidays for
+that date, in the echo area if they fit there, otherwise in a separate
+window.
+
+@kindex x @r{(Calendar mode)}
+@findex mark-calendar-holidays
+@kindex u @r{(Calendar mode)}
+@findex calendar-unmark
+ To view the distribution of holidays for all the dates shown in the
+calendar, use the @kbd{x} command. This displays the dates that are
+holidays in a different face (or places a @samp{*} after these dates, if
+display with multiple faces is not available). The command applies both
+to the currently visible months and to other months that subsequently
+become visible by scrolling. To turn marking off and erase the current
+marks, type @kbd{u}, which also erases any diary marks (@pxref{Diary}).
+
+@kindex a @r{(Calendar mode)}
+@findex list-calendar-holidays
+ To get even more detailed information, use the @kbd{a} command, which
+displays a separate buffer containing a list of all holidays in the
+current three-month range. You can use @key{SPC} in the calendar window
+to scroll that list.
+
+@findex holidays
+ The command @kbd{M-x holidays} displays the list of holidays for the
+current month and the preceding and succeeding months; this works even
+if you don't have a calendar window. If you want the list of holidays
+centered around a different month, use @kbd{C-u M-x holidays}, which
+prompts for the month and year.
+
+ The holidays known to Emacs include United States holidays and the
+major Christian, Jewish, and Islamic holidays; also the solstices and
+equinoxes.
+
+@findex list-holidays
+ The command @kbd{M-x list-holidays} displays the list of holidays for
+a range of years. This function asks you for the starting and stopping
+years, and allows you to choose all the holidays or one of several
+categories of holidays. You can use this command even if you don't have
+a calendar window.
+
+ The dates used by Emacs for holidays are based on @emph{current
+practice}, not historical fact. Historically, for instance, the start
+of daylight savings time and even its existence have varied from year to
+year, but present United States law mandates that daylight savings time
+begins on the first Sunday in April. When the daylight savings rules
+are set up for the United States, Emacs always uses the present
+definition, even though it is wrong for some prior years.
+
+@node Sunrise/Sunset
+@section Times of Sunrise and Sunset
+@cindex sunrise and sunset
+
+ Special calendar commands can tell you, to within a minute or two, the
+times of sunrise and sunset for any date.
+
+@table @kbd
+@item S
+Display times of sunrise and sunset for the selected date
+(@code{calendar-sunrise-sunset}).
+@item Mouse-2 Sunrise/Sunset
+Display times of sunrise and sunset for the date you click on.
+@item M-x sunrise-sunset
+Display times of sunrise and sunset for today's date.
+@item C-u M-x sunrise-sunset
+Display times of sunrise and sunset for a specified date.
+@end table
+
+@kindex S @r{(Calendar mode)}
+@findex calendar-sunrise-sunset
+@findex sunrise-sunset
+ Within the calendar, to display the @emph{local times} of sunrise and
+sunset in the echo area, move point to the date you want, and type
+@kbd{S}. Alternatively, click @kbd{Mouse-2} on the date, then choose
+@kbd{Sunrise/Sunset} from the menu that appears. The command @kbd{M-x
+sunrise-sunset} is available outside the calendar to display this
+information for today's date or a specified date. To specify a date
+other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
+the year, month, and day.
+
+ You can display the times of sunrise and sunset for any location and
+any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a
+longitude, latitude, number of minutes difference from Coordinated
+Universal Time, and date, and then tells you the times of sunrise and
+sunset for that location on that date.
+
+ Because the times of sunrise and sunset depend on the location on
+earth, you need to tell Emacs your latitude, longitude, and location
+name before using these commands. Here is an example of what to set:
+
+@vindex calendar-location-name
+@vindex calendar-longitude
+@vindex calendar-latitude
+@example
+(setq calendar-latitude 40.1)
+(setq calendar-longitude -88.2)
+(setq calendar-location-name "Urbana, IL")
+@end example
+
+@noindent
+Use one decimal place in the values of @code{calendar-latitude} and
+@code{calendar-longitude}.
+
+ Your time zone also affects the local time of sunrise and sunset.
+Emacs usually gets time zone information from the operating system, but
+if these values are not what you want (or if the operating system does
+not supply them), you must set them yourself. Here is an example:
+
+@vindex calendar-time-zone
+@vindex calendar-standard-time-zone-name
+@vindex calendar-daylight-time-zone-name
+@example
+(setq calendar-time-zone -360)
+(setq calendar-standard-time-zone-name "CST")
+(setq calendar-daylight-time-zone-name "CDT")
+@end example
+
+@noindent
+The value of @code{calendar-time-zone} is the number of minutes
+difference between your local standard time and Coordinated Universal
+Time (Greenwich time). The values of
+@code{calendar-standard-time-zone-name} and
+@code{calendar-daylight-time-zone-name} are the abbreviations used in
+your time zone. Emacs displays the times of sunrise and sunset
+@emph{corrected for daylight savings time}. @xref{Daylight Savings},
+for how daylight savings time is determined.
+
+ As a user, you might find it convenient to set the calendar location
+variables for your usual physical location in your @file{.emacs} file.
+And when you install Emacs on a machine, you can create a
+@file{default.el} file which sets them properly for the typical location
+of most users of that machine. @xref{Init File}.
+
+@node Lunar Phases
+@section Phases of the Moon
+@cindex phases of the moon
+@cindex moon, phases of
+
+ These calendar commands display the dates and times of the phases of
+the moon (new moon, first quarter, full moon, last quarter). This
+feature is useful for debugging problems that ``depend on the phase of
+the moon.''
+
+@table @kbd
+@item M
+Display the dates and times for all the quarters of the moon for the
+three-month period shown (@code{calendar-phases-of-moon}).
+@item M-x phases-of-moon
+Display dates and times of the quarters of the moon for three months around
+today's date.
+@end table
+
+@kindex M @r{(Calendar mode)}
+@findex calendar-phases-of-moon
+ Within the calendar, use the @kbd{M} command to display a separate
+buffer of the phases of the moon for the current three-month range. The
+dates and times listed are accurate to within a few minutes.
+
+@findex phases-of-moon
+ Outside the calendar, use the command @kbd{M-x phases-of-moon} to
+display the list of the phases of the moon for the current month and the
+preceding and succeeding months. For information about a different
+month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and
+year.
+
+ The dates and times given for the phases of the moon are given in
+local time (corrected for daylight savings, when appropriate); but if
+the variable @code{calendar-time-zone} is void, Coordinated Universal
+Time (the Greenwich time zone) is used. @xref{Daylight Savings}.
+
+@node Other Calendars
+@section Conversion To and From Other Calendars
+
+@cindex Gregorian calendar
+ The Emacs calendar displayed is @emph{always} the Gregorian calendar,
+sometimes called the ``new style'' calendar, which is used in most of
+the world today. However, this calendar did not exist before the
+sixteenth century and was not widely used before the eighteenth century;
+it did not fully displace the Julian calendar and gain universal
+acceptance until the early twentieth century. The Emacs calendar can
+display any month since January, year 1 of the current era, but the
+calendar displayed is the Gregorian, even for a date at which the
+Gregorian calendar did not exist.
+
+ While Emacs cannot display other calendars, it can convert dates to
+and from several other calendars.
+
+@menu
+* Calendar Systems:: The calendars Emacs understands
+ (aside from Gregorian).
+* To Other Calendar:: Converting the selected date to various calendars.
+* From Other Calendar:: Moving to a date specified in another calendar.
+* Mayan Calendar:: Moving to a date specified in a Mayan calendar.
+@end menu
+
+@node Calendar Systems
+@subsection Supported Calendar Systems
+
+@cindex ISO commercial calendar
+ The ISO commercial calendar is used largely in Europe.
+
+@cindex Julian calendar
+ The Julian calendar, named after Julius Caesar, was the one used in Europe
+throughout medieval times, and in many countries up until the nineteenth
+century.
+
+@cindex Julian day numbers
+@cindex astronomical day numbers
+ Astronomers use a simple counting of days elapsed since noon, Monday,
+January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
+is called the @emph{Julian day number} or the @emph{Astronomical day number}.
+
+@cindex Hebrew calendar
+ The Hebrew calendar is used by tradition in the Jewish religion. The
+Emacs calendar program uses the Hebrew calendar to determine the dates
+of Jewish holidays. Hebrew calendar dates begin and end at sunset.
+
+@cindex Islamic calendar
+ The Islamic calendar is used in many predominantly Islamic countries.
+Emacs uses it to determine the dates of Islamic holidays. There is no
+universal agreement in the Islamic world about the calendar; Emacs uses
+a widely accepted version, but the precise dates of Islamic holidays
+often depend on proclamation by religious authorities, not on
+calculations. As a consequence, the actual dates of observance can vary
+slightly from the dates computed by Emacs. Islamic calendar dates begin
+and end at sunset.
+
+@cindex French Revolutionary calendar
+ The French Revolutionary calendar was created by the Jacobins after the 1789
+revolution, to represent a more secular and nature-based view of the annual
+cycle, and to install a 10-day week in a rationalization measure similar to
+the metric system. The French government officially abandoned this
+calendar at the end of 1805.
+
+@cindex Mayan calendar
+ The Maya of Central America used three separate, overlapping calendar
+systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}.
+Emacs knows about all three of these calendars. Experts dispute the
+exact correlation between the Mayan calendar and our calendar; Emacs uses the
+Goodman-Martinez-Thompson correlation in its calculations.
+
+@cindex Coptic calendar
+@cindex Ethiopic calendar
+ The Copts use a calendar based on the ancient Egyptian solar calendar.
+Their calendar consists of twelve 30-day months followed by an extra
+five-day period. Once every fourth year they add a leap day to this
+extra period to make it six days. The Ethiopic calendar is identical in
+structure, but has different year numbers and month names.
+
+@cindex Persian calendar
+ The Persians use a solar calendar based on a design of Omar Khayyam.
+Their calendar consists of twelve months of which the first six have 31
+days, the next five have 30 days, and the last has 29 in ordinary years
+and 30 in leap years. Leap years occur in a complicated pattern every
+four or five years.
+
+@cindex Chinese calendar
+ The Chinese calendar is a complicated system of lunar months arranged
+into solar years. The years go in cycles of sixty, each year containing
+either twelve months in an ordinary year or thirteen months in a leap
+year; each month has either 29 or 30 days. Years, ordinary months, and
+days are named by combining one of ten ``celestial stems'' with one of
+twelve ``terrestrial branches'' for a total of sixty names that are
+repeated in a cycle of sixty.
+
+@node To Other Calendar
+@subsection Converting To Other Calendars
+
+ The following commands describe the selected date (the date at point)
+in various other calendar systems:
+
+@table @kbd
+@item Mouse-2 Other Calendars
+Display the date that you click on, expressed in various other calendars.
+@kindex p @r{(Calendar mode)}
+@findex calendar-print-iso-date
+@item p c
+Display ISO commercial calendar equivalent for selected day
+(@code{calendar-print-iso-date}).
+@findex calendar-print-julian-date
+@item p j
+Display Julian date for selected day (@code{calendar-print-julian-date}).
+@findex calendar-print-astro-day-number
+@item p a
+Display astronomical (Julian) day number for selected day
+(@code{calendar-print-astro-day-number}).
+@findex calendar-print-hebrew-date
+@item p h
+Display Hebrew date for selected day (@code{calendar-print-hebrew-date}).
+@findex calendar-print-islamic-date
+@item p i
+Display Islamic date for selected day (@code{calendar-print-islamic-date}).
+@findex calendar-print-french-date
+@item p f
+Display French Revolutionary date for selected day
+(@code{calendar-print-french-date}).
+@findex calendar-print-chinese-date
+@item p C
+Display Chinese date for selected day
+(@code{calendar-print-chinese-date}).
+@findex calendar-print-coptic-date
+@item p k
+Display Coptic date for selected day
+(@code{calendar-print-coptic-date}).
+@findex calendar-print-ethiopic-date
+@item p e
+Display Ethiopic date for selected day
+(@code{calendar-print-ethiopic-date}).
+@findex calendar-print-persian-date
+@item p p
+Display Persian date for selected day
+(@code{calendar-print-persian-date}).
+@findex calendar-print-mayan-date
+@item p m
+Display Mayan date for selected day (@code{calendar-print-mayan-date}).
+@end table
+
+ If you are using X, the easiest way to translate a date into other
+calendars is to click on it with @kbd{Mouse-2}, then choose @kbd{Other
+Calendars} from the menu that appears. This displays the equivalent
+forms of the date in all the calendars Emacs understands, in the form of
+a menu. (Choosing an alternative from this menu doesn't actually do
+anything---the menu is used only for display.)
+
+ Put point on the desired date of the Gregorian calendar, then type the
+appropriate keys. The @kbd{p} is a mnemonic for ``print'' since Emacs
+``prints'' the equivalent date in the echo area.
+
+@node From Other Calendar
+@subsection Converting From Other Calendars
+
+ You can use the other supported calendars to specify a date to move
+to. This section describes the commands for doing this using calendars
+other than Mayan; for the Mayan calendar, see the following section.
+
+@kindex g @var{char} @r{(Calendar mode)}
+@findex calendar-goto-iso-date
+@findex calendar-goto-julian-date
+@findex calendar-goto-astro-day-number
+@findex calendar-goto-hebrew-date
+@findex calendar-goto-islamic-date
+@findex calendar-goto-french-date
+@findex calendar-goto-chinese-date
+@findex calendar-goto-persian-date
+@findex calendar-goto-coptic-date
+@findex calendar-goto-ethiopic-date
+@table @kbd
+@item g c
+Move to a date specified in the ISO commercial calendar
+(@code{calendar-goto-iso-date}).
+@item g j
+Move to a date specified in the Julian calendar
+(@code{calendar-goto-julian-date}).
+@item g a
+Move to a date specified in astronomical (Julian) day number
+(@code{calendar-goto-astro-day-number}).
+@item g h
+Move to a date specified in the Hebrew calendar
+(@code{calendar-goto-hebrew-date}).
+@item g i
+Move to a date specified in the Islamic calendar
+(@code{calendar-goto-islamic-date}).
+@item g f
+Move to a date specified in the French Revolutionary calendar
+(@code{calendar-goto-french-date}).
+@item g C
+Move to a date specified in the Chinese calendar
+(@code{calendar-goto-chinese-date}).
+@item g p
+Move to a date specified in the Persian calendar
+(@code{calendar-goto-persian-date}).
+@item g k
+Move to a date specified in the Coptic calendar
+(@code{calendar-goto-coptic-date}).
+@item g e
+Move to a date specified in the Ethiopic calendar
+(@code{calendar-goto-ethiopic-date}).
+@end table
+
+ These commands ask you for a date on the other calendar, move point to
+the Gregorian calendar date equivalent to that date, and display the
+other calendar's date in the echo area. Emacs uses strict completion
+(@pxref{Completion}) whenever it asks you to type a month name, so you
+don't have to worry about the spelling of Hebrew, Islamic, or French names.
+
+@findex list-yahrzeit-dates
+@cindex yahrzeits
+ One common question concerning the Hebrew calendar is the computation
+of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs
+calendar includes a facility for such calculations. If you are in the
+calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a
+range of years and then displays a list of the yahrzeit dates for those
+years for the date given by point. If you are not in the calendar,
+this command first asks you for the date of death and the range of
+years, and then displays the list of yahrzeit dates.
+
+@node Mayan Calendar
+@subsection Converting from the Mayan Calendar
+
+ Here are the commands to select dates based on the Mayan calendar:
+
+@table @kbd
+@item g m l
+Move to a date specified by the long count calendar
+(@code{calendar-goto-mayan-long-count-date}).
+@item g m n t
+Move to the next occurrence of a place in the
+tzolkin calendar (@code{calendar-next-tzolkin-date}).
+@item g m p t
+Move to the previous occurrence of a place in the
+tzolkin calendar (@code{calendar-previous-tzolkin-date}).
+@item g m n h
+Move to the next occurrence of a place in the
+haab calendar (@code{calendar-next-haab-date}).
+@item g m p h
+Move to the previous occurrence of a place in the
+haab calendar (@code{calendar-previous-haab-date}).
+@item g m n c
+Move to the next occurrence of a place in the
+calendar round (@code{calendar-next-calendar-round-date}).
+@item g m p c
+Move to the previous occurrence of a place in the
+calendar round (@code{calendar-previous-calendar-round-date}).
+@end table
+
+@cindex Mayan long count
+ To understand these commands, you need to understand the Mayan calendars.
+The @dfn{long count} is a counting of days with these units:
+
+@display
+1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
+1 katun = 20 tun@ @ @ 1 baktun = 20 katun
+@end display
+
+@kindex g m @r{(Calendar mode)}
+@findex calendar-goto-mayan-long-count-date
+@noindent
+Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
+tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long
+count dates as early as 7.17.18.13.1, but no earlier. When you use the
+@kbd{g m l} command, type the Mayan long count date with the baktun,
+katun, tun, uinal, and kin separated by periods.
+
+@findex calendar-previous-tzolkin-date
+@findex calendar-next-tzolkin-date
+@cindex Mayan tzolkin calendar
+ The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
+independent cycles of 13 and 20 days. Since this cycle repeats
+endlessly, Emacs provides commands to move backward and forward to the
+previous or next point in the cycle. Type @kbd{g m p t} to go to the
+previous tzolkin date; Emacs asks you for a tzolkin date and moves point
+to the previous occurrence of that date. Similarly, type @kbd{g m n t}
+to go to the next occurrence of a tzolkin date.
+
+@findex calendar-previous-haab-date
+@findex calendar-next-haab-date
+@cindex Mayan haab calendar
+ The Mayan haab calendar is a cycle of 365 days arranged as 18 months
+of 20 days each, followed a 5-day monthless period. Like the tzolkin
+cycle, this cycle repeats endlessly, and there are commands to move
+backward and forward to the previous or next point in the cycle. Type
+@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab
+date and moves point to the previous occurrence of that date.
+Similarly, type @kbd{g m n h} to go to the next occurrence of a haab
+date.
+
+@c This is omitted because it is too long for smallbook format.
+@c @findex calendar-previous-calendar-round-date
+@findex calendar-next-calendar-round-date
+@cindex Mayan calendar round
+ The Maya also used the combination of the tzolkin date and the haab
+date. This combination is a cycle of about 52 years called a
+@emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for
+both a haab and a tzolkin date and then moves point to the previous
+occurrence of that combination. Use @kbd{g m n c} to move point to the
+next occurrence of a combination. These commands signal an error if the
+haab/tzolkin date combination you have typed is impossible.
+
+ Emacs uses strict completion (@pxref{Strict Completion}) whenever it
+asks you to type a Mayan name, so you don't have to worry about
+spelling.
+
+@node Diary
+@section The Diary
+@cindex diary
+
+ The Emacs diary keeps track of appointments or other events on a daily
+basis, in conjunction with the calendar. To use the diary feature, you
+must first create a @dfn{diary file} containing a list of events and
+their dates. Then Emacs can automatically pick out and display the
+events for today, for the immediate future, or for any specified
+date.
+
+ By default, Emacs uses @file{~/diary} as the diary file. This is the
+same file that the @code{calendar} utility uses. A sample
+@file{~/diary} file is:
+
+@example
+12/22/1988 Twentieth wedding anniversary!!
+&1/1. Happy New Year!
+10/22 Ruth's birthday.
+* 21, *: Payday
+Tuesday--weekly meeting with grad students at 10am
+ Supowit, Shen, Bitner, and Kapoor to attend.
+1/13/89 Friday the thirteenth!!
+&thu 4pm squash game with Lloyd.
+mar 16 Dad's birthday
+April 15, 1989 Income tax due.
+&* 15 time cards due.
+@end example
+
+@noindent
+This example uses extra spaces to align the event descriptions of most
+of the entries. Such formatting is purely a matter of taste.
+
+ Although you probably will start by creating a diary manually, Emacs
+provides a number of commands to let you view, add, and change diary
+entries.
+
+@menu
+* Diary Commands:: Viewing diary entries and associated calendar dates.
+* Format of Diary File:: Entering events in your diary.
+* Date Formats:: Various ways you can specify dates.
+* Adding to Diary:: Commands to create diary entries.
+* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
+@end menu
+
+@node Diary Commands
+@subsection Commands Displaying Diary Entries
+
+ Once you have created a @file{~/diary} file, you can use the calendar
+to view it. You can also view today's events outside of Calendar mode.
+
+@table @kbd
+@item d
+Display all diary entries for the selected date
+(@code{view-diary-entries}).
+@item Mouse-2 Diary
+Display all diary entries for the date you click on.
+@item s
+Display the entire diary file (@code{show-all-diary-entries}).
+@item m
+Mark all visible dates that have diary entries
+(@code{mark-diary-entries}).
+@item u
+Unmark the calendar window (@code{calendar-unmark}).
+@item M-x print-diary-entries
+Print hard copy of the diary display as it appears.
+@item M-x diary
+Display all diary entries for today's date.
+@item M-x diary-mail-entries
+Mail yourself email reminders about upcoming diary entries.
+@end table
+
+@kindex d @r{(Calendar mode)}
+@findex view-diary-entries
+ Displaying the diary entries with @kbd{d} shows in a separate window
+the diary entries for the selected date in the calendar. The mode line
+of the new window shows the date of the diary entries and any holidays
+that fall on that date. If you specify a numeric argument with @kbd{d},
+it shows all the diary entries for that many successive days. Thus,
+@kbd{2 d} displays all the entries for the selected date and for the
+following day.
+
+ Another way to display the diary entries for a date is to click
+@kbd{Mouse-2} on the date, and then choose @kbd{Diary} from the menu
+that appears.
+
+@kindex m @r{(Calendar mode)}
+@findex mark-diary-entries
+ To get a broader view of which days are mentioned in the diary, use
+the @kbd{m} command. This displays the dates that have diary entries
+in a different face (or places a @samp{+} after these dates, if
+display with multiple faces is not available). The command applies both
+to the currently visible months and to other months that subsequently
+become visible by scrolling. To turn marking off and erase the current
+marks, type @kbd{u}, which also turns off holiday marks
+(@pxref{Holidays}).
+
+@kindex s @r{(Calendar mode)}
+@findex show-all-diary-entries
+ To see the full diary file, rather than just some of the entries, use
+the @kbd{s} command.
+
+ Display of selected diary entries uses the selective display feature
+to hide entries that don't apply.
+
+ The diary buffer as you see it is an illusion, so simply printing the
+buffer does not print what you see on your screen. There is a special
+command to print hard copy of the diary buffer @emph{as it appears};
+this command is @kbd{M-x print-diary-entries}. It sends the data
+directly to the printer. You can customize it like @code{lpr-region}
+(@pxref{Hardcopy}).
+
+@findex diary
+ The command @kbd{M-x diary} displays the diary entries for the current
+date, independently of the calendar display, and optionally for the next
+few days as well; the variable @code{number-of-diary-entries} specifies
+how many days to include. @xref{Calendar, Customizing the Calendar
+and Diary,, elisp, The Emacs Lisp Reference Manual}.
+
+ If you put @code{(diary)} in your @file{.emacs} file, this
+automatically displays a window with the day's diary entries, when you
+enter Emacs. The mode line of the displayed window shows the date and
+any holidays that fall on that date.
+
+@findex diary-mail-entries
+@vindex diary-mail-days
+ Many users like to receive notice of events in their diary as email.
+To send such mail to yourself, use the command @kbd{M-x
+diary-mail-entries}. A prefix argument specifies how many days
+(starting with today) to check; otherwise, the variable
+@code{diary-mail-days} says how many days.
+
+@node Format of Diary File
+@subsection The Diary File
+@cindex diary file
+
+@vindex diary-file
+ Your @dfn{diary file} is a file that records events associated with
+particular dates. The name of the diary file is specified by the
+variable @code{diary-file}; @file{~/diary} is the default. The
+@code{calendar} utility program supports a subset of the format allowed
+by the Emacs diary facilities, so you can use that utility to view the
+diary file, with reasonable results aside from the entries it cannot
+understand.
+
+ Each entry in the diary file describes one event and consists of one
+or more lines. An entry always begins with a date specification at the
+left margin. The rest of the entry is simply text to describe the
+event. If the entry has more than one line, then the lines after the
+first must begin with whitespace to indicate they continue a previous
+entry. Lines that do not begin with valid dates and do not continue a
+preceding entry are ignored.
+
+ You can inhibit the marking of certain diary entries in the calendar
+window; to do this, insert an ampersand (@samp{&}) at the beginning of
+the entry, before the date. This has no effect on display of the entry
+in the diary window; it affects only marks on dates in the calendar
+window. Nonmarking entries are especially useful for generic entries
+that would otherwise mark many different dates.
+
+ If the first line of a diary entry consists only of the date or day
+name with no following blanks or punctuation, then the diary window
+display doesn't include that line; only the continuation lines appear.
+For example, this entry:
+
+@example
+02/11/1989
+ Bill B. visits Princeton today
+ 2pm Cognitive Studies Committee meeting
+ 2:30-5:30 Liz at Lawrenceville
+ 4:00pm Dentist appt
+ 7:30pm Dinner at George's
+ 8:00-10:00pm concert
+@end example
+
+@noindent
+appears in the diary window without the date line at the beginning.
+This style of entry looks neater when you display just a single day's
+entries, but can cause confusion if you ask for more than one day's
+entries.
+
+ You can edit the diary entries as they appear in the window, but it is
+important to remember that the buffer displayed contains the @emph{entire}
+diary file, with portions of it concealed from view. This means, for
+instance, that the @kbd{C-f} (@code{forward-char}) command can put point
+at what appears to be the end of the line, but what is in reality the
+middle of some concealed line.
+
+ @emph{Be careful when editing the diary entries!} Inserting
+additional lines or adding/deleting characters in the middle of a
+visible line cannot cause problems, but editing at the end of a line may
+not do what you expect. Deleting a line may delete other invisible
+entries that follow it. Before editing the diary, it is best to display
+the entire file with @kbd{s} (@code{show-all-diary-entries}).
+
+@node Date Formats
+@subsection Date Formats
+
+ Here are some sample diary entries, illustrating different ways of
+formatting a date. The examples all show dates in American order
+(month, day, year), but Calendar mode supports European order (day,
+month, year) as an option.
+
+@example
+4/20/93 Switch-over to new tabulation system
+apr. 25 Start tabulating annual results
+4/30 Results for April are due
+*/25 Monthly cycle finishes
+Friday Don't leave without backing up files
+@end example
+
+ The first entry appears only once, on April 20, 1993. The second and
+third appear every year on the specified dates, and the fourth uses a
+wildcard (asterisk) for the month, so it appears on the 25th of every
+month. The final entry appears every week on Friday.
+
+ You can use just numbers to express a date, as in
+@samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}.
+This must be followed by a nondigit. In the date itself, @var{month}
+and @var{day} are numbers of one or two digits. The optional @var{year}
+is also a number, and may be abbreviated to the last two digits; that
+is, you can use @samp{11/12/1989} or @samp{11/12/89}.
+
+ Dates can also have the form @samp{@var{monthname} @var{day}} or
+@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
+be spelled in full or abbreviated to three characters (with or without a
+period). Case is not significant.
+
+ A date may be @dfn{generic}; that is, partially unspecified. Then the
+entry applies to all dates that match the specification. If the date
+does not contain a year, it is generic and applies to any year.
+Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
+this matches any month, day, or year, respectively. Thus, a diary entry
+@samp{3/*/*} matches any day in March of any year; so does @samp{march
+*}.
+
+@vindex european-calendar-style
+@findex european-calendar
+@findex american-calendar
+ If you prefer the European style of writing dates---in which the day
+comes before the month---type @kbd{M-x european-calendar} while in the
+calendar, or set the variable @code{european-calendar-style} to @code{t}
+@emph{before} using any calendar or diary command. This mode interprets
+all dates in the diary in the European manner, and also uses European
+style for displaying diary dates. (Note that there is no comma after
+the @var{monthname} in the European style.) To go back to the (default)
+American style of writing dates, type @kbd{M-x american-calendar}.
+
+ You can use the name of a day of the week as a generic date which
+applies to any date falling on that day of the week. You can abbreviate
+the day of the week to three letters (with or without a period) or spell
+it in full; case is not significant.
+
+@node Adding to Diary
+@subsection Commands to Add to the Diary
+
+ While in the calendar, there are several commands to create diary
+entries:
+
+@table @kbd
+@item i d
+Add a diary entry for the selected date (@code{insert-diary-entry}).
+@item i w
+Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}).
+@item i m
+Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}).
+@item i y
+Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}).
+@end table
+
+@kindex i d @r{(Calendar mode)}
+@findex insert-diary-entry
+ You can make a diary entry for a specific date by selecting that date
+in the calendar window and typing the @kbd{i d} command. This command
+displays the end of your diary file in another window and inserts the
+date; you can then type the rest of the diary entry.
+
+@kindex i w @r{(Calendar mode)}
+@findex insert-weekly-diary-entry
+@kindex i m @r{(Calendar mode)}
+@findex insert-monthly-diary-entry
+@kindex i y @r{(Calendar mode)}
+@findex insert-yearly-diary-entry
+ If you want to make a diary entry that applies to a specific day of
+the week, select that day of the week (any occurrence will do) and type
+@kbd{i w}. This inserts the day-of-week as a generic date; you can then
+type the rest of the diary entry. You can make a monthly diary entry in
+the same fashion. Select the day of the month, use the @kbd{i m}
+command, and type rest of the entry. Similarly, you can insert a yearly
+diary entry with the @kbd{i y} command.
+
+ All of the above commands make marking diary entries by default. To
+make a nonmarking diary entry, give a numeric argument to the command.
+For example, @kbd{C-u i w} makes a nonmarking weekly diary entry.
+
+ When you modify the diary file, be sure to save the file before
+exiting Emacs.
+
+@node Special Diary Entries
+@subsection Special Diary Entries
+
+ In addition to entries based on calendar dates, the diary file can
+contain @dfn{sexp entries} for regular events such as anniversaries.
+These entries are based on Lisp expressions (sexps) that Emacs evaluates
+as it scans the diary file. Instead of a date, a sexp entry contains
+@samp{%%} followed by a Lisp expression which must begin and end with
+parentheses. The Lisp expression determines which dates the entry
+applies to.
+
+ Calendar mode provides commands to insert certain commonly used
+sexp entries:
+
+@table @kbd
+@item i a
+Add an anniversary diary entry for the selected date
+(@code{insert-anniversary-diary-entry}).
+@item i b
+Add a block diary entry for the current region
+(@code{insert-block-diary-entry}).
+@item i c
+Add a cyclic diary entry starting at the date
+(@code{insert-cyclic-diary-entry}).
+@end table
+
+@kindex i a @r{(Calendar mode)}
+@findex insert-anniversary-diary-entry
+ If you want to make a diary entry that applies to the anniversary of a
+specific date, move point to that date and use the @kbd{i a} command.
+This displays the end of your diary file in another window and inserts
+the anniversary description; you can then type the rest of the diary
+entry. The entry looks like this:
+
+@findex diary-anniversary
+@example
+%%(diary-anniversary 10 31 1948) Arthur's birthday
+@end example
+
+@noindent
+This entry applies to October 31 in any year after 1948; @samp{10 31
+1948} specifies the date. (If you are using the European calendar
+style, the month and day are interchanged.) The reason this expression
+requires a beginning year is that advanced diary functions can use it to
+calculate the number of elapsed years.
+
+ A @dfn{block} diary entry applies to a specified range of consecutive
+dates. Here is a block diary entry that applies to all dates from June
+24, 1990 through July 10, 1990:
+
+@findex diary-block
+@example
+%%(diary-block 6 24 1990 7 10 1990) Vacation
+@end example
+
+@noindent
+The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
+indicates the stopping date. (Again, if you are using the European calendar
+style, the month and day are interchanged.)
+
+@kindex i b @r{(Calendar mode)}
+@findex insert-block-diary-entry
+ To insert a block entry, place point and the mark on the two
+dates that begin and end the range, and type @kbd{i b}. This command
+displays the end of your diary file in another window and inserts the
+block description; you can then type the diary entry.
+
+@kindex i c @r{(Calendar mode)}
+@findex insert-cyclic-diary-entry
+ @dfn{Cyclic} diary entries repeat after a fixed interval of days. To
+create one, select the starting date and use the @kbd{i c} command. The
+command prompts for the length of interval, then inserts the entry,
+which looks like this:
+
+@findex diary-cyclic
+@example
+%%(diary-cyclic 50 3 1 1990) Renew medication
+@end example
+
+@noindent
+This entry applies to March 1, 1990 and every 50th day following;
+@samp{3 1 1990} specifies the starting date. (If you are using the
+European calendar style, the month and day are interchanged.)
+
+ All three of these commands make marking diary entries. To insert a
+nonmarking entry, give a numeric argument to the command. For example,
+@kbd{C-u i a} makes a nonmarking anniversary diary entry.
+
+ Marking sexp diary entries in the calendar is @emph{extremely}
+time-consuming, since every date visible in the calendar window must be
+individually checked. So it's a good idea to make sexp diary entries
+nonmarking (with @samp{&}) when possible.
+
+ Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
+specifies a regularly occurring event by offsets specified in days,
+weeks, and months. It is comparable to a crontab entry interpreted by
+the @code{cron} utility. Here is a nonmarking, floating diary entry
+that applies to the last Thursday in November:
+
+@findex diary-float
+@example
+&%%(diary-float 11 4 -1) American Thanksgiving
+@end example
+
+@noindent
+The 11 specifies November (the eleventh month), the 4 specifies Thursday
+(the fourth day of the week, where Sunday is numbered zero), and the
+@minus{}1 specifies ``last'' (1 would mean ``first,'' 2 would mean
+``second,'' @minus{}2 would mean ``second-to-last,'' and so on). The
+month can be a single month or a list of months. Thus you could change
+the 11 above to @samp{'(1 2 3)} and have the entry apply to the last
+Thursday of January, February, and March. If the month is @code{t}, the
+entry applies to all months of the year.@refill
+
+ Most generally, sexp diary entries can perform arbitrary
+computations to determine when they apply. @xref{Sexp Diary Entries,,
+Sexp Diary Entries, elisp, The Emacs Lisp Reference Manual}.
+
+@node Appointments
+@section Appointments
+@cindex appointment notification
+
+ If you have a diary entry for an appointment, and that diary entry
+begins with a recognizable time of day, Emacs can warn you, several
+minutes beforehand, that that appointment is pending. Emacs alerts you
+to the appointment by displaying a message in the mode line.
+
+@vindex diary-hook
+@findex appt-make-list
+ To enable appointment notification, you must enable the time display
+feature of Emacs, @kbd{M-x display-time} (@pxref{Mode Line}). You must
+also add the function @code{appt-make-list} to the
+@code{diary-hook}, like this:
+
+@example
+(add-hook 'diary-hook 'appt-make-list)
+@end example
+
+@noindent
+Adding this text to your @file{.emacs} file does the whole job:
+
+@example
+(display-time)
+(add-hook 'diary-hook 'appt-make-list)
+(diary 0)
+@end example
+
+ With these preparations done, when you display the diary (either with
+the @kbd{d} command in the calendar window or with the @kbd{M-x diary}
+command), it sets up an appointment list of all the diary entries found
+with recognizable times of day, and reminds you just before each of
+them.
+
+ For example, suppose the diary file contains these lines:
+
+@example
+Monday
+ 9:30am Coffee break
+ 12:00pm Lunch
+@end example
+
+@noindent
+Then on Mondays, after you have displayed the diary, you will be
+reminded at 9:20am about your coffee break and at 11:50am about lunch.
+
+ You can write times in am/pm style (with @samp{12:00am} standing
+for midnight and @samp{12:00pm} standing for noon), or 24-hour
+European/military style. You need not be consistent; your diary file
+can have a mixture of the two styles.
+
+@vindex appt-display-diary
+ Emacs updates the appointments list automatically just after
+midnight. This also displays the next day's diary entries in the diary
+buffer, unless you set @code{appt-display-diary} to @code{nil}.
+
+@findex appt-add
+@findex appt-delete
+@cindex alarm clock
+ You can also use the appointment notification facility like an alarm
+clock. The command @kbd{M-x appt-add} adds entries to the appointment
+list without affecting your diary file. You delete entries from the
+appointment list with @kbd{M-x appt-delete}.
+
+@vindex appt-issue-message
+ You can turn off the appointment notification feature at any time by
+setting @code{appt-issue-message} to @code{nil}.
+
+@node Daylight Savings
+@section Daylight Savings Time
+@cindex daylight savings time
+
+ Emacs understands the difference between standard time and daylight
+savings time---the times given for sunrise, sunset, solstices,
+equinoxes, and the phases of the moon take that into account. The rules
+for daylight savings time vary from place to place and have also varied
+historically from year to year. To do the job properly, Emacs needs to
+know which rules to use.
+
+@vindex calendar-daylight-savings-starts
+@vindex calendar-daylight-savings-ends
+ Some operating systems keep track of the rules that apply to the place
+where you are; on these systems, Emacs gets the information it needs
+from the system automatically. If some or all of this information is
+missing, Emacs fills in the gaps with the rules currently used in
+Cambridge, Massachusetts. If the resulting rules are not what you want,
+you can tell Emacs the rules to use by setting certain variables:
+@code{calendar-daylight-savings-starts} and
+@code{calendar-daylight-savings-ends}.
+
+ These values should be Lisp expressions that refer to the variable
+@code{year}, and evaluate to the Gregorian date on which daylight
+savings time starts or (respectively) ends, in the form of a list
+@code{(@var{month} @var{day} @var{year})}. The values should be
+@code{nil} if your area does not use daylight savings time.
+
+ Emacs uses these expressions to determine the starting date of
+daylight savings time for the holiday list and for correcting times of
+day in the solar and lunar calculations.
+
+ The values for Cambridge, Massachusetts are as follows:
+
+@example
+(calendar-nth-named-day 1 0 4 year)
+(calendar-nth-named-day -1 0 10 year)
+@end example
+
+@noindent
+That is, the first 0th day (Sunday) of the fourth month (April) in
+the year specified by @code{year}, and the last Sunday of the tenth month
+(October) of that year. If daylight savings time were
+changed to start on October 1, you would set
+@code{calendar-daylight-savings-starts} to this:
+
+@example
+(list 10 1 year)
+@end example
+
+ If there is no daylight savings time at your location, or if you want
+all times in standard time, set @code{calendar-daylight-savings-starts}
+and @code{calendar-daylight-savings-ends} to @code{nil}.
+
+@vindex calendar-daylight-time-offset
+ The variable @code{calendar-daylight-time-offset} specifies the
+difference between daylight savings time and standard time, measured in
+minutes. The value for Cambridge, Massachusetts is 60.
+
+@c @vindex calendar-daylight-savings-starts-time too long!
+@vindex calendar-daylight-savings-ends-time
+ The two variables @code{calendar-daylight-savings-starts-time} and
+@code{calendar-daylight-savings-ends-time} specify the number of minutes
+after midnight local time when the transition to and from daylight
+savings time should occur. For Cambridge, Massachusetts both variables'
+values are 120.
--- /dev/null
+\input texinfo
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment %**start of header (This is for running Texinfo on a region)
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@setfilename ../info/ccmode
+@settitle CC MODE Version 5 Documentation
+@footnotestyle end
+
+@dircategory Editors
+@direntry
+* CC mode: (ccmode). The GNU Emacs mode for editing C, C++, Objective-C
+ and Java code.
+@end direntry
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment @setchapternewpage odd !! we don't want blank pages !!
+@comment %**end of header (This is for running Texinfo on a region)
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment
+@comment Texinfo manual for CC Mode
+@comment Generated from the original README file by Krishna Padmasola
+@comment <krishna@earth-gw.njit.edu>
+@comment
+@comment Maintained by Barry A. Warsaw <cc-mode-help@python.org>
+@comment
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment The following line inserts the copyright notice
+@comment into the Info file.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ifinfo
+Copyright @copyright{} 1995,96,97,98 Free Software Foundation, Inc.
+@end ifinfo
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment !!!The titlepage section does not appear in the Info file.!!!
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@titlepage
+@sp 10
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment The title is printed in a large font.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@center @titlefont{CC Mode 5.21}
+@sp 2
+@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
+@sp 2
+@center Barry A. Warsaw
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment The following two commands start the copyright page
+@comment for the printed manual. This will not appear in the Info file.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1995,96,97,98 Free Software Foundation, Inc.
+@end titlepage
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment The Top node contains the master menu for the Info file.
+@comment This appears only in the Info file, not the printed manual.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@node Top, Introduction, (dir), (dir)
+@comment node-name, next, previous, up
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@menu
+* Introduction::
+* Getting Connected::
+* New Indentation Engine::
+* Minor Modes::
+* Commands::
+* Customizing Indentation::
+* Syntactic Symbols::
+* Performance Issues::
+* Frequently Asked Questions::
+* Getting the latest CC Mode release::
+* Sample .emacs File::
+* Limitations and Known Bugs::
+* Mailing Lists and Submitting Bug Reports::
+* Concept Index::
+* Command Index:: Command Index
+* Key Index:: Key Index
+* Variable Index:: Variable Index
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@node Introduction, Getting Connected, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+@cindex Introduction
+
+@macro ccmode
+CC Mode
+@end macro
+
+@cindex BOCM
+
+Welcome to @ccmode{}. This is a GNU Emacs mode for editing files
+containing C, C++, Objective-C, Java, and CORBA IDL code. This
+incarnation of the mode is descendant from @file{c-mode.el} (also called
+"Boring Old C Mode" or BOCM @code{:-)}, and @file{c++-mode.el} version
+2, which I have been maintaining since 1992. @ccmode{} represents a
+significant milestone in the mode's life. It has been fully merged back
+with Emacs 19's @file{c-mode.el}. Also a new, more intuitive and
+flexible mechanism for controlling indentation has been developed.
+
+@ccmode{} supports the editing of K&R and ANSI C, @dfn{ARM}
+@footnote{``The Annotated C++ Reference Manual'', by Ellis and
+Stroustrup.} C++, Objective-C, Java and CORBA's Interface
+Definition Language files. In this way, you can
+easily set up consistent coding styles for use in editing all C, C++,
+Objective-C, Java and IDL programs. @ccmode{} does @emph{not} handle
+font-locking (a.k.a. syntax coloring, keyword highlighting) or anything
+of that nature, for any of these modes. Font-locking is handled by other
+Emacs packages.
+
+This manual will describe the following:
+
+@itemize @bullet
+@item
+How to get started using @ccmode{}.
+
+@item
+How the new indentation engine works.
+
+@item
+How to customize the new indentation engine.
+
+@end itemize
+
+@findex c-mode
+@findex c++-mode
+@findex objc-mode
+@findex java-mode
+@findex idl-mode
+Note that the name of this package is ``@ccmode{}'', but there is no top
+level @code{cc-mode} entry point. All of the variables, commands, and
+functions in @ccmode{} are prefixed with @code{c-@var{<thing>}}, and
+@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, and
+@code{idl-mode} entry points are provided. This file is intended to be
+a replacement for @file{c-mode.el} and @file{c++-mode.el}.
+
+@cindex @file{cc-compat.el} file
+This distribution also contains a file
+called @file{cc-compat.el} which should ease your transition from BOCM
+to @ccmode{}. If you have a BOCM configuration you are really happy
+with, and want to postpone learning how to configure @ccmode{}, take a
+look at that file. It maps BOCM configuration variables to @ccmode{}'s
+new indentation model. It is not actively supported so for the long
+run, you should learn how to customize @ccmode{} to support your coding
+style.
+
+A special word of thanks goes to Krishna Padmasola for his work in
+converting the original @file{README} file to Texinfo format. I'd also
+like to thank all the @ccmode{} victims who help enormously during the
+early beta stages of @ccmode{}'s development.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@node Getting Connected, New Indentation Engine, Introduction, Top
+@comment node-name, next, previous, up
+@chapter Getting Connected
+@cindex Getting Connected
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+If you got this version of @ccmode{} with Emacs or XEmacs, it should
+work just fine right out of the box. Note however that you may not have
+the latest @ccmode{} release and may want to upgrade your copy.
+
+If you are upgrading an existing @ccmode{} installation, please see the
+@file{README} file for installation details. @ccmode{} may not work
+with older versions of Emacs or XEmacs. See the @ccmode{} release notes
+Web pages for the latest information on Emacs version and package
+compatibility (see @ref{Getting the latest CC Mode release}).
+
+@cindex @file{cc-mode-18.el} file
+@emph{Note that @ccmode{} no longer works with Emacs 18!} The
+@file{cc-mode-18.el} file is no longer distributed with @ccmode{}. If
+you haven't upgraded from Emacs 18 by now, you are out of luck.
+
+@findex c-version
+@findex version (c-)
+You can find out what version of @ccmode{} you are using by visiting a C
+file and entering @kbd{M-x c-version RET}. You should see this message in
+the echo area:
+@example
+
+Using CC Mode version 5.XX
+
+@end example
+
+@noindent
+where @samp{XX} is the minor release number.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node New Indentation Engine, Minor Modes, Getting Connected, Top
+@comment node-name, next, previous, up
+
+@chapter New Indentation Engine
+@cindex New Indentation Engine
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ccmode{} has a new indentation engine, providing a simplified, yet
+flexible and general mechanism for customizing indentation. It separates
+indentation calculation into two steps: first, @ccmode{} analyzes the
+line of code being indented to determine the kind of language construct
+it's looking at, then it applies user defined offsets to the current
+line based on this analysis.
+
+This section will briefly cover how indentation is calculated in
+@ccmode{}. It is important to understand the indentation model
+being used so that you will know how to customize @ccmode{} for
+your personal coding style.
+
+@menu
+* Syntactic Analysis::
+* Indentation Calculation::
+@end menu
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Syntactic Analysis, Indentation Calculation, , New Indentation Engine
+@comment node-name, next, previous,up
+@section Syntactic Analysis
+@cindex Syntactic Analysis
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+@cindex relative buffer position
+@cindex syntactic symbol
+@cindex syntactic component
+@cindex syntactic component list
+@cindex relative buffer position
+The first thing @ccmode{} does when indenting a line of code, is to
+analyze the line, determining the @dfn{syntactic component list} of the
+construct on that line. A syntactic component consists of a pair
+of information (in lisp parlance, a @emph{cons cell}), where the first
+part is a @dfn{syntactic symbol}, and the second part is a @dfn{relative
+buffer position}. Syntactic symbols describe elements of C code
+@footnote{or C++, Objective-C, Java or IDL code. In general, for the rest
+of this manual I'll use the term ``C code'' to refer to all the C-like
+dialects, unless otherwise noted.}, e.g. @code{statement},
+@code{substatement}, @code{class-open}, @code{class-close}, etc.
+@xref{Syntactic Symbols}, for a complete list of currently recognized
+syntactic symbols and their semantics. The variable
+@code{c-offsets-alist} also contains the list of currently supported
+syntactic symbols.
+
+Conceptually, a line of C code is always indented relative to the
+indentation of some line higher up in the buffer. This is represented
+by the relative buffer position in the syntactic component.
+
+Here is an example. Suppose we had the following code as the only thing
+in a @code{c++-mode} buffer @footnote{The line numbers in this and
+future examples don't actually appear in the buffer, of course!}:
+@example
+@group
+
+ 1: void swap( int& a, int& b )
+ 2: @{
+ 3: int tmp = a;
+ 4: a = b;
+ 5: b = tmp;
+ 6: @}
+
+@end group
+@end example
+
+@kindex C-c C-s
+@findex c-show-syntactic-information
+@findex show-syntactic-information (c-)
+We can use the command @kbd{C-c C-s}
+(@code{c-show-syntactic-information}) to simply report what the
+syntactic analysis is for the current line. Running this command on
+line 4 of this example, we'd see in the echo area@footnote{With a universal
+argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted into the
+buffer as a comment
+on the current line.}:
+@example
+
+((statement . 35))
+
+@end example
+
+This tells us that the line is a statement and it is indented relative
+to buffer position 35, which happens to be the @samp{i} in @code{int} on
+line 3. If you were to move point to line 3 and hit @kbd{C-c C-s}, you
+would see:
+@example
+
+((defun-block-intro . 29))
+
+@end example
+
+This indicates that the @samp{int} line is the first statement in a top
+level function block, and is indented relative to buffer position 29,
+which is the brace just after the function header.
+
+Here's another example:
+@example
+@group
+
+ 1: int add( int val, int incr, int doit )
+ 2: @{
+ 3: if( doit )
+ 4: @{
+ 5: return( val + incr );
+ 6: @}
+ 7: return( val );
+ 8: @}
+
+@end group
+@end example
+
+@noindent
+Hitting @kbd{C-c C-s} on line 4 gives us:
+@example
+
+((substatement-open . 46))
+
+@end example
+
+@cindex substatement
+@cindex substatment block
+@noindent
+which tells us that this is a brace that @emph{opens} a substatement
+block. @footnote{A @dfn{substatement} is the line after a
+conditional statement, such as @code{if}, @code{else}, @code{while},
+@code{do}, @code{switch}, etc. A @dfn{substatement
+block} is a brace block following one of these conditional statements.}
+
+@cindex comment-only line
+Syntactic component lists can contain more than one component, and
+individual syntactic components need not have relative buffer positions.
+The most common example of this is a line that contains a @dfn{comment
+only line}.
+@example
+@group
+
+ 1: void draw_list( List<Drawables>& drawables )
+ 2: @{
+ 3: // call the virtual draw() method on each element in list
+ 4: for( int i=0; i < drawables.count(), ++i )
+ 5: @{
+ 6: drawables[i].draw();
+ 7: @}
+ 8: @}
+
+@end group
+@end example
+
+@noindent
+Hitting @kbd{C-c C-s} on line 3 of this example gives:
+@example
+
+((comment-intro) (defun-block-intro . 46))
+
+@end example
+
+@noindent
+and you can see that the syntactic component list contains two syntactic
+components. Also notice that the first component,
+@samp{(comment-intro)} has no relative buffer position.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Indentation Calculation, , Syntactic Analysis, New Indentation Engine
+@comment node-name, next, previous,up
+@section Indentation Calculation
+@cindex Indentation Calculation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+Indentation for a line is calculated using the syntactic
+component list derived in step 1 above (see @ref{Syntactic Analysis}).
+Each component contributes to the final total indentation of the line in
+two ways.
+
+First, the syntactic symbols are looked up in the @code{c-offsets-alist}
+variable, which is an association list of syntactic symbols and the
+offsets to apply for those symbols. These offsets are added to a
+running total.
+
+Second, if the component has a relative buffer position, @ccmode{}
+adds the column number of that position to the running total. By adding
+up the offsets and columns for every syntactic component on the list,
+the final total indentation for the current line is computed.
+
+Let's use our two code examples above to see how this works. Here is
+our first example again:
+@example
+@group
+
+ 1: void swap( int& a, int& b )
+ 2: @{
+ 3: int tmp = a;
+ 4: a = b;
+ 5: b = tmp;
+ 6: @}
+
+@end group
+@end example
+
+@kindex TAB
+Let's say point is on line 3 and we hit the @kbd{TAB} key to re-indent
+the line. Remember that the syntactic component list for that
+line is:
+@example
+
+((defun-block-intro . 29))
+
+@end example
+
+@noindent
+@ccmode{} looks up @code{defun-block-intro} in the
+@code{c-offsets-alist} variable. Let's say it finds the value @samp{4};
+it adds this to the running total (initialized to zero), yielding a
+running total indentation of 4 spaces.
+
+Next @ccmode{} goes to buffer position 29 and asks for the current
+column. This brace is in column zero, so @ccmode{}
+adds @samp{0} to the running total. Since there is only one syntactic
+component on the list for this line, indentation calculation is
+complete, and the total indentation for the line
+is 4 spaces.
+
+Here's another example:
+@example
+@group
+
+ 1: int add( int val, int incr, int doit )
+ 2: @{
+ 3: if( doit )
+ 4: @{
+ 5: return( val + incr );
+ 6: @}
+ 7: return( val );
+ 8: @}
+
+@end group
+@end example
+
+If we were to hit @kbd{TAB} on line 4 in the above example, the same
+basic process is performed, despite the differences in the syntactic
+component list. Remember that the list for this line is:
+@example
+
+((substatement-open . 46))
+
+@end example
+
+Here, @ccmode{} first looks up the @code{substatement-open} symbol
+in @code{c-offsets-alist}. Let's say it finds the value @samp{4}. This
+yields a running total of 4. @ccmode{} then goes to
+buffer position 46, which is the @samp{i} in @code{if} on line 3. This
+character is in the fourth column on that line so adding this to the
+running total yields an indentation for the line of 8 spaces.
+
+Simple, huh?
+
+Actually, the mode usually just does The Right Thing without you having
+to think about it in this much detail. But when customizing
+indentation, it's helpful to understand the general indentation model
+being used.
+
+@vindex c-echo-syntactic-information-p
+@vindex echo-syntactic-information-p (c-)
+@cindex TAB
+As you configure @ccmode{}, you might want to set the variable
+@code{c-echo-syntactic-information-p} to non-@code{nil} so that the
+syntactic component list and calculated offset will always be echoed in
+the minibuffer when you hit @kbd{TAB}.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Minor Modes, Commands, New Indentation Engine, Top
+@comment node-name, next, previous,up
+
+@chapter Minor Modes
+@cindex Minor Modes
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ccmode{} contains two minor-mode-like features that you should
+find useful while you enter new C code. The first is called
+@dfn{auto-newline} mode, and the second is called @dfn{hungry-delete}
+mode. These minor modes can be toggled on and off independently, and
+@ccmode{} can be configured so that it starts up with any
+combination of these minor modes. By default, both of these minor modes
+are turned off.
+
+The state of the minor modes is always reflected in the minor mode list
+on the modeline of the @ccmode{} buffer. When auto-newline mode is
+enabled, you will see @samp{C/a} on the mode line @footnote{Remember
+that the @samp{C} could be replaced with @samp{C++}, @samp{ObjC},
+@samp{Java} or @samp{IDL}.}. When hungry delete mode is enabled you
+would see @samp{C/h} and when both modes are enabled, you'd see
+@samp{C/ah}.
+
+@kindex C-c C-a
+@kindex C-c C-d
+@kindex C-c C-t
+@findex c-toggle-hungry-state
+@findex c-toggle-auto-state
+@findex c-toggle-auto-hungry-state
+@findex toggle-hungry-state (c-)
+@findex toggle-auto-state (c-)
+@findex toggle-auto-hungry-state (c-)
+@ccmode{} provides keybindings which allow you to toggle the minor
+modes on the fly while editing code. To toggle just the auto-newline
+state, hit @kbd{C-c C-a} (@code{c-toggle-auto-state}). When you do
+this, you should see the @samp{a} indicator either appear or disappear
+on the modeline. Similarly, to toggle just the hungry-delete state, use
+@kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states,
+use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}).
+
+To set up the auto-newline and hungry-delete states to your preferred
+values, you would need to add some lisp to your @file{.emacs} file that
+called one of the @code{c-toggle-*-state} functions directly. When
+called programmatically, each function takes a numeric value, where
+a positive number enables the minor mode, a negative number disables the
+mode, and zero toggles the current state of the mode.
+
+So for example, if you wanted to enable both auto-newline and
+hungry-delete for all your C file editing, you could add the following
+to your @file{.emacs} file:
+@example
+
+(add-hook 'c-mode-common-hook
+ '(lambda () (c-toggle-auto-hungry-state 1)))
+
+@end example
+
+
+@cindex electric characters
+
+@menu
+* Auto-newline insertion::
+* Hungry-deletion of whitespace::
+* Auto-fill mode interaction::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Auto-newline insertion, Hungry-deletion of whitespace, , Minor Modes
+@comment node-name, next, previous,up
+
+@section Auto-newline insertion
+@cindex Auto-newline insertion
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex electric commands
+Auto-newline minor mode works by enabling certain @dfn{electric
+commands}. Electric commands are typically bound to special characters
+such as the left and right braces, colons, semi-colons, etc., which when
+typed, perform some magic formatting in addition to inserting the typed
+character. As a general rule, electric commands are only electric when
+the following conditions apply:
+
+@itemize @bullet
+@item
+Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or
+@samp{C/ah} indicator on the modeline.
+
+@cindex literal
+@cindex syntactic whitespace
+@item
+The character was not typed inside of a literal @footnote{A
+@dfn{literal} is defined as any comment, string, or C preprocessor macro
+definition. These constructs are also known as @dfn{syntactic
+whitespace} since they are usually ignored when scanning C code.}.
+
+@item
+@kindex C-u
+No numeric argument was supplied to the command (i.e. it was typed as
+normal, with no @kbd{C-u} prefix).
+
+@end itemize
+
+@menu
+* Hanging Braces::
+* Hanging Colons::
+* Hanging Semi-colons and commas::
+* Other electric commands::
+* Clean-ups::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Hanging Braces, Hanging Colons, , Auto-newline insertion
+@comment node-name, next, previous,up
+
+@subsection Hanging Braces
+@cindex Hanging Braces
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@findex c-electric-brace
+@findex electric-brace (c-)
+@vindex c-hanging-braces-alist
+@vindex hanging-braces-alist (c-)
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}),
+the electric command @code{c-electric-brace} gets run. This command has
+two electric formatting behaviors. First, it will perform some
+re-indentation of the line the brace was typed on, and second, it will
+add various newlines before and/or after the typed brace.
+Re-indentation occurs automatically whenever the electric behavior is
+enabled. If the brace ends up on a line other than the one it was typed
+on, then that line is also re-indented.
+
+@cindex class-open syntactic symbol
+@cindex class-close syntactic symbol
+@cindex defun-open syntactic symbol
+@cindex defun-close syntactic symbol
+@cindex inline-open syntactic symbol
+@cindex inline-close syntactic symbol
+@cindex brace-list-open syntactic symbol
+@cindex brace-list-close syntactic symbol
+@cindex brace-list-intro syntactic symbol
+@cindex brace-list-entry syntactic symbol
+@cindex block-open syntactic symbol
+@cindex block-close syntactic symbol
+@cindex substatement-open syntactic symbol
+@cindex statement-case-open syntactic symbol
+@cindex extern-lang-open syntactic symbol
+@cindex extern-lang-close syntactic symbol
+@cindex namespace-open symbol
+@cindex namespace-close symbol
+
+The insertion of newlines is controlled by the
+@code{c-hanging-braces-alist} variable. This variable contains a
+mapping between syntactic symbols related to braces, and a list of
+places to insert a newline. The syntactic symbols that are useful for
+this list are: @code{class-open}, @code{class-close}, @code{defun-open},
+@code{defun-close}, @code{inline-open}, @code{inline-close},
+@code{brace-list-open}, @code{brace-list-close},
+@code{brace-list-intro}, @code{brace-list-entry}, @code{block-open},
+@code{block-close}, @code{substatement-open},
+@code{statement-case-open},
+@code{extern-lang-open}, @code{extern-lang-close},
+@code{namespace-open}, and @code{namespace-close}.
+@xref{Syntactic Symbols} for a more
+detailed description of these syntactic symbols.
+
+@cindex Custom Indentation Functions
+The value associated with each syntactic symbol in this association list
+is called an @var{ACTION} which can be either a function or a list.
+@xref{Custom Brace and Colon Hanging} for a more detailed discussion of
+using a function as a brace hanging @var{ACTION}.
+
+When the @var{ACTION} is a list, it can contain any combination of the
+symbols @code{before} and @code{after}, directing @ccmode{} where to
+put newlines in relationship to the brace being inserted. Thus, if the
+list contains only the symbol @code{after}, then the brace is said to
+@dfn{hang} on the right side of the line, as in:
+@example
+@group
+
+// here, open braces always `hang'
+void spam( int i ) @{
+ if( i == 7 ) @{
+ dosomething(i);
+ @}
+@}
+
+
+@end group
+@end example
+
+When the list contains both @code{after} and @code{before}, the braces
+will appear on a line by themselves, as shown by the close braces in the
+above example. The list can also be empty, in which case no newlines
+are added either before or after the brace.
+
+For example, the default value of @code{c-hanging-braces-alist} is:
+@example
+@group
+
+(defvar c-hanging-braces-alist '((brace-list-open)
+ (substatement-open after)
+ (block-close . c-snug-do-while)
+ (extern-lang-open after)))
+
+@end group
+@end example
+
+@noindent
+which says that @code{brace-list-open} braces should both hang on the
+right side, and allow subsequent text to follow on the same line as the
+brace. Also, @code{substatement-open} and @code{extern-lang-open}
+braces should hang on the right side, but subsequent text should follow
+on the next line. Here, in the @code{block-close} entry, you also see
+an example of using a function as an @var{ACTION}.
+
+A word of caution: it is not a good idea to hang top-level construct
+introducing braces, such as @code{class-open} or @code{defun-open}.
+Emacs makes an assumption that such braces will always appear in column
+zero, hanging such braces can introduce performance problems.
+@xref{Performance Issues} for more information.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Hanging Colons, Hanging Semi-colons and commas, Hanging Braces, Auto-newline insertion
+@comment node-name, next, previous,up
+
+@subsection Hanging Colons
+@cindex Hanging Colons
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex hanging-colons-alist (c-)
+@vindex c-hanging-colons-alist
+Using a mechanism similar to brace hanging (see @ref{Hanging Braces}),
+colons can also be made to hang using the variable
+@code{c-hanging-colons-alist}. The syntactic symbols appropriate for
+this assocation list are: @code{case-label}, @code{label},
+@code{access-label}, @code{member-init-intro}, and @code{inher-intro}.
+Note however that for @code{c-hanging-colons-alist}, @var{ACTION}s as
+functions are not supported. See also @ref{Custom Brace and Colon
+Hanging} for details.
+
+@cindex Clean-ups
+In C++, double-colons are used as a scope operator but because these
+colons always appear right next to each other, newlines before and after
+them are controlled by a different mechanism, called @dfn{clean-ups} in
+@ccmode{}. @xref{Clean-ups} for details.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Hanging Semi-colons and commas, Other electric commands, Hanging Colons, Auto-newline insertion
+@comment node-name, next, previous,up
+
+@subsection Hanging Semi-colons and commas
+@cindex Hanging Semi-colons and commas
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Semicolons and commas are also electric in @ccmode{}, but since
+these characters do not correspond directly to syntactic symbols, a
+different mechanism is used to determine whether newlines should be
+automatically inserted after these characters. @xref{Customizing
+Semi-colons and Commas} for details.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Other electric commands, Clean-ups, Hanging Semi-colons and commas, Auto-newline insertion
+@comment node-name, next, previous,up
+
+@subsection Other electric commands
+@cindex Other electric commands
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@kindex #
+@findex c-electric-pound
+@vindex c-electric-pound-behavior
+@findex electric-pound (c-)
+@vindex electric-pound-behavior (c-)
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+A few other keys also provide electric behavior. For example
+@kbd{#} (@code{c-electric-pound}) is electric when typed as
+the first non-whitespace character on a line. In this case, the
+variable @code{c-electric-pound-behavior} is consulted for the electric
+behavior. This variable takes a list value, although the only element
+currently defined is @code{alignleft}, which tells this command to force
+the @samp{#} character into column zero. This is useful for entering
+C preprocessor macro definitions.
+
+@findex c-electric-star
+@findex c-electric-slash
+@findex electric-star (c-)
+@findex electric-slash (c-)
+@cindex comment-only line
+Stars and slashes (i.e. @kbd{*} and @kbd{/}, @code{c-electric-star} and
+@code{c-electric-slash} respectively) are also electric under
+certain circumstances. If a star is inserted as the second character of
+a C style block comment on a @dfn{comment-only} line, then the comment
+delimiter is indented as defined by @code{c-offsets-alist}. A
+comment-only line is defined as a line which contains only a comment, as
+in:
+@example
+@group
+
+void spam( int i )
+@{
+ // this is a comment-only line...
+ if( i == 7 ) // but this is not
+ @{
+ dosomething(i);
+ @}
+@}
+
+@end group
+@end example
+
+Likewise, if a slash is inserted as the second slash in a C++ style line
+comment (also only on a comment-only line), then the line is indented as
+defined by @code{c-offsets-alist}.
+
+@findex c-electric-lt-gt
+@findex electric-lt-gt (c-)
+@kindex <
+@kindex >
+Less-than and greater-than signs (@code{c-electric-lt-gt}) are also
+electric, but only in C++ mode. Hitting the second of two @kbd{<} or
+@kbd{>} keys re-indents the line if it is a C++ style stream operator.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Clean-ups, , Other electric commands, Auto-newline insertion
+@comment node-name, next, previous,up
+
+@subsection Clean-ups
+@cindex Clean-ups
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@dfn{Clean-ups} are a mechanism complementary to colon and brace
+hanging. On the surface, it would seem that clean-ups overlap the
+functionality provided by the @code{c-hanging-*-alist} variables, and
+similarly, clean-ups are only enabled when auto-newline minor mode is
+enabled. Clean-ups are used however to adjust code ``after-the-fact'',
+i.e. to eliminate some whitespace that is inserted by electric
+commands, or whitespace that contains intervening constructs.
+
+@cindex literal
+You can configure @ccmode{}'s clean-ups by setting the variable
+@code{c-cleanup-list}, which is a list of clean-up symbols. By default,
+@ccmode{} cleans up only the @code{scope-operator} construct, which
+is necessary for proper C++ support. Note that clean-ups are only
+performed when the construct does not occur within a literal (see
+@ref{Auto-newline insertion}), and when there is nothing but whitespace
+appearing between the individual components of the construct.
+
+@vindex c-cleanup-list
+@vindex cleanup-list (c-)
+There are currently only five specific constructs that @ccmode{}
+can clean up, as indicated by these symbols:
+
+@itemize @bullet
+@item
+@code{brace-else-brace} --- cleans up @samp{@} else @{} constructs by
+placing the entire construct on a single line. Clean-up occurs when the
+open brace after the @samp{else} is typed. So for example, this:
+@example
+@group
+
+void spam(int i)
+@{
+ if( i==7 )
+ @{
+ dosomething();
+ @}
+ else
+ @{
+
+@end group
+@end example
+@noindent
+appears like this after the open brace is typed:
+@example
+@group
+
+void spam(int i)
+@{
+ if( i==7 ) @{
+ dosomething();
+ @} else @{
+
+@end group
+@end example
+
+@item
+@code{brace-elseif-brace} --- similar to the @code{brace-else-brace}
+clean-up, but this cleans up @samp{@} else if (...) @{} constructs. For
+example:
+@example
+@group
+
+void spam(int i)
+@{
+ if( i==7 )
+ @{
+ dosomething();
+ @}
+ else if( i==3 ) @{
+
+@end group
+@end example
+@noindent
+appears like this after the open brace is typed:
+@example
+@group
+
+void spam(int i)
+@{
+ if( i==7 ) @{
+ dosomething();
+ @} else if( i==3 ) @{
+
+@end group
+@end example
+
+@item
+@code{empty-defun-braces} --- cleans up braces following a top-level
+function or class definition that contains no body. Clean up occurs
+when the closing brace is typed. Thus the following:
+@example
+@group
+
+class Spam
+@{
+@}
+
+@end group
+@end example
+@noindent
+is transformed into this when the close brace is typed:
+@example
+@group
+
+class Spam
+@{@}
+
+@end group
+@end example
+
+@item
+@code{defun-close-semi} --- cleans up the terminating semi-colon on
+top-level function or class definitions when they follow a close
+brace. Clean up occurs when the semi-colon is typed.
+So for example, the following:
+@example
+@group
+
+class Spam
+@{
+@}
+;
+
+@end group
+@end example
+@noindent
+is transformed into this when the semi-colon is typed:
+
+@example
+@group
+
+class Spam
+@{
+@};
+
+@end group
+@end example
+
+@item
+@code{list-close-comma} --- cleans up commas following braces in array
+and aggregate initializers. Clean up occurs when the comma is typed.
+
+@item
+@code{scope-operator} --- cleans up double colons which may designate a
+C++ scope operator split across multiple lines@footnote{Certain C++
+constructs introduce ambiguous situations, so @code{scope-operator}
+clean-ups may not always be correct. This usually only occurs when
+scoped identifiers appear in switch label tags.}. Clean up occurs when
+the second colon is typed. You will always want @code{scope-operator}
+in the @code{c-cleanup-list} when you are editing C++ code.
+
+@end itemize
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Hungry-deletion of whitespace, Auto-fill mode interaction, Auto-newline insertion, Minor Modes
+@comment node-name, next, previous,up
+
+@section Hungry-deletion of whitespace
+@cindex Hungry-deletion of whitespace
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Hungry deletion of whitespace, or as it more commonly called,
+@dfn{hungry-delete mode}, is a simple feature that some people find
+extremely useful. In fact, you might find yourself wanting
+hungry-delete in @strong{all} your editing modes!
+
+@kindex DEL
+@kindex Backspace
+In a nutshell, when hungry-delete mode is enabled, hitting the
+@key{Backspace} key@footnote{I say ``hit the @key{Backspace} key'' but
+what I really mean is ``when Emacs receives the @code{BackSpace} key
+event''. The difference usually isn't significant to most users, but
+advanced users will realize that under window systems such as X, any
+physical key (keycap) on the keyboard can be configured to generate any
+keysym, and thus any Emacs key event. Also, the use of Emacs on TTYs
+will affect which keycap generates which key event. From a pedantic
+point of view, here we are only concerned with the key event that
+Emacs receives.} will consume all preceding whitespace, including
+newlines and tabs. This can really cut down on the number of
+@key{Backspace}'s you have to type if, for example you made a mistake on
+the preceding line.
+
+@findex c-electric-backspace
+@findex electric-backspace (c-)
+@vindex c-backspace-function
+@vindex backspace-function (c-)
+
+@findex c-electric-delete
+@findex electric-delete (c-)
+@vindex c-delete-function
+@vindex delete-function (c-)
+@cindex literal
+
+@findex backward-delete-char-untabify
+
+By default, when you hit the @key{Backspace} key
+@ccmode{} runs the command @code{c-electric-backspace}, which deletes
+text in the backwards direction. When deleting a single character, or
+when @key{Backspace} is hit in a literal
+(see @ref{Auto-newline insertion}),
+or when hungry-delete mode is disabled, the function
+contained in the @code{c-backspace-function} variable is called with one
+argument (the number of characters to delete). This variable is set to
+@code{backward-delete-char-untabify} by default.
+
+@vindex delete-key-deletes-forward
+@findex delete-char
+
+Similarly, hitting the @key{Delete} key runs the command
+@code{c-electric-delete}. When deleting a single character, or when
+@key{Delete} is hit in a literal, or when hungry-delete mode is
+disabled, the function contained in the @code{c-delete-function}
+variable is called with one argument (the number of characters to
+delete). This variable is set to @code{delete-char} by default.
+
+However, if @code{delete-key-deletes-forward} is @code{nil}, or your
+Emacs does not support separation of @key{Backspace} and @key{DEL}, then
+@code{c-electric-delete} simply calls @code{c-electric-backspace}.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Auto-fill mode interaction, , Hungry-deletion of whitespace, Minor Modes
+@comment node-name, next, previous,up
+
+@section Auto-fill mode interaction
+@cindex Auto-fill mode interaction
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+One other note about minor modes is worth mentioning here. CC Mode now
+works much better with auto-fill mode (a standard Emacs minor mode) by
+correctly auto-filling both line (e.g. C++ style) and block (e.g. C
+style) oriented comments. When @code{auto-fill-mode} is enabled, line
+oriented comments will also be auto-filled by inserting a newline at the
+line break, and inserting @samp{//} at the start of the next line.
+
+@vindex c-comment-continuation-stars
+@vindex comment-continuation-stars (c-)
+@vindex comment-line-break-function
+When auto-filling block oriented comments, the behavior is dependent on
+the value of the variable @code{c-comment-continuation-stars}. When
+this variable is @code{nil}, the old behavior for auto-filling C
+comments is in effect. In this case, the line is broken by closing the
+comment and starting a new comment on the next line.
+
+If you set @code{c-comment-continuation-stars} to a string, then a long
+C block comment line is broken by inserting a newline at the line break
+position, and inserting this string at the beginning of the next comment
+line. The default value for @code{c-comment-continuation-stars} is
+@samp{* } (a star followed by a single space)@footnote{To get block
+comment continuation lines indented under the block comment starter
+(e.g. the @samp{/*}), it is not enough to set
+@code{c-comment-continuation-stars} to the empty string. You need to do
+this, but you also need to set the offset for the @code{c} syntactic
+symbol to be zero.}.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Commands, Customizing Indentation, Minor Modes, Top
+@comment node-name, next, previous,up
+
+@chapter Commands
+@cindex Commands
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@menu
+* Indentation Commands::
+* Other Commands::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Indentation Commands, Other Commands, , Commands
+@comment node-name, next, previous,up
+
+@section Indentation Commands
+@cindex Indentation Commands
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Various commands are provided which allow you to conveniently re-indent
+C constructs. There are several things to
+note about these indentation commands. First, when you
+change your programming style, either interactively or through some
+other means, your file does @emph{not} automatically get re-indented.
+When you change style parameters, you will typically need to reformat
+the line, expression, or buffer to see the effects of your changes.
+
+@cindex c-hanging- functions
+@findex c-hanging-braces-alist
+@findex hanging-braces-alist (c-)
+Second, changing some variables have no effect on existing code, even
+when you do re-indent. For example, the @code{c-hanging-*} variables
+and @code{c-cleanup-list} only affect new code as it is typed in
+on-the-fly, so changing @code{c-hanging-braces-alist} and re-indenting
+the buffer will not adjust placement of braces already in the file.
+
+@vindex c-progress-interval
+@vindex progress-interval (c-)
+Third, re-indenting large portions of code is currently rather
+inefficient. Improvements have been made since previous releases of
+@ccmode{}, and much more radical improvements are planned, but for now
+you need to be aware of this @footnote{In particular, I have had people
+complain about the speed with which @code{lex(1)} output is re-indented.
+Lex, yacc, and other code generators usually output some pretty
+perversely formatted code. @emph{Don't} try to indent this stuff!}.
+Some provision has been made to at least inform you as to the progress
+of the re-indentation. The variable @code{c-progress-interval} controls
+how often a progress message is displayed. Set this variable to
+@code{nil} to inhibit progress messages, including messages normally
+printed when indentation is started and completed.
+
+Also, except as noted below, re-indentation is always driven by the
+same mechanisms that control on-the-fly indentation of code. @xref{New
+Indentation Engine} for details.
+
+@findex c-indent-command
+@findex indent-command (c-)
+@vindex c-tab-always-indent
+@vindex tab-always-indent (c-)
+@kindex TAB
+@cindex literal
+@vindex indent-tabs-mode
+@vindex c-insert-tab-function
+@vindex insert-tab-function (c-)
+@findex tab-to-tab-stop
+To indent a single line of code, use @kbd{TAB}
+(@code{c-indent-command}). The behavior of this command is controlled
+by the variable @code{c-tab-always-indent}. When this variable is
+@code{t}, @kbd{TAB} always just indents the current line. When
+@code{nil}, the line is indented only if point is at the left margin, or
+on or before the first non-whitespace character on the line, otherwise
+@emph{something else happens}@footnote{Actually what happens is that the
+function stored in @code{c-insert-tab-function} is called.
+Normally this just inserts a real tab character, or the equivalent
+number of spaces, depending on the setting of the variable
+@code{indent-tabs-mode}. If you preferred, you could set
+@code{c-insert-tab-function} to @code{tab-to-tab-stop} for example.}.
+If the value of @code{c-tab-always-indent} is something other than
+@code{t} or @code{nil} (e.g. @code{'other}), then a real tab
+character@footnote{The caveat about @code{indent-tabs-mode} in the
+previous footnote also applies here.} is inserted only when point is
+inside a literal (see @ref{Auto-newline insertion}), otherwise the line
+is indented.
+
+@kindex M-C-q
+@findex c-indent-exp
+@findex indent-exp (c-)
+To indent an entire balanced brace or parenthesis expression, use
+@kbd{M-C-q} (@code{c-indent-exp}). Note that point should be on
+the opening brace or parenthesis of the expression you want to indent.
+
+@kindex C-c C-q
+@findex c-indent-defun
+@findex indent-defun (c-)
+Another very convenient keystroke is @kbd{C-c C-q}
+(@code{c-indent-defun}) when re-indents the entire top-level function or
+class definition that encompasses point. It leaves point at the
+same position within the buffer.
+
+@kindex M-C-\
+@findex indent-region
+To indent any arbitrary region of code, use @kbd{M-C-\}
+(@code{indent-region}). This is a standard Emacs command, specially
+tailored for C code in a @ccmode{} buffer. Note that of course,
+point and mark must delineate the region you
+want to indent.
+
+@kindex M-C-h
+@findex c-mark-function
+@findex mark-function (c-)
+While not strictly an indentation function, @kbd{M-C-h}
+(@code{c-mark-function}) is useful for marking the current top-level
+function or class definition as the current region.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Other Commands, , Indentation Commands, Commands
+@comment node-name, next, previous,up
+
+@section Other Commands
+@cindex Other Commands
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ccmode{} contains other useful command for moving around in C
+code.
+
+@table @code
+@findex c-beginning-of-defun
+@findex beginning-of-defun (c-)
+@findex beginning-of-defun
+@item M-x c-beginning-of-defun
+Moves point back to the least-enclosing brace. This function is
+analogous to the Emacs built-in command @code{beginning-of-defun},
+except it eliminates the constraint that the top-level opening brace
+must be in column zero. See @code{beginning-of-defun} for more
+information.
+
+Depending on the coding style being used, you might prefer
+@code{c-beginning-of-defun} to @code{beginning-of-defun}. If so,
+consider binding @kbd{C-M-a} to the former instead. For backwards
+compatibility reasons, the default binding remains in effect.
+
+@findex c-end-of-defun
+@findex end-of-defun (c-)
+@findex end-of-defun
+@item M-x c-end-of-defun
+Moves point to the end of the current top-level definition. This
+function is analogous to the Emacs built-in command @code{end-of-defun},
+except it eliminates the constraint that the top-level opening brace of
+the defun must be in column zero. See @code{beginning-of-defun} for more
+information.
+
+Depending on the coding style being used, you might prefer
+@code{c-end-of-defun} to @code{end-of-defun}. If so,
+consider binding @kbd{C-M-e} to the former instead. For backwards
+compatibility reasons, the default binding remains in effect.
+
+@kindex C-c C-u
+@findex c-up-conditional
+@findex up-conditional (c-)
+@item C-c C-u (c-up-conditional)
+Move point back to the containing preprocessor conditional, leaving the
+mark behind. A prefix argument acts as a repeat count. With a negative
+argument, move point forward to the end of the containing
+preprocessor conditional. When going backwards, @code{#elif} is treated
+like @code{#else} followed by @code{#if}. When going forwards,
+@code{#elif} is ignored.@refill
+
+@kindex C-c C-p
+@findex c-backward-conditional
+@findex backward-conditional (c-)
+@item C-c C-p (c-backward-conditional)
+Move point back over a preprocessor conditional, leaving the mark
+behind. A prefix argument acts as a repeat count. With a negative
+argument, move forward.
+
+@kindex C-c C-n
+@findex c-forward-conditional
+@findex forward-conditional (c-)
+@item C-c C-n (c-forward-conditional)
+Move point forward across a preprocessor conditional, leaving the mark
+behind. A prefix argument acts as a repeat count. With a negative
+argument, move backward.
+
+@kindex ESC a
+@findex c-beginning-of-statement
+@findex beginning-of-statement (c-)
+@item M-a (c-beginning-of-statement)
+Move point to the beginning of the innermost C statement. If point is
+already at the beginning of a statement, it moves to the beginning of
+the closest preceding statement, even if that means moving into a block
+(you can use @kbd{M-C-b} to move over a balanced block). With prefix
+argument @var{n}, move back @var{n} @minus{} 1 statements.
+
+If point is within a comment, or next to a comment, this command moves
+by sentences instead of statements.
+
+When called from a program, this function takes three optional
+arguments: the numeric prefix argument, a buffer position limit (used as
+a starting point for syntactic parsing and as a limit for backward
+movement), and a flag to indicate whether movement should be by
+statements (if @code{nil}) or sentence (if non-@code{nil}).
+
+@kindex ESC e
+@findex c-end-of-statement
+@findex end-of-statement (c-)
+@item M-e (c-end-of-statement)
+Move point to the end of the innermost C statement. If point is at the
+end of a statement, move to the end of the next statement, even if it's
+inside a nested block (use @kbd{M-C-f} to move to the other side of the
+block). With prefix argument @var{n}, move forward @var{n} @minus{} 1
+statements.
+
+If point is within a comment, or next to a comment, this command moves
+by sentences instead of statements.
+
+When called from a program, this function takes three optional
+arguments: the numeric prefix argument, a buffer position limit (used as
+a starting point for syntactic parsing and as a limit for backward
+movement), and a flag to indicate whether movement should be by
+statements (if @code{nil}) or sentence (if non-@code{nil}).
+
+@findex c-forward-into-nomenclature
+@findex forward-into-nomenclature (c-)
+@item M-x c-forward-into-nomenclature
+A popular programming style, especially for object-oriented languages
+such as C++ is to write symbols in a mixed case format, where the first
+letter of each word is capitalized, and not separated by underscores.
+E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}.
+
+This command moves point forward to next capitalized word. With prefix
+argument @var{n}, move @var{n} times.
+
+@findex c-backward-into-nomenclature
+@findex backward-into-nomenclature (c-)
+@item M-x c-backward-into-nomenclature
+Move point backward to beginning of the next capitalized
+word. With prefix argument @var{n}, move @var{n} times. If
+@var{n} is negative, move forward.
+
+@kindex C-c :
+@findex c-scope-operator
+@findex scope-operator (c-)
+@item C-c : (c-scope-operator)
+In C++, it is also sometimes desirable to insert the double-colon scope
+operator without performing the electric behavior of colon insertion.
+@kbd{C-c :} does just this.
+
+@kindex ESC q
+@findex fill-paragraph
+@vindex c-hanging-comment-starter-p
+@vindex c-hanging-comment-ender-p
+@vindex hanging-comment-starter-p (c-)
+@vindex hanging-comment-ender-p (c-)
+@item M-q (fill-paragraph)
+The command is used to fill a block style (C) or line style (C++)
+comment, in much the same way that text in the various text modes can be
+filled@footnote{You should not use specialized filling packages such as
+@code{filladapt} with CC Mode. They don't work as well for filling as
+@code{c-fill-paragraph}}. You should never attempt to fill non-comment
+code sections; you'll end up with garbage! Two variables control how C
+style block comments are filled, specifically how the comment start and
+end delimiters are handled.
+
+The variable @code{c-hanging-comment-starter-p} controls whether comment
+start delimiters which appear on a line by themselves, end up on a line
+by themselves after the fill. When the value is @code{nil}, the comment
+starter will remain on its own line@footnote{It will not be placed on a
+separate line if it is not already on a separate line.}. Otherwise,
+text on the next line will be put on the same line as the comment
+starter. This is called @dfn{hanging} because the following text hangs
+on the line with the comment starter@footnote{This variable is @code{t}
+by default, except in @code{java-mode}. Hanging comment starters mess
+up Javadoc style comments.}
+
+The variable @code{c-hanging-comment-ender-p} controls the analogous
+behavior for the block comment end delimiter. When the value is
+@code{nil}, the comment ender will remain on its own line after the
+file@footnote{The same caveat as above holds true.}. Otherwise, the
+comment end delimiter will be placed at the end of the previous line.
+
+@end table
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Customizing Indentation, Syntactic Symbols, Commands, Top
+@comment node-name, next, previous,up
+
+@chapter Customizing Indentation
+@cindex Customizing Indentation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+@cindex c-set-offset
+@cindex set-offset (c-)
+The variable @code{c-offsets-alist} contains the mappings between
+syntactic symbols and the offsets to apply for those symbols. You
+should never modify this variable directly though. Use the function
+@code{c-set-offset} instead (see below for details).
+
+The @code{c-offsets-alist} variable is where you customize all your
+indentations. You simply need to decide what additional offset you want
+to add for every syntactic symbol. You can use the command @kbd{C-c
+C-o} (@code{c-set-offset}) as the way to set offsets, both interactively
+and from your mode hook. Also, you can set up @emph{styles} of
+indentatio. Most likely, you'll
+find one of the pre-defined styles will suit your needs, but if not,
+this section will describe how to set up basic editing configurations.
+@xref{Styles} for an explanation of how to set up named styles.
+
+@cindex c-basic-offset
+@cindex basic-offset (c-)
+As mentioned previously, the variable @code{c-offsets-alist} is an
+association list of syntactic symbols and the offsets to be applied for
+those symbols. In fact, these offset values can be any of an integer, a
+function or lambda expression, a variable name, or one of the following
+symbols: @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or
+@code{/}. These symbols describe offset in multiples of the value of
+the variable @code{c-basic-offset}. By defining a style's indentation
+in terms of this fundamental variable, you can change the amount of
+whitespace given to an indentation level while leaving the same
+relationship between levels. Here are the values that the special
+symbols correspond to:
+
+@table @code
+
+@item +
+@code{c-basic-offset} times 1
+@item -
+@code{c-basic-offset} times -1
+@item ++
+@code{c-basic-offset} times 2
+@item --
+@code{c-basic-offset} times -2
+@item *
+@code{c-basic-offset} times 0.5
+@item /
+@code{c-basic-offset} times -0.5
+
+@end table
+
+@vindex c-style-variables-are-local-p
+@vindex style-variables-are-local-p (c-)
+@noindent
+So, for example, because most of the default offsets are defined in
+terms of @code{+}, @code{-}, and @code{0}, if you like the general
+indentation style, but you use 4 spaces instead of 2 spaces per level,
+you can probably achieve your style just by changing
+@code{c-basic-offset} like so (in your @file{.emacs} file):
+@example
+
+(setq c-basic-offset 4)
+
+@end example
+
+@noindent
+This would change
+@example
+@group
+
+int add( int val, int incr, int doit )
+@{
+ if( doit )
+ @{
+ return( val + incr );
+ @}
+ return( val );
+@}
+
+@end group
+@end example
+@noindent
+to
+@example
+@group
+
+int add( int val, int incr, int doit )
+@{
+ if( doit )
+ @{
+ return( val + incr );
+ @}
+ return( val );
+@}
+
+@end group
+@end example
+
+
+To change indentation styles more radically, you will want to change the
+value associated with the syntactic symbols in the
+@code{c-offsets-alist} variable. First, I'll show you how to do that
+interactively, then I'll describe how to make changes to your
+@file{.emacs} file so that your changes are more permanent.
+
+@menu
+* Interactive Customization::
+* Permanent Customization::
+* Styles::
+* Advanced Customizations::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Interactive Customization, Permanent Customization, , Customizing Indentation
+@comment node-name, next, previous,up
+
+@section Interactive Customization
+@cindex Interactive Customization
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+As an example of how to customize indentation, let's change the
+style of this example@footnote{In this an subsequent examples, the
+original code is formatted using the @samp{gnu} style unless otherwise
+indicated. @xref{Styles}.}:
+@example
+@group
+
+1: int add( int val, int incr, int doit )
+2: @{
+3: if( doit )
+4: @{
+5: return( val + incr );
+6: @}
+7: return( val );
+8: @}
+
+@end group
+@end example
+@noindent
+to:
+@example
+@group
+
+1: int add( int val, int incr, int doit )
+2: @{
+3: if( doit )
+4: @{
+5: return( val + incr );
+6: @}
+7: return( val );
+8: @}
+
+@end group
+@end example
+
+In other words, we want to change the indentation of braces that open a
+block following a condition so that the braces line up under the
+conditional, instead of being indented. Notice that the construct we
+want to change starts on line 4. To change the indentation of a line,
+we need to see which syntactic components affect the offset calculations
+for that line. Hitting @kbd{C-c C-s} on line 4 yields:
+@example
+
+((substatement-open . 44))
+
+@end example
+
+@findex c-set-offset
+@findex set-offset (c-)
+@kindex C-c C-o
+@noindent
+so we know that to change the offset of the open brace, we need to
+change the indentation for the @code{substatement-open} syntactic
+symbol. To do this interactively, just hit @kbd{C-c C-o}
+(@code{c-set-offset}). This prompts you for the syntactic symbol to
+change, providing a reasonable default. In this case, the default is
+@code{substatement-open}, which is just the syntactic symbol we want to
+change!
+
+After you hit return, @ccmode{} will then prompt you for the new
+offset value, with the old value as the default. The default in this
+case is @samp{+}, but we want no extra indentation so enter
+@samp{0} and @kbd{RET}. This will associate the offset 0 with the
+syntactic symbol @code{substatement-open} in the @code{c-offsets-alist}
+variable.
+
+@findex c-indent-defun
+@findex indent-defun (c-)
+@kindex C-c C-q
+To check your changes quickly, just hit @kbd{C-c C-q}
+(@code{c-indent-defun}) to reindent the entire function. The example
+should now look like:
+@example
+@group
+
+1: int add( int val, int incr, int doit )
+2: @{
+3: if( doit )
+4: @{
+5: return( val + incr );
+6: @}
+7: return( val );
+8: @}
+
+@end group
+@end example
+
+Notice how just changing the open brace offset on line 4 is all we
+needed to do. Since the other affected lines are indented relative to
+line 4, they are automatically indented the way you'd expect. For more
+complicated examples, this may not always work. The general approach to
+take is to always start adjusting offsets for lines higher up in the
+file, then re-indent and see if any following lines need further
+adjustments.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Permanent Customization, Styles, Interactive Customization, Customizing Indentation
+@comment node-name, next, previous,up
+
+@section Permanent Customization
+@cindex Permanent Customization
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex c-mode-common-hook
+@vindex c-mode-hook
+@vindex c++-mode-hook
+@vindex objc-mode-hook
+@vindex java-mode-hook
+@vindex idl-mode-hook
+@vindex c-initialization-hook
+@vindex initialization-hook (c-)
+@cindex hooks
+To make your changes permanent, you need to add some lisp code to your
+@file{.emacs} file, but first you need to decide whether your styles
+should be global in every buffer, or local to each specific buffer.
+
+If you edit primarily one style of code, you may want to make the
+@ccmode{} style variables have global values so that every buffer will
+share the style settings. This will allow you to set the @ccmode{}
+variables at the top level of your @file{.emacs} file, and is the
+way @ccmode{} works by default.
+
+@vindex c-mode-common-hook
+@vindex mode-common-hook (c-)
+@vindex c-style-variables-are-local-p
+@vindex style-variables-are-local-p (c-)
+If you edit many different styles of code at
+the same time, you might want to make the @ccmode{} style variables
+have buffer local values. If you do this, then you will need to set any
+@ccmode{} style variables in a hook function (e.g. off of
+@code{c-mode-common-hook} instead of at the top level of your
+@file{.emacs} file). The recommended way to do this is to set the
+variable @code{c-style-variables-are-local-p} to @code{t}
+@strong{before} @ccmode{} is loaded into your Emacs session.
+
+@ccmode{} provides several hooks that you can
+use to customize the mode according to your coding style. Each language
+mode has its own hook, adhering to standard Emacs major mode
+conventions. There is also one general hook and one package
+initialization hook:
+
+@itemize @bullet
+
+@item
+@code{c-mode-hook} --- for C buffers only
+@item
+@code{c++-mode-hook} --- for C++ buffers only
+@item
+@code{objc-mode-hook} --- for Objective-C buffers only
+@item
+@code{java-mode-hook} --- for Java buffers only
+@item
+@code{idl-mode-hook} --- for IDL buffers only
+@item
+@code{c-mode-common-hook} --- common across all languages
+@item
+@code{c-initialization-hook} --- hook run only once per Emacs session,
+when @ccmode{} is initialized.
+
+@end itemize
+
+The language hooks get run as the last thing when you enter that
+language mode. The @code{c-mode-common-hook} is run by all
+supported modes @emph{before} the language specific hook, and thus can
+contain customizations that are common across all languages. Most of
+the examples in this section will assume you are using the common
+hook@footnote{The interaction between @code{java-mode} and the hook
+variables is slightly different than for the other modes.
+@code{java-mode} sets the style (see @ref{Styles}) of the buffer to
+@samp{java} @emph{before} running the @code{c-mode-common-hook} or
+@code{java-mode-hook}. You need to be aware of this so that style
+settings in @code{c-mode-common-hook} don't clobber your Java style.}.
+
+Here's a simplified example of what you can add to your @file{.emacs}
+file to make the changes described in the previous section
+(@ref{Interactive Customization}) more permanent. See the Emacs manuals
+for more information on customizing Emacs via hooks. @xref{Sample
+.emacs File} for a more complete sample @file{.emacs} file.
+@example
+@group
+
+(defun my-c-mode-common-hook ()
+ ;; my customizations for all of c-mode and related modes
+ (c-set-offset 'substatement-open 0)
+ ;; other customizations can go here
+ )
+(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+
+@end group
+@end example
+
+For complex customizations, you will probably want to set up a
+@emph{style} that groups all your customizations under a single
+name.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Styles, Advanced Customizations, Permanent Customization, Customizing Indentation
+@comment node-name, next, previous,up
+
+@section Styles
+@cindex Styles
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Most people only need to edit code formatted in just a few well-defined
+and consistent styles. For example, their organization might impose a
+``blessed'' style that all its programmers must conform to. Similarly,
+people who work on GNU software will have to use the GNU coding style on
+C code. Some shops are more lenient, allowing a variety of coding
+styles, and as programmers come and go, there could be a number of
+styles in use. For this reason, @ccmode{} makes it convenient for
+you to set up logical groupings of customizations called @dfn{styles},
+associate a single name for any particular style, and pretty easily
+start editing new or existing code using these styles.
+
+@menu
+* Built-in Styles::
+* Adding Styles::
+* File Styles::
+@end menu
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Built-in Styles, Adding Styles, , Styles
+@comment node-name, next, previous,up
+
+@subsection Built-in Styles
+@cindex Built-in Styles
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+If you're lucky, one of @ccmode{}'s built-in styles might be just
+what you're looking for. These include:
+
+@itemize @bullet
+@cindex GNU style
+@item
+@code{gnu} --- coding style blessed by the Free Software Foundation
+for C code in GNU programs. This is the default style for all newly
+created buffers, but you can change this by setting the variable
+@code{c-default-style}.
+
+@cindex K&R style
+@item
+@code{k&r} --- The classic Kernighan and Ritchie style for C code.
+
+@cindex BSD style
+@item
+@code{bsd} --- Also known as ``Allman style'' after Eric Allman.
+
+@cindex Whitesmith style
+@item
+@code{whitesmith} --- Popularized by the examples that came with
+Whitesmiths C, an early commercial C compiler.
+
+@cindex Stroustrup style
+@item
+@code{stroustrup} --- The classic Stroustrup style for C++ code.
+
+@cindex Ellemtel style
+@item
+@code{ellemtel} --- Popular C++ coding standards as defined by
+``Programming in C++, Rules and Recommendations'', Erik Nyquist and Mats
+Henricson, Ellemtel @footnote{This document is ftp'able from
+@code{euagate.eua.ericsson.se}}.
+
+@cindex Linux style
+@item
+@code{linux} --- C coding standard for Linux development.
+
+@cindex Python style
+@item
+@code{python} --- C coding standard for Python extension
+modules@footnote{Python is a high level scripting language with a C/C++
+foreign function interface. For more information, see
+@code{<http://www.python.org/>}.}.
+
+@cindex Java style
+@cindex java-mode
+@item
+@code{java} --- The style for editing Java code. Note that this style is
+automatically installed when you enter @code{java-mode}.
+
+@cindex User style
+@cindex .emacs file
+@vindex c-default-style
+@vindex default-style (c-)
+@item
+@code{user} --- This is a special style for several reasons. First, if
+you customize @ccmode{} by using either the new Custom interface or by
+doing @code{setq}'s at the top level of your @file{.emacs} file, these
+settings will be captured in the @code{user} style. Also, all other
+styles implicitly inherit their settings from @code{user} style. This
+means that for any styles you add via @code{c-add-style} (@xref{Adding
+Styles}) you need only define the differences between your new style and
+@code{user} style.
+
+Note however that @code{user} style is @emph{not} the default style.
+@code{gnu} is the default style for all newly created buffers, but you
+can change this by setting variable @code{c-default-style}. Be careful
+if you customize @ccmode{} as described above; since your changes will
+be captured in the @code{user} style, you will also have to change
+@code{c-default-style} to "user" to see the effect of your
+customizations.
+
+@end itemize
+
+@findex c-set-style
+@findex set-style (c-)
+@kindex C-c .
+If you'd like to experiment with these built-in styles you can simply
+type the following in a @ccmode{} buffer:
+@example
+@group
+
+@kbd{C-c . @var{STYLE-NAME} RET}
+
+@end group
+@end example
+@noindent
+@kbd{C-c .} runs the command @code{c-set-style}. Note that all style
+names are case insensitive, even the ones you define.
+
+Setting a style in this way does @emph{not} automatically re-indent your
+file. For commands that you can use to view the effect of your changes,
+see @ref{Commands}.
+
+Once you find a built-in style you like, you can make the change
+permanent by adding some lisp to your @file{.emacs} file. Let's say for
+example that you want to use the @samp{ellemtel} style in all your
+files. You would add this:
+@example
+@group
+
+(defun my-c-mode-common-hook ()
+ ;; use Ellemtel style for all C like languages
+ (c-set-style "ellemtel")
+ ;; other customizations can go here
+ )
+(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+
+@end group
+@end example
+
+@vindex c-indentation-style
+@vindex indentation-style (c-)
+Note that for BOCM compatibility, @samp{gnu} is the default
+style, and any non-style based customizations you make (i.e. in
+@code{c-mode-common-hook} in your
+@file{.emacs} file) will be based on @samp{gnu} style unless you do
+a @code{c-set-style} as the first thing in your hook. The variable
+@code{c-indentation-style} always contains the buffer's current style name,
+as a string.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Adding Styles, File Styles, Built-in Styles, Styles
+@comment node-name, next, previous,up
+
+@subsection Adding Styles
+@cindex Adding Styles
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex c-style-alist
+@vindex style-alist (c-)
+@findex c-add-style
+@findex add-style (c-)
+If none of the built-in styles is appropriate, you'll probably want to
+add a new @dfn{style definition}. Styles are kept in the
+@code{c-style-alist} variable, but you should never modify this variable
+directly. Instead, @ccmode{} provides the function
+@code{c-add-style} that you can use to easily add new styles or change
+existing styles. This function takes two arguments, a @var{stylename}
+string, and an association list @var{description} of style
+customizations. If @var{stylename} is not already in
+@code{c-style-alist}, the new style is added, otherwise the style is
+changed to the new @var{description}.
+This function also takes an optional third argument, which if
+non-@code{nil}, automatically applies the new style to the current
+buffer.
+
+@comment TBD: The next paragraph is bogus. I really need to better
+@comment document adding styles, including setting up inherited styles.
+
+The sample @file{.emacs} file provides a concrete example of how a new
+style can be added and automatically set. @xref{Sample .emacs File}.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node File Styles, , Adding Styles, Styles
+@comment node-name, next, previous,up
+
+@subsection File Styles
+@cindex File Styles
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex local variables
+
+The Emacs manual describes how you can customize certain variables on a
+per-file basis by including a @dfn{Local Variable} block at the end of
+the file. So far, you've only seen a functional interface to @ccmode{}
+customization, which is highly inconvenient for use in a Local Variable
+block. @ccmode{} provides two variables that make it easier for you to
+customize your style on a per-file basis.
+It works via the standard Emacs hook variable
+@code{hack-local-variables-hook}.
+
+@vindex c-file-style
+@vindex file-style (c-)
+@vindex c-file-offsets
+@vindex file-offsets (c-)
+
+The variable @code{c-file-style} can be set to a style name string.
+When the file is visited, @ccmode{} will automatically set the
+file's style to this style using @code{c-set-style}.
+
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+@findex c-set-offset
+@findex set-offset (c-)
+Another variable, @code{c-file-offsets}, takes an association list
+similar to what is allowed in @code{c-offsets-alist}. When the file is
+visited, @ccmode{} will automatically institute these offets using
+@code{c-set-offset}.
+
+Note that file style settings (i.e. @code{c-file-style}) are applied
+before file offset settings (i.e. @code{c-file-offsets}). Also, if
+either of these are set in a file's local variable section, all the
+style variable values are made local to that buffer.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Advanced Customizations, , Styles, Customizing Indentation
+@comment node-name, next, previous,up
+
+@section Advanced Customizations
+@cindex Advanced Customizations
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex c-style-alist
+@vindex style-alist (c-)
+@vindex c-basic-offset
+@vindex basic-offset (c-)
+For most users, @ccmode{} will support their coding styles with
+very little need for more advanced customizations. Usually, one of the
+standard styles defined in @code{c-style-alist} will do the trick. At
+most, perhaps one of the syntactic symbol offsets will need to be
+tweaked slightly, or maybe @code{c-basic-offset} will need to be
+changed. However, some styles require a more flexible framework for
+customization, and one of the real strengths of @ccmode{} is that
+the syntactic analysis model provides just such a framework. This allows
+you to implement custom indentation calculations for situations not
+handled by the mode directly.
+
+@vindex c-style-variables-are-local-p
+@vindex style-variables-are-local-p
+Note that the style controlling variables can either have global values,
+or can be buffer local (e.g. different in every buffer). If all the C
+files you edit tend to have the same style, you might want to keep the
+variables global. If you tend to edit files with many different styles,
+you will have to make the variables buffer local. The variable
+@code{c-style-variables-are-local-p} controls this.
+
+When @code{c-style-variables-are-local-p} is non-nil, then the style
+variables will have a different settable value for each buffer,
+otherwise all buffers will share the same values. By default, its value
+is @code{nil} (i.e. global values). You @strong{must} set this variable
+before @ccmode{} is loaded into your Emacs session, and once the
+variables are made buffer local, they cannot be made global again
+(unless you restart Emacs of course!)
+
+@menu
+* Custom Indentation Functions::
+* Custom Brace and Colon Hanging::
+* Customizing Semi-colons and Commas::
+* Other Special Indentations::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations
+@comment node-name, next, previous,up
+
+@subsection Custom Indentation Functions
+@cindex Custom Indentation Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex Custom Indentation Functions
+The most flexible way to customize @ccmode{} is by writing @dfn{custom
+indentation functions} and associating them with specific syntactic
+symbols (see @ref{Syntactic Symbols}). @ccmode{} itself uses custom
+indentation functions to provide more sophisticated indentation, for
+example when lining up C++ stream operator blocks:
+@example
+@group
+
+1: void main(int argc, char**)
+2: @{
+3: cout << "There were "
+4: << argc
+5: << "arguments passed to the program"
+6: << endl;
+7: @}
+
+@end group
+@end example
+
+In this example, lines 4 through 6 are assigned the @code{stream-op}
+syntactic symbol. Here, @code{stream-op} has an offset of @code{+}, and
+with a @code{c-basic-offset} of 2, you can see that lines 4 through 6
+are simply indented two spaces to the right of line 3. But perhaps we'd
+like @ccmode{} to be a little more intelligent so that it aligns
+all the @samp{<<} symbols in lines 3 through 6. To do this, we have
+to write a custom indentation function which finds the column of first
+stream operator on the first line of the statement. Here is sample
+lisp code implementing this:
+@example
+@group
+
+(defun c-lineup-streamop (langelem)
+ ;; lineup stream operators
+ (save-excursion
+ (let* ((relpos (cdr langelem))
+ (curcol (progn (goto-char relpos)
+ (current-column))))
+ (re-search-forward "<<\\|>>" (c-point 'eol) 'move)
+ (goto-char (match-beginning 0))
+ (- (current-column) curcol))))
+
+@end group
+@end example
+@noindent
+Custom indent functions take a single argument, which is a syntactic
+component cons cell (see @ref{Syntactic Analysis}). The
+function returns an integer offset value that will be added to the
+running total indentation for the line. Note that what actually gets
+returned is the difference between the column that the first stream
+operator is on, and the column of the buffer relative position passed in
+the function's argument. Remember that @ccmode{} automatically
+adds in the column of the component's relative buffer position and we
+don't the column offset added in twice.
+
+@cindex stream-op syntactic symbol
+@findex c-lineup-streamop
+@findex lineup-streamop (c-)
+Now, to associate the function @code{c-lineup-streamop} with the
+@code{stream-op} syntactic symbol, we can add something like the
+following to our @code{c++-mode-hook}@footnote{It probably makes more
+sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook}
+since stream operators are only relevent for C++.}:
+@example
+
+(c-set-offset 'stream-op 'c-lineup-streamop)
+
+@end example
+
+@kindex C-c C-q
+Now the function looks like this after re-indenting (using @kbd{C-c
+C-q}):
+@example
+@group
+
+1: void main(int argc, char**)
+2: @{
+3: cout << "There were "
+4: << argc
+5: << "arguments passed to the program"
+6: << endl;
+7: @}
+
+@end group
+@end example
+
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+Custom indentation functions can be as simple or as complex as you like,
+and any syntactic symbol that appears in @code{c-offsets-alist} can have
+a custom indentation function associated with it. @ccmode{} comes
+with several standard custom indentation functions, not all of which are
+used by the default styles.
+
+@itemize @bullet
+@findex c-lineup-arglist
+@findex lineup-arglist (c-)
+@item
+@code{c-lineup-arglist} --- lines up function argument lines under the
+argument on the previous line.
+
+@findex c-lineup-arglist-intro-after-paren
+@findex lineup-arglist-intro-after-paren (c-)
+@item
+@code{c-lineup-arglist-intro-after-paren} --- similar to
+@code{c-lineup-arglist}, but works for argument lists that begin with an
+open parenthesis followed by a newline.
+
+@findex c-lineup-arglist-close-under-paren
+@findex lineup-arglist-close-under-paren (c-)
+@item
+@code{c-lineup-arglist-close-under-paren} --- set your
+@code{arglist-close} syntactic symbol to this line-up function so that
+parentheses that close argument lists will line up under the parenthesis
+that opened the argument list.
+
+@findex c-lineup-close-paren
+@findex lineup-close-paren (c-)
+@item
+@code{c-lineup-close-paren} --- lines up the closing parenthesis under
+its corresponding open parenthesis if that one is followed by code.
+Otherwise, if the open parenthesis ends its line, no indentation is
+added. Works with any @code{@dots{}-close} symbol.
+
+@findex c-lineup-streamop
+@findex lineup-streamop (c-)
+@item
+@code{c-lineup-streamop} --- lines up C++ stream operators
+(e.g. @samp{<<} and @samp{>>}).
+
+@findex c-lineup-multi-inher
+@findex lineup-multi-inher (c-)
+@item
+@code{c-lineup-multi-inher} --- lines up multiple inheritance lines.
+
+@findex c-indent-one-line-block
+@findex indent-one-line-block (c-)
+@item
+@code{c-indent-one-line-block} --- adds @code{c-basic-offset} to the
+indentation if the line is a one line block, otherwise 0. Intended to
+be used with any opening brace symbol, e.g. @code{substatement-open}.
+
+@findex c-lineup-C-comments
+@findex lineup-C-comments (c-)
+@item
+@code{c-lineup-C-comments} --- lines up C block comment continuation
+lines.
+
+@findex c-lineup-comment
+@findex lineup-comment (c-)
+@vindex c-comment-only-line-offset
+@vindex comment-only-line-offset (c-)
+@item
+@code{c-lineup-comment} --- lines up comment only lines according to
+the variable @code{c-comment-only-line-offset}.
+
+@findex c-lineup-runin-statements
+@findex lineup-runin-statements (c-)
+@item
+@code{c-lineup-runin-statements} --- lines up @code{statement}s for coding
+standards which place the first statement in a block on the same line as
+the block opening brace@footnote{Run-in style doesn't really work too
+well. You might need to write your own custom indentation functions to
+better support this style.}.
+
+@findex c-lineup-math
+@findex lineup-math (c-)
+@item
+@code{c-lineup-math} --- lines up math @code{statement-cont} lines under
+the previous line after the equals sign.
+
+@findex c-lineup-ObjC-method-call
+@findex lineup-ObjC-method-call (c-)
+@item
+@code{c-lineup-ObjC-method-call} --- for Objective-C code, lines up
+selector arguments just after the message receiver.
+
+@findex c-lineup-ObjC-method-args
+@findex lineup-ObjC-method-args (c-)
+@item
+@code{c-lineup-ObjC-method-args} --- for Objective-C code, lines up the
+colons that separate arguments by aligning colons vertically.
+
+@findex c-lineup-ObjC-method-args-2
+@findex lineup-ObjC-method-args-2 (c-)
+@item
+@code{c-lineup-ObjC-method-args-2} --- similar to
+@code{c-lineup-ObjC-method-args} but lines up the colon on the current
+line with the colon on the previous line.
+
+@findex c-lineup-dont-change
+@findex lineup-dont-change (c-)
+@item
+@code{c-lineup-dont-change} --- this lineup function returns the
+indentation of the current line. Think of it as an identity function
+for lineups; it is used for @code{cpp-macro-cont} lines.
+
+@end itemize
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations
+@comment node-name, next, previous,up
+
+@subsection Custom Brace and Colon Hanging
+@cindex Custom Brace and Colon Hanging
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex c-hanging-braces-alist
+@vindex hanging-braces-alist (c-)
+Syntactic symbols aren't the only place where you can customize
+@ccmode{} with the lisp equivalent of callback functions. Brace
+``hanginess'' can also be determined by custom functions associated with
+syntactic symbols on the @code{c-hanging-braces-alist} variable.
+Remember that @var{ACTION}'s are typically a list containing some
+combination of the symbols @code{before} and @code{after} (see
+@ref{Hanging Braces}). However, an @var{ACTION} can also be a function
+which gets called when a brace matching that syntactic symbol is
+entered.
+
+@cindex customizing brace hanging
+These @var{ACTION} functions are called with two arguments: the
+syntactic symbol for the brace, and the buffer position at which the
+brace was inserted. The @var{ACTION} function is expected to return a
+list containing some combination of @code{before} and @code{after}. The
+function can also return @code{nil}. This return value has the normal
+brace hanging semantics.
+
+As an example, @ccmode{} itself uses this feature to dynamically
+determine the hanginess of braces which close ``do-while''
+constructs:
+@example
+@group
+
+void do_list( int count, char** atleast_one_string )
+@{
+ int i=0;
+ do @{
+ handle_string( atleast_one_string[i] );
+ i++;
+ @} while( i < count );
+@}
+
+@end group
+@end example
+
+@findex c-snug-do-while
+@findex snug-do-while (c-)
+@ccmode{} assigns the @code{block-close} syntactic symbol to the
+brace that closes the @code{do} construct, and normally we'd like the
+line that follows a @code{block-close} brace to begin on a separate
+line. However, with ``do-while'' constructs, we want the
+@code{while} clause to follow the closing brace. To do this, we
+associate the @code{block-close} symbol with the @var{ACTION} function
+@code{c-snug-do-while}:
+@example
+
+(defun c-snug-do-while (syntax pos)
+ "Dynamically calculate brace hanginess for do-while statements.
+Using this function, `while' clauses that end a `do-while' block will
+remain on the same line as the brace that closes that block.
+
+See `c-hanging-braces-alist' for how to utilize this function as an
+ACTION associated with `block-close' syntax."
+ (save-excursion
+ (let (langelem)
+ (if (and (eq syntax 'block-close)
+ (setq langelem (assq 'block-close c-syntactic-context))
+ (progn (goto-char (cdr langelem))
+ (if (= (following-char) ?@{)
+ (forward-sexp -1))
+ (looking-at "\\<do\\>[^_]")))
+ '(before)
+ '(before after)))))
+
+@end example
+
+This function simply looks to see if the brace closes a ``do-while''
+clause and if so, returns the list @samp{(before)} indicating
+that a newline should be inserted before the brace, but not after it.
+In all other cases, it returns the list @samp{(before after)} so
+that the brace appears on a line by itself.
+
+@vindex c-syntactic-context
+@vindex syntactic-context (c-)
+During the call to the brace hanging @var{ACTION} function, the variable
+@code{c-syntactic-context} is bound to the full syntactic analysis list.
+
+@cindex customizing colon hanging
+@vindex c-hanging-colon-alist
+@vindex hanging-colon-alist (c-)
+Note that for symmetry, colon hanginess should be customizable by
+allowing function symbols as @var{ACTION}s on the
+@code{c-hanging-colon-alist} variable. Since no use has actually been
+found for this feature, it isn't currently implemented!
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations
+@comment node-name, next, previous,up
+
+@subsection Customizing Semi-colons and Commas
+@cindex Customizing Semi-colons and Commas
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex Customizing Semi-colons and Commas
+@vindex c-hanging-semi&comma-criteria
+@vindex hanging-semi&comma-criteria (c-)
+You can also customize the insertion of newlines after semi-colons and
+commas, when the auto-newline minor mode is enabled (see @ref{Minor
+Modes}). This is controlled by the variable
+@code{c-hanging-semi&comma-criteria}, which contains a list of functions
+that are called in the order they appear. Each function is called with
+zero arguments, and is expected to return one of the following values:
+
+@itemize @bullet
+@item
+non-@code{nil} --- A newline is inserted, and no more functions from the
+list are called.
+
+@item
+@code{stop} --- No more functions from the list are called, but no
+newline is inserted.
+
+@item
+@code{nil} --- No determination is made, and the next function in the
+list is called.
+
+@end itemize
+
+If every function in the list is called without a determination being
+made, then no newline is added. The default value for this variable is a
+list containing a single function which inserts newlines only after
+semi-colons which do not appear inside parenthesis lists (i.e. those
+that separate @code{for}-clause statements).
+
+@findex c-semi&comma-no-newlines-before-nonblanks
+@findex semi&comma-no-newlines-before-nonblanks (c-)
+Here's an example of a criteria function, provided by @ccmode{}, that
+will prevent newlines from being inserted after semicolons when there is
+a non-blank following line. Otherwise, it makes no determination. To
+use, add this to the front of the @code{c-hanging-semi&comma-criteria}
+list.
+
+@example
+@group
+
+(defun c-semi&comma-no-newlines-before-nonblanks ()
+ (save-excursion
+ (if (and (eq last-command-char ?\;)
+ (zerop (forward-line 1))
+ (not (looking-at "^[ \t]*$")))
+ 'stop
+ nil)))
+
+@end group
+@end example
+
+@findex c-semi&comma-inside-parenlist
+@findex c-semi&comma-no-newlines-for-oneline-inliners
+@findex semi&comma-inside-parenlist (c-)
+@findex semi&comma-no-newlines-for-oneline-inliners (c-)
+The default value of @code{c-hanging-semi&comma-criteria} is a list
+containing just the function @code{c-semi&comma-inside-parenlist}, which
+suppresses newlines after semicolons inside parenthesis lists
+(e.g. @code{for}-loops). In addition to
+@code{c-semi&comma-no-newlines-before-nonblanks} described above,
+@ccmode{} also comes with the criteria function
+@code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses
+newlines after semicolons inside one-line inline method definitions
+(i.e. in C++ or Java).
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations
+@comment node-name, next, previous,up
+
+@subsection Other Special Indentations
+@cindex Customizing Semi-colons and Commas
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex c-label-minimum-indentation
+@vindex label-minimum-indentation (c-)
+In @samp{gnu} style (see @ref{Built-in Styles}), a minimum indentation
+is imposed on lines inside top-level constructs. This minimum
+indentation is controlled by the variable
+@code{c-label-minimum-indentation}. The default value for this variable
+is 1.
+
+@vindex c-special-indent-hook
+@vindex special-indent-hook (c-)
+One other customization variable is available in @ccmode{}:
+@code{c-special-indent-hook}. This is a standard hook variable that is
+called after every line is indented by @ccmode{}. You can use it
+to do any special indentation or line adjustments your style dictates,
+such as adding extra indentation to constructors or destructor
+declarations in a class definition, etc. Note however, that you should
+not change point or mark inside your @code{c-special-indent-hook}
+functions (i.e. you'll probably want to wrap your function in a
+@code{save-excursion}).
+
+Setting @code{c-special-indent-hook} in your style definition is handled
+slightly differently than other variables. In your style definition,
+you should set the value for
+@code{c-special-indent-hook} to a function or list of functions, which
+will be appended to @code{c-special-indent-hook} using @code{add-hook}.
+That way, the current setting for the buffer local value of
+@code{c-special-indent-hook} won't be overridden.
+
+@kindex M-;
+@findex indent-for-comment
+@vindex c-indent-comments-syntactically-p
+@vindex indent-comments-syntactically-p (c-)
+@vindex comment-column
+
+Normally, the standard Emacs command @kbd{M-;}
+(@code{indent-for-comment}) will indent comment only lines to
+@code{comment-column}. Some users however, prefer that @kbd{M-;} act
+just like @kbd{TAB} for purposes of indenting comment-only lines;
+i.e. they want the comments to always indent as they would for normal
+code, regardless of whether @kbd{TAB} or @kbd{M-;} were used. This
+behavior is controlled by the variable
+@code{c-indent-comments-syntactically-p}. When @code{nil} (the
+default), @kbd{M-;} indents comment-only lines to @code{comment-column},
+otherwise, they are indented just as they would be if @kbd{TAB} were
+typed.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Syntactic Symbols, Performance Issues, Customizing Indentation, Top
+@comment node-name, next, previous,up
+
+@chapter Syntactic Symbols
+@cindex Syntactic Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+
+Here is a complete list of the recognized syntactic symbols as described
+in the @code{c-offsets-alist} variable, along with a brief description.
+More detailed descriptions follow below.
+
+@itemize @bullet
+@item
+@code{string} --- inside multi-line string
+@item
+@code{c} --- inside a multi-line C style block comment
+@item
+@code{defun-open} --- brace that opens a function definition
+@item
+@code{defun-close} --- brace that closes a function definition
+@item
+@code{defun-block-intro} --- the first line in a top-level defun
+@item
+@code{class-open} --- brace that opens a class definition
+@item
+@code{class-close} --- brace that closes a class definition
+@item
+@code{inline-open} --- brace that opens an in-class inline method
+@item
+@code{inline-close} --- brace that closes an in-class inline method
+@item
+@code{func-decl-cont} --- the region between a function definition's
+argument list and the function opening brace (excluding K&R argument
+declarations). In C, you cannot put anything but whitespace and comments
+between them; in C++ and Java, @code{throws} declarations and other
+things can appear in this context.
+@item
+@code{knr-argdecl-intro} --- first line of a K&R C argument declaration
+@item
+@code{knr-argdecl} --- subsequent lines in a K&R C argument declaration
+@item
+@code{topmost-intro} --- the first line in a topmost definition
+@item
+@code{topmost-intro-cont} --- topmost definition continuation lines
+@item
+@code{member-init-intro} --- first line in a member initialization list
+@item
+@code{member-init-cont} --- subsequent member initialization list lines
+@item
+@code{inher-intro} --- first line of a multiple inheritance list
+@item
+@code{inher-cont} --- subsequent multiple inheritance lines
+@item
+@code{block-open} --- statement block open brace
+@item
+@code{block-close} --- statement block close brace
+@item
+@code{brace-list-open} --- open brace of an enum or static array list
+@item
+@code{brace-list-close} --- close brace of an enum or static array list
+@item
+@code{brace-list-intro} --- first line in an enum or static array list
+@item
+@code{brace-list-entry} --- subsequent lines in an enum or static array list
+@item
+@code{statement} --- a C statement
+@item
+@code{statement-cont} --- a continuation of a C statement
+@item
+@code{statement-block-intro} --- the first line in a new statement block
+@item
+@code{statement-case-intro} --- the first line in a case `block'
+@item
+@code{statement-case-open} --- the first line in a case block starting
+with brace
+@item
+@code{substatement} --- the first line after a conditional
+@item
+@code{substatement-open} --- the brace that opens a substatement block
+@item
+@code{case-label} --- a case or default label
+@item
+@code{access-label} --- C++ access control label
+@item
+@code{label} --- any non-special C label
+@item
+@code{do-while-closure} --- the `while' that ends a
+@code{do}-@code{while} construct
+@item
+@code{else-clause} --- the `else' of an @code{if}-@code{else} construct
+@item
+@code{comment-intro} --- a line containing only a comment introduction
+@item
+@code{arglist-intro} --- the first line in an argument list
+@item
+@code{arglist-cont} --- subsequent argument list lines when no arguments
+follow on the same line as the the arglist opening paren
+@item
+@code{arglist-cont-nonempty} --- subsequent argument list lines when at
+least one argument follows on the same line as the arglist opening paren
+@item
+@code{arglist-close} --- the solo close paren of an argument list
+@item
+@code{stream-op} --- lines continuing a stream operator
+@item
+@code{inclass} --- the line is nested inside a class definition
+@item
+@code{cpp-macro} --- the start of a C preprocessor macro definition
+@item
+@code{cpp-macro-cont} --- subsequent lines of a multi-line C
+preprocessor macro definition
+@item
+@code{friend} --- a C++ friend declaration
+@item
+@code{objc-method-intro} --- the first line of an Objective-C method definition
+@item
+@code{objc-method-args-cont} --- lines continuing an Objective-C method
+definition
+@item
+@code{objc-method-call-cont} --- lines continuing an Objective-C method call
+@item
+@code{extern-lang-open} --- brace that opens an external language block
+@item
+@code{extern-lang-close} --- brace that closes an external language block
+@item
+@code{inextern-lang} --- analogous to `inclass' syntactic symbol, but
+used inside external language blocks (e.g. @code{extern "C" @{}).
+@item
+@code{namespace-open} --- brace that opens a C++ namespace block.
+@item
+@code{namespace-close} --- brace that closes a C++ namespace block.
+@item
+@code{innamespace} --- analogous to `inextern-lang' syntactic symbol,
+but used inside C++ namespace blocks.
+@item
+@code{template-args-cont} --- C++ template argument list continuations
+@end itemize
+
+@cindex -open syntactic symbols
+@cindex -close syntactic symbols
+Most syntactic symbol names follow a general naming convention. When a
+line begins with an open or close brace, the syntactic symbol will
+contain the suffix @code{-open} or @code{-close} respectively.
+
+@cindex -intro syntactic symbols
+@cindex -cont syntactic symbols
+@cindex -block-intro syntactic symbols
+Usually, a distinction is made between the first line that introduces a
+construct and lines that continue a construct, and the syntactic symbols
+that represent these lines will contain the suffix @code{-intro} or
+@code{-cont} respectively. As a sub-classification of this scheme, a
+line which is the first of a particular brace block construct will
+contain the suffix @code{-block-intro}.
+
+@kindex C-c C-s
+Let's look at some examples to understand how this works. Remember that
+you can check the syntax of any line by using @kbd{C-c C-s}.
+@example
+@group
+
+ 1: void
+ 2: swap( int& a, int& b )
+ 3: @{
+ 4: int tmp = a;
+ 5: a = b;
+ 6: b = tmp;
+ 7: int ignored =
+ 8: a + b;
+ 9: @}
+
+@end group
+@end example
+
+@cindex topmost-intro syntactic symbol
+@cindex topmost-intro-cont syntactic symbol
+@cindex defun-open syntactic symbol
+@cindex defun-close syntactic symbol
+@cindex defun-block-intro syntactic symbol
+Line 1 shows a @code{topmost-intro} since it is the first line that
+introduces a top-level construct. Line 2 is a continuation of the
+top-level construct introduction so it has the syntax
+@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
+the brace that opens a top-level function definition. Line 9 is a
+@code{defun-close} since it contains the brace that closes the top-level
+function definition. Line 4 is a @code{defun-block-intro}, i.e. it is
+the first line of a brace-block, enclosed in a
+top-level function definition.
+
+@cindex statement syntactic symbol
+@cindex statement-cont syntactic symbol
+Lines 5, 6, and 7 are all given @code{statement} syntax since there
+isn't much special about them. Note however that line 8 is given
+@code{statement-cont} syntax since it continues the statement begun
+on the previous line.
+
+Here's another example, which illustrates some C++ class syntactic
+symbols:
+@example
+@group
+
+ 1: class Bass
+ 2: : public Guitar,
+ 3: public Amplifiable
+ 4: @{
+ 5: public:
+ 6: Bass()
+ 7: : eString( new BassString( 0.105 )),
+ 8: aString( new BassString( 0.085 )),
+ 9: dString( new BassString( 0.065 )),
+ 10: gString( new BassString( 0.045 ))
+ 11: @{
+ 12: eString.tune( 'E' );
+ 13: aString.tune( 'A' );
+ 14: dString.tune( 'D' );
+ 15: gString.tune( 'G' );
+ 16: @}
+ 17: friend class Luthier;
+ 18: @}
+
+@end group
+@end example
+
+@cindex class-open syntactic symbol
+@cindex class-close syntactic symbol
+As in the previous example, line 1 has the @code{topmost-intro} syntax.
+Here however, the brace that opens a C++ class definition on line 4 is
+assigned the @code{class-open} syntax. Note that in C++, classes,
+structs, and unions are essentially equivalent syntactically (and are
+very similar semantically), so replacing the @code{class} keyword in the
+example above with @code{struct} or @code{union} would still result in a
+syntax of @code{class-open} for line 4 @footnote{This is the case even
+for C and Objective-C. For consistency, structs in all supported
+languages are syntactically equivalent to classes. Note however that
+the keyword @code{class} is meaningless in C and Objective-C.}.
+Similarly, line 18 is assigned @code{class-close} syntax.
+
+@cindex inher-intro syntactic symbol
+@cindex inher-cont syntactic symbol
+Line 2 introduces the inheritance list for the class so it is assigned
+the @code{inher-intro} syntax, and line 3, which continues the
+inheritance list is given @code{inher-cont} syntax.
+
+@cindex access-label syntactic symbol
+@cindex inclass syntactic symbol
+Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
+
+@example
+@group
+
+@code{((inclass . 1) (access-label . 67))}
+
+@end group
+@end example
+
+@noindent
+The primary syntactic symbol for this line is @code{access-label} as
+this a label keyword that specifies access protection in C++. However,
+because this line is also a top-level construct inside a class
+definition, the analysis actually shows two syntactic symbols. The
+other syntactic symbol assigned to this line is @code{inclass}.
+Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
+syntax:
+
+@example
+@group
+
+@code{((inclass . 58) (topmost-intro . 60))}
+
+@end group
+@end example
+
+@cindex member-init-intro syntactic symbol
+@cindex member-init-cont syntactic symbol
+Line 7 introduces a C++ member initialization list and as such is given
+@code{member-init-intro} syntax. Note that in this case it is
+@emph{not} assigned @code{inclass} since this is not considered a
+top-level construct. Lines 8 through 10 are all assigned
+@code{member-init-cont} since they continue the member initialization
+list started on line 7.
+
+@cindex in-class inline methods
+@cindex inline-open syntactic symbol
+@cindex inline-close syntactic symbol
+Line 11's analysis is a bit more complicated:
+
+@example
+@group
+
+@code{((inclass . 1) (inline-open))}
+
+@end group
+@end example
+
+This line is assigned a syntax of both @code{inline-open} and
+@code{inclass} because it opens an @dfn{in-class} C++ inline method
+definition. This is distinct from, but related to, the C++ notion of an
+inline function in that its definition occurs inside an enclosing class
+definition, which in C++ implies that the function should be inlined.
+If though, the definition of the @code{Bass} constructor appeared
+outside the class definition, the construct would be given the
+@code{defun-open} syntax, even if the keyword @code{inline} appeared
+before the method name, as in:
+@example
+@group
+
+class Bass
+ : public Guitar,
+ public Amplifiable
+@{
+public:
+ Bass();
+@}
+
+inline
+Bass::Bass()
+ : eString( new BassString( 0.105 )),
+ aString( new BassString( 0.085 )),
+ dString( new BassString( 0.065 )),
+ gString( new BassString( 0.045 ))
+@{
+ eString.tune( 'E' );
+ aString.tune( 'A' );
+ dString.tune( 'D' );
+ gString.tune( 'G' );
+@}
+
+@end group
+@end example
+
+@cindex friend syntactic symbol
+Returning to the previous example, line 16 is given @code{inline-close}
+syntax, while line 12 is given @code{defun-block-open} syntax, and lines
+13 through 15 are all given @code{statement} syntax. Line 17 is
+interesting in that its syntactic analysis list contains three
+elements:
+
+@example
+
+@code{((friend) (inclass . 58) (topmost-intro . 380))}
+
+@end example
+
+The @code{friend} syntactic symbol is a modifier that typically does not
+have a relative buffer position.
+
+Template definitions introduce yet another syntactic symbol:
+
+@example
+@group
+
+ 1: ThingManager <int,
+ 2: Framework::Callback *,
+ 3: Mutex> framework_callbacks;
+
+@end group
+@end example
+
+Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
+are both analyzed as @code{template-args-cont} lines.
+
+Here is another (totally contrived) example which illustrates how syntax
+is assigned to various conditional constructs:
+@example
+@group
+
+ 1: void spam( int index )
+ 2: @{
+ 3: for( int i=0; i<index; i++ )
+ 4: @{
+ 5: if( i == 10 )
+ 6: @{
+ 7: do_something_special();
+ 8: @}
+ 9: else
+ 10: do_something( i );
+ 11: @}
+ 12: do @{
+ 13: another_thing( i-- );
+ 14: @}
+ 15: while( i > 0 );
+ 16: @}
+
+
+@end group
+@end example
+
+@noindent
+Only the lines that illustrate new syntactic symbols will be discussed.
+
+@cindex substatement-open syntactic symbol
+@cindex substatement-block-intro syntactic symbol
+@cindex block-close syntactic symbol
+Line 4 has a brace which opens a conditional's substatement block. It
+is thus assigned @code{substatement-open} syntax, and since line 5 is
+the first line in the substatement block, it is assigned
+@code{substatement-block-intro} syntax. Lines 6 and 7 are assigned
+similar syntax. Line 8 contains the brace that closes the inner
+substatement block. It is given the syntax @code{block-close},
+as are lines 11 and 14.
+
+@cindex else-clause syntactic symbol
+@cindex substatement syntactic symbol
+Line 9 is a little different --- since it contains the keyword
+@code{else} matching the @code{if} statement introduced on line 5, it is
+given the @code{else-clause} syntax. Note also that line 10 is slightly
+different too. Because @code{else} is considered a conditional
+introducing keyword @footnote{The list of conditional keywords are (in
+C, C++, Objective-C, and Java): @code{for}, @code{if}, @code{do},
+@code{else}, @code{while}, and @code{switch}. C++ and Java have two
+additional conditional keywords: @code{try} and @code{catch}. Java also
+has the @code{finally} and @code{synchronized} keywords.}, and because
+the following substatement is not a brace block, line 10 is assigned the
+@code{substatement} syntax.
+
+@cindex do-while-closure syntactic symbol
+One other difference is seen on line 15. The @code{while} construct
+that closes a @code{do} conditional is given the special syntax
+@code{do-while-closure} if it appears on a line by itself. Note that if
+the @code{while} appeared on the same line as the preceding close brace,
+that line would have been assigned @code{block-close} syntax instead.
+
+Switch statements have their own set of syntactic symbols. Here's an
+example:
+@example
+@group
+
+ 1: void spam( enum Ingredient i )
+ 2: @{
+ 3: switch( i ) @{
+ 4: case Ham:
+ 5: be_a_pig();
+ 6: break;
+ 7: case Salt:
+ 8: drink_some_water();
+ 9: break;
+ 10: default:
+ 11: @{
+ 12: what_is_it();
+ 13: break;
+ 14: @}
+ 15: @}
+ 14: @}
+
+@end group
+@end example
+
+@cindex case-label syntactic symbol
+@cindex statement-case-intro syntactic symbol
+@cindex statement-case-open syntactic symbol
+Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
+while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
+is treated slightly differently since it contains a brace that opens a
+block --- it is given @code{statement-case-open} syntax.
+
+@cindex brace lists
+There are a set of syntactic symbols that are used to recognize
+constructs inside of brace lists. A brace list is defined as an
+@code{enum} or aggregate initializer list, such as might statically
+initialize an array of structs. For example:
+@example
+@group
+
+ 1: static char* ingredients[] =
+ 2: @{
+ 3: "Ham",
+ 4: "Salt",
+ 5: NULL
+ 6: @}
+
+@end group
+@end example
+
+@cindex brace-list-open syntactic symbol
+@cindex brace-list-intro syntactic symbol
+@cindex brace-list-close syntactic symbol
+@cindex brace-list-entry syntactic symbol
+Following convention, line 2 in this example is assigned
+@code{brace-list-open} syntax, and line 3 is assigned
+@code{brace-list-intro} syntax. Likewise, line 6 is assigned
+@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
+@code{brace-list-entry} syntax, as would all subsequent lines in this
+initializer list.
+
+External language definition blocks also have their own syntactic
+symbols. In this example:
+@example
+@group
+
+ 1: extern "C"
+ 2: @{
+ 3: int thing_one( int );
+ 4: int thing_two( double );
+ 5: @}
+
+@end group
+@end example
+
+@cindex extern-lang-open syntactic symbol
+@cindex extern-lang-close syntactic symbol
+@cindex inextern-lang syntactic symbol
+@cindex inclass syntactic symbol
+@noindent
+line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
+the @code{extern-lang-close} syntax. The analysis for line 3 yields:
+@code{((inextern-lang) (topmost-intro . 14))}, where
+@code{inextern-lang} is a modifier similar in purpose to @code{inclass}.
+
+Similarly, C++ namespace constructs have their own associated syntactic
+symbols. In this example:
+@example
+@group
+
+ 1: namespace foo
+ 2: @{
+ 3: void xxx() @{@}
+ 4: @}
+
+@end group
+@end example
+
+@cindex namespace-open syntactic-symbol
+@cindex namespace-close syntactic-symbol
+@cindex innamespace syntactic-symbol
+@noindent
+line 2 is given the @code{namespace-open} syntax, while line 4 is given
+the @code{namespace-close} syntax. The analysis for line 3 yields:
+@code{((innamespace) (topmost-intro . 17))}, where @code{innamespace} is
+a modifier similar in purpose to @code{inextern-lang} and @code{inclass}.
+
+A number of syntactic symbols are associated with parenthesis lists,
+a.k.a argument lists, as found in function declarations and function
+calls. This example illustrates these:
+@example
+@group
+
+ 1: void a_function( int line1,
+ 2: int line2 );
+ 3:
+ 4: void a_longer_function(
+ 5: int line1,
+ 6: int line2
+ 7: );
+ 8:
+ 9: void call_them( int line1, int line2 )
+ 10: @{
+ 11: a_function(
+ 12: line1,
+ 13: line2
+ 14: );
+ 15:
+ 16: a_longer_function( line1,
+ 17: line2 );
+ 18: @}
+
+@end group
+@end example
+
+@cindex arglist-intro syntactic symbol
+@cindex arglist-close syntactic symbol
+Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
+the first line following the open parenthesis, and lines 7 and 14 are
+assigned @code{arglist-close} syntax since they contain the parenthesis
+that closes the argument list.
+
+@cindex arglist-cont-nonempty syntactic symbol
+@cindex arglist-cont syntactic symbol
+Lines that continue argument lists can be assigned one of two syntactic
+symbols. For example, Lines 2 and 17
+are assigned @code{arglist-cont-nonempty} syntax. What this means
+is that they continue an argument list, but that the line containing the
+parenthesis that opens the list is @emph{not empty} following the open
+parenthesis. Contrast this against lines 6 and 13 which are assigned
+@code{arglist-cont} syntax. This is because the parenthesis that opens
+their argument lists is the last character on that line.
+
+Note that there is no @code{arglist-open} syntax. This is because any
+parenthesis that opens an argument list, appearing on a separate line,
+is assigned the @code{statement-cont} syntax instead.
+
+A few miscellaneous syntactic symbols that haven't been previously
+covered are illustrated by this C++ example:
+@example
+@group
+
+ 1: void Bass::play( int volume )
+ 2: const
+ 3: @{
+ 4: /* this line starts a multi-line
+ 5: * comment. This line should get `c' syntax */
+ 6:
+ 7: char* a_multiline_string = "This line starts a multi-line \
+ 8: string. This line should get `string' syntax.";
+ 9:
+ 10: note:
+ 11: @{
+ 12: #ifdef LOCK
+ 13: Lock acquire();
+ 14: #endif // LOCK
+ 15: slap_pop();
+ 16: cout << "I played "
+ 17: << "a note\n";
+ 18: @}
+ 19: @}
+
+@end group
+@end example
+
+@cindex modifier syntactic symbol
+The lines to note in this example include:
+
+@itemize @bullet
+
+@cindex func-decl-cont syntactic symbol
+@item
+line 2, assigned the @code{func-decl-cont} syntax;
+
+@cindex comment-intro syntactic symbol
+@item
+line 4, assigned both @code{defun-block-intro} @emph{and}
+@code{comment-intro} syntax;
+
+@cindex c syntactic symbol
+@item
+line 5, assigned @code{c} syntax;
+
+@item
+@cindex syntactic whitespace
+line 6 which, even though it contains nothing but whitespace, is
+assigned @code{defun-block-intro}. Note that the appearance of the
+comment on lines 4 and 5 do not cause line 6 to be assigned
+@code{statement} syntax because comments are considered to be
+@dfn{syntactic whitespace}, which are ignored when analyzing
+code;
+
+@cindex string syntactic symbol
+@item
+line 8, assigned @code{string} syntax;
+
+@cindex label syntactic symbol
+@item
+line 10, assigned @code{label} syntax;
+
+@cindex block-open syntactic symbol
+@item
+line 11, assigned @code{block-open} syntax;
+
+@cindex cpp-macro syntactic symbol
+@cindex cpp-macro-cont syntactic symbol
+@item
+lines 12 and 14, assigned @code{cpp-macro} syntax.
+
+@cindex stream-op syntactic symbol
+@item
+line 17, assigned @code{stream-op} syntax.
+
+@end itemize
+
+@cindex multi-line macros
+@cindex syntactic whitespace
+Multi-line C preprocessor macros are now (somewhat) supported. At least
+CC Mode now recognizes the fact that it is inside a multi-line macro,
+and it properly skips such macros as syntactic whitespace. In this
+example:
+@example
+@group
+
+ 1: #define LIST_LOOP(cons, listp) \
+ 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
+ 3: if (!CONSP (cons)) \
+ 4: signal_error ("Invalid list format", listp); \
+ 5: else
+
+@end group
+@end example
+@noindent
+line 1 is given the syntactic symbol @code{cpp-macro}. This first line
+of a macro is always given this symbol. The second and subsequent lines
+(e.g. lines 2 through 5) are given the @code{cpp-macro-cont} syntactic
+symbol, with a relative buffer position pointing to the @code{#} which
+starts the macro definition.
+
+In Objective-C buffers, there are three additional syntactic symbols
+assigned to various message calling constructs. Here's an example
+illustrating these:
+@example
+@group
+
+ 1: - (void)setDelegate:anObject
+ 2: withStuff:stuff
+ 3: @{
+ 4: [delegate masterWillRebind:self
+ 5: toDelegate:anObject
+ 6: withExtraStuff:stuff];
+ 7: @}
+
+@end group
+@end example
+
+@cindex objc-method-intro syntactic symbol
+@cindex objc-method-args-cont syntactic symbol
+@cindex objc-method-call-cont syntactic symbol
+Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
+assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
+assigned @code{objc-method-call-cont} syntax.
+
+@cindex knr-argdecl-intro syntactic symbol
+@cindex knr-argdecl syntactic symbol
+Two other syntactic symbols can appear in old style, non-prototyped C
+code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
+@example
+@group
+
+ 1: int add_three_integers(a, b, c)
+ 2: int a;
+ 3: int b;
+ 4: int c;
+ 5: @{
+ 6: return a + b + c;
+ 7: @}
+
+@end group
+@end example
+
+Here, line 2 is the first line in an argument declaration list and so is
+given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
+(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}
+syntax.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Performance Issues, Frequently Asked Questions, Syntactic Symbols, Top
+@comment node-name, next, previous,up
+
+@chapter Performance Issues
+@cindex Performance Issues
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+C and its derivative languages are highly complex creatures. Often,
+ambiguous code situations arise that require @ccmode{} to scan
+large portions of the buffer to determine syntactic context. Such
+pathological code@footnote{such as the output of @code{lex(1)}!}
+can cause @ccmode{} to perform fairly badly.
+This section identifies some of the coding styles to watch out for, and
+suggests some workarounds that you can use to improve performance.
+
+Because @ccmode{} has to scan the buffer backwards from the current
+insertion point, and because C's syntax is fairly difficult to parse in
+the backwards direction, @ccmode{} often tries to find the nearest
+position higher up in the buffer from which to begin a forward scan.
+The farther this position is from the current insertion point, the
+slower the mode gets. Some coding styles can even force @ccmode{}
+to scan from the beginning of the buffer for every line of code!
+
+@findex beginning-of-defun
+@findex defun-prompt-regexp
+One of the simplest things you can do to reduce scan time, is make sure
+any brace that opens a top-level construct@footnote{e.g. a function in
+C, or outermost class definition in C++ or Java.} always appears in the
+leftmost column. This is actually an Emacs constraint, as embodied in
+the @code{beginning-of-defun} function which @ccmode{} uses
+heavily. If you insist on hanging top-level open braces on the right
+side of the line, then you might want to set the variable
+@code{defun-prompt-regexp} to something reasonable @footnote{Note that
+this variable is only defined in Emacs 19.}, however that ``something
+reasonable'' is difficult to define, so @ccmode{} doesn't do it
+for you.
+
+@vindex c-Java-defun-prompt-regexp
+@vindex Java-defun-prompt-regexp (c-)
+A special note about @code{defun-prompt-regexp} in Java mode: while much
+of the early sample Java code seems to encourage a style where the brace
+that opens a class is hung on the right side of the line, this is not a
+good style to pursue in Emacs. @ccmode{} comes with a variable
+@code{c-Java-defun-prompt-regexp} which tries to define a regular
+expression usable for this style, but there are problems with it. In
+some cases it can cause @code{beginning-of-defun} to hang@footnote{This
+has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason,
+it is not used by default, but if you feel adventurous, you can set
+@code{defun-prompt-regexp} to it in your mode hook. In any event,
+setting and rely on @code{defun-prompt-regexp} will definitely slow
+things down!
+
+You will probably notice pathological behavior from @ccmode{} when
+working in files containing large amounts of C preprocessor macros.
+This is because Emacs cannot skip backwards over these lines as quickly
+as it can comment.
+
+@vindex c-recognize-knr-p
+@vindex recognize-knr-p (c-)
+Previous versions of @ccmode{} had potential performance problems
+when recognizing K&R style function argument declarations. This was
+because there are ambiguities in the C syntax when K&R style argument
+lists are used@footnote{It is hard to distinguish them from top-level
+declarations.}. @ccmode{} has adopted BOCM's convention for
+limiting the search: it assumes that argdecls are indented at least one
+space, and that the function headers are not indented at all. With
+current versions of @ccmode{}, user customization of
+@code{c-recognize-knr-p} is deprecated. Just don't put argdecls in
+column zero!
+
+@cindex @file{cc-lobotomy.el} file
+@vindex cc-lobotomy-pith-list
+You might want to investigate the speed-ups contained in the
+file @file{cc-lobotomy.el}, which comes as part of the @ccmode{}
+distribution, but is completely unsupported.
+As mentioned previous, @ccmode{} always trades speed for accuracy,
+however it is recognized that sometimes you need speed and can sacrifice
+some accuracy in indentation. The file @file{cc-lobotomy.el} contains
+hacks that will ``dumb down'' @ccmode{} in some specific ways, making
+that trade-off of accurancy for speed. I won't go into details of its
+use here; you should read the comments at the top of the file, and look
+at the variable @code{cc-lobotomy-pith-list} for details.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Frequently Asked Questions, Getting the latest CC Mode release, Performance Issues, Top
+@comment node-name, next, previous,up
+
+@chapter Frequently Asked Questions
+@cindex Frequently Asked Questions
+@comment FAQ
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@kindex C-x h
+@kindex ESC C-\
+@kindex ESC C-x
+@kindex C-c C-q
+@kindex ESC C-q
+@kindex ESC C-u
+@kindex RET
+@kindex C-j
+@findex newline-and-indent
+@quotation
+
+@strong{Q.} @emph{How do I re-indent the whole file?}
+
+@strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole
+buffer. Then hit @kbd{ESC C-\}.
+@sp 1
+
+@strong{Q.} @emph{How do I re-indent the entire function?
+@kbd{ESC C-x} doesn't work.}
+
+@strong{A.} @kbd{ESC C-x} is reserved for future Emacs use.
+To re-indent the entire function hit @kbd{C-c C-q}.
+@sp 1
+
+@strong{Q.} @emph{How do I re-indent the current block?}
+
+@strong{A.} First move to the brace which opens the block with
+@kbd{ESC C-u}, then re-indent that expression with
+@kbd{ESC C-q}.
+@sp 1
+
+@strong{Q.} @emph{Why doesn't the @kbd{RET} key indent the line to
+where the new text should go after inserting the newline?}
+
+@strong{A.} Emacs' convention is that @kbd{RET} just adds a newline,
+and that @kbd{C-j} adds a newline and indents it. You can make
+@kbd{RET} do this too by adding this to your
+@code{c-mode-common-hook} (see the sample @file{.emacs} file
+@ref{Sample .emacs File}):
+@example
+
+(define-key c-mode-base-map "\C-m" 'newline-and-indent)
+
+@end example
+
+This is a very common question. If you want this to be the default
+behavior, don't lobby me, lobby RMS! @code{:-)}
+@sp 1
+
+@strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)}
+in my @file{.emacs} file but I get an error saying that
+@code{c-set-offset}'s function definition is void.}
+
+@strong{A.} This means that @ccmode{} wasn't loaded into your
+Emacs session by the time the @code{c-set-offset} call was reached,
+mostly likely because @ccmode{} is being autoloaded. Instead
+of putting the @code{c-set-offset} line in your top-level
+@file{.emacs} file, put it in your @code{c-mode-common-hook}, or
+simply add the following to the top of your @file{.emacs} file:
+@example
+
+(require 'cc-mode)
+
+@end example
+
+See the sample @file{.emacs} file @ref{Sample .emacs File} for
+details.
+
+@sp 1
+@strong{Q.} @emph{How do I make strings, comments, keywords, and other
+constructs appear in different colors, or in bold face, etc.?}
+
+@strong{A.} ``Syntax Colorization'' is a standard Emacs feature,
+controlled by @code{font-lock-mode}. It is not part of @ccmode{}.
+
+@sp 1
+@strong{Q.} @emph{@kbd{M-a} and @kbd{M-e} used to move over entire
+balanced brace lists, but now they move into blocks. How do I get the
+old behavior back?}
+
+@strong{A.} Use @kbd{C-M-f} and @kbd{C-M-b} to move over balanced brace
+blocks. Use @kbd{M-a} and @kbd{M-e} to move by statements, which will
+move into blocks.
+
+@end quotation
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Getting the latest CC Mode release, Sample .emacs File, Frequently Asked Questions, Top
+@comment node-name, next, previous,up
+
+@chapter Getting the latest CC Mode release
+@cindex Getting the latest CC Mode release
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ccmode{} is now standard with the latest versions of Emacs 19 and
+XEmacs 19. It is also the standard for Emacs 20 and XEmacs 20. You
+would typically just use the version that comes with your X/Emacs.
+These may be slightly out of date due to release schedule skew, so you
+should always check the canonical site for the latest version.
+
+@example
+@group
+
+ World Wide Web:
+
+ @code{http://www.python.org/ftp/emacs/}
+
+ Anonymous FTP:
+
+ @code{ftp://ftp.python.org/pub/emacs/}
+
+@end group
+@end example
+
+There are many files under these directories; you can pick up the entire
+distribution (named @code{cc-mode.tar.gz}; a gzip'd tar file), or any of
+the individual files, including PostScript documentation.
+
+If you do not have World Wide Web, or anonymous ftp access, you can get
+the distribution through an anonymous ftp-to-mail gateway, such as the
+one run by DEC at:
+@example
+
+@code{ftpmail@@decwrl.dec.com}
+
+@end example
+To get @ccmode{} via email, send the following message in the body of
+your mail to that address:
+@example
+
+reply <a valid net address back to you>
+connect ftp.python.org
+binary
+uuencode
+chdir pub/emacs
+get cc-mode.tar.gz
+
+@end example
+@noindent
+or just send the message "help" for more information on ftpmail.
+Response times will vary with the number of requests in the queue. I am
+in no way connected to this service, so I make no claims or guarantees
+about its availability!
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Sample .emacs File, Limitations and Known Bugs, Getting the latest CC Mode release, Top
+@comment node-name, next, previous,up
+
+@chapter Sample .emacs file
+@cindex Sample .emacs file
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@example
+;; Here's a sample .emacs file that might help you along the way. Just
+;; copy this region and paste it into your .emacs file. You may want to
+;; change some of the actual values.
+
+(defconst my-c-style
+ '((c-tab-always-indent . t)
+ (c-comment-only-line-offset . 4)
+ (c-hanging-braces-alist . ((substatement-open after)
+ (brace-list-open)))
+ (c-hanging-colons-alist . ((member-init-intro before)
+ (inher-intro)
+ (case-label after)
+ (label after)
+ (access-label after)))
+ (c-cleanup-list . (scope-operator
+ empty-defun-braces
+ defun-close-semi))
+ (c-offsets-alist . ((arglist-close . c-lineup-arglist)
+ (substatement-open . 0)
+ (case-label . 4)
+ (block-open . 0)
+ (knr-argdecl-intro . -)))
+ (c-echo-syntactic-information-p . t)
+ )
+ "My C Programming Style")
+
+;; Customizations for all of c-mode, c++-mode, and objc-mode
+(defun my-c-mode-common-hook ()
+ ;; add my personal style and set it for the current buffer
+ (c-add-style "PERSONAL" my-c-style t)
+ ;; offset customizations not in my-c-style
+ (c-set-offset 'member-init-intro '++)
+ ;; other customizations
+ (setq tab-width 8
+ ;; this will make sure spaces are used instead of tabs
+ indent-tabs-mode nil)
+ ;; we like auto-newline and hungry-delete
+ (c-toggle-auto-hungry-state 1)
+ ;; keybindings for all supported languages. We can put these in
+ ;; c-mode-base-map because c-mode-map, c++-mode-map, objc-mode-map,
+ ;; java-mode-map, and idl-mode-map inherit from it.
+ (define-key c-mode-base-map "\C-m" 'newline-and-indent)
+ )
+
+(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+@end example
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Sample .emacs File, Top
+@comment node-name, next, previous,up
+@chapter Limitations and Known Bugs
+@cindex Limitations and Known Bugs
+@comment * Limitations and Known Bugs
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@itemize @bullet
+@item
+Re-indenting large regions or expressions can be slow.
+
+@item
+Add-on fill packages may not work as well as @ccmode{}'s built-in
+filling routines. I no longer recommend you use @code{filladapt} to
+fill comments.
+
+@cindex c-indent-exp
+@cindex indent-exp (c-)
+@item
+@code{c-indent-exp} has not been fully optimized. It essentially
+equivalent to hitting @kbd{TAB} (@code{c-indent-command}) on every
+line. Some information is cached from line to line, but such caching
+invariable causes inaccuracies in analysis in some bizarre situations.
+
+@end itemize
+
+@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Mailing Lists and Submitting Bug Reports, Concept Index, Limitations and Known Bugs, Top
+@comment node-name, next, previous,up
+@chapter Mailing Lists and Submitting Bug Reports
+@cindex Mailing Lists and Submitting Bug Reports
+@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@kindex C-c C-b
+@findex c-submit-bug-report
+@findex submit-bug-report (c-)
+@cindex beta testers mailing list
+@cindex announcement mailing list
+To report bugs, use the @kbd{C-c C-b} (@code{c-submit-bug-report})
+command. This provides vital information I need to reproduce your
+problem. Make sure you include a concise, but complete code example.
+Please try to boil your example down to just the essential code needed
+to reproduce the problem, and include an exact recipe of steps needed to
+expose the bug. Be especially sure to include any code that appears
+@emph{before} your bug example, if you think it might affect my ability
+to reproduce it.
+
+Bug reports are now sent to the following email addresses:
+@code{cc-mode-help@@python.org} and
+@code{bug-gnu-emacs@@gnu.org}; the latter is mirrored on the
+Usenet newsgroup @code{gnu.emacs.bug}. You can send other questions and
+suggestions (kudos? @code{;-)} to @code{cc-mode-help@@python.org}, or
+@code{help-gnu-emacs@@gnu.org} which is mirrored on newsgroup
+@code{gnu.emacs.help}.
+
+If you want to get announcements of new CC Mode releases, send the
+word @emph{subscribe} in the body of a message to
+@code{cc-mode-announce-request@@python.org}. Announcements will also be
+posted to the Usenet newsgroup @code{gnu.emacs.sources}. Note that the
+@code{cc-mode-victims@@python.org} mailing list was recently
+decommissioned.
+
+@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Concept Index, Command Index, Mailing Lists and Submitting Bug Reports, Top
+@comment node-name, next, previous, up
+@unnumbered Concept Index
+@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@printindex cp
+
+
+@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Command Index, Key Index, Concept Index, Top
+@comment node-name, next, previous, up
+@unnumbered Command Index
+@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ifinfo
+
+@end ifinfo
+Since all @ccmode{} commands are prepended with the string
+@samp{c-}, each appears under its @code{c-@var{<thing>}} name and its
+@code{@var{<thing>} (c-)} name.
+@iftex
+@sp 2
+@end iftex
+@printindex fn
+
+
+@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Key Index, Variable Index, Command Index, Top
+@comment node-name, next, previous, up
+@unnumbered Key Index
+@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@printindex ky
+
+
+@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Variable Index, , Key Index, Top
+@comment node-name, next, previous, up
+@unnumbered Variable Index
+@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ifinfo
+
+@end ifinfo
+Since all @ccmode{} variables are prepended with the string
+@samp{c-}, each appears under its @code{c-@var{<thing>}} name and its
+@code{@var{<thing>} (c-)} name.
+@iftex
+@sp 2
+@end iftex
+@printindex vr
+@page
+@summarycontents
+@contents
+@bye
+
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@setfilename ../info/cl
+@settitle Common Lisp Extensions
+
+@dircategory Editors
+@direntry
+* CL: (cl). Partial Common Lisp support for Emacs Lisp.
+@end direntry
+
+@iftex
+@finalout
+@end iftex
+
+@ifinfo
+This file documents the GNU Emacs Common Lisp emulation package.
+
+Copyright (C) 1993 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included exactly as
+in the original, and provided that the entire resulting derived work is
+distributed under the terms of a permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the section entitled ``GNU General Public License'' may be
+included in a translation approved by the author instead of in the
+original English.
+@end ifinfo
+
+@titlepage
+@sp 6
+@center @titlefont{Common Lisp Extensions}
+@sp 4
+@center For GNU Emacs Lisp
+@sp 1
+@center Version 2.02
+@sp 5
+@center Dave Gillespie
+@center daveg@@synaptics.com
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1993 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included exactly as
+in the original, and provided that the entire resulting derived work is
+distributed under the terms of a permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the section entitled ``GNU General Public License'' may be
+included in a translation approved by the author instead of in the
+original English.
+@end titlepage
+
+@node Top, Overview,, (dir)
+@chapter Common Lisp Extensions
+
+@noindent
+This document describes a set of Emacs Lisp facilities borrowed from
+Common Lisp. All the facilities are described here in detail. While
+this document does not assume any prior knowledge of Common Lisp, it
+does assume a basic familiarity with Emacs Lisp.
+
+@menu
+* Overview:: Installation, usage, etc.
+* Program Structure:: Arglists, `eval-when', `defalias'
+* Predicates:: `typep', `eql', and `equalp'
+* Control Structure:: `setf', `do', `loop', etc.
+* Macros:: Destructuring, `define-compiler-macro'
+* Declarations:: `proclaim', `declare', etc.
+* Symbols:: Property lists, `gensym'
+* Numbers:: Predicates, functions, random numbers
+* Sequences:: Mapping, functions, searching, sorting
+* Lists:: `cadr', `sublis', `member*', `assoc*', etc.
+* Hash Tables:: `make-hash-table', `gethash', etc.
+* Structures:: `defstruct'
+* Assertions:: `check-type', `assert', `ignore-errors'.
+
+* Efficiency Concerns:: Hints and techniques
+* Common Lisp Compatibility:: All known differences with Steele
+* Old CL Compatibility:: All known differences with old cl.el
+* Porting Common Lisp:: Hints for porting Common Lisp code
+
+* Function Index::
+* Variable Index::
+@end menu
+
+@node Overview, Program Structure, Top, Top
+@ifinfo
+@chapter Overview
+@end ifinfo
+@iftex
+@section Overview
+@end iftex
+
+@noindent
+Common Lisp is a huge language, and Common Lisp systems tend to be
+massive and extremely complex. Emacs Lisp, by contrast, is rather
+minimalist in the choice of Lisp features it offers the programmer.
+As Emacs Lisp programmers have grown in number, and the applications
+they write have grown more ambitious, it has become clear that Emacs
+Lisp could benefit from many of the conveniences of Common Lisp.
+
+The @dfn{CL} package adds a number of Common Lisp functions and
+control structures to Emacs Lisp. While not a 100% complete
+implementation of Common Lisp, @dfn{CL} adds enough functionality
+to make Emacs Lisp programming significantly more convenient.
+
+Some Common Lisp features have been omitted from this package
+for various reasons:
+
+@itemize @bullet
+@item
+Some features are too complex or bulky relative to their benefit
+to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
+examples of this group.
+
+@item
+Other features cannot be implemented without modification to the
+Emacs Lisp interpreter itself, such as multiple return values,
+lexical scoping, case-insensitive symbols, and complex numbers.
+The @dfn{CL} package generally makes no attempt to emulate these
+features.
+
+@item
+Some features conflict with existing things in Emacs Lisp. For
+example, Emacs' @code{assoc} function is incompatible with the
+Common Lisp @code{assoc}. In such cases, this package usually
+adds the suffix @samp{*} to the function name of the Common
+Lisp version of the function (e.g., @code{assoc*}).
+@end itemize
+
+The package described here was written by Dave Gillespie,
+@file{daveg@@synaptics.com}. It is a total rewrite of the original
+1986 @file{cl.el} package by Cesar Quiroz. Most features of the
+the Quiroz package have been retained; any incompatibilities are
+noted in the descriptions below. Care has been taken in this
+version to ensure that each function is defined efficiently,
+concisely, and with minimal impact on the rest of the Emacs
+environment.
+
+@menu
+* Usage:: How to use the CL package
+* Organization:: The package's five component files
+* Installation:: Compiling and installing CL
+* Naming Conventions:: Notes on CL function names
+@end menu
+
+@node Usage, Organization, Overview, Overview
+@section Usage
+
+@noindent
+Lisp code that uses features from the @dfn{CL} package should
+include at the beginning:
+
+@example
+(require 'cl)
+@end example
+
+@noindent
+If you want to ensure that the new (Gillespie) version of @dfn{CL}
+is the one that is present, add an additional @code{(require 'cl-19)}
+call:
+
+@example
+(require 'cl)
+(require 'cl-19)
+@end example
+
+@noindent
+The second call will fail (with ``@file{cl-19.el} not found'') if
+the old @file{cl.el} package was in use.
+
+It is safe to arrange to load @dfn{CL} at all times, e.g.,
+in your @file{.emacs} file. But it's a good idea, for portability,
+to @code{(require 'cl)} in your code even if you do this.
+
+@node Organization, Installation, Usage, Overview
+@section Organization
+
+@noindent
+The Common Lisp package is organized into four files:
+
+@table @file
+@item cl.el
+This is the ``main'' file, which contains basic functions
+and information about the package. This file is relatively
+compact---about 700 lines.
+
+@item cl-extra.el
+This file contains the larger, more complex or unusual functions.
+It is kept separate so that packages which only want to use Common
+Lisp fundamentals like the @code{cadr} function won't need to pay
+the overhead of loading the more advanced functions.
+
+@item cl-seq.el
+This file contains most of the advanced functions for operating
+on sequences or lists, such as @code{delete-if} and @code{assoc*}.
+
+@item cl-macs.el
+This file contains the features of the packages which are macros
+instead of functions. Macros expand when the caller is compiled,
+not when it is run, so the macros generally only need to be
+present when the byte-compiler is running (or when the macros are
+used in uncompiled code such as a @file{.emacs} file). Most of
+the macros of this package are isolated in @file{cl-macs.el} so
+that they won't take up memory unless you are compiling.
+@end table
+
+The file @file{cl.el} includes all necessary @code{autoload}
+commands for the functions and macros in the other three files.
+All you have to do is @code{(require 'cl)}, and @file{cl.el}
+will take care of pulling in the other files when they are
+needed.
+
+There is another file, @file{cl-compat.el}, which defines some
+routines from the older @file{cl.el} package that are no longer
+present in the new package. This includes internal routines
+like @code{setelt} and @code{zip-lists}, deprecated features
+like @code{defkeyword}, and an emulation of the old-style
+multiple-values feature. @xref{Old CL Compatibility}.
+
+@node Installation, Naming Conventions, Organization, Overview
+@section Installation
+
+@noindent
+Installation of the @dfn{CL} package is simple: Just put the
+byte-compiled files @file{cl.elc}, @file{cl-extra.elc},
+@file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc}
+into a directory on your @code{load-path}.
+
+There are no special requirements to compile this package:
+The files do not have to be loaded before they are compiled,
+nor do they need to be compiled in any particular order.
+
+You may choose to put the files into your main @file{lisp/}
+directory, replacing the original @file{cl.el} file there. Or,
+you could put them into a directory that comes before @file{lisp/}
+on your @code{load-path} so that the old @file{cl.el} is
+effectively hidden.
+
+Also, format the @file{cl.texinfo} file and put the resulting
+Info files in the @file{info/} directory or another suitable place.
+
+You may instead wish to leave this package's components all in
+their own directory, and then add this directory to your
+@code{load-path} and (Emacs 19 only) @code{Info-directory-list}.
+Add the directory to the front of the list so the old @dfn{CL}
+package and its documentation are hidden.
+
+@node Naming Conventions, , Installation, Overview
+@section Naming Conventions
+
+@noindent
+Except where noted, all functions defined by this package have the
+same names and calling conventions as their Common Lisp counterparts.
+
+Following is a complete list of functions whose names were changed
+from Common Lisp, usually to avoid conflicts with Emacs. In each
+case, a @samp{*} has been appended to the Common Lisp name to obtain
+the Emacs name:
+
+@example
+defun* defsubst* defmacro* function*
+member* assoc* rassoc* get*
+remove* delete* mapcar* sort*
+floor* ceiling* truncate* round*
+mod* rem* random* last*
+@end example
+
+Internal function and variable names in the package are prefixed
+by @code{cl-}. Here is a complete list of functions @emph{not}
+prefixed by @code{cl-} which were not taken from Common Lisp:
+
+@example
+member delete remove remq
+rassoc floatp-safe lexical-let lexical-let*
+callf callf2 letf letf*
+defsubst* defalias add-hook eval-when-compile
+@end example
+
+@noindent
+(Most of these are Emacs 19 features provided to Emacs 18 users,
+or introduced, like @code{remq}, for reasons of symmetry
+with similar features.)
+
+The following simple functions and macros are defined in @file{cl.el};
+they do not cause other components like @file{cl-extra} to be loaded.
+
+@example
+eql floatp-safe abs endp
+evenp oddp plusp minusp
+butlast nbutlast caar .. cddddr
+list* ldiff rest first .. tenth
+member [1] copy-list subst mapcar* [2]
+adjoin [3] acons pairlis pop [4]
+push [4] pushnew [3,4] incf [4] decf [4]
+proclaim declaim
+@end example
+
+@noindent
+[1] This is the Emacs 19-compatible function, not @code{member*}.
+
+@noindent
+[2] Only for one sequence argument or two list arguments.
+
+@noindent
+[3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
+and @code{:key} is not used.
+
+@noindent
+[4] Only when @var{place} is a plain variable name.
+
+@iftex
+@chapno=4
+@end iftex
+
+@node Program Structure, Predicates, Overview, Top
+@chapter Program Structure
+
+@noindent
+This section describes features of the @dfn{CL} package which have to
+do with programs as a whole: advanced argument lists for functions,
+and the @code{eval-when} construct.
+
+@menu
+* Argument Lists:: `&key', `&aux', `defun*', `defmacro*'.
+* Time of Evaluation:: The `eval-when' construct.
+* Function Aliases:: The `defalias' function.
+@end menu
+
+@iftex
+@secno=1
+@end iftex
+
+@node Argument Lists, Time of Evaluation, Program Structure, Program Structure
+@section Argument Lists
+
+@noindent
+Emacs Lisp's notation for argument lists of functions is a subset of
+the Common Lisp notation. As well as the familiar @code{&optional}
+and @code{&rest} markers, Common Lisp allows you to specify default
+values for optional arguments, and it provides the additional markers
+@code{&key} and @code{&aux}.
+
+Since argument parsing is built-in to Emacs, there is no way for
+this package to implement Common Lisp argument lists seamlessly.
+Instead, this package defines alternates for several Lisp forms
+which you must use if you need Common Lisp argument lists.
+
+@defspec defun* name arglist body...
+This form is identical to the regular @code{defun} form, except
+that @var{arglist} is allowed to be a full Common Lisp argument
+list. Also, the function body is enclosed in an implicit block
+called @var{name}; @pxref{Blocks and Exits}.
+@end defspec
+
+@defspec defsubst* name arglist body...
+This is just like @code{defun*}, except that the function that
+is defined is automatically proclaimed @code{inline}, i.e.,
+calls to it may be expanded into in-line code by the byte compiler.
+This is analogous to the @code{defsubst} form in Emacs 19;
+@code{defsubst*} uses a different method (compiler macros) which
+works in all version of Emacs, and also generates somewhat more
+efficient inline expansions. In particular, @code{defsubst*}
+arranges for the processing of keyword arguments, default values,
+etc., to be done at compile-time whenever possible.
+@end defspec
+
+@defspec defmacro* name arglist body...
+This is identical to the regular @code{defmacro} form,
+except that @var{arglist} is allowed to be a full Common Lisp
+argument list. The @code{&environment} keyword is supported as
+described in Steele. The @code{&whole} keyword is supported only
+within destructured lists (see below); top-level @code{&whole}
+cannot be implemented with the current Emacs Lisp interpreter.
+The macro expander body is enclosed in an implicit block called
+@var{name}.
+@end defspec
+
+@defspec function* symbol-or-lambda
+This is identical to the regular @code{function} form,
+except that if the argument is a @code{lambda} form then that
+form may use a full Common Lisp argument list.
+@end defspec
+
+Also, all forms (such as @code{defsetf} and @code{flet}) defined
+in this package that include @var{arglist}s in their syntax allow
+full Common Lisp argument lists.
+
+Note that it is @emph{not} necessary to use @code{defun*} in
+order to have access to most @dfn{CL} features in your function.
+These features are always present; @code{defun*}'s only
+difference from @code{defun} is its more flexible argument
+lists and its implicit block.
+
+The full form of a Common Lisp argument list is
+
+@example
+(@var{var}...
+ &optional (@var{var} @var{initform} @var{svar})...
+ &rest @var{var}
+ &key ((@var{keyword} @var{var}) @var{initform} @var{svar})...
+ &aux (@var{var} @var{initform})...)
+@end example
+
+Each of the five argument list sections is optional. The @var{svar},
+@var{initform}, and @var{keyword} parts are optional; if they are
+omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
+
+The first section consists of zero or more @dfn{required} arguments.
+These arguments must always be specified in a call to the function;
+there is no difference between Emacs Lisp and Common Lisp as far as
+required arguments are concerned.
+
+The second section consists of @dfn{optional} arguments. These
+arguments may be specified in the function call; if they are not,
+@var{initform} specifies the default value used for the argument.
+(No @var{initform} means to use @code{nil} as the default.) The
+@var{initform} is evaluated with the bindings for the preceding
+arguments already established; @code{(a &optional (b (1+ a)))}
+matches one or two arguments, with the second argument defaulting
+to one plus the first argument. If the @var{svar} is specified,
+it is an auxiliary variable which is bound to @code{t} if the optional
+argument was specified, or to @code{nil} if the argument was omitted.
+If you don't use an @var{svar}, then there will be no way for your
+function to tell whether it was called with no argument, or with
+the default value passed explicitly as an argument.
+
+The third section consists of a single @dfn{rest} argument. If
+more arguments were passed to the function than are accounted for
+by the required and optional arguments, those extra arguments are
+collected into a list and bound to the ``rest'' argument variable.
+Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
+Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
+macro contexts; this package accepts it all the time.
+
+The fourth section consists of @dfn{keyword} arguments. These
+are optional arguments which are specified by name rather than
+positionally in the argument list. For example,
+
+@example
+(defun* foo (a &optional b &key c d (e 17)))
+@end example
+
+@noindent
+defines a function which may be called with one, two, or more
+arguments. The first two arguments are bound to @code{a} and
+@code{b} in the usual way. The remaining arguments must be
+pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
+by the value to be bound to the corresponding argument variable.
+(Symbols whose names begin with a colon are called @dfn{keywords},
+and they are self-quoting in the same way as @code{nil} and
+@code{t}.)
+
+For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
+arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
+appears more than once in the function call, the first occurrence
+takes precedence over the later ones. Note that it is not possible
+to specify keyword arguments without specifying the optional
+argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
+@code{b} to the keyword @code{:c}, then signal an error because
+@code{2} is not a valid keyword.
+
+If a @var{keyword} symbol is explicitly specified in the argument
+list as shown in the above diagram, then that keyword will be
+used instead of just the variable name prefixed with a colon.
+You can specify a @var{keyword} symbol which does not begin with
+a colon at all, but such symbols will not be self-quoting; you
+will have to quote them explicitly with an apostrophe in the
+function call.
+
+Ordinarily it is an error to pass an unrecognized keyword to
+a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
+Lisp to ignore unrecognized keywords, either by adding the
+marker @code{&allow-other-keys} after the keyword section
+of the argument list, or by specifying an @code{:allow-other-keys}
+argument in the call whose value is non-@code{nil}. If the
+function uses both @code{&rest} and @code{&key} at the same time,
+the ``rest'' argument is bound to the keyword list as it appears
+in the call. For example:
+
+@smallexample
+(defun* find-thing (thing &rest rest &key need &allow-other-keys)
+ (or (apply 'member* thing thing-list :allow-other-keys t rest)
+ (if need (error "Thing not found"))))
+@end smallexample
+
+@noindent
+This function takes a @code{:need} keyword argument, but also
+accepts other keyword arguments which are passed on to the
+@code{member*} function. @code{allow-other-keys} is used to
+keep both @code{find-thing} and @code{member*} from complaining
+about each others' keywords in the arguments.
+
+As a (significant) performance optimization, this package
+implements the scan for keyword arguments by calling @code{memq}
+to search for keywords in a ``rest'' argument. Technically
+speaking, this is incorrect, since @code{memq} looks at the
+odd-numbered values as well as the even-numbered keywords.
+The net effect is that if you happen to pass a keyword symbol
+as the @emph{value} of another keyword argument, where that
+keyword symbol happens to equal the name of a valid keyword
+argument of the same function, then the keyword parser will
+become confused. This minor bug can only affect you if you
+use keyword symbols as general-purpose data in your program;
+this practice is strongly discouraged in Emacs Lisp.
+
+The fifth section of the argument list consists of @dfn{auxiliary
+variables}. These are not really arguments at all, but simply
+variables which are bound to @code{nil} or to the specified
+@var{initforms} during execution of the function. There is no
+difference between the following two functions, except for a
+matter of stylistic taste:
+
+@example
+(defun* foo (a b &aux (c (+ a b)) d)
+ @var{body})
+
+(defun* foo (a b)
+ (let ((c (+ a b)) d)
+ @var{body}))
+@end example
+
+Argument lists support @dfn{destructuring}. In Common Lisp,
+destructuring is only allowed with @code{defmacro}; this package
+allows it with @code{defun*} and other argument lists as well.
+In destructuring, any argument variable (@var{var} in the above
+diagram) can be replaced by a list of variables, or more generally,
+a recursive argument list. The corresponding argument value must
+be a list whose elements match this recursive argument list.
+For example:
+
+@example
+(defmacro* dolist ((var listform &optional resultform)
+ &rest body)
+ ...)
+@end example
+
+This says that the first argument of @code{dolist} must be a list
+of two or three items; if there are other arguments as well as this
+list, they are stored in @code{body}. All features allowed in
+regular argument lists are allowed in these recursive argument lists.
+In addition, the clause @samp{&whole @var{var}} is allowed at the
+front of a recursive argument list. It binds @var{var} to the
+whole list being matched; thus @code{(&whole all a b)} matches
+a list of two things, with @code{a} bound to the first thing,
+@code{b} bound to the second thing, and @code{all} bound to the
+list itself. (Common Lisp allows @code{&whole} in top-level
+@code{defmacro} argument lists as well, but Emacs Lisp does not
+support this usage.)
+
+One last feature of destructuring is that the argument list may be
+dotted, so that the argument list @code{(a b . c)} is functionally
+equivalent to @code{(a b &rest c)}.
+
+If the optimization quality @code{safety} is set to 0
+(@pxref{Declarations}), error checking for wrong number of
+arguments and invalid keyword arguments is disabled. By default,
+argument lists are rigorously checked.
+
+@node Time of Evaluation, Function Aliases, Argument Lists, Program Structure
+@section Time of Evaluation
+
+@noindent
+Normally, the byte-compiler does not actually execute the forms in
+a file it compiles. For example, if a file contains @code{(setq foo t)},
+the act of compiling it will not actually set @code{foo} to @code{t}.
+This is true even if the @code{setq} was a top-level form (i.e., not
+enclosed in a @code{defun} or other form). Sometimes, though, you
+would like to have certain top-level forms evaluated at compile-time.
+For example, the compiler effectively evaluates @code{defmacro} forms
+at compile-time so that later parts of the file can refer to the
+macros that are defined.
+
+@defspec eval-when (situations...) forms...
+This form controls when the body @var{forms} are evaluated.
+The @var{situations} list may contain any set of the symbols
+@code{compile}, @code{load}, and @code{eval} (or their long-winded
+ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
+and @code{:execute}).
+
+The @code{eval-when} form is handled differently depending on
+whether or not it is being compiled as a top-level form.
+Specifically, it gets special treatment if it is being compiled
+by a command such as @code{byte-compile-file} which compiles files
+or buffers of code, and it appears either literally at the
+top level of the file or inside a top-level @code{progn}.
+
+For compiled top-level @code{eval-when}s, the body @var{forms} are
+executed at compile-time if @code{compile} is in the @var{situations}
+list, and the @var{forms} are written out to the file (to be executed
+at load-time) if @code{load} is in the @var{situations} list.
+
+For non-compiled-top-level forms, only the @code{eval} situation is
+relevant. (This includes forms executed by the interpreter, forms
+compiled with @code{byte-compile} rather than @code{byte-compile-file},
+and non-top-level forms.) The @code{eval-when} acts like a
+@code{progn} if @code{eval} is specified, and like @code{nil}
+(ignoring the body @var{forms}) if not.
+
+The rules become more subtle when @code{eval-when}s are nested;
+consult Steele (second edition) for the gruesome details (and
+some gruesome examples).
+
+Some simple examples:
+
+@example
+;; Top-level forms in foo.el:
+(eval-when (compile) (setq foo1 'bar))
+(eval-when (load) (setq foo2 'bar))
+(eval-when (compile load) (setq foo3 'bar))
+(eval-when (eval) (setq foo4 'bar))
+(eval-when (eval compile) (setq foo5 'bar))
+(eval-when (eval load) (setq foo6 'bar))
+(eval-when (eval compile load) (setq foo7 'bar))
+@end example
+
+When @file{foo.el} is compiled, these variables will be set during
+the compilation itself:
+
+@example
+foo1 foo3 foo5 foo7 ; `compile'
+@end example
+
+When @file{foo.elc} is loaded, these variables will be set:
+
+@example
+foo2 foo3 foo6 foo7 ; `load'
+@end example
+
+And if @file{foo.el} is loaded uncompiled, these variables will
+be set:
+
+@example
+foo4 foo5 foo6 foo7 ; `eval'
+@end example
+
+If these seven @code{eval-when}s had been, say, inside a @code{defun},
+then the first three would have been equivalent to @code{nil} and the
+last four would have been equivalent to the corresponding @code{setq}s.
+
+Note that @code{(eval-when (load eval) @dots{})} is equivalent
+to @code{(progn @dots{})} in all contexts. The compiler treats
+certain top-level forms, like @code{defmacro} (sort-of) and
+@code{require}, as if they were wrapped in @code{(eval-when
+(compile load eval) @dots{})}.
+@end defspec
+
+Emacs 19 includes two special forms related to @code{eval-when}.
+One of these, @code{eval-when-compile}, is not quite equivalent to
+any @code{eval-when} construct and is described below. This package
+defines a version of @code{eval-when-compile} for the benefit of
+Emacs 18 users.
+
+The other form, @code{(eval-and-compile @dots{})}, is exactly
+equivalent to @samp{(eval-when (compile load eval) @dots{})} and
+so is not itself defined by this package.
+
+@defspec eval-when-compile forms...
+The @var{forms} are evaluated at compile-time; at execution time,
+this form acts like a quoted constant of the resulting value. Used
+at top-level, @code{eval-when-compile} is just like @samp{eval-when
+(compile eval)}. In other contexts, @code{eval-when-compile}
+allows code to be evaluated once at compile-time for efficiency
+or other reasons.
+
+This form is similar to the @samp{#.} syntax of true Common Lisp.
+@end defspec
+
+@defspec load-time-value form
+The @var{form} is evaluated at load-time; at execution time,
+this form acts like a quoted constant of the resulting value.
+
+Early Common Lisp had a @samp{#,} syntax that was similar to
+this, but ANSI Common Lisp replaced it with @code{load-time-value}
+and gave it more well-defined semantics.
+
+In a compiled file, @code{load-time-value} arranges for @var{form}
+to be evaluated when the @file{.elc} file is loaded and then used
+as if it were a quoted constant. In code compiled by
+@code{byte-compile} rather than @code{byte-compile-file}, the
+effect is identical to @code{eval-when-compile}. In uncompiled
+code, both @code{eval-when-compile} and @code{load-time-value}
+act exactly like @code{progn}.
+
+@example
+(defun report ()
+ (insert "This function was executed on: "
+ (current-time-string)
+ ", compiled on: "
+ (eval-when-compile (current-time-string))
+ ;; or '#.(current-time-string) in real Common Lisp
+ ", and loaded on: "
+ (load-time-value (current-time-string))))
+@end example
+
+@noindent
+Byte-compiled, the above defun will result in the following code
+(or its compiled equivalent, of course) in the @file{.elc} file:
+
+@example
+(setq --temp-- (current-time-string))
+(defun report ()
+ (insert "This function was executed on: "
+ (current-time-string)
+ ", compiled on: "
+ '"Wed Jun 23 18:33:43 1993"
+ ", and loaded on: "
+ --temp--))
+@end example
+@end defspec
+
+@node Function Aliases, , Time of Evaluation, Program Structure
+@section Function Aliases
+
+@noindent
+This section describes a feature from GNU Emacs 19 which this
+package makes available in other versions of Emacs.
+
+@defun defalias symbol function
+This function sets @var{symbol}'s function cell to @var{function}.
+It is equivalent to @code{fset}, except that in GNU Emacs 19 it also
+records the setting in @code{load-history} so that it can be undone
+by a later @code{unload-feature}.
+
+In other versions of Emacs, @code{defalias} is a synonym for
+@code{fset}.
+@end defun
+
+@node Predicates, Control Structure, Program Structure, Top
+@chapter Predicates
+
+@noindent
+This section describes functions for testing whether various
+facts are true or false.
+
+@menu
+* Type Predicates:: `typep', `deftype', and `coerce'
+* Equality Predicates:: `eql' and `equalp'
+@end menu
+
+@node Type Predicates, Equality Predicates, Predicates, Predicates
+@section Type Predicates
+
+@noindent
+The @dfn{CL} package defines a version of the Common Lisp @code{typep}
+predicate.
+
+@defun typep object type
+Check if @var{object} is of type @var{type}, where @var{type} is a
+(quoted) type name of the sort used by Common Lisp. For example,
+@code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}.
+@end defun
+
+The @var{type} argument to the above function is either a symbol
+or a list beginning with a symbol.
+
+@itemize @bullet
+@item
+If the type name is a symbol, Emacs appends @samp{-p} to the
+symbol name to form the name of a predicate function for testing
+the type. (Built-in predicates whose names end in @samp{p} rather
+than @samp{-p} are used when appropriate.)
+
+@item
+The type symbol @code{t} stands for the union of all types.
+@code{(typep @var{object} t)} is always true. Likewise, the
+type symbol @code{nil} stands for nothing at all, and
+@code{(typep @var{object} nil)} is always false.
+
+@item
+The type symbol @code{null} represents the symbol @code{nil}.
+Thus @code{(typep @var{object} 'null)} is equivalent to
+@code{(null @var{object})}.
+
+@item
+The type symbol @code{real} is a synonym for @code{number}, and
+@code{fixnum} is a synonym for @code{integer}.
+
+@item
+The type symbols @code{character} and @code{string-char} match
+integers in the range from 0 to 255.
+
+@item
+The type symbol @code{float} uses the @code{floatp-safe} predicate
+defined by this package rather than @code{floatp}, so it will work
+correctly even in Emacs versions without floating-point support.
+
+@item
+The type list @code{(integer @var{low} @var{high})} represents all
+integers between @var{low} and @var{high}, inclusive. Either bound
+may be a list of a single integer to specify an exclusive limit,
+or a @code{*} to specify no limit. The type @code{(integer * *)}
+is thus equivalent to @code{integer}.
+
+@item
+Likewise, lists beginning with @code{float}, @code{real}, or
+@code{number} represent numbers of that type falling in a particular
+range.
+
+@item
+Lists beginning with @code{and}, @code{or}, and @code{not} form
+combinations of types. For example, @code{(or integer (float 0 *))}
+represents all objects that are integers or non-negative floats.
+
+@item
+Lists beginning with @code{member} or @code{member*} represent
+objects @code{eql} to any of the following values. For example,
+@code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
+and @code{(member nil)} is equivalent to @code{null}.
+
+@item
+Lists of the form @code{(satisfies @var{predicate})} represent
+all objects for which @var{predicate} returns true when called
+with that object as an argument.
+@end itemize
+
+The following function and macro (not technically predicates) are
+related to @code{typep}.
+
+@defun coerce object type
+This function attempts to convert @var{object} to the specified
+@var{type}. If @var{object} is already of that type as determined by
+@code{typep}, it is simply returned. Otherwise, certain types of
+conversions will be made: If @var{type} is any sequence type
+(@code{string}, @code{list}, etc.) then @var{object} will be
+converted to that type if possible. If @var{type} is
+@code{character}, then strings of length one and symbols with
+one-character names can be coerced. If @var{type} is @code{float},
+then integers can be coerced in versions of Emacs that support
+floats. In all other circumstances, @code{coerce} signals an
+error.
+@end defun
+
+@defspec deftype name arglist forms...
+This macro defines a new type called @var{name}. It is similar
+to @code{defmacro} in many ways; when @var{name} is encountered
+as a type name, the body @var{forms} are evaluated and should
+return a type specifier that is equivalent to the type. The
+@var{arglist} is a Common Lisp argument list of the sort accepted
+by @code{defmacro*}. The type specifier @samp{(@var{name} @var{args}...)}
+is expanded by calling the expander with those arguments; the type
+symbol @samp{@var{name}} is expanded by calling the expander with
+no arguments. The @var{arglist} is processed the same as for
+@code{defmacro*} except that optional arguments without explicit
+defaults use @code{*} instead of @code{nil} as the ``default''
+default. Some examples:
+
+@example
+(deftype null () '(satisfies null)) ; predefined
+(deftype list () '(or null cons)) ; predefined
+(deftype unsigned-byte (&optional bits)
+ (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
+(unsigned-byte 8) @equiv{} (integer 0 255)
+(unsigned-byte) @equiv{} (integer 0 *)
+unsigned-byte @equiv{} (integer 0 *)
+@end example
+
+@noindent
+The last example shows how the Common Lisp @code{unsigned-byte}
+type specifier could be implemented if desired; this package does
+not implement @code{unsigned-byte} by default.
+@end defspec
+
+The @code{typecase} and @code{check-type} macros also use type
+names. @xref{Conditionals}. @xref{Assertions}. The @code{map},
+@code{concatenate}, and @code{merge} functions take type-name
+arguments to specify the type of sequence to return. @xref{Sequences}.
+
+@node Equality Predicates, , Type Predicates, Predicates
+@section Equality Predicates
+
+@noindent
+This package defines two Common Lisp predicates, @code{eql} and
+@code{equalp}.
+
+@defun eql a b
+This function is almost the same as @code{eq}, except that if @var{a}
+and @var{b} are numbers of the same type, it compares them for numeric
+equality (as if by @code{equal} instead of @code{eq}). This makes a
+difference only for versions of Emacs that are compiled with
+floating-point support, such as Emacs 19. Emacs floats are allocated
+objects just like cons cells, which means that @code{(eq 3.0 3.0)}
+will not necessarily be true---if the two @code{3.0}s were allocated
+separately, the pointers will be different even though the numbers are
+the same. But @code{(eql 3.0 3.0)} will always be true.
+
+The types of the arguments must match, so @code{(eql 3 3.0)} is
+still false.
+
+Note that Emacs integers are ``direct'' rather than allocated, which
+basically means @code{(eq 3 3)} will always be true. Thus @code{eq}
+and @code{eql} behave differently only if floating-point numbers are
+involved, and are indistinguishable on Emacs versions that don't
+support floats.
+
+There is a slight inconsistency with Common Lisp in the treatment of
+positive and negative zeros. Some machines, notably those with IEEE
+standard arithmetic, represent @code{+0} and @code{-0} as distinct
+values. Normally this doesn't matter because the standard specifies
+that @code{(= 0.0 -0.0)} should always be true, and this is indeed
+what Emacs Lisp and Common Lisp do. But the Common Lisp standard
+states that @code{(eql 0.0 -0.0)} and @code{(equal 0.0 -0.0)} should
+be false on IEEE-like machines; Emacs Lisp does not do this, and in
+fact the only known way to distinguish between the two zeros in Emacs
+Lisp is to @code{format} them and check for a minus sign.
+@end defun
+
+@defun equalp a b
+This function is a more flexible version of @code{equal}. In
+particular, it compares strings case-insensitively, and it compares
+numbers without regard to type (so that @code{(equalp 3 3.0)} is
+true). Vectors and conses are compared recursively. All other
+objects are compared as if by @code{equal}.
+
+This function differs from Common Lisp @code{equalp} in several
+respects. First, Common Lisp's @code{equalp} also compares
+@emph{characters} case-insensitively, which would be impractical
+in this package since Emacs does not distinguish between integers
+and characters. In keeping with the idea that strings are less
+vector-like in Emacs Lisp, this package's @code{equalp} also will
+not compare strings against vectors of integers. Finally, Common
+Lisp's @code{equalp} compares hash tables without regard to
+ordering, whereas this package simply compares hash tables in
+terms of their underlying structure (which means vectors for Lucid
+Emacs 19 hash tables, or lists for other hash tables).
+@end defun
+
+Also note that the Common Lisp functions @code{member} and @code{assoc}
+use @code{eql} to compare elements, whereas Emacs Lisp follows the
+MacLisp tradition and uses @code{equal} for these two functions.
+In Emacs, use @code{member*} and @code{assoc*} to get functions
+which use @code{eql} for comparisons.
+
+@node Control Structure, Macros, Predicates, Top
+@chapter Control Structure
+
+@noindent
+The features described in the following sections implement
+various advanced control structures, including the powerful
+@code{setf} facility and a number of looping and conditional
+constructs.
+
+@menu
+* Assignment:: The `psetq' form
+* Generalized Variables:: `setf', `incf', `push', etc.
+* Variable Bindings:: `progv', `lexical-let', `flet', `macrolet'
+* Conditionals:: `case', `typecase'
+* Blocks and Exits:: `block', `return', `return-from'
+* Iteration:: `do', `dotimes', `dolist', `do-symbols'
+* Loop Facility:: The Common Lisp `loop' macro
+* Multiple Values:: `values', `multiple-value-bind', etc.
+@end menu
+
+@node Assignment, Generalized Variables, Control Structure, Control Structure
+@section Assignment
+
+@noindent
+The @code{psetq} form is just like @code{setq}, except that multiple
+assignments are done in parallel rather than sequentially.
+
+@defspec psetq [symbol form]@dots{}
+This special form (actually a macro) is used to assign to several
+variables simultaneously. Given only one @var{symbol} and @var{form},
+it has the same effect as @code{setq}. Given several @var{symbol}
+and @var{form} pairs, it evaluates all the @var{form}s in advance
+and then stores the corresponding variables afterwards.
+
+@example
+(setq x 2 y 3)
+(setq x (+ x y) y (* x y))
+x
+ @result{} 5
+y ; @r{@code{y} was computed after @code{x} was set.}
+ @result{} 15
+(setq x 2 y 3)
+(psetq x (+ x y) y (* x y))
+x
+ @result{} 5
+y ; @r{@code{y} was computed before @code{x} was set.}
+ @result{} 6
+@end example
+
+The simplest use of @code{psetq} is @code{(psetq x y y x)}, which
+exchanges the values of two variables. (The @code{rotatef} form
+provides an even more convenient way to swap two variables;
+@pxref{Modify Macros}.)
+
+@code{psetq} always returns @code{nil}.
+@end defspec
+
+@node Generalized Variables, Variable Bindings, Assignment, Control Structure
+@section Generalized Variables
+
+@noindent
+A ``generalized variable'' or ``place form'' is one of the many places
+in Lisp memory where values can be stored. The simplest place form is
+a regular Lisp variable. But the cars and cdrs of lists, elements
+of arrays, properties of symbols, and many other locations are also
+places where Lisp values are stored.
+
+The @code{setf} form is like @code{setq}, except that it accepts
+arbitrary place forms on the left side rather than just
+symbols. For example, @code{(setf (car a) b)} sets the car of
+@code{a} to @code{b}, doing the same operation as @code{(setcar a b)}
+but without having to remember two separate functions for setting
+and accessing every type of place.
+
+Generalized variables are analogous to ``lvalues'' in the C
+language, where @samp{x = a[i]} gets an element from an array
+and @samp{a[i] = x} stores an element using the same notation.
+Just as certain forms like @code{a[i]} can be lvalues in C, there
+is a set of forms that can be generalized variables in Lisp.
+
+@menu
+* Basic Setf:: `setf' and place forms
+* Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc.
+* Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method'
+@end menu
+
+@node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables
+@subsection Basic Setf
+
+@noindent
+The @code{setf} macro is the most basic way to operate on generalized
+variables.
+
+@defspec setf [place form]@dots{}
+This macro evaluates @var{form} and stores it in @var{place}, which
+must be a valid generalized variable form. If there are several
+@var{place} and @var{form} pairs, the assignments are done sequentially
+just as with @code{setq}. @code{setf} returns the value of the last
+@var{form}.
+
+The following Lisp forms will work as generalized variables, and
+so may legally appear in the @var{place} argument of @code{setf}:
+
+@itemize @bullet
+@item
+A symbol naming a variable. In other words, @code{(setf x y)} is
+exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
+strictly speaking redundant now that @code{setf} exists. Many
+programmers continue to prefer @code{setq} for setting simple
+variables, though, purely for stylistic or historical reasons.
+The macro @code{(setf x y)} actually expands to @code{(setq x y)},
+so there is no performance penalty for using it in compiled code.
+
+@item
+A call to any of the following Lisp functions:
+
+@smallexample
+car cdr caar .. cddddr
+nth rest first .. tenth
+aref elt nthcdr
+symbol-function symbol-value symbol-plist
+get get* getf
+gethash subseq
+@end smallexample
+
+@noindent
+Note that for @code{nthcdr} and @code{getf}, the list argument
+of the function must itself be a valid @var{place} form. For
+example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself
+to 7. Note that @code{push} and @code{pop} on an @code{nthcdr}
+place can be used to insert or delete at any position in a list.
+The use of @code{nthcdr} as a @var{place} form is an extension
+to standard Common Lisp.
+
+@item
+The following Emacs-specific functions are also @code{setf}-able.
+(Some of these are defined only in Emacs 19 or only in Lucid Emacs.)
+
+@smallexample
+buffer-file-name marker-position
+buffer-modified-p match-data
+buffer-name mouse-position
+buffer-string overlay-end
+buffer-substring overlay-get
+current-buffer overlay-start
+current-case-table point
+current-column point-marker
+current-global-map point-max
+current-input-mode point-min
+current-local-map process-buffer
+current-window-configuration process-filter
+default-file-modes process-sentinel
+default-value read-mouse-position
+documentation-property screen-height
+extent-data screen-menubar
+extent-end-position screen-width
+extent-start-position selected-window
+face-background selected-screen
+face-background-pixmap selected-frame
+face-font standard-case-table
+face-foreground syntax-table
+face-underline-p window-buffer
+file-modes window-dedicated-p
+frame-height window-display-table
+frame-parameters window-height
+frame-visible-p window-hscroll
+frame-width window-point
+get-register window-start
+getenv window-width
+global-key-binding x-get-cut-buffer
+keymap-parent x-get-cutbuffer
+local-key-binding x-get-secondary-selection
+mark x-get-selection
+mark-marker
+@end smallexample
+
+Most of these have directly corresponding ``set'' functions, like
+@code{use-local-map} for @code{current-local-map}, or @code{goto-char}
+for @code{point}. A few, like @code{point-min}, expand to longer
+sequences of code when they are @code{setf}'d (@code{(narrow-to-region
+x (point-max))} in this case).
+
+@item
+A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
+where @var{subplace} is itself a legal generalized variable whose
+current value is a string, and where the value stored is also a
+string. The new string is spliced into the specified part of the
+destination string. For example:
+
+@example
+(setq a (list "hello" "world"))
+ @result{} ("hello" "world")
+(cadr a)
+ @result{} "world"
+(substring (cadr a) 2 4)
+ @result{} "rl"
+(setf (substring (cadr a) 2 4) "o")
+ @result{} "o"
+(cadr a)
+ @result{} "wood"
+a
+ @result{} ("hello" "wood")
+@end example
+
+The generalized variable @code{buffer-substring}, listed above,
+also works in this way by replacing a portion of the current buffer.
+
+@item
+A call of the form @code{(apply '@var{func} @dots{})} or
+@code{(apply (function @var{func}) @dots{})}, where @var{func}
+is a @code{setf}-able function whose store function is ``suitable''
+in the sense described in Steele's book; since none of the standard
+Emacs place functions are suitable in this sense, this feature is
+only interesting when used with places you define yourself with
+@code{define-setf-method} or the long form of @code{defsetf}.
+
+@item
+A macro call, in which case the macro is expanded and @code{setf}
+is applied to the resulting form.
+
+@item
+Any form for which a @code{defsetf} or @code{define-setf-method}
+has been made.
+@end itemize
+
+Using any forms other than these in the @var{place} argument to
+@code{setf} will signal an error.
+
+The @code{setf} macro takes care to evaluate all subforms in
+the proper left-to-right order; for example,
+
+@example
+(setf (aref vec (incf i)) i)
+@end example
+
+@noindent
+looks like it will evaluate @code{(incf i)} exactly once, before the
+following access to @code{i}; the @code{setf} expander will insert
+temporary variables as necessary to ensure that it does in fact work
+this way no matter what setf-method is defined for @code{aref}.
+(In this case, @code{aset} would be used and no such steps would
+be necessary since @code{aset} takes its arguments in a convenient
+order.)
+
+However, if the @var{place} form is a macro which explicitly
+evaluates its arguments in an unusual order, this unusual order
+will be preserved. Adapting an example from Steele, given
+
+@example
+(defmacro wrong-order (x y) (list 'aref y x))
+@end example
+
+@noindent
+the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
+evaluate @var{b} first, then @var{a}, just as in an actual call
+to @code{wrong-order}.
+@end defspec
+
+@node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables
+@subsection Modify Macros
+
+@noindent
+This package defines a number of other macros besides @code{setf}
+that operate on generalized variables. Many are interesting and
+useful even when the @var{place} is just a variable name.
+
+@defspec psetf [place form]@dots{}
+This macro is to @code{setf} what @code{psetq} is to @code{setq}:
+When several @var{place}s and @var{form}s are involved, the
+assignments take place in parallel rather than sequentially.
+Specifically, all subforms are evaluated from left to right, then
+all the assignments are done (in an undefined order).
+@end defspec
+
+@defspec incf place &optional x
+This macro increments the number stored in @var{place} by one, or
+by @var{x} if specified. The incremented value is returned. For
+example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and
+@code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
+
+Once again, care is taken to preserve the ``apparent'' order of
+evaluation. For example,
+
+@example
+(incf (aref vec (incf i)))
+@end example
+
+@noindent
+appears to increment @code{i} once, then increment the element of
+@code{vec} addressed by @code{i}; this is indeed exactly what it
+does, which means the above form is @emph{not} equivalent to the
+``obvious'' expansion,
+
+@example
+(setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong!
+@end example
+
+@noindent
+but rather to something more like
+
+@example
+(let ((temp (incf i)))
+ (setf (aref vec temp) (1+ (aref vec temp))))
+@end example
+
+@noindent
+Again, all of this is taken care of automatically by @code{incf} and
+the other generalized-variable macros.
+
+As a more Emacs-specific example of @code{incf}, the expression
+@code{(incf (point) @var{n})} is essentially equivalent to
+@code{(forward-char @var{n})}.
+@end defspec
+
+@defspec decf place &optional x
+This macro decrements the number stored in @var{place} by one, or
+by @var{x} if specified.
+@end defspec
+
+@defspec pop place
+This macro removes and returns the first element of the list stored
+in @var{place}. It is analogous to @code{(prog1 (car @var{place})
+(setf @var{place} (cdr @var{place})))}, except that it takes care
+to evaluate all subforms only once.
+@end defspec
+
+@defspec push x place
+This macro inserts @var{x} at the front of the list stored in
+@var{place}. It is analogous to @code{(setf @var{place} (cons
+@var{x} @var{place}))}, except for evaluation of the subforms.
+@end defspec
+
+@defspec pushnew x place @t{&key :test :test-not :key}
+This macro inserts @var{x} at the front of the list stored in
+@var{place}, but only if @var{x} was not @code{eql} to any
+existing element of the list. The optional keyword arguments
+are interpreted in the same way as for @code{adjoin}.
+@xref{Lists as Sets}.
+@end defspec
+
+@defspec shiftf place@dots{} newvalue
+This macro shifts the @var{place}s left by one, shifting in the
+value of @var{newvalue} (which may be any Lisp expression, not just
+a generalized variable), and returning the value shifted out of
+the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c}
+@var{d})} is equivalent to
+
+@example
+(prog1
+ @var{a}
+ (psetf @var{a} @var{b}
+ @var{b} @var{c}
+ @var{c} @var{d}))
+@end example
+
+@noindent
+except that the subforms of @var{a}, @var{b}, and @var{c} are actually
+evaluated only once each and in the apparent order.
+@end defspec
+
+@defspec rotatef place@dots{}
+This macro rotates the @var{place}s left by one in circular fashion.
+Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
+
+@example
+(psetf @var{a} @var{b}
+ @var{b} @var{c}
+ @var{c} @var{d}
+ @var{d} @var{a})
+@end example
+
+@noindent
+except for the evaluation of subforms. @code{rotatef} always
+returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})}
+conveniently exchanges @var{a} and @var{b}.
+@end defspec
+
+The following macros were invented for this package; they have no
+analogues in Common Lisp.
+
+@defspec letf (bindings@dots{}) forms@dots{}
+This macro is analogous to @code{let}, but for generalized variables
+rather than just symbols. Each @var{binding} should be of the form
+@code{(@var{place} @var{value})}; the original contents of the
+@var{place}s are saved, the @var{value}s are stored in them, and
+then the body @var{form}s are executed. Afterwards, the @var{places}
+are set back to their original saved contents. This cleanup happens
+even if the @var{form}s exit irregularly due to a @code{throw} or an
+error.
+
+For example,
+
+@example
+(letf (((point) (point-min))
+ (a 17))
+ ...)
+@end example
+
+@noindent
+moves ``point'' in the current buffer to the beginning of the buffer,
+and also binds @code{a} to 17 (as if by a normal @code{let}, since
+@code{a} is just a regular variable). After the body exits, @code{a}
+is set back to its original value and point is moved back to its
+original position.
+
+Note that @code{letf} on @code{(point)} is not quite like a
+@code{save-excursion}, as the latter effectively saves a marker
+which tracks insertions and deletions in the buffer. Actually,
+a @code{letf} of @code{(point-marker)} is much closer to this
+behavior. (@code{point} and @code{point-marker} are equivalent
+as @code{setf} places; each will accept either an integer or a
+marker as the stored value.)
+
+Since generalized variables look like lists, @code{let}'s shorthand
+of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
+be ambiguous in @code{letf} and is not allowed.
+
+However, a @var{binding} specifier may be a one-element list
+@samp{(@var{place})}, which is similar to @samp{(@var{place}
+@var{place})}. In other words, the @var{place} is not disturbed
+on entry to the body, and the only effect of the @code{letf} is
+to restore the original value of @var{place} afterwards. (The
+redundant access-and-store suggested by the @code{(@var{place}
+@var{place})} example does not actually occur.)
+
+In most cases, the @var{place} must have a well-defined value on
+entry to the @code{letf} form. The only exceptions are plain
+variables and calls to @code{symbol-value} and @code{symbol-function}.
+If the symbol is not bound on entry, it is simply made unbound by
+@code{makunbound} or @code{fmakunbound} on exit.
+@end defspec
+
+@defspec letf* (bindings@dots{}) forms@dots{}
+This macro is to @code{letf} what @code{let*} is to @code{let}:
+It does the bindings in sequential rather than parallel order.
+@end defspec
+
+@defspec callf @var{function} @var{place} @var{args}@dots{}
+This is the ``generic'' modify macro. It calls @var{function},
+which should be an unquoted function name, macro name, or lambda.
+It passes @var{place} and @var{args} as arguments, and assigns the
+result back to @var{place}. For example, @code{(incf @var{place}
+@var{n})} is the same as @code{(callf + @var{place} @var{n})}.
+Some more examples:
+
+@example
+(callf abs my-number)
+(callf concat (buffer-name) "<" (int-to-string n) ">")
+(callf union happy-people (list joe bob) :test 'same-person)
+@end example
+
+@xref{Customizing Setf}, for @code{define-modify-macro}, a way
+to create even more concise notations for modify macros. Note
+again that @code{callf} is an extension to standard Common Lisp.
+@end defspec
+
+@defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
+This macro is like @code{callf}, except that @var{place} is
+the @emph{second} argument of @var{function} rather than the
+first. For example, @code{(push @var{x} @var{place})} is
+equivalent to @code{(callf2 cons @var{x} @var{place})}.
+@end defspec
+
+The @code{callf} and @code{callf2} macros serve as building
+blocks for other macros like @code{incf}, @code{pushnew}, and
+@code{define-modify-macro}. The @code{letf} and @code{letf*}
+macros are used in the processing of symbol macros;
+@pxref{Macro Bindings}.
+
+@node Customizing Setf, , Modify Macros, Generalized Variables
+@subsection Customizing Setf
+
+@noindent
+Common Lisp defines three macros, @code{define-modify-macro},
+@code{defsetf}, and @code{define-setf-method}, that allow the
+user to extend generalized variables in various ways.
+
+@defspec define-modify-macro name arglist function [doc-string]
+This macro defines a ``read-modify-write'' macro similar to
+@code{incf} and @code{decf}. The macro @var{name} is defined
+to take a @var{place} argument followed by additional arguments
+described by @var{arglist}. The call
+
+@example
+(@var{name} @var{place} @var{args}...)
+@end example
+
+@noindent
+will be expanded to
+
+@example
+(callf @var{func} @var{place} @var{args}...)
+@end example
+
+@noindent
+which in turn is roughly equivalent to
+
+@example
+(setf @var{place} (@var{func} @var{place} @var{args}...))
+@end example
+
+For example:
+
+@example
+(define-modify-macro incf (&optional (n 1)) +)
+(define-modify-macro concatf (&rest args) concat)
+@end example
+
+Note that @code{&key} is not allowed in @var{arglist}, but
+@code{&rest} is sufficient to pass keywords on to the function.
+
+Most of the modify macros defined by Common Lisp do not exactly
+follow the pattern of @code{define-modify-macro}. For example,
+@code{push} takes its arguments in the wrong order, and @code{pop}
+is completely irregular. You can define these macros ``by hand''
+using @code{get-setf-method}, or consult the source file
+@file{cl-macs.el} to see how to use the internal @code{setf}
+building blocks.
+@end defspec
+
+@defspec defsetf access-fn update-fn
+This is the simpler of two @code{defsetf} forms. Where
+@var{access-fn} is the name of a function which accesses a place,
+this declares @var{update-fn} to be the corresponding store
+function. From now on,
+
+@example
+(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
+@end example
+
+@noindent
+will be expanded to
+
+@example
+(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
+@end example
+
+@noindent
+The @var{update-fn} is required to be either a true function, or
+a macro which evaluates its arguments in a function-like way. Also,
+the @var{update-fn} is expected to return @var{value} as its result.
+Otherwise, the above expansion would not obey the rules for the way
+@code{setf} is supposed to behave.
+
+As a special (non-Common-Lisp) extension, a third argument of @code{t}
+to @code{defsetf} says that the @code{update-fn}'s return value is
+not suitable, so that the above @code{setf} should be expanded to
+something more like
+
+@example
+(let ((temp @var{value}))
+ (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
+ temp)
+@end example
+
+Some examples of the use of @code{defsetf}, drawn from the standard
+suite of setf methods, are:
+
+@example
+(defsetf car setcar)
+(defsetf symbol-value set)
+(defsetf buffer-name rename-buffer t)
+@end example
+@end defspec
+
+@defspec defsetf access-fn arglist (store-var) forms@dots{}
+This is the second, more complex, form of @code{defsetf}. It is
+rather like @code{defmacro} except for the additional @var{store-var}
+argument. The @var{forms} should return a Lisp form which stores
+the value of @var{store-var} into the generalized variable formed
+by a call to @var{access-fn} with arguments described by @var{arglist}.
+The @var{forms} may begin with a string which documents the @code{setf}
+method (analogous to the doc string that appears at the front of a
+function).
+
+For example, the simple form of @code{defsetf} is shorthand for
+
+@example
+(defsetf @var{access-fn} (&rest args) (store)
+ (append '(@var{update-fn}) args (list store)))
+@end example
+
+The Lisp form that is returned can access the arguments from
+@var{arglist} and @var{store-var} in an unrestricted fashion;
+macros like @code{setf} and @code{incf} which invoke this
+setf-method will insert temporary variables as needed to make
+sure the apparent order of evaluation is preserved.
+
+Another example drawn from the standard package:
+
+@example
+(defsetf nth (n x) (store)
+ (list 'setcar (list 'nthcdr n x) store))
+@end example
+@end defspec
+
+@defspec define-setf-method access-fn arglist forms@dots{}
+This is the most general way to create new place forms. When
+a @code{setf} to @var{access-fn} with arguments described by
+@var{arglist} is expanded, the @var{forms} are evaluated and
+must return a list of five items:
+
+@enumerate
+@item
+A list of @dfn{temporary variables}.
+
+@item
+A list of @dfn{value forms} corresponding to the temporary variables
+above. The temporary variables will be bound to these value forms
+as the first step of any operation on the generalized variable.
+
+@item
+A list of exactly one @dfn{store variable} (generally obtained
+from a call to @code{gensym}).
+
+@item
+A Lisp form which stores the contents of the store variable into
+the generalized variable, assuming the temporaries have been
+bound as described above.
+
+@item
+A Lisp form which accesses the contents of the generalized variable,
+assuming the temporaries have been bound.
+@end enumerate
+
+This is exactly like the Common Lisp macro of the same name,
+except that the method returns a list of five values rather
+than the five values themselves, since Emacs Lisp does not
+support Common Lisp's notion of multiple return values.
+
+Once again, the @var{forms} may begin with a documentation string.
+
+A setf-method should be maximally conservative with regard to
+temporary variables. In the setf-methods generated by
+@code{defsetf}, the second return value is simply the list of
+arguments in the place form, and the first return value is a
+list of a corresponding number of temporary variables generated
+by @code{gensym}. Macros like @code{setf} and @code{incf} which
+use this setf-method will optimize away most temporaries that
+turn out to be unnecessary, so there is little reason for the
+setf-method itself to optimize.
+@end defspec
+
+@defun get-setf-method place &optional env
+This function returns the setf-method for @var{place}, by
+invoking the definition previously recorded by @code{defsetf}
+or @code{define-setf-method}. The result is a list of five
+values as described above. You can use this function to build
+your own @code{incf}-like modify macros. (Actually, it is
+better to use the internal functions @code{cl-setf-do-modify}
+and @code{cl-setf-do-store}, which are a bit easier to use and
+which also do a number of optimizations; consult the source
+code for the @code{incf} function for a simple example.)
+
+The argument @var{env} specifies the ``environment'' to be
+passed on to @code{macroexpand} if @code{get-setf-method} should
+need to expand a macro in @var{place}. It should come from
+an @code{&environment} argument to the macro or setf-method
+that called @code{get-setf-method}.
+
+See also the source code for the setf-methods for @code{apply}
+and @code{substring}, each of which works by calling
+@code{get-setf-method} on a simpler case, then massaging
+the result in various ways.
+@end defun
+
+Modern Common Lisp defines a second, independent way to specify
+the @code{setf} behavior of a function, namely ``@code{setf}
+functions'' whose names are lists @code{(setf @var{name})}
+rather than symbols. For example, @code{(defun (setf foo) @dots{})}
+defines the function that is used when @code{setf} is applied to
+@code{foo}. This package does not currently support @code{setf}
+functions. In particular, it is a compile-time error to use
+@code{setf} on a form which has not already been @code{defsetf}'d
+or otherwise declared; in newer Common Lisps, this would not be
+an error since the function @code{(setf @var{func})} might be
+defined later.
+
+@iftex
+@secno=4
+@end iftex
+
+@node Variable Bindings, Conditionals, Generalized Variables, Control Structure
+@section Variable Bindings
+
+@noindent
+These Lisp forms make bindings to variables and function names,
+analogous to Lisp's built-in @code{let} form.
+
+@xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which
+are also related to variable bindings.
+
+@menu
+* Dynamic Bindings:: The `progv' form
+* Lexical Bindings:: `lexical-let' and lexical closures
+* Function Bindings:: `flet' and `labels'
+* Macro Bindings:: `macrolet' and `symbol-macrolet'
+@end menu
+
+@node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings
+@subsection Dynamic Bindings
+
+@noindent
+The standard @code{let} form binds variables whose names are known
+at compile-time. The @code{progv} form provides an easy way to
+bind variables whose names are computed at run-time.
+
+@defspec progv symbols values forms@dots{}
+This form establishes @code{let}-style variable bindings on a
+set of variables computed at run-time. The expressions
+@var{symbols} and @var{values} are evaluated, and must return lists
+of symbols and values, respectively. The symbols are bound to the
+corresponding values for the duration of the body @var{form}s.
+If @var{values} is shorter than @var{symbols}, the last few symbols
+are made unbound (as if by @code{makunbound}) inside the body.
+If @var{symbols} is shorter than @var{values}, the excess values
+are ignored.
+@end defspec
+
+@node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings
+@subsection Lexical Bindings
+
+@noindent
+The @dfn{CL} package defines the following macro which
+more closely follows the Common Lisp @code{let} form:
+
+@defspec lexical-let (bindings@dots{}) forms@dots{}
+This form is exactly like @code{let} except that the bindings it
+establishes are purely lexical. Lexical bindings are similar to
+local variables in a language like C: Only the code physically
+within the body of the @code{lexical-let} (after macro expansion)
+may refer to the bound variables.
+
+@example
+(setq a 5)
+(defun foo (b) (+ a b))
+(let ((a 2)) (foo a))
+ @result{} 4
+(lexical-let ((a 2)) (foo a))
+ @result{} 7
+@end example
+
+@noindent
+In this example, a regular @code{let} binding of @code{a} actually
+makes a temporary change to the global variable @code{a}, so @code{foo}
+is able to see the binding of @code{a} to 2. But @code{lexical-let}
+actually creates a distinct local variable @code{a} for use within its
+body, without any effect on the global variable of the same name.
+
+The most important use of lexical bindings is to create @dfn{closures}.
+A closure is a function object that refers to an outside lexical
+variable. For example:
+
+@example
+(defun make-adder (n)
+ (lexical-let ((n n))
+ (function (lambda (m) (+ n m)))))
+(setq add17 (make-adder 17))
+(funcall add17 4)
+ @result{} 21
+@end example
+
+@noindent
+The call @code{(make-adder 17)} returns a function object which adds
+17 to its argument. If @code{let} had been used instead of
+@code{lexical-let}, the function object would have referred to the
+global @code{n}, which would have been bound to 17 only during the
+call to @code{make-adder} itself.
+
+@example
+(defun make-counter ()
+ (lexical-let ((n 0))
+ (function* (lambda (&optional (m 1)) (incf n m)))))
+(setq count-1 (make-counter))
+(funcall count-1 3)
+ @result{} 3
+(funcall count-1 14)
+ @result{} 17
+(setq count-2 (make-counter))
+(funcall count-2 5)
+ @result{} 5
+(funcall count-1 2)
+ @result{} 19
+(funcall count-2)
+ @result{} 6
+@end example
+
+@noindent
+Here we see that each call to @code{make-counter} creates a distinct
+local variable @code{n}, which serves as a private counter for the
+function object that is returned.
+
+Closed-over lexical variables persist until the last reference to
+them goes away, just like all other Lisp objects. For example,
+@code{count-2} refers to a function object which refers to an
+instance of the variable @code{n}; this is the only reference
+to that variable, so after @code{(setq count-2 nil)} the garbage
+collector would be able to delete this instance of @code{n}.
+Of course, if a @code{lexical-let} does not actually create any
+closures, then the lexical variables are free as soon as the
+@code{lexical-let} returns.
+
+Many closures are used only during the extent of the bindings they
+refer to; these are known as ``downward funargs'' in Lisp parlance.
+When a closure is used in this way, regular Emacs Lisp dynamic
+bindings suffice and will be more efficient than @code{lexical-let}
+closures:
+
+@example
+(defun add-to-list (x list)
+ (mapcar (function (lambda (y) (+ x y))) list))
+(add-to-list 7 '(1 2 5))
+ @result{} (8 9 12)
+@end example
+
+@noindent
+Since this lambda is only used while @code{x} is still bound,
+it is not necessary to make a true closure out of it.
+
+You can use @code{defun} or @code{flet} inside a @code{lexical-let}
+to create a named closure. If several closures are created in the
+body of a single @code{lexical-let}, they all close over the same
+instance of the lexical variable.
+
+The @code{lexical-let} form is an extension to Common Lisp. In
+true Common Lisp, all bindings are lexical unless declared otherwise.
+@end defspec
+
+@defspec lexical-let* (bindings@dots{}) forms@dots{}
+This form is just like @code{lexical-let}, except that the bindings
+are made sequentially in the manner of @code{let*}.
+@end defspec
+
+@node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings
+@subsection Function Bindings
+
+@noindent
+These forms make @code{let}-like bindings to functions instead
+of variables.
+
+@defspec flet (bindings@dots{}) forms@dots{}
+This form establishes @code{let}-style bindings on the function
+cells of symbols rather than on the value cells. Each @var{binding}
+must be a list of the form @samp{(@var{name} @var{arglist}
+@var{forms}@dots{})}, which defines a function exactly as if
+it were a @code{defun*} form. The function @var{name} is defined
+accordingly for the duration of the body of the @code{flet}; then
+the old function definition, or lack thereof, is restored.
+
+While @code{flet} in Common Lisp establishes a lexical binding of
+@var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The
+result is that @code{flet} affects indirect calls to a function as
+well as calls directly inside the @code{flet} form itself.
+
+You can use @code{flet} to disable or modify the behavior of a
+function in a temporary fashion. This will even work on Emacs
+primitives, although note that some calls to primitive functions
+internal to Emacs are made without going through the symbol's
+function cell, and so will not be affected by @code{flet}. For
+example,
+
+@example
+(flet ((message (&rest args) (push args saved-msgs)))
+ (do-something))
+@end example
+
+This code attempts to replace the built-in function @code{message}
+with a function that simply saves the messages in a list rather
+than displaying them. The original definition of @code{message}
+will be restored after @code{do-something} exits. This code will
+work fine on messages generated by other Lisp code, but messages
+generated directly inside Emacs will not be caught since they make
+direct C-language calls to the message routines rather than going
+through the Lisp @code{message} function.
+
+Functions defined by @code{flet} may use the full Common Lisp
+argument notation supported by @code{defun*}; also, the function
+body is enclosed in an implicit block as if by @code{defun*}.
+@xref{Program Structure}.
+@end defspec
+
+@defspec labels (bindings@dots{}) forms@dots{}
+The @code{labels} form is like @code{flet}, except that it
+makes lexical bindings of the function names rather than
+dynamic bindings. (In true Common Lisp, both @code{flet} and
+@code{labels} make lexical bindings of slightly different sorts;
+since Emacs Lisp is dynamically bound by default, it seemed
+more appropriate for @code{flet} also to use dynamic binding.
+The @code{labels} form, with its lexical binding, is fully
+compatible with Common Lisp.)
+
+Lexical scoping means that all references to the named
+functions must appear physically within the body of the
+@code{labels} form. References may appear both in the body
+@var{forms} of @code{labels} itself, and in the bodies of
+the functions themselves. Thus, @code{labels} can define
+local recursive functions, or mutually-recursive sets of
+functions.
+
+A ``reference'' to a function name is either a call to that
+function, or a use of its name quoted by @code{quote} or
+@code{function} to be passed on to, say, @code{mapcar}.
+@end defspec
+
+@node Macro Bindings, , Function Bindings, Variable Bindings
+@subsection Macro Bindings
+
+@noindent
+These forms create local macros and ``symbol macros.''
+
+@defspec macrolet (bindings@dots{}) forms@dots{}
+This form is analogous to @code{flet}, but for macros instead of
+functions. Each @var{binding} is a list of the same form as the
+arguments to @code{defmacro*} (i.e., a macro name, argument list,
+and macro-expander forms). The macro is defined accordingly for
+use within the body of the @code{macrolet}.
+
+Because of the nature of macros, @code{macrolet} is lexically
+scoped even in Emacs Lisp: The @code{macrolet} binding will
+affect only calls that appear physically within the body
+@var{forms}, possibly after expansion of other macros in the
+body.
+@end defspec
+
+@defspec symbol-macrolet (bindings@dots{}) forms@dots{}
+This form creates @dfn{symbol macros}, which are macros that look
+like variable references rather than function calls. Each
+@var{binding} is a list @samp{(@var{var} @var{expansion})};
+any reference to @var{var} within the body @var{forms} is
+replaced by @var{expansion}.
+
+@example
+(setq bar '(5 . 9))
+(symbol-macrolet ((foo (car bar)))
+ (incf foo))
+bar
+ @result{} (6 . 9)
+@end example
+
+A @code{setq} of a symbol macro is treated the same as a @code{setf}.
+I.e., @code{(setq foo 4)} in the above would be equivalent to
+@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
+
+Likewise, a @code{let} or @code{let*} binding a symbol macro is
+treated like a @code{letf} or @code{letf*}. This differs from true
+Common Lisp, where the rules of lexical scoping cause a @code{let}
+binding to shadow a @code{symbol-macrolet} binding. In this package,
+only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
+macro.
+
+There is no analogue of @code{defmacro} for symbol macros; all symbol
+macros are local. A typical use of @code{symbol-macrolet} is in the
+expansion of another macro:
+
+@example
+(defmacro* my-dolist ((x list) &rest body)
+ (let ((var (gensym)))
+ (list 'loop 'for var 'on list 'do
+ (list* 'symbol-macrolet (list (list x (list 'car var)))
+ body))))
+
+(setq mylist '(1 2 3 4))
+(my-dolist (x mylist) (incf x))
+mylist
+ @result{} (2 3 4 5)
+@end example
+
+@noindent
+In this example, the @code{my-dolist} macro is similar to @code{dolist}
+(@pxref{Iteration}) except that the variable @code{x} becomes a true
+reference onto the elements of the list. The @code{my-dolist} call
+shown here expands to
+
+@example
+(loop for G1234 on mylist do
+ (symbol-macrolet ((x (car G1234)))
+ (incf x)))
+@end example
+
+@noindent
+which in turn expands to
+
+@example
+(loop for G1234 on mylist do (incf (car G1234)))
+@end example
+
+@xref{Loop Facility}, for a description of the @code{loop} macro.
+This package defines a nonstandard @code{in-ref} loop clause that
+works much like @code{my-dolist}.
+@end defspec
+
+@node Conditionals, Blocks and Exits, Variable Bindings, Control Structure
+@section Conditionals
+
+@noindent
+These conditional forms augment Emacs Lisp's simple @code{if},
+@code{and}, @code{or}, and @code{cond} forms.
+
+@defspec case keyform clause@dots{}
+This macro evaluates @var{keyform}, then compares it with the key
+values listed in the various @var{clause}s. Whichever clause matches
+the key is executed; comparison is done by @code{eql}. If no clause
+matches, the @code{case} form returns @code{nil}. The clauses are
+of the form
+
+@example
+(@var{keylist} @var{body-forms}@dots{})
+@end example
+
+@noindent
+where @var{keylist} is a list of key values. If there is exactly
+one value, and it is not a cons cell or the symbol @code{nil} or
+@code{t}, then it can be used by itself as a @var{keylist} without
+being enclosed in a list. All key values in the @code{case} form
+must be distinct. The final clauses may use @code{t} in place of
+a @var{keylist} to indicate a default clause that should be taken
+if none of the other clauses match. (The symbol @code{otherwise}
+is also recognized in place of @code{t}. To make a clause that
+matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
+enclose the symbol in a list.)
+
+For example, this expression reads a keystroke, then does one of
+four things depending on whether it is an @samp{a}, a @samp{b},
+a @key{RET} or @kbd{C-j}, or anything else.
+
+@example
+(case (read-char)
+ (?a (do-a-thing))
+ (?b (do-b-thing))
+ ((?\r ?\n) (do-ret-thing))
+ (t (do-other-thing)))
+@end example
+@end defspec
+
+@defspec ecase keyform clause@dots{}
+This macro is just like @code{case}, except that if the key does
+not match any of the clauses, an error is signaled rather than
+simply returning @code{nil}.
+@end defspec
+
+@defspec typecase keyform clause@dots{}
+This macro is a version of @code{case} that checks for types
+rather than values. Each @var{clause} is of the form
+@samp{(@var{type} @var{body}...)}. @xref{Type Predicates},
+for a description of type specifiers. For example,
+
+@example
+(typecase x
+ (integer (munch-integer x))
+ (float (munch-float x))
+ (string (munch-integer (string-to-int x)))
+ (t (munch-anything x)))
+@end example
+
+The type specifier @code{t} matches any type of object; the word
+@code{otherwise} is also allowed. To make one clause match any of
+several types, use an @code{(or ...)} type specifier.
+@end defspec
+
+@defspec etypecase keyform clause@dots{}
+This macro is just like @code{typecase}, except that if the key does
+not match any of the clauses, an error is signaled rather than
+simply returning @code{nil}.
+@end defspec
+
+@node Blocks and Exits, Iteration, Conditionals, Control Structure
+@section Blocks and Exits
+
+@noindent
+Common Lisp @dfn{blocks} provide a non-local exit mechanism very
+similar to @code{catch} and @code{throw}, but lexically rather than
+dynamically scoped. This package actually implements @code{block}
+in terms of @code{catch}; however, the lexical scoping allows the
+optimizing byte-compiler to omit the costly @code{catch} step if the
+body of the block does not actually @code{return-from} the block.
+
+@defspec block name forms@dots{}
+The @var{forms} are evaluated as if by a @code{progn}. However,
+if any of the @var{forms} execute @code{(return-from @var{name})},
+they will jump out and return directly from the @code{block} form.
+The @code{block} returns the result of the last @var{form} unless
+a @code{return-from} occurs.
+
+The @code{block}/@code{return-from} mechanism is quite similar to
+the @code{catch}/@code{throw} mechanism. The main differences are
+that block @var{name}s are unevaluated symbols, rather than forms
+(such as quoted symbols) which evaluate to a tag at run-time; and
+also that blocks are lexically scoped whereas @code{catch}/@code{throw}
+are dynamically scoped. This means that functions called from the
+body of a @code{catch} can also @code{throw} to the @code{catch},
+but the @code{return-from} referring to a block name must appear
+physically within the @var{forms} that make up the body of the block.
+They may not appear within other called functions, although they may
+appear within macro expansions or @code{lambda}s in the body. Block
+names and @code{catch} names form independent name-spaces.
+
+In true Common Lisp, @code{defun} and @code{defmacro} surround
+the function or expander bodies with implicit blocks with the
+same name as the function or macro. This does not occur in Emacs
+Lisp, but this package provides @code{defun*} and @code{defmacro*}
+forms which do create the implicit block.
+
+The Common Lisp looping constructs defined by this package,
+such as @code{loop} and @code{dolist}, also create implicit blocks
+just as in Common Lisp.
+
+Because they are implemented in terms of Emacs Lisp @code{catch}
+and @code{throw}, blocks have the same overhead as actual
+@code{catch} constructs (roughly two function calls). However,
+Zawinski and Furuseth's optimizing byte compiler (standard in
+Emacs 19) will optimize away the @code{catch} if the block does
+not in fact contain any @code{return} or @code{return-from} calls
+that jump to it. This means that @code{do} loops and @code{defun*}
+functions which don't use @code{return} don't pay the overhead to
+support it.
+@end defspec
+
+@defspec return-from name [result]
+This macro returns from the block named @var{name}, which must be
+an (unevaluated) symbol. If a @var{result} form is specified, it
+is evaluated to produce the result returned from the @code{block}.
+Otherwise, @code{nil} is returned.
+@end defspec
+
+@defspec return [result]
+This macro is exactly like @code{(return-from nil @var{result})}.
+Common Lisp loops like @code{do} and @code{dolist} implicitly enclose
+themselves in @code{nil} blocks.
+@end defspec
+
+@node Iteration, Loop Facility, Blocks and Exits, Control Structure
+@section Iteration
+
+@noindent
+The macros described here provide more sophisticated, high-level
+looping constructs to complement Emacs Lisp's basic @code{while}
+loop.
+
+@defspec loop forms@dots{}
+The @dfn{CL} package supports both the simple, old-style meaning of
+@code{loop} and the extremely powerful and flexible feature known as
+the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
+facility is discussed in the following section; @pxref{Loop Facility}.
+The simple form of @code{loop} is described here.
+
+If @code{loop} is followed by zero or more Lisp expressions,
+then @code{(loop @var{exprs}@dots{})} simply creates an infinite
+loop executing the expressions over and over. The loop is
+enclosed in an implicit @code{nil} block. Thus,
+
+@example
+(loop (foo) (if (no-more) (return 72)) (bar))
+@end example
+
+@noindent
+is exactly equivalent to
+
+@example
+(block nil (while t (foo) (if (no-more) (return 72)) (bar)))
+@end example
+
+If any of the expressions are plain symbols, the loop is instead
+interpreted as a Loop Macro specification as described later.
+(This is not a restriction in practice, since a plain symbol
+in the above notation would simply access and throw away the
+value of a variable.)
+@end defspec
+
+@defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
+This macro creates a general iterative loop. Each @var{spec} is
+of the form
+
+@example
+(@var{var} [@var{init} [@var{step}]])
+@end example
+
+The loop works as follows: First, each @var{var} is bound to the
+associated @var{init} value as if by a @code{let} form. Then, in
+each iteration of the loop, the @var{end-test} is evaluated; if
+true, the loop is finished. Otherwise, the body @var{forms} are
+evaluated, then each @var{var} is set to the associated @var{step}
+expression (as if by a @code{psetq} form) and the next iteration
+begins. Once the @var{end-test} becomes true, the @var{result}
+forms are evaluated (with the @var{var}s still bound to their
+values) to produce the result returned by @code{do}.
+
+The entire @code{do} loop is enclosed in an implicit @code{nil}
+block, so that you can use @code{(return)} to break out of the
+loop at any time.
+
+If there are no @var{result} forms, the loop returns @code{nil}.
+If a given @var{var} has no @var{step} form, it is bound to its
+@var{init} value but not otherwise modified during the @code{do}
+loop (unless the code explicitly modifies it); this case is just
+a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
+around the loop. If @var{init} is also omitted it defaults to
+@code{nil}, and in this case a plain @samp{@var{var}} can be used
+in place of @samp{(@var{var})}, again following the analogy with
+@code{let}.
+
+This example (from Steele) illustrates a loop which applies the
+function @code{f} to successive pairs of values from the lists
+@code{foo} and @code{bar}; it is equivalent to the call
+@code{(mapcar* 'f foo bar)}. Note that this loop has no body
+@var{forms} at all, performing all its work as side effects of
+the rest of the loop.
+
+@example
+(do ((x foo (cdr x))
+ (y bar (cdr y))
+ (z nil (cons (f (car x) (car y)) z)))
+ ((or (null x) (null y))
+ (nreverse z)))
+@end example
+@end defspec
+
+@defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
+This is to @code{do} what @code{let*} is to @code{let}. In
+particular, the initial values are bound as if by @code{let*}
+rather than @code{let}, and the steps are assigned as if by
+@code{setq} rather than @code{psetq}.
+
+Here is another way to write the above loop:
+
+@example
+(do* ((xp foo (cdr xp))
+ (yp bar (cdr yp))
+ (x (car xp) (car xp))
+ (y (car yp) (car yp))
+ z)
+ ((or (null xp) (null yp))
+ (nreverse z))
+ (push (f x y) z))
+@end example
+@end defspec
+
+@defspec dolist (var list [result]) forms@dots{}
+This is a more specialized loop which iterates across the elements
+of a list. @var{list} should evaluate to a list; the body @var{forms}
+are executed with @var{var} bound to each element of the list in
+turn. Finally, the @var{result} form (or @code{nil}) is evaluated
+with @var{var} bound to @code{nil} to produce the result returned by
+the loop. The loop is surrounded by an implicit @code{nil} block.
+@end defspec
+
+@defspec dotimes (var count [result]) forms@dots{}
+This is a more specialized loop which iterates a specified number
+of times. The body is executed with @var{var} bound to the integers
+from zero (inclusive) to @var{count} (exclusive), in turn. Then
+the @code{result} form is evaluated with @var{var} bound to the total
+number of iterations that were done (i.e., @code{(max 0 @var{count})})
+to get the return value for the loop form. The loop is surrounded
+by an implicit @code{nil} block.
+@end defspec
+
+@defspec do-symbols (var [obarray [result]]) forms@dots{}
+This loop iterates over all interned symbols. If @var{obarray}
+is specified and is not @code{nil}, it loops over all symbols in
+that obarray. For each symbol, the body @var{forms} are evaluated
+with @var{var} bound to that symbol. The symbols are visited in
+an unspecified order. Afterward the @var{result} form, if any,
+is evaluated (with @var{var} bound to @code{nil}) to get the return
+value. The loop is surrounded by an implicit @code{nil} block.
+@end defspec
+
+@defspec do-all-symbols (var [result]) forms@dots{}
+This is identical to @code{do-symbols} except that the @var{obarray}
+argument is omitted; it always iterates over the default obarray.
+@end defspec
+
+@xref{Mapping over Sequences}, for some more functions for
+iterating over vectors or lists.
+
+@node Loop Facility, Multiple Values, Iteration, Control Structure
+@section Loop Facility
+
+@noindent
+A common complaint with Lisp's traditional looping constructs is
+that they are either too simple and limited, such as Common Lisp's
+@code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
+obscure, like Common Lisp's @code{do} loop.
+
+To remedy this, recent versions of Common Lisp have added a new
+construct called the ``Loop Facility'' or ``@code{loop} macro,''
+with an easy-to-use but very powerful and expressive syntax.
+
+@menu
+* Loop Basics:: `loop' macro, basic clause structure
+* Loop Examples:: Working examples of `loop' macro
+* For Clauses:: Clauses introduced by `for' or `as'
+* Iteration Clauses:: `repeat', `while', `thereis', etc.
+* Accumulation Clauses:: `collect', `sum', `maximize', etc.
+* Other Clauses:: `with', `if', `initially', `finally'
+@end menu
+
+@node Loop Basics, Loop Examples, Loop Facility, Loop Facility
+@subsection Loop Basics
+
+@noindent
+The @code{loop} macro essentially creates a mini-language within
+Lisp that is specially tailored for describing loops. While this
+language is a little strange-looking by the standards of regular Lisp,
+it turns out to be very easy to learn and well-suited to its purpose.
+
+Since @code{loop} is a macro, all parsing of the loop language
+takes place at byte-compile time; compiled @code{loop}s are just
+as efficient as the equivalent @code{while} loops written longhand.
+
+@defspec loop clauses@dots{}
+A loop construct consists of a series of @var{clause}s, each
+introduced by a symbol like @code{for} or @code{do}. Clauses
+are simply strung together in the argument list of @code{loop},
+with minimal extra parentheses. The various types of clauses
+specify initializations, such as the binding of temporary
+variables, actions to be taken in the loop, stepping actions,
+and final cleanup.
+
+Common Lisp specifies a certain general order of clauses in a
+loop:
+
+@example
+(loop @var{name-clause}
+ @var{var-clauses}@dots{}
+ @var{action-clauses}@dots{})
+@end example
+
+The @var{name-clause} optionally gives a name to the implicit
+block that surrounds the loop. By default, the implicit block
+is named @code{nil}. The @var{var-clauses} specify what
+variables should be bound during the loop, and how they should
+be modified or iterated throughout the course of the loop. The
+@var{action-clauses} are things to be done during the loop, such
+as computing, collecting, and returning values.
+
+The Emacs version of the @code{loop} macro is less restrictive about
+the order of clauses, but things will behave most predictably if
+you put the variable-binding clauses @code{with}, @code{for}, and
+@code{repeat} before the action clauses. As in Common Lisp,
+@code{initially} and @code{finally} clauses can go anywhere.
+
+Loops generally return @code{nil} by default, but you can cause
+them to return a value by using an accumulation clause like
+@code{collect}, an end-test clause like @code{always}, or an
+explicit @code{return} clause to jump out of the implicit block.
+(Because the loop body is enclosed in an implicit block, you can
+also use regular Lisp @code{return} or @code{return-from} to
+break out of the loop.)
+@end defspec
+
+The following sections give some examples of the Loop Macro in
+action, and describe the particular loop clauses in great detail.
+Consult the second edition of Steele's @dfn{Common Lisp, the Language},
+for additional discussion and examples of the @code{loop} macro.
+
+@node Loop Examples, For Clauses, Loop Basics, Loop Facility
+@subsection Loop Examples
+
+@noindent
+Before listing the full set of clauses that are allowed, let's
+look at a few example loops just to get a feel for the @code{loop}
+language.
+
+@example
+(loop for buf in (buffer-list)
+ collect (buffer-file-name buf))
+@end example
+
+@noindent
+This loop iterates over all Emacs buffers, using the list
+returned by @code{buffer-list}. For each buffer @code{buf},
+it calls @code{buffer-file-name} and collects the results into
+a list, which is then returned from the @code{loop} construct.
+The result is a list of the file names of all the buffers in
+Emacs' memory. The words @code{for}, @code{in}, and @code{collect}
+are reserved words in the @code{loop} language.
+
+@example
+(loop repeat 20 do (insert "Yowsa\n"))
+@end example
+
+@noindent
+This loop inserts the phrase ``Yowsa'' twenty times in the
+current buffer.
+
+@example
+(loop until (eobp) do (munch-line) (forward-line 1))
+@end example
+
+@noindent
+This loop calls @code{munch-line} on every line until the end
+of the buffer. If point is already at the end of the buffer,
+the loop exits immediately.
+
+@example
+(loop do (munch-line) until (eobp) do (forward-line 1))
+@end example
+
+@noindent
+This loop is similar to the above one, except that @code{munch-line}
+is always called at least once.
+
+@example
+(loop for x from 1 to 100
+ for y = (* x x)
+ until (>= y 729)
+ finally return (list x (= y 729)))
+@end example
+
+@noindent
+This more complicated loop searches for a number @code{x} whose
+square is 729. For safety's sake it only examines @code{x}
+values up to 100; dropping the phrase @samp{to 100} would
+cause the loop to count upwards with no limit. The second
+@code{for} clause defines @code{y} to be the square of @code{x}
+within the loop; the expression after the @code{=} sign is
+reevaluated each time through the loop. The @code{until}
+clause gives a condition for terminating the loop, and the
+@code{finally} clause says what to do when the loop finishes.
+(This particular example was written less concisely than it
+could have been, just for the sake of illustration.)
+
+Note that even though this loop contains three clauses (two
+@code{for}s and an @code{until}) that would have been enough to
+define loops all by themselves, it still creates a single loop
+rather than some sort of triple-nested loop. You must explicitly
+nest your @code{loop} constructs if you want nested loops.
+
+@node For Clauses, Iteration Clauses, Loop Examples, Loop Facility
+@subsection For Clauses
+
+@noindent
+Most loops are governed by one or more @code{for} clauses.
+A @code{for} clause simultaneously describes variables to be
+bound, how those variables are to be stepped during the loop,
+and usually an end condition based on those variables.
+
+The word @code{as} is a synonym for the word @code{for}. This
+word is followed by a variable name, then a word like @code{from}
+or @code{across} that describes the kind of iteration desired.
+In Common Lisp, the phrase @code{being the} sometimes precedes
+the type of iteration; in this package both @code{being} and
+@code{the} are optional. The word @code{each} is a synonym
+for @code{the}, and the word that follows it may be singular
+or plural: @samp{for x being the elements of y} or
+@samp{for x being each element of y}. Which form you use
+is purely a matter of style.
+
+The variable is bound around the loop as if by @code{let}:
+
+@example
+(setq i 'happy)
+(loop for i from 1 to 10 do (do-something-with i))
+i
+ @result{} happy
+@end example
+
+@table @code
+@item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
+This type of @code{for} clause creates a counting loop. Each of
+the three sub-terms is optional, though there must be at least one
+term so that the clause is marked as a counting clause.
+
+The three expressions are the starting value, the ending value, and
+the step value, respectively, of the variable. The loop counts
+upwards by default (@var{expr3} must be positive), from @var{expr1}
+to @var{expr2} inclusively. If you omit the @code{from} term, the
+loop counts from zero; if you omit the @code{to} term, the loop
+counts forever without stopping (unless stopped by some other
+loop clause, of course); if you omit the @code{by} term, the loop
+counts in steps of one.
+
+You can replace the word @code{from} with @code{upfrom} or
+@code{downfrom} to indicate the direction of the loop. Likewise,
+you can replace @code{to} with @code{upto} or @code{downto}.
+For example, @samp{for x from 5 downto 1} executes five times
+with @code{x} taking on the integers from 5 down to 1 in turn.
+Also, you can replace @code{to} with @code{below} or @code{above},
+which are like @code{upto} and @code{downto} respectively except
+that they are exclusive rather than inclusive limits:
+
+@example
+(loop for x to 10 collect x)
+ @result{} (0 1 2 3 4 5 6 7 8 9 10)
+(loop for x below 10 collect x)
+ @result{} (0 1 2 3 4 5 6 7 8 9)
+@end example
+
+The @code{by} value is always positive, even for downward-counting
+loops. Some sort of @code{from} value is required for downward
+loops; @samp{for x downto 5} is not a legal loop clause all by
+itself.
+
+@item for @var{var} in @var{list} by @var{function}
+This clause iterates @var{var} over all the elements of @var{list},
+in turn. If you specify the @code{by} term, then @var{function}
+is used to traverse the list instead of @code{cdr}; it must be a
+function taking one argument. For example:
+
+@example
+(loop for x in '(1 2 3 4 5 6) collect (* x x))
+ @result{} (1 4 9 16 25 36)
+(loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
+ @result{} (1 9 25)
+@end example
+
+@item for @var{var} on @var{list} by @var{function}
+This clause iterates @var{var} over all the cons cells of @var{list}.
+
+@example
+(loop for x on '(1 2 3 4) collect x)
+ @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
+@end example
+
+With @code{by}, there is no real reason that the @code{on} expression
+must be a list. For example:
+
+@example
+(loop for x on first-animal by 'next-animal collect x)
+@end example
+
+@noindent
+where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
+the next in the (assumed) sequence of animals, or @code{nil} if
+@var{x} was the last animal in the sequence.
+
+@item for @var{var} in-ref @var{list} by @var{function}
+This is like a regular @code{in} clause, but @var{var} becomes
+a @code{setf}-able ``reference'' onto the elements of the list
+rather than just a temporary variable. For example,
+
+@example
+(loop for x in-ref my-list do (incf x))
+@end example
+
+@noindent
+increments every element of @code{my-list} in place. This clause
+is an extension to standard Common Lisp.
+
+@item for @var{var} across @var{array}
+This clause iterates @var{var} over all the elements of @var{array},
+which may be a vector or a string.
+
+@example
+(loop for x across "aeiou"
+ do (use-vowel (char-to-string x)))
+@end example
+
+@item for @var{var} across-ref @var{array}
+This clause iterates over an array, with @var{var} a @code{setf}-able
+reference onto the elements; see @code{in-ref} above.
+
+@item for @var{var} being the elements of @var{sequence}
+This clause iterates over the elements of @var{sequence}, which may
+be a list, vector, or string. Since the type must be determined
+at run-time, this is somewhat less efficient than @code{in} or
+@code{across}. The clause may be followed by the additional term
+@samp{using (index @var{var2})} to cause @var{var2} to be bound to
+the successive indices (starting at 0) of the elements.
+
+This clause type is taken from older versions of the @code{loop} macro,
+and is not present in modern Common Lisp. The @samp{using (sequence ...)}
+term of the older macros is not supported.
+
+@item for @var{var} being the elements of-ref @var{sequence}
+This clause iterates over a sequence, with @var{var} a @code{setf}-able
+reference onto the elements; see @code{in-ref} above.
+
+@item for @var{var} being the symbols [of @var{obarray}]
+This clause iterates over symbols, either over all interned symbols
+or over all symbols in @var{obarray}. The loop is executed with
+@var{var} bound to each symbol in turn. The symbols are visited in
+an unspecified order.
+
+As an example,
+
+@example
+(loop for sym being the symbols
+ when (fboundp sym)
+ when (string-match "^map" (symbol-name sym))
+ collect sym)
+@end example
+
+@noindent
+returns a list of all the functions whose names begin with @samp{map}.
+
+The Common Lisp words @code{external-symbols} and @code{present-symbols}
+are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
+
+Due to a minor implementation restriction, it will not work to have
+more than one @code{for} clause iterating over symbols, hash tables,
+keymaps, overlays, or intervals in a given @code{loop}. Fortunately,
+it would rarely if ever be useful to do so. It @emph{is} legal to mix
+one of these types of clauses with other clauses like @code{for ... to}
+or @code{while}.
+
+@item for @var{var} being the hash-keys of @var{hash-table}
+This clause iterates over the entries in @var{hash-table}. For each
+hash table entry, @var{var} is bound to the entry's key. If you write
+@samp{the hash-values} instead, @var{var} is bound to the values
+of the entries. The clause may be followed by the additional
+term @samp{using (hash-values @var{var2})} (where @code{hash-values}
+is the opposite word of the word following @code{the}) to cause
+@var{var} and @var{var2} to be bound to the two parts of each
+hash table entry.
+
+@item for @var{var} being the key-codes of @var{keymap}
+This clause iterates over the entries in @var{keymap}. In GNU Emacs
+18 and 19, keymaps are either alists or vectors, and key-codes are
+integers or symbols. In Lucid Emacs 19, keymaps are a special new
+data type, and key-codes are symbols or lists of symbols. The
+iteration does not enter nested keymaps or inherited (parent) keymaps.
+You can use @samp{the key-bindings} to access the commands bound to
+the keys rather than the key codes, and you can add a @code{using}
+clause to access both the codes and the bindings together.
+
+@item for @var{var} being the key-seqs of @var{keymap}
+This clause iterates over all key sequences defined by @var{keymap}
+and its nested keymaps, where @var{var} takes on values which are
+strings in Emacs 18 or vectors in Emacs 19. The strings or vectors
+are reused for each iteration, so you must copy them if you wish to keep
+them permanently. You can add a @samp{using (key-bindings ...)}
+clause to get the command bindings as well.
+
+@item for @var{var} being the overlays [of @var{buffer}] @dots{}
+This clause iterates over the Emacs 19 ``overlays'' or Lucid
+Emacs ``extents'' of a buffer (the clause @code{extents} is synonymous
+with @code{overlays}). Under Emacs 18, this clause iterates zero
+times. If the @code{of} term is omitted, the current buffer is used.
+This clause also accepts optional @samp{from @var{pos}} and
+@samp{to @var{pos}} terms, limiting the clause to overlays which
+overlap the specified region.
+
+@item for @var{var} being the intervals [of @var{buffer}] @dots{}
+This clause iterates over all intervals of a buffer with constant
+text properties. The variable @var{var} will be bound to conses
+of start and end positions, where one start position is always equal
+to the previous end position. The clause allows @code{of},
+@code{from}, @code{to}, and @code{property} terms, where the latter
+term restricts the search to just the specified property. The
+@code{of} term may specify either a buffer or a string. This
+clause is useful only in GNU Emacs 19; in other versions, all
+buffers and strings consist of a single interval.
+
+@item for @var{var} being the frames
+This clause iterates over all frames, i.e., X window system windows
+open on Emacs files. This clause works only under Emacs 19. The
+clause @code{screens} is a synonym for @code{frames}. The frames
+are visited in @code{next-frame} order starting from
+@code{selected-frame}.
+
+@item for @var{var} being the windows [of @var{frame}]
+This clause iterates over the windows (in the Emacs sense) of
+the current frame, or of the specified @var{frame}. (In Emacs 18
+there is only ever one frame, and the @code{of} term is not
+allowed there.)
+
+@item for @var{var} being the buffers
+This clause iterates over all buffers in Emacs. It is equivalent
+to @samp{for @var{var} in (buffer-list)}.
+
+@item for @var{var} = @var{expr1} then @var{expr2}
+This clause does a general iteration. The first time through
+the loop, @var{var} will be bound to @var{expr1}. On the second
+and successive iterations it will be set by evaluating @var{expr2}
+(which may refer to the old value of @var{var}). For example,
+these two loops are effectively the same:
+
+@example
+(loop for x on my-list by 'cddr do ...)
+(loop for x = my-list then (cddr x) while x do ...)
+@end example
+
+Note that this type of @code{for} clause does not imply any sort
+of terminating condition; the above example combines it with a
+@code{while} clause to tell when to end the loop.
+
+If you omit the @code{then} term, @var{expr1} is used both for
+the initial setting and for successive settings:
+
+@example
+(loop for x = (random) when (> x 0) return x)
+@end example
+
+@noindent
+This loop keeps taking random numbers from the @code{(random)}
+function until it gets a positive one, which it then returns.
+@end table
+
+If you include several @code{for} clauses in a row, they are
+treated sequentially (as if by @code{let*} and @code{setq}).
+You can instead use the word @code{and} to link the clauses,
+in which case they are processed in parallel (as if by @code{let}
+and @code{psetq}).
+
+@example
+(loop for x below 5 for y = nil then x collect (list x y))
+ @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
+(loop for x below 5 and y = nil then x collect (list x y))
+ @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
+@end example
+
+@noindent
+In the first loop, @code{y} is set based on the value of @code{x}
+that was just set by the previous clause; in the second loop,
+@code{x} and @code{y} are set simultaneously so @code{y} is set
+based on the value of @code{x} left over from the previous time
+through the loop.
+
+Another feature of the @code{loop} macro is @dfn{destructuring},
+similar in concept to the destructuring provided by @code{defmacro}.
+The @var{var} part of any @code{for} clause can be given as a list
+of variables instead of a single variable. The values produced
+during loop execution must be lists; the values in the lists are
+stored in the corresponding variables.
+
+@example
+(loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
+ @result{} (5 9 13)
+@end example
+
+In loop destructuring, if there are more values than variables
+the trailing values are ignored, and if there are more variables
+than values the trailing variables get the value @code{nil}.
+If @code{nil} is used as a variable name, the corresponding
+values are ignored. Destructuring may be nested, and dotted
+lists of variables like @code{(x . y)} are allowed.
+
+@node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility
+@subsection Iteration Clauses
+
+@noindent
+Aside from @code{for} clauses, there are several other loop clauses
+that control the way the loop operates. They might be used by
+themselves, or in conjunction with one or more @code{for} clauses.
+
+@table @code
+@item repeat @var{integer}
+This clause simply counts up to the specified number using an
+internal temporary variable. The loops
+
+@example
+(loop repeat n do ...)
+(loop for temp to n do ...)
+@end example
+
+@noindent
+are identical except that the second one forces you to choose
+a name for a variable you aren't actually going to use.
+
+@item while @var{condition}
+This clause stops the loop when the specified condition (any Lisp
+expression) becomes @code{nil}. For example, the following two
+loops are equivalent, except for the implicit @code{nil} block
+that surrounds the second one:
+
+@example
+(while @var{cond} @var{forms}@dots{})
+(loop while @var{cond} do @var{forms}@dots{})
+@end example
+
+@item until @var{condition}
+This clause stops the loop when the specified condition is true,
+i.e., non-@code{nil}.
+
+@item always @var{condition}
+This clause stops the loop when the specified condition is @code{nil}.
+Unlike @code{while}, it stops the loop using @code{return nil} so that
+the @code{finally} clauses are not executed. If all the conditions
+were non-@code{nil}, the loop returns @code{t}:
+
+@example
+(if (loop for size in size-list always (> size 10))
+ (some-big-sizes)
+ (no-big-sizes))
+@end example
+
+@item never @var{condition}
+This clause is like @code{always}, except that the loop returns
+@code{t} if any conditions were false, or @code{nil} otherwise.
+
+@item thereis @var{condition}
+This clause stops the loop when the specified form is non-@code{nil};
+in this case, it returns that non-@code{nil} value. If all the
+values were @code{nil}, the loop returns @code{nil}.
+@end table
+
+@node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility
+@subsection Accumulation Clauses
+
+@noindent
+These clauses cause the loop to accumulate information about the
+specified Lisp @var{form}. The accumulated result is returned
+from the loop unless overridden, say, by a @code{return} clause.
+
+@table @code
+@item collect @var{form}
+This clause collects the values of @var{form} into a list. Several
+examples of @code{collect} appear elsewhere in this manual.
+
+The word @code{collecting} is a synonym for @code{collect}, and
+likewise for the other accumulation clauses.
+
+@item append @var{form}
+This clause collects lists of values into a result list using
+@code{append}.
+
+@item nconc @var{form}
+This clause collects lists of values into a result list by
+destructively modifying the lists rather than copying them.
+
+@item concat @var{form}
+This clause concatenates the values of the specified @var{form}
+into a string. (It and the following clause are extensions to
+standard Common Lisp.)
+
+@item vconcat @var{form}
+This clause concatenates the values of the specified @var{form}
+into a vector.
+
+@item count @var{form}
+This clause counts the number of times the specified @var{form}
+evaluates to a non-@code{nil} value.
+
+@item sum @var{form}
+This clause accumulates the sum of the values of the specified
+@var{form}, which must evaluate to a number.
+
+@item maximize @var{form}
+This clause accumulates the maximum value of the specified @var{form},
+which must evaluate to a number. The return value is undefined if
+@code{maximize} is executed zero times.
+
+@item minimize @var{form}
+This clause accumulates the minimum value of the specified @var{form}.
+@end table
+
+Accumulation clauses can be followed by @samp{into @var{var}} to
+cause the data to be collected into variable @var{var} (which is
+automatically @code{let}-bound during the loop) rather than an
+unnamed temporary variable. Also, @code{into} accumulations do
+not automatically imply a return value. The loop must use some
+explicit mechanism, such as @code{finally return}, to return
+the accumulated result.
+
+It is legal for several accumulation clauses of the same type to
+accumulate into the same place. From Steele:
+
+@example
+(loop for name in '(fred sue alice joe june)
+ for kids in '((bob ken) () () (kris sunshine) ())
+ collect name
+ append kids)
+ @result{} (fred bob ken sue alice joe kris sunshine june)
+@end example
+
+@node Other Clauses, , Accumulation Clauses, Loop Facility
+@subsection Other Clauses
+
+@noindent
+This section describes the remaining loop clauses.
+
+@table @code
+@item with @var{var} = @var{value}
+This clause binds a variable to a value around the loop, but
+otherwise leaves the variable alone during the loop. The following
+loops are basically equivalent:
+
+@example
+(loop with x = 17 do ...)
+(let ((x 17)) (loop do ...))
+(loop for x = 17 then x do ...)
+@end example
+
+Naturally, the variable @var{var} might be used for some purpose
+in the rest of the loop. For example:
+
+@example
+(loop for x in my-list with res = nil do (push x res)
+ finally return res)
+@end example
+
+This loop inserts the elements of @code{my-list} at the front of
+a new list being accumulated in @code{res}, then returns the
+list @code{res} at the end of the loop. The effect is similar
+to that of a @code{collect} clause, but the list gets reversed
+by virtue of the fact that elements are being pushed onto the
+front of @code{res} rather than the end.
+
+If you omit the @code{=} term, the variable is initialized to
+@code{nil}. (Thus the @samp{= nil} in the above example is
+unnecessary.)
+
+Bindings made by @code{with} are sequential by default, as if
+by @code{let*}. Just like @code{for} clauses, @code{with} clauses
+can be linked with @code{and} to cause the bindings to be made by
+@code{let} instead.
+
+@item if @var{condition} @var{clause}
+This clause executes the following loop clause only if the specified
+condition is true. The following @var{clause} should be an accumulation,
+@code{do}, @code{return}, @code{if}, or @code{unless} clause.
+Several clauses may be linked by separating them with @code{and}.
+These clauses may be followed by @code{else} and a clause or clauses
+to execute if the condition was false. The whole construct may
+optionally be followed by the word @code{end} (which may be used to
+disambiguate an @code{else} or @code{and} in a nested @code{if}).
+
+The actual non-@code{nil} value of the condition form is available
+by the name @code{it} in the ``then'' part. For example:
+
+@example
+(setq funny-numbers '(6 13 -1))
+ @result{} (6 13 -1)
+(loop for x below 10
+ if (oddp x)
+ collect x into odds
+ and if (memq x funny-numbers) return (cdr it) end
+ else
+ collect x into evens
+ finally return (vector odds evens))
+ @result{} [(1 3 5 7 9) (0 2 4 6 8)]
+(setq funny-numbers '(6 7 13 -1))
+ @result{} (6 7 13 -1)
+(loop <@r{same thing again}>)
+ @result{} (13 -1)
+@end example
+
+Note the use of @code{and} to put two clauses into the ``then''
+part, one of which is itself an @code{if} clause. Note also that
+@code{end}, while normally optional, was necessary here to make
+it clear that the @code{else} refers to the outermost @code{if}
+clause. In the first case, the loop returns a vector of lists
+of the odd and even values of @var{x}. In the second case, the
+odd number 7 is one of the @code{funny-numbers} so the loop
+returns early; the actual returned value is based on the result
+of the @code{memq} call.
+
+@item when @var{condition} @var{clause}
+This clause is just a synonym for @code{if}.
+
+@item unless @var{condition} @var{clause}
+The @code{unless} clause is just like @code{if} except that the
+sense of the condition is reversed.
+
+@item named @var{name}
+This clause gives a name other than @code{nil} to the implicit
+block surrounding the loop. The @var{name} is the symbol to be
+used as the block name.
+
+@item initially [do] @var{forms}...
+This keyword introduces one or more Lisp forms which will be
+executed before the loop itself begins (but after any variables
+requested by @code{for} or @code{with} have been bound to their
+initial values). @code{initially} clauses can appear anywhere;
+if there are several, they are executed in the order they appear
+in the loop. The keyword @code{do} is optional.
+
+@item finally [do] @var{forms}...
+This introduces Lisp forms which will be executed after the loop
+finishes (say, on request of a @code{for} or @code{while}).
+@code{initially} and @code{finally} clauses may appear anywhere
+in the loop construct, but they are executed (in the specified
+order) at the beginning or end, respectively, of the loop.
+
+@item finally return @var{form}
+This says that @var{form} should be executed after the loop
+is done to obtain a return value. (Without this, or some other
+clause like @code{collect} or @code{return}, the loop will simply
+return @code{nil}.) Variables bound by @code{for}, @code{with},
+or @code{into} will still contain their final values when @var{form}
+is executed.
+
+@item do @var{forms}...
+The word @code{do} may be followed by any number of Lisp expressions
+which are executed as an implicit @code{progn} in the body of the
+loop. Many of the examples in this section illustrate the use of
+@code{do}.
+
+@item return @var{form}
+This clause causes the loop to return immediately. The following
+Lisp form is evaluated to give the return value of the @code{loop}
+form. The @code{finally} clauses, if any, are not executed.
+Of course, @code{return} is generally used inside an @code{if} or
+@code{unless}, as its use in a top-level loop clause would mean
+the loop would never get to ``loop'' more than once.
+
+The clause @samp{return @var{form}} is equivalent to
+@samp{do (return @var{form})} (or @code{return-from} if the loop
+was named). The @code{return} clause is implemented a bit more
+efficiently, though.
+@end table
+
+While there is no high-level way to add user extensions to @code{loop}
+(comparable to @code{defsetf} for @code{setf}, say), this package
+does offer two properties called @code{cl-loop-handler} and
+@code{cl-loop-for-handler} which are functions to be called when
+a given symbol is encountered as a top-level loop clause or
+@code{for} clause, respectively. Consult the source code in
+file @file{cl-macs.el} for details.
+
+This package's @code{loop} macro is compatible with that of Common
+Lisp, except that a few features are not implemented: @code{loop-finish}
+and data-type specifiers. Naturally, the @code{for} clauses which
+iterate over keymaps, overlays, intervals, frames, windows, and
+buffers are Emacs-specific extensions.
+
+@node Multiple Values, , Loop Facility, Control Structure
+@section Multiple Values
+
+@noindent
+Common Lisp functions can return zero or more results. Emacs Lisp
+functions, by contrast, always return exactly one result. This
+package makes no attempt to emulate Common Lisp multiple return
+values; Emacs versions of Common Lisp functions that return more
+than one value either return just the first value (as in
+@code{compiler-macroexpand}) or return a list of values (as in
+@code{get-setf-method}). This package @emph{does} define placeholders
+for the Common Lisp functions that work with multiple values, but
+in Emacs Lisp these functions simply operate on lists instead.
+The @code{values} form, for example, is a synonym for @code{list}
+in Emacs.
+
+@defspec multiple-value-bind (var@dots{}) values-form forms@dots{}
+This form evaluates @var{values-form}, which must return a list of
+values. It then binds the @var{var}s to these respective values,
+as if by @code{let}, and then executes the body @var{forms}.
+If there are more @var{var}s than values, the extra @var{var}s
+are bound to @code{nil}. If there are fewer @var{var}s than
+values, the excess values are ignored.
+@end defspec
+
+@defspec multiple-value-setq (var@dots{}) form
+This form evaluates @var{form}, which must return a list of values.
+It then sets the @var{var}s to these respective values, as if by
+@code{setq}. Extra @var{var}s or values are treated the same as
+in @code{multiple-value-bind}.
+@end defspec
+
+The older Quiroz package attempted a more faithful (but still
+imperfect) emulation of Common Lisp multiple values. The old
+method ``usually'' simulated true multiple values quite well,
+but under certain circumstances would leave spurious return
+values in memory where a later, unrelated @code{multiple-value-bind}
+form would see them.
+
+Since a perfect emulation is not feasible in Emacs Lisp, this
+package opts to keep it as simple and predictable as possible.
+
+@node Macros, Declarations, Control Structure, Top
+@chapter Macros
+
+@noindent
+This package implements the various Common Lisp features of
+@code{defmacro}, such as destructuring, @code{&environment},
+and @code{&body}. Top-level @code{&whole} is not implemented
+for @code{defmacro} due to technical difficulties.
+@xref{Argument Lists}.
+
+Destructuring is made available to the user by way of the
+following macro:
+
+@defspec destructuring-bind arglist expr forms@dots{}
+This macro expands to code which executes @var{forms}, with
+the variables in @var{arglist} bound to the list of values
+returned by @var{expr}. The @var{arglist} can include all
+the features allowed for @code{defmacro} argument lists,
+including destructuring. (The @code{&environment} keyword
+is not allowed.) The macro expansion will signal an error
+if @var{expr} returns a list of the wrong number of arguments
+or with incorrect keyword arguments.
+@end defspec
+
+This package also includes the Common Lisp @code{define-compiler-macro}
+facility, which allows you to define compile-time expansions and
+optimizations for your functions.
+
+@defspec define-compiler-macro name arglist forms@dots{}
+This form is similar to @code{defmacro}, except that it only expands
+calls to @var{name} at compile-time; calls processed by the Lisp
+interpreter are not expanded, nor are they expanded by the
+@code{macroexpand} function.
+
+The argument list may begin with a @code{&whole} keyword and a
+variable. This variable is bound to the macro-call form itself,
+i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
+If the macro expander returns this form unchanged, then the
+compiler treats it as a normal function call. This allows
+compiler macros to work as optimizers for special cases of a
+function, leaving complicated cases alone.
+
+For example, here is a simplified version of a definition that
+appears as a standard part of this package:
+
+@example
+(define-compiler-macro member* (&whole form a list &rest keys)
+ (if (and (null keys)
+ (eq (car-safe a) 'quote)
+ (not (floatp-safe (cadr a))))
+ (list 'memq a list)
+ form))
+@end example
+
+@noindent
+This definition causes @code{(member* @var{a} @var{list})} to change
+to a call to the faster @code{memq} in the common case where @var{a}
+is a non-floating-point constant; if @var{a} is anything else, or
+if there are any keyword arguments in the call, then the original
+@code{member*} call is left intact. (The actual compiler macro
+for @code{member*} optimizes a number of other cases, including
+common @code{:test} predicates.)
+@end defspec
+
+@defun compiler-macroexpand form
+This function is analogous to @code{macroexpand}, except that it
+expands compiler macros rather than regular macros. It returns
+@var{form} unchanged if it is not a call to a function for which
+a compiler macro has been defined, or if that compiler macro
+decided to punt by returning its @code{&whole} argument. Like
+@code{macroexpand}, it expands repeatedly until it reaches a form
+for which no further expansion is possible.
+@end defun
+
+@xref{Macro Bindings}, for descriptions of the @code{macrolet}
+and @code{symbol-macrolet} forms for making ``local'' macro
+definitions.
+
+@node Declarations, Symbols, Macros, Top
+@chapter Declarations
+
+@noindent
+Common Lisp includes a complex and powerful ``declaration''
+mechanism that allows you to give the compiler special hints
+about the types of data that will be stored in particular variables,
+and about the ways those variables and functions will be used. This
+package defines versions of all the Common Lisp declaration forms:
+@code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
+and @code{the}.
+
+Most of the Common Lisp declarations are not currently useful in
+Emacs Lisp, as the byte-code system provides little opportunity
+to benefit from type information, and @code{special} declarations
+are redundant in a fully dynamically-scoped Lisp. A few
+declarations are meaningful when the optimizing Emacs 19 byte
+compiler is being used, however. Under the earlier non-optimizing
+compiler, these declarations will effectively be ignored.
+
+@defun proclaim decl-spec
+This function records a ``global'' declaration specified by
+@var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec}
+is evaluated and thus should normally be quoted.
+@end defun
+
+@defspec declaim decl-specs@dots{}
+This macro is like @code{proclaim}, except that it takes any number
+of @var{decl-spec} arguments, and the arguments are unevaluated and
+unquoted. The @code{declaim} macro also puts an @code{(eval-when
+(compile load eval) ...)} around the declarations so that they will
+be registered at compile-time as well as at run-time. (This is vital,
+since normally the declarations are meant to influence the way the
+compiler treats the rest of the file that contains the @code{declaim}
+form.)
+@end defspec
+
+@defspec declare decl-specs@dots{}
+This macro is used to make declarations within functions and other
+code. Common Lisp allows declarations in various locations, generally
+at the beginning of any of the many ``implicit @code{progn}s''
+throughout Lisp syntax, such as function bodies, @code{let} bodies,
+etc. Currently the only declaration understood by @code{declare}
+is @code{special}.
+@end defspec
+
+@defspec locally declarations@dots{} forms@dots{}
+In this package, @code{locally} is no different from @code{progn}.
+@end defspec
+
+@defspec the type form
+Type information provided by @code{the} is ignored in this package;
+in other words, @code{(the @var{type} @var{form})} is equivalent
+to @var{form}. Future versions of the optimizing byte-compiler may
+make use of this information.
+
+For example, @code{mapcar} can map over both lists and arrays. It is
+hard for the compiler to expand @code{mapcar} into an in-line loop
+unless it knows whether the sequence will be a list or an array ahead
+of time. With @code{(mapcar 'car (the vector foo))}, a future
+compiler would have enough information to expand the loop in-line.
+For now, Emacs Lisp will treat the above code as exactly equivalent
+to @code{(mapcar 'car foo)}.
+@end defspec
+
+Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or
+@code{declare} should be a list beginning with a symbol that says
+what kind of declaration it is. This package currently understands
+@code{special}, @code{inline}, @code{notinline}, @code{optimize},
+and @code{warn} declarations. (The @code{warn} declaration is an
+extension of standard Common Lisp.) Other Common Lisp declarations,
+such as @code{type} and @code{ftype}, are silently ignored.
+
+@table @code
+@item special
+Since all variables in Emacs Lisp are ``special'' (in the Common
+Lisp sense), @code{special} declarations are only advisory. They
+simply tell the optimizing byte compiler that the specified
+variables are intentionally being referred to without being
+bound in the body of the function. The compiler normally emits
+warnings for such references, since they could be typographical
+errors for references to local variables.
+
+The declaration @code{(declare (special @var{var1} @var{var2}))} is
+equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
+optimizing compiler, or to nothing at all in older compilers (which
+do not warn for non-local references).
+
+In top-level contexts, it is generally better to write
+@code{(defvar @var{var})} than @code{(declaim (special @var{var}))},
+since @code{defvar} makes your intentions clearer. But the older
+byte compilers can not handle @code{defvar}s appearing inside of
+functions, while @code{(declare (special @var{var}))} takes care
+to work correctly with all compilers.
+
+@item inline
+The @code{inline} @var{decl-spec} lists one or more functions
+whose bodies should be expanded ``in-line'' into calling functions
+whenever the compiler is able to arrange for it. For example,
+the Common Lisp function @code{cadr} is declared @code{inline}
+by this package so that the form @code{(cadr @var{x})} will
+expand directly into @code{(car (cdr @var{x}))} when it is called
+in user functions, for a savings of one (relatively expensive)
+function call.
+
+The following declarations are all equivalent. Note that the
+@code{defsubst} form is a convenient way to define a function
+and declare it inline all at once, but it is available only in
+Emacs 19.
+
+@example
+(declaim (inline foo bar))
+(eval-when (compile load eval) (proclaim '(inline foo bar)))
+(proclaim-inline foo bar) ; Lucid Emacs only
+(defsubst foo (...) ...) ; instead of defun; Emacs 19 only
+@end example
+
+@strong{Note:} This declaration remains in effect after the
+containing source file is done. It is correct to use it to
+request that a function you have defined should be inlined,
+but it is impolite to use it to request inlining of an external
+function.
+
+In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
+before a particular call to a function to cause just that call to
+be inlined; the current byte compilers provide no way to implement
+this, so @code{(declare (inline @dots{}))} is currently ignored by
+this package.
+
+@item notinline
+The @code{notinline} declaration lists functions which should
+not be inlined after all; it cancels a previous @code{inline}
+declaration.
+
+@item optimize
+This declaration controls how much optimization is performed by
+the compiler. Naturally, it is ignored by the earlier non-optimizing
+compilers.
+
+The word @code{optimize} is followed by any number of lists like
+@code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
+optimization ``qualities''; this package ignores all but @code{speed}
+and @code{safety}. The value of a quality should be an integer from
+0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.''
+The default level for both qualities is 1.
+
+In this package, with the Emacs 19 optimizing compiler, the
+@code{speed} quality is tied to the @code{byte-compile-optimize}
+flag, which is set to @code{nil} for @code{(speed 0)} and to
+@code{t} for higher settings; and the @code{safety} quality is
+tied to the @code{byte-compile-delete-errors} flag, which is
+set to @code{t} for @code{(safety 3)} and to @code{nil} for all
+lower settings. (The latter flag controls whether the compiler
+is allowed to optimize out code whose only side-effect could
+be to signal an error, e.g., rewriting @code{(progn foo bar)} to
+@code{bar} when it is not known whether @code{foo} will be bound
+at run-time.)
+
+Note that even compiling with @code{(safety 0)}, the Emacs
+byte-code system provides sufficient checking to prevent real
+harm from being done. For example, barring serious bugs in
+Emacs itself, Emacs will not crash with a segmentation fault
+just because of an error in a fully-optimized Lisp program.
+
+The @code{optimize} declaration is normally used in a top-level
+@code{proclaim} or @code{declaim} in a file; Common Lisp allows
+it to be used with @code{declare} to set the level of optimization
+locally for a given form, but this will not work correctly with the
+current version of the optimizing compiler. (The @code{declare}
+will set the new optimization level, but that level will not
+automatically be unset after the enclosing form is done.)
+
+@item warn
+This declaration controls what sorts of warnings are generated
+by the byte compiler. Again, only the optimizing compiler
+generates warnings. The word @code{warn} is followed by any
+number of ``warning qualities,'' similar in form to optimization
+qualities. The currently supported warning types are
+@code{redefine}, @code{callargs}, @code{unresolved}, and
+@code{free-vars}; in the current system, a value of 0 will
+disable these warnings and any higher value will enable them.
+See the documentation for the optimizing byte compiler for details.
+@end table
+
+@node Symbols, Numbers, Declarations, Top
+@chapter Symbols
+
+@noindent
+This package defines several symbol-related features that were
+missing from Emacs Lisp.
+
+@menu
+* Property Lists:: `get*', `remprop', `getf', `remf'
+* Creating Symbols:: `gensym', `gentemp'
+@end menu
+
+@node Property Lists, Creating Symbols, Symbols, Symbols
+@section Property Lists
+
+@noindent
+These functions augment the standard Emacs Lisp functions @code{get}
+and @code{put} for operating on properties attached to symbols.
+There are also functions for working with property lists as
+first-class data structures not attached to particular symbols.
+
+@defun get* symbol property &optional default
+This function is like @code{get}, except that if the property is
+not found, the @var{default} argument provides the return value.
+(The Emacs Lisp @code{get} function always uses @code{nil} as
+the default; this package's @code{get*} is equivalent to Common
+Lisp's @code{get}.)
+
+The @code{get*} function is @code{setf}-able; when used in this
+fashion, the @var{default} argument is allowed but ignored.
+@end defun
+
+@defun remprop symbol property
+This function removes the entry for @var{property} from the property
+list of @var{symbol}. It returns a true value if the property was
+indeed found and removed, or @code{nil} if there was no such property.
+(This function was probably omitted from Emacs originally because,
+since @code{get} did not allow a @var{default}, it was very difficult
+to distinguish between a missing property and a property whose value
+was @code{nil}; thus, setting a property to @code{nil} was close
+enough to @code{remprop} for most purposes.)
+@end defun
+
+@defun getf place property &optional default
+This function scans the list @var{place} as if it were a property
+list, i.e., a list of alternating property names and values. If
+an even-numbered element of @var{place} is found which is @code{eq}
+to @var{property}, the following odd-numbered element is returned.
+Otherwise, @var{default} is returned (or @code{nil} if no default
+is given).
+
+In particular,
+
+@example
+(get sym prop) @equiv{} (getf (symbol-plist sym) prop)
+@end example
+
+It is legal to use @code{getf} as a @code{setf} place, in which case
+its @var{place} argument must itself be a legal @code{setf} place.
+The @var{default} argument, if any, is ignored in this context.
+The effect is to change (via @code{setcar}) the value cell in the
+list that corresponds to @var{property}, or to cons a new property-value
+pair onto the list if the property is not yet present.
+
+@example
+(put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val)
+@end example
+
+The @code{get} and @code{get*} functions are also @code{setf}-able.
+The fact that @code{default} is ignored can sometimes be useful:
+
+@example
+(incf (get* 'foo 'usage-count 0))
+@end example
+
+Here, symbol @code{foo}'s @code{usage-count} property is incremented
+if it exists, or set to 1 (an incremented 0) otherwise.
+
+When not used as a @code{setf} form, @code{getf} is just a regular
+function and its @var{place} argument can actually be any Lisp
+expression.
+@end defun
+
+@defspec remf place property
+This macro removes the property-value pair for @var{property} from
+the property list stored at @var{place}, which is any @code{setf}-able
+place expression. It returns true if the property was found. Note
+that if @var{property} happens to be first on the list, this will
+effectively do a @code{(setf @var{place} (cddr @var{place}))},
+whereas if it occurs later, this simply uses @code{setcdr} to splice
+out the property and value cells.
+@end defspec
+
+@iftex
+@secno=2
+@end iftex
+
+@node Creating Symbols, , Property Lists, Symbols
+@section Creating Symbols
+
+@noindent
+These functions create unique symbols, typically for use as
+temporary variables.
+
+@defun gensym &optional x
+This function creates a new, uninterned symbol (using @code{make-symbol})
+with a unique name. (The name of an uninterned symbol is relevant
+only if the symbol is printed.) By default, the name is generated
+from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
+@samp{G1002}, etc. If the optional argument @var{x} is a string, that
+string is used as a prefix instead of @samp{G}. Uninterned symbols
+are used in macro expansions for temporary variables, to ensure that
+their names will not conflict with ``real'' variables in the user's
+code.
+@end defun
+
+@defvar *gensym-counter*
+This variable holds the counter used to generate @code{gensym} names.
+It is incremented after each use by @code{gensym}. In Common Lisp
+this is initialized with 0, but this package initializes it with a
+random (time-dependent) value to avoid trouble when two files that
+each used @code{gensym} in their compilation are loaded together.
+(Uninterned symbols become interned when the compiler writes them
+out to a file and the Emacs loader loads them, so their names have to
+be treated a bit more carefully than in Common Lisp where uninterned
+symbols remain uninterned after loading.)
+@end defvar
+
+@defun gentemp &optional x
+This function is like @code{gensym}, except that it produces a new
+@emph{interned} symbol. If the symbol that is generated already
+exists, the function keeps incrementing the counter and trying
+again until a new symbol is generated.
+@end defun
+
+The Quiroz @file{cl.el} package also defined a @code{defkeyword}
+form for creating self-quoting keyword symbols. This package
+automatically creates all keywords that are called for by
+@code{&key} argument specifiers, and discourages the use of
+keywords as data unrelated to keyword arguments, so the
+@code{defkeyword} form has been discontinued.
+
+@iftex
+@chapno=11
+@end iftex
+
+@node Numbers, Sequences, Symbols, Top
+@chapter Numbers
+
+@noindent
+This section defines a few simple Common Lisp operations on numbers
+which were left out of Emacs Lisp.
+
+@menu
+* Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc.
+* Numerical Functions:: `abs', `expt', `floor*', etc.
+* Random Numbers:: `random*', `make-random-state'
+* Implementation Parameters:: `most-positive-fixnum', `most-positive-float'
+@end menu
+
+@iftex
+@secno=1
+@end iftex
+
+@node Predicates on Numbers, Numerical Functions, Numbers, Numbers
+@section Predicates on Numbers
+
+@noindent
+These functions return @code{t} if the specified condition is
+true of the numerical argument, or @code{nil} otherwise.
+
+@defun plusp number
+This predicate tests whether @var{number} is positive. It is an
+error if the argument is not a number.
+@end defun
+
+@defun minusp number
+This predicate tests whether @var{number} is negative. It is an
+error if the argument is not a number.
+@end defun
+
+@defun oddp integer
+This predicate tests whether @var{integer} is odd. It is an
+error if the argument is not an integer.
+@end defun
+
+@defun evenp integer
+This predicate tests whether @var{integer} is even. It is an
+error if the argument is not an integer.
+@end defun
+
+@defun floatp-safe object
+This predicate tests whether @var{object} is a floating-point
+number. On systems that support floating-point, this is equivalent
+to @code{floatp}. On other systems, this always returns @code{nil}.
+@end defun
+
+@iftex
+@secno=3
+@end iftex
+
+@node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers
+@section Numerical Functions
+
+@noindent
+These functions perform various arithmetic operations on numbers.
+
+@defun abs number
+This function returns the absolute value of @var{number}. (Newer
+versions of Emacs provide this as a built-in function; this package
+defines @code{abs} only for Emacs 18 versions which don't provide
+it as a primitive.)
+@end defun
+
+@defun expt base power
+This function returns @var{base} raised to the power of @var{number}.
+(Newer versions of Emacs provide this as a built-in function; this
+package defines @code{expt} only for Emacs 18 versions which don't
+provide it as a primitive.)
+@end defun
+
+@defun gcd &rest integers
+This function returns the Greatest Common Divisor of the arguments.
+For one argument, it returns the absolute value of that argument.
+For zero arguments, it returns zero.
+@end defun
+
+@defun lcm &rest integers
+This function returns the Least Common Multiple of the arguments.
+For one argument, it returns the absolute value of that argument.
+For zero arguments, it returns one.
+@end defun
+
+@defun isqrt integer
+This function computes the ``integer square root'' of its integer
+argument, i.e., the greatest integer less than or equal to the true
+square root of the argument.
+@end defun
+
+@defun floor* number &optional divisor
+This function implements the Common Lisp @code{floor} function.
+It is called @code{floor*} to avoid name conflicts with the
+simpler @code{floor} function built-in to Emacs 19.
+
+With one argument, @code{floor*} returns a list of two numbers:
+The argument rounded down (toward minus infinity) to an integer,
+and the ``remainder'' which would have to be added back to the
+first return value to yield the argument again. If the argument
+is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
+If the argument is an Emacs 19 floating-point number, the first
+result is a Lisp integer and the second is a Lisp float between
+0 (inclusive) and 1 (exclusive).
+
+With two arguments, @code{floor*} divides @var{number} by
+@var{divisor}, and returns the floor of the quotient and the
+corresponding remainder as a list of two numbers. If
+@code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})},
+then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
+between 0 (inclusive) and @var{r} (exclusive). Also, note
+that @code{(floor* @var{x})} is exactly equivalent to
+@code{(floor* @var{x} 1)}.
+
+This function is entirely compatible with Common Lisp's @code{floor}
+function, except that it returns the two results in a list since
+Emacs Lisp does not support multiple-valued functions.
+@end defun
+
+@defun ceiling* number &optional divisor
+This function implements the Common Lisp @code{ceiling} function,
+which is analogous to @code{floor} except that it rounds the
+argument or quotient of the arguments up toward plus infinity.
+The remainder will be between 0 and minus @var{r}.
+@end defun
+
+@defun truncate* number &optional divisor
+This function implements the Common Lisp @code{truncate} function,
+which is analogous to @code{floor} except that it rounds the
+argument or quotient of the arguments toward zero. Thus it is
+equivalent to @code{floor*} if the argument or quotient is
+positive, or to @code{ceiling*} otherwise. The remainder has
+the same sign as @var{number}.
+@end defun
+
+@defun round* number &optional divisor
+This function implements the Common Lisp @code{round} function,
+which is analogous to @code{floor} except that it rounds the
+argument or quotient of the arguments to the nearest integer.
+In the case of a tie (the argument or quotient is exactly
+halfway between two integers), it rounds to the even integer.
+@end defun
+
+@defun mod* number divisor
+This function returns the same value as the second return value
+of @code{floor}.
+@end defun
+
+@defun rem* number divisor
+This function returns the same value as the second return value
+of @code{truncate}.
+@end defun
+
+These definitions are compatible with those in the Quiroz
+@file{cl.el} package, except that this package appends @samp{*}
+to certain function names to avoid conflicts with existing
+Emacs 19 functions, and that the mechanism for returning
+multiple values is different.
+
+@iftex
+@secno=8
+@end iftex
+
+@node Random Numbers, Implementation Parameters, Numerical Functions, Numbers
+@section Random Numbers
+
+@noindent
+This package also provides an implementation of the Common Lisp
+random number generator. It uses its own additive-congruential
+algorithm, which is much more likely to give statistically clean
+random numbers than the simple generators supplied by many
+operating systems.
+
+@defun random* number &optional state
+This function returns a random nonnegative number less than
+@var{number}, and of the same type (either integer or floating-point).
+The @var{state} argument should be a @code{random-state} object
+which holds the state of the random number generator. The
+function modifies this state object as a side effect. If
+@var{state} is omitted, it defaults to the variable
+@code{*random-state*}, which contains a pre-initialized
+@code{random-state} object.
+@end defun
+
+@defvar *random-state*
+This variable contains the system ``default'' @code{random-state}
+object, used for calls to @code{random*} that do not specify an
+alternative state object. Since any number of programs in the
+Emacs process may be accessing @code{*random-state*} in interleaved
+fashion, the sequence generated from this variable will be
+irreproducible for all intents and purposes.
+@end defvar
+
+@defun make-random-state &optional state
+This function creates or copies a @code{random-state} object.
+If @var{state} is omitted or @code{nil}, it returns a new copy of
+@code{*random-state*}. This is a copy in the sense that future
+sequences of calls to @code{(random* @var{n})} and
+@code{(random* @var{n} @var{s})} (where @var{s} is the new
+random-state object) will return identical sequences of random
+numbers.
+
+If @var{state} is a @code{random-state} object, this function
+returns a copy of that object. If @var{state} is @code{t}, this
+function returns a new @code{random-state} object seeded from the
+date and time. As an extension to Common Lisp, @var{state} may also
+be an integer in which case the new object is seeded from that
+integer; each different integer seed will result in a completely
+different sequence of random numbers.
+
+It is legal to print a @code{random-state} object to a buffer or
+file and later read it back with @code{read}. If a program wishes
+to use a sequence of pseudo-random numbers which can be reproduced
+later for debugging, it can call @code{(make-random-state t)} to
+get a new sequence, then print this sequence to a file. When the
+program is later rerun, it can read the original run's random-state
+from the file.
+@end defun
+
+@defun random-state-p object
+This predicate returns @code{t} if @var{object} is a
+@code{random-state} object, or @code{nil} otherwise.
+@end defun
+
+@node Implementation Parameters, , Random Numbers, Numbers
+@section Implementation Parameters
+
+@noindent
+This package defines several useful constants having to with numbers.
+
+@defvar most-positive-fixnum
+This constant equals the largest value a Lisp integer can hold.
+It is typically @code{2^23-1} or @code{2^25-1}.
+@end defvar
+
+@defvar most-negative-fixnum
+This constant equals the smallest (most negative) value a Lisp
+integer can hold.
+@end defvar
+
+The following parameters have to do with floating-point numbers.
+This package determines their values by exercising the computer's
+floating-point arithmetic in various ways. Because this operation
+might be slow, the code for initializing them is kept in a separate
+function that must be called before the parameters can be used.
+
+@defun cl-float-limits
+This function makes sure that the Common Lisp floating-point
+parameters like @code{most-positive-float} have been initialized.
+Until it is called, these parameters will be @code{nil}. If this
+version of Emacs does not support floats (e.g., most versions of
+Emacs 18), the parameters will remain @code{nil}. If the parameters
+have already been initialized, the function returns immediately.
+
+The algorithm makes assumptions that will be valid for most modern
+machines, but will fail if the machine's arithmetic is extremely
+unusual, e.g., decimal.
+@end defun
+
+Since true Common Lisp supports up to four different floating-point
+precisions, it has families of constants like
+@code{most-positive-single-float}, @code{most-positive-double-float},
+@code{most-positive-long-float}, and so on. Emacs has only one
+floating-point precision, so this package omits the precision word
+from the constants' names.
+
+@defvar most-positive-float
+This constant equals the largest value a Lisp float can hold.
+For those systems whose arithmetic supports infinities, this is
+the largest @emph{finite} value. For IEEE machines, the value
+is approximately @code{1.79e+308}.
+@end defvar
+
+@defvar most-negative-float
+This constant equals the most-negative value a Lisp float can hold.
+(It is assumed to be equal to @code{(- most-positive-float)}.)
+@end defvar
+
+@defvar least-positive-float
+This constant equals the smallest Lisp float value greater than zero.
+For IEEE machines, it is about @code{4.94e-324} if denormals are
+supported or @code{2.22e-308} if not.
+@end defvar
+
+@defvar least-positive-normalized-float
+This constant equals the smallest @emph{normalized} Lisp float greater
+than zero, i.e., the smallest value for which IEEE denormalization
+will not result in a loss of precision. For IEEE machines, this
+value is about @code{2.22e-308}. For machines that do not support
+the concept of denormalization and gradual underflow, this constant
+will always equal @code{least-positive-float}.
+@end defvar
+
+@defvar least-negative-float
+This constant is the negative counterpart of @code{least-positive-float}.
+@end defvar
+
+@defvar least-negative-normalized-float
+This constant is the negative counterpart of
+@code{least-positive-normalized-float}.
+@end defvar
+
+@defvar float-epsilon
+This constant is the smallest positive Lisp float that can be added
+to 1.0 to produce a distinct value. Adding a smaller number to 1.0
+will yield 1.0 again due to roundoff. For IEEE machines, epsilon
+is about @code{2.22e-16}.
+@end defvar
+
+@defvar float-negative-epsilon
+This is the smallest positive value that can be subtracted from
+1.0 to produce a distinct value. For IEEE machines, it is about
+@code{1.11e-16}.
+@end defvar
+
+@iftex
+@chapno=13
+@end iftex
+
+@node Sequences, Lists, Numbers, Top
+@chapter Sequences
+
+@noindent
+Common Lisp defines a number of functions that operate on
+@dfn{sequences}, which are either lists, strings, or vectors.
+Emacs Lisp includes a few of these, notably @code{elt} and
+@code{length}; this package defines most of the rest.
+
+@menu
+* Sequence Basics:: Arguments shared by all sequence functions
+* Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc.
+* Sequence Functions:: `subseq', `remove*', `substitute', etc.
+* Searching Sequences:: `find', `position', `count', `search', etc.
+* Sorting Sequences:: `sort*', `stable-sort', `merge'
+@end menu
+
+@node Sequence Basics, Mapping over Sequences, Sequences, Sequences
+@section Sequence Basics
+
+@noindent
+Many of the sequence functions take keyword arguments; @pxref{Argument
+Lists}. All keyword arguments are optional and, if specified,
+may appear in any order.
+
+The @code{:key} argument should be passed either @code{nil}, or a
+function of one argument. This key function is used as a filter
+through which the elements of the sequence are seen; for example,
+@code{(find x y :key 'car)} is similar to @code{(assoc* x y)}:
+It searches for an element of the list whose @code{car} equals
+@code{x}, rather than for an element which equals @code{x} itself.
+If @code{:key} is omitted or @code{nil}, the filter is effectively
+the identity function.
+
+The @code{:test} and @code{:test-not} arguments should be either
+@code{nil}, or functions of two arguments. The test function is
+used to compare two sequence elements, or to compare a search value
+with sequence elements. (The two values are passed to the test
+function in the same order as the original sequence function
+arguments from which they are derived, or, if they both come from
+the same sequence, in the same order as they appear in that sequence.)
+The @code{:test} argument specifies a function which must return
+true (non-@code{nil}) to indicate a match; instead, you may use
+@code{:test-not} to give a function which returns @emph{false} to
+indicate a match. The default test function is @code{:test 'eql}.
+
+Many functions which take @var{item} and @code{:test} or @code{:test-not}
+arguments also come in @code{-if} and @code{-if-not} varieties,
+where a @var{predicate} function is passed instead of @var{item},
+and sequence elements match if the predicate returns true on them
+(or false in the case of @code{-if-not}). For example:
+
+@example
+(remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq)
+@end example
+
+@noindent
+to remove all zeros from sequence @code{seq}.
+
+Some operations can work on a subsequence of the argument sequence;
+these function take @code{:start} and @code{:end} arguments which
+default to zero and the length of the sequence, respectively.
+Only elements between @var{start} (inclusive) and @var{end}
+(exclusive) are affected by the operation. The @var{end} argument
+may be passed @code{nil} to signify the length of the sequence;
+otherwise, both @var{start} and @var{end} must be integers, with
+@code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
+If the function takes two sequence arguments, the limits are
+defined by keywords @code{:start1} and @code{:end1} for the first,
+and @code{:start2} and @code{:end2} for the second.
+
+A few functions accept a @code{:from-end} argument, which, if
+non-@code{nil}, causes the operation to go from right-to-left
+through the sequence instead of left-to-right, and a @code{:count}
+argument, which specifies an integer maximum number of elements
+to be removed or otherwise processed.
+
+The sequence functions make no guarantees about the order in
+which the @code{:test}, @code{:test-not}, and @code{:key} functions
+are called on various elements. Therefore, it is a bad idea to depend
+on side effects of these functions. For example, @code{:from-end}
+may cause the sequence to be scanned actually in reverse, or it may
+be scanned forwards but computing a result ``as if'' it were scanned
+backwards. (Some functions, like @code{mapcar*} and @code{every},
+@emph{do} specify exactly the order in which the function is called
+so side effects are perfectly acceptable in those cases.)
+
+Strings in GNU Emacs 19 may contain ``text properties'' as well
+as character data. Except as noted, it is undefined whether or
+not text properties are preserved by sequence functions. For
+example, @code{(remove* ?A @var{str})} may or may not preserve
+the properties of the characters copied from @var{str} into the
+result.
+
+@node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences
+@section Mapping over Sequences
+
+@noindent
+These functions ``map'' the function you specify over the elements
+of lists or arrays. They are all variations on the theme of the
+built-in function @code{mapcar}.
+
+@defun mapcar* function seq &rest more-seqs
+This function calls @var{function} on successive parallel sets of
+elements from its argument sequences. Given a single @var{seq}
+argument it is equivalent to @code{mapcar}; given @var{n} sequences,
+it calls the function with the first elements of each of the sequences
+as the @var{n} arguments to yield the first element of the result
+list, then with the second elements, and so on. The mapping stops as
+soon as the shortest sequence runs out. The argument sequences may
+be any mixture of lists, strings, and vectors; the return sequence
+is always a list.
+
+Common Lisp's @code{mapcar} accepts multiple arguments but works
+only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
+argument. This package's @code{mapcar*} works as a compatible
+superset of both.
+@end defun
+
+@defun map result-type function seq &rest more-seqs
+This function maps @var{function} over the argument sequences,
+just like @code{mapcar*}, but it returns a sequence of type
+@var{result-type} rather than a list. @var{result-type} must
+be one of the following symbols: @code{vector}, @code{string},
+@code{list} (in which case the effect is the same as for
+@code{mapcar*}), or @code{nil} (in which case the results are
+thrown away and @code{map} returns @code{nil}).
+@end defun
+
+@defun maplist function list &rest more-lists
+This function calls @var{function} on each of its argument lists,
+then on the @code{cdr}s of those lists, and so on, until the
+shortest list runs out. The results are returned in the form
+of a list. Thus, @code{maplist} is like @code{mapcar*} except
+that it passes in the list pointers themselves rather than the
+@code{car}s of the advancing pointers.
+@end defun
+
+@defun mapc function seq &rest more-seqs
+This function is like @code{mapcar*}, except that the values
+returned by @var{function} are ignored and thrown away rather
+than being collected into a list. The return value of @code{mapc}
+is @var{seq}, the first sequence.
+@end defun
+
+@defun mapl function list &rest more-lists
+This function is like @code{maplist}, except that it throws away
+the values returned by @var{function}.
+@end defun
+
+@defun mapcan function seq &rest more-seqs
+This function is like @code{mapcar*}, except that it concatenates
+the return values (which must be lists) using @code{nconc},
+rather than simply collecting them into a list.
+@end defun
+
+@defun mapcon function list &rest more-lists
+This function is like @code{maplist}, except that it concatenates
+the return values using @code{nconc}.
+@end defun
+
+@defun some predicate seq &rest more-seqs
+This function calls @var{predicate} on each element of @var{seq}
+in turn; if @var{predicate} returns a non-@code{nil} value,
+@code{some} returns that value, otherwise it returns @code{nil}.
+Given several sequence arguments, it steps through the sequences
+in parallel until the shortest one runs out, just as in
+@code{mapcar*}. You can rely on the left-to-right order in which
+the elements are visited, and on the fact that mapping stops
+immediately as soon as @var{predicate} returns non-@code{nil}.
+@end defun
+
+@defun every predicate seq &rest more-seqs
+This function calls @var{predicate} on each element of the sequence(s)
+in turn; it returns @code{nil} as soon as @var{predicate} returns
+@code{nil} for any element, or @code{t} if the predicate was true
+for all elements.
+@end defun
+
+@defun notany predicate seq &rest more-seqs
+This function calls @var{predicate} on each element of the sequence(s)
+in turn; it returns @code{nil} as soon as @var{predicate} returns
+a non-@code{nil} value for any element, or @code{t} if the predicate
+was @code{nil} for all elements.
+@end defun
+
+@defun notevery predicate seq &rest more-seqs
+This function calls @var{predicate} on each element of the sequence(s)
+in turn; it returns a non-@code{nil} value as soon as @var{predicate}
+returns @code{nil} for any element, or @code{t} if the predicate was
+true for all elements.
+@end defun
+
+@defun reduce function seq @t{&key :from-end :start :end :initial-value :key}
+This function combines the elements of @var{seq} using an associative
+binary operation. Suppose @var{function} is @code{*} and @var{seq} is
+the list @code{(2 3 4 5)}. The first two elements of the list are
+combined with @code{(* 2 3) = 6}; this is combined with the next
+element, @code{(* 6 4) = 24}, and that is combined with the final
+element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
+to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
+an explicit call to @code{reduce}.
+
+If @code{:from-end} is true, the reduction is right-associative instead
+of left-associative:
+
+@example
+(reduce '- '(1 2 3 4))
+ @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
+(reduce '- '(1 2 3 4) :from-end t)
+ @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
+@end example
+
+If @code{:key} is specified, it is a function of one argument which
+is called on each of the sequence elements in turn.
+
+If @code{:initial-value} is specified, it is effectively added to the
+front (or rear in the case of @code{:from-end}) of the sequence.
+The @code{:key} function is @emph{not} applied to the initial value.
+
+If the sequence, including the initial value, has exactly one element
+then that element is returned without ever calling @var{function}.
+If the sequence is empty (and there is no initial value), then
+@var{function} is called with no arguments to obtain the return value.
+@end defun
+
+All of these mapping operations can be expressed conveniently in
+terms of the @code{loop} macro. In compiled code, @code{loop} will
+be faster since it generates the loop as in-line code with no
+function calls.
+
+@node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences
+@section Sequence Functions
+
+@noindent
+This section describes a number of Common Lisp functions for
+operating on sequences.
+
+@defun subseq sequence start &optional end
+This function returns a given subsequence of the argument
+@var{sequence}, which may be a list, string, or vector.
+The indices @var{start} and @var{end} must be in range, and
+@var{start} must be no greater than @var{end}. If @var{end}
+is omitted, it defaults to the length of the sequence. The
+return value is always a copy; it does not share structure
+with @var{sequence}.
+
+As an extension to Common Lisp, @var{start} and/or @var{end}
+may be negative, in which case they represent a distance back
+from the end of the sequence. This is for compatibility with
+Emacs' @code{substring} function. Note that @code{subseq} is
+the @emph{only} sequence function that allows negative
+@var{start} and @var{end}.
+
+You can use @code{setf} on a @code{subseq} form to replace a
+specified range of elements with elements from another sequence.
+The replacement is done as if by @code{replace}, described below.
+@end defun
+
+@defun concatenate result-type &rest seqs
+This function concatenates the argument sequences together to
+form a result sequence of type @var{result-type}, one of the
+symbols @code{vector}, @code{string}, or @code{list}. The
+arguments are always copied, even in cases such as
+@code{(concatenate 'list '(1 2 3))} where the result is
+identical to an argument.
+@end defun
+
+@defun fill seq item @t{&key :start :end}
+This function fills the elements of the sequence (or the specified
+part of the sequence) with the value @var{item}.
+@end defun
+
+@defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
+This function copies part of @var{seq2} into part of @var{seq1}.
+The sequence @var{seq1} is not stretched or resized; the amount
+of data copied is simply the shorter of the source and destination
+(sub)sequences. The function returns @var{seq1}.
+
+If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
+will work correctly even if the regions indicated by the start
+and end arguments overlap. However, if @var{seq1} and @var{seq2}
+are lists which share storage but are not @code{eq}, and the
+start and end arguments specify overlapping regions, the effect
+is undefined.
+@end defun
+
+@defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end}
+This returns a copy of @var{seq} with all elements matching
+@var{item} removed. The result may share storage with or be
+@code{eq} to @var{seq} in some circumstances, but the original
+@var{seq} will not be modified. The @code{:test}, @code{:test-not},
+and @code{:key} arguments define the matching test that is used;
+by default, elements @code{eql} to @var{item} are removed. The
+@code{:count} argument specifies the maximum number of matching
+elements that can be removed (only the leftmost @var{count} matches
+are removed). The @code{:start} and @code{:end} arguments specify
+a region in @var{seq} in which elements will be removed; elements
+outside that region are not matched or removed. The @code{:from-end}
+argument, if true, says that elements should be deleted from the
+end of the sequence rather than the beginning (this matters only
+if @var{count} was also specified).
+@end defun
+
+@defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end}
+This deletes all elements of @var{seq} which match @var{item}.
+It is a destructive operation. Since Emacs Lisp does not support
+stretchable strings or vectors, this is the same as @code{remove*}
+for those sequence types. On lists, @code{remove*} will copy the
+list if necessary to preserve the original list, whereas
+@code{delete*} will splice out parts of the argument list.
+Compare @code{append} and @code{nconc}, which are analogous
+non-destructive and destructive list operations in Emacs Lisp.
+@end defun
+
+@findex remove-if
+@findex remove-if-not
+@findex delete-if
+@findex delete-if-not
+The predicate-oriented functions @code{remove-if}, @code{remove-if-not},
+@code{delete-if}, and @code{delete-if-not} are defined similarly.
+
+@defun delete item list
+This MacLisp-compatible function deletes from @var{list} all elements
+which are @code{equal} to @var{item}. The @code{delete} function is
+built-in to Emacs 19; this package defines it equivalently in Emacs 18.
+@end defun
+
+@defun remove item list
+This function removes from @var{list} all elements which are
+@code{equal} to @var{item}. This package defines it for symmetry
+with @code{delete}, even though @code{remove} is not built-in to
+Emacs 19.
+@end defun
+
+@defun remq item list
+This function removes from @var{list} all elements which are
+@code{eq} to @var{item}. This package defines it for symmetry
+with @code{delq}, even though @code{remq} is not built-in to
+Emacs 19.
+@end defun
+
+@defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
+This function returns a copy of @var{seq} with duplicate elements
+removed. Specifically, if two elements from the sequence match
+according to the @code{:test}, @code{:test-not}, and @code{:key}
+arguments, only the rightmost one is retained. If @code{:from-end}
+is true, the leftmost one is retained instead. If @code{:start} or
+@code{:end} is specified, only elements within that subsequence are
+examined or removed.
+@end defun
+
+@defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
+This function deletes duplicate elements from @var{seq}. It is
+a destructive version of @code{remove-duplicates}.
+@end defun
+
+@defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
+This function returns a copy of @var{seq}, with all elements
+matching @var{old} replaced with @var{new}. The @code{:count},
+@code{:start}, @code{:end}, and @code{:from-end} arguments may be
+used to limit the number of substitutions made.
+@end defun
+
+@defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
+This is a destructive version of @code{substitute}; it performs
+the substitution using @code{setcar} or @code{aset} rather than
+by returning a changed copy of the sequence.
+@end defun
+
+@findex substitute-if
+@findex substitute-if-not
+@findex nsubstitute-if
+@findex nsubstitute-if-not
+The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if},
+and @code{nsubstitute-if-not} functions are defined similarly. For
+these, a @var{predicate} is given in place of the @var{old} argument.
+
+@node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences
+@section Searching Sequences
+
+@noindent
+These functions search for elements or subsequences in a sequence.
+(See also @code{member*} and @code{assoc*}; @pxref{Lists}.)
+
+@defun find item seq @t{&key :test :test-not :key :start :end :from-end}
+This function searches @var{seq} for an element matching @var{item}.
+If it finds a match, it returns the matching element. Otherwise,
+it returns @code{nil}. It returns the leftmost match, unless
+@code{:from-end} is true, in which case it returns the rightmost
+match. The @code{:start} and @code{:end} arguments may be used to
+limit the range of elements that are searched.
+@end defun
+
+@defun position item seq @t{&key :test :test-not :key :start :end :from-end}
+This function is like @code{find}, except that it returns the
+integer position in the sequence of the matching item rather than
+the item itself. The position is relative to the start of the
+sequence as a whole, even if @code{:start} is non-zero. The function
+returns @code{nil} if no matching element was found.
+@end defun
+
+@defun count item seq @t{&key :test :test-not :key :start :end}
+This function returns the number of elements of @var{seq} which
+match @var{item}. The result is always a nonnegative integer.
+@end defun
+
+@findex find-if
+@findex find-if-not
+@findex position-if
+@findex position-if-not
+@findex count-if
+@findex count-if-not
+The @code{find-if}, @code{find-if-not}, @code{position-if},
+@code{position-if-not}, @code{count-if}, and @code{count-if-not}
+functions are defined similarly.
+
+@defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
+This function compares the specified parts of @var{seq1} and
+@var{seq2}. If they are the same length and the corresponding
+elements match (according to @code{:test}, @code{:test-not},
+and @code{:key}), the function returns @code{nil}. If there is
+a mismatch, the function returns the index (relative to @var{seq1})
+of the first mismatching element. This will be the leftmost pair of
+elements which do not match, or the position at which the shorter of
+the two otherwise-matching sequences runs out.
+
+If @code{:from-end} is true, then the elements are compared from right
+to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
+If the sequences differ, then one plus the index of the rightmost
+difference (relative to @var{seq1}) is returned.
+
+An interesting example is @code{(mismatch str1 str2 :key 'upcase)},
+which compares two strings case-insensitively.
+@end defun
+
+@defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
+This function searches @var{seq2} for a subsequence that matches
+@var{seq1} (or part of it specified by @code{:start1} and
+@code{:end1}.) Only matches which fall entirely within the region
+defined by @code{:start2} and @code{:end2} will be considered.
+The return value is the index of the leftmost element of the
+leftmost match, relative to the start of @var{seq2}, or @code{nil}
+if no matches were found. If @code{:from-end} is true, the
+function finds the @emph{rightmost} matching subsequence.
+@end defun
+
+@node Sorting Sequences, , Searching Sequences, Sequences
+@section Sorting Sequences
+
+@defun sort* seq predicate @t{&key :key}
+This function sorts @var{seq} into increasing order as determined
+by using @var{predicate} to compare pairs of elements. @var{predicate}
+should return true (non-@code{nil}) if and only if its first argument
+is less than (not equal to) its second argument. For example,
+@code{<} and @code{string-lessp} are suitable predicate functions
+for sorting numbers and strings, respectively; @code{>} would sort
+numbers into decreasing rather than increasing order.
+
+This function differs from Emacs' built-in @code{sort} in that it
+can operate on any type of sequence, not just lists. Also, it
+accepts a @code{:key} argument which is used to preprocess data
+fed to the @var{predicate} function. For example,
+
+@example
+(setq data (sort data 'string-lessp :key 'downcase))
+@end example
+
+@noindent
+sorts @var{data}, a sequence of strings, into increasing alphabetical
+order without regard to case. A @code{:key} function of @code{car}
+would be useful for sorting association lists.
+
+The @code{sort*} function is destructive; it sorts lists by actually
+rearranging the @code{cdr} pointers in suitable fashion.
+@end defun
+
+@defun stable-sort seq predicate @t{&key :key}
+This function sorts @var{seq} @dfn{stably}, meaning two elements
+which are equal in terms of @var{predicate} are guaranteed not to
+be rearranged out of their original order by the sort.
+
+In practice, @code{sort*} and @code{stable-sort} are equivalent
+in Emacs Lisp because the underlying @code{sort} function is
+stable by default. However, this package reserves the right to
+use non-stable methods for @code{sort*} in the future.
+@end defun
+
+@defun merge type seq1 seq2 predicate @t{&key :key}
+This function merges two sequences @var{seq1} and @var{seq2} by
+interleaving their elements. The result sequence, of type @var{type}
+(in the sense of @code{concatenate}), has length equal to the sum
+of the lengths of the two input sequences. The sequences may be
+modified destructively. Order of elements within @var{seq1} and
+@var{seq2} is preserved in the interleaving; elements of the two
+sequences are compared by @var{predicate} (in the sense of
+@code{sort}) and the lesser element goes first in the result.
+When elements are equal, those from @var{seq1} precede those from
+@var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
+both sorted according to @var{predicate}, then the result will be
+a merged sequence which is (stably) sorted according to
+@var{predicate}.
+@end defun
+
+@node Lists, Hash Tables, Sequences, Top
+@chapter Lists
+
+@noindent
+The functions described here operate on lists.
+
+@menu
+* List Functions:: `caddr', `first', `last*', `list*', etc.
+* Substitution of Expressions:: `subst', `sublis', etc.
+* Lists as Sets:: `member*', `adjoin', `union', etc.
+* Association Lists:: `assoc*', `rassoc*', `acons', `pairlis'
+@end menu
+
+@node List Functions, Substitution of Expressions, Lists, Lists
+@section List Functions
+
+@noindent
+This section describes a number of simple operations on lists,
+i.e., chains of cons cells.
+
+@defun caddr x
+This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
+Likewise, this package defines all 28 @code{c@var{xxx}r} functions
+where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
+All of these functions are @code{setf}-able, and calls to them
+are expanded inline by the byte-compiler for maximum efficiency.
+@end defun
+
+@defun first x
+This function is a synonym for @code{(car @var{x})}. Likewise,
+the functions @code{second}, @code{third}, @dots{}, through
+@code{tenth} return the given element of the list @var{x}.
+@end defun
+
+@defun rest x
+This function is a synonym for @code{(cdr @var{x})}.
+@end defun
+
+@defun endp x
+Common Lisp defines this function to act like @code{null}, but
+signaling an error if @code{x} is neither a @code{nil} nor a
+cons cell. This package simply defines @code{endp} as a synonym
+for @code{null}.
+@end defun
+
+@defun list-length x
+This function returns the length of list @var{x}, exactly like
+@code{(length @var{x})}, except that if @var{x} is a circular
+list (where the cdr-chain forms a loop rather than terminating
+with @code{nil}), this function returns @code{nil}. (The regular
+@code{length} function would get stuck if given a circular list.)
+@end defun
+
+@defun last* x &optional n
+This function returns the last cons, or the @var{n}th-to-last cons,
+of the list @var{x}. If @var{n} is omitted it defaults to 1.
+The ``last cons'' means the first cons cell of the list whose
+@code{cdr} is not another cons cell. (For normal lists, the
+@code{cdr} of the last cons will be @code{nil}.) This function
+returns @code{nil} if @var{x} is @code{nil} or shorter than
+@var{n}. Note that the last @emph{element} of the list is
+@code{(car (last @var{x}))}.
+
+The Emacs function @code{last} does the same thing
+except that it does not handle the optional argument @var{n}.
+@end defun
+
+@defun butlast x &optional n
+This function returns the list @var{x} with the last element,
+or the last @var{n} elements, removed. If @var{n} is greater
+than zero it makes a copy of the list so as not to damage the
+original list. In general, @code{(append (butlast @var{x} @var{n})
+(last @var{x} @var{n}))} will return a list equal to @var{x}.
+@end defun
+
+@defun nbutlast x &optional n
+This is a version of @code{butlast} that works by destructively
+modifying the @code{cdr} of the appropriate element, rather than
+making a copy of the list.
+@end defun
+
+@defun list* arg &rest others
+This function constructs a list of its arguments. The final
+argument becomes the @code{cdr} of the last cell constructed.
+Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to
+@code{(cons @var{a} (cons @var{b} @var{c}))}, and
+@code{(list* @var{a} @var{b} nil)} is equivalent to
+@code{(list @var{a} @var{b})}.
+
+(Note that this function really is called @code{list*} in Common
+Lisp; it is not a name invented for this package like @code{member*}
+or @code{defun*}.)
+@end defun
+
+@defun ldiff list sublist
+If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
+one of the cons cells of @var{list}, then this function returns
+a copy of the part of @var{list} up to but not including
+@var{sublist}. For example, @code{(ldiff x (cddr x))} returns
+the first two elements of the list @code{x}. The result is a
+copy; the original @var{list} is not modified. If @var{sublist}
+is not a sublist of @var{list}, a copy of the entire @var{list}
+is returned.
+@end defun
+
+@defun copy-list list
+This function returns a copy of the list @var{list}. It copies
+dotted lists like @code{(1 2 . 3)} correctly.
+@end defun
+
+@defun copy-tree x &optional vecp
+This function returns a copy of the tree of cons cells @var{x}.
+Unlike @code{copy-sequence} (and its alias @code{copy-list}),
+which copies only along the @code{cdr} direction, this function
+copies (recursively) along both the @code{car} and the @code{cdr}
+directions. If @var{x} is not a cons cell, the function simply
+returns @var{x} unchanged. If the optional @var{vecp} argument
+is true, this function copies vectors (recursively) as well as
+cons cells.
+@end defun
+
+@defun tree-equal x y @t{&key :test :test-not :key}
+This function compares two trees of cons cells. If @var{x} and
+@var{y} are both cons cells, their @code{car}s and @code{cdr}s are
+compared recursively. If neither @var{x} nor @var{y} is a cons
+cell, they are compared by @code{eql}, or according to the
+specified test. The @code{:key} function, if specified, is
+applied to the elements of both trees. @xref{Sequences}.
+@end defun
+
+@iftex
+@secno=3
+@end iftex
+
+@node Substitution of Expressions, Lists as Sets, List Functions, Lists
+@section Substitution of Expressions
+
+@noindent
+These functions substitute elements throughout a tree of cons
+cells. (@xref{Sequence Functions}, for the @code{substitute}
+function, which works on just the top-level elements of a list.)
+
+@defun subst new old tree @t{&key :test :test-not :key}
+This function substitutes occurrences of @var{old} with @var{new}
+in @var{tree}, a tree of cons cells. It returns a substituted
+tree, which will be a copy except that it may share storage with
+the argument @var{tree} in parts where no substitutions occurred.
+The original @var{tree} is not modified. This function recurses
+on, and compares against @var{old}, both @code{car}s and @code{cdr}s
+of the component cons cells. If @var{old} is itself a cons cell,
+then matching cells in the tree are substituted as usual without
+recursively substituting in that cell. Comparisons with @var{old}
+are done according to the specified test (@code{eql} by default).
+The @code{:key} function is applied to the elements of the tree
+but not to @var{old}.
+@end defun
+
+@defun nsubst new old tree @t{&key :test :test-not :key}
+This function is like @code{subst}, except that it works by
+destructive modification (by @code{setcar} or @code{setcdr})
+rather than copying.
+@end defun
+
+@findex subst-if
+@findex subst-if-not
+@findex nsubst-if
+@findex nsubst-if-not
+The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and
+@code{nsubst-if-not} functions are defined similarly.
+
+@defun sublis alist tree @t{&key :test :test-not :key}
+This function is like @code{subst}, except that it takes an
+association list @var{alist} of @var{old}-@var{new} pairs.
+Each element of the tree (after applying the @code{:key}
+function, if any), is compared with the @code{car}s of
+@var{alist}; if it matches, it is replaced by the corresponding
+@code{cdr}.
+@end defun
+
+@defun nsublis alist tree @t{&key :test :test-not :key}
+This is a destructive version of @code{sublis}.
+@end defun
+
+@node Lists as Sets, Association Lists, Substitution of Expressions, Lists
+@section Lists as Sets
+
+@noindent
+These functions perform operations on lists which represent sets
+of elements.
+
+@defun member item list
+This MacLisp-compatible function searches @var{list} for an element
+which is @code{equal} to @var{item}. The @code{member} function is
+built-in to Emacs 19; this package defines it equivalently in Emacs 18.
+See the following function for a Common-Lisp compatible version.
+@end defun
+
+@defun member* item list @t{&key :test :test-not :key}
+This function searches @var{list} for an element matching @var{item}.
+If a match is found, it returns the cons cell whose @code{car} was
+the matching element. Otherwise, it returns @code{nil}. Elements
+are compared by @code{eql} by default; you can use the @code{:test},
+@code{:test-not}, and @code{:key} arguments to modify this behavior.
+@xref{Sequences}.
+
+Note that this function's name is suffixed by @samp{*} to avoid
+the incompatible @code{member} function defined in Emacs 19.
+(That function uses @code{equal} for comparisons; it is equivalent
+to @code{(member* @var{item} @var{list} :test 'equal)}.)
+@end defun
+
+@findex member-if
+@findex member-if-not
+The @code{member-if} and @code{member-if-not} functions
+analogously search for elements which satisfy a given predicate.
+
+@defun tailp sublist list
+This function returns @code{t} if @var{sublist} is a sublist of
+@var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
+any of its @code{cdr}s.
+@end defun
+
+@defun adjoin item list @t{&key :test :test-not :key}
+This function conses @var{item} onto the front of @var{list},
+like @code{(cons @var{item} @var{list})}, but only if @var{item}
+is not already present on the list (as determined by @code{member*}).
+If a @code{:key} argument is specified, it is applied to
+@var{item} as well as to the elements of @var{list} during
+the search, on the reasoning that @var{item} is ``about'' to
+become part of the list.
+@end defun
+
+@defun union list1 list2 @t{&key :test :test-not :key}
+This function combines two lists which represent sets of items,
+returning a list that represents the union of those two sets.
+The result list will contain all items which appear in @var{list1}
+or @var{list2}, and no others. If an item appears in both
+@var{list1} and @var{list2} it will be copied only once. If
+an item is duplicated in @var{list1} or @var{list2}, it is
+undefined whether or not that duplication will survive in the
+result list. The order of elements in the result list is also
+undefined.
+@end defun
+
+@defun nunion list1 list2 @t{&key :test :test-not :key}
+This is a destructive version of @code{union}; rather than copying,
+it tries to reuse the storage of the argument lists if possible.
+@end defun
+
+@defun intersection list1 list2 @t{&key :test :test-not :key}
+This function computes the intersection of the sets represented
+by @var{list1} and @var{list2}. It returns the list of items
+which appear in both @var{list1} and @var{list2}.
+@end defun
+
+@defun nintersection list1 list2 @t{&key :test :test-not :key}
+This is a destructive version of @code{intersection}. It
+tries to reuse storage of @var{list1} rather than copying.
+It does @emph{not} reuse the storage of @var{list2}.
+@end defun
+
+@defun set-difference list1 list2 @t{&key :test :test-not :key}
+This function computes the ``set difference'' of @var{list1}
+and @var{list2}, i.e., the set of elements that appear in
+@var{list1} but @emph{not} in @var{list2}.
+@end defun
+
+@defun nset-difference list1 list2 @t{&key :test :test-not :key}
+This is a destructive @code{set-difference}, which will try
+to reuse @var{list1} if possible.
+@end defun
+
+@defun set-exclusive-or list1 list2 @t{&key :test :test-not :key}
+This function computes the ``set exclusive or'' of @var{list1}
+and @var{list2}, i.e., the set of elements that appear in
+exactly one of @var{list1} and @var{list2}.
+@end defun
+
+@defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
+This is a destructive @code{set-exclusive-or}, which will try
+to reuse @var{list1} and @var{list2} if possible.
+@end defun
+
+@defun subsetp list1 list2 @t{&key :test :test-not :key}
+This function checks whether @var{list1} represents a subset
+of @var{list2}, i.e., whether every element of @var{list1}
+also appears in @var{list2}.
+@end defun
+
+@node Association Lists, , Lists as Sets, Lists
+@section Association Lists
+
+@noindent
+An @dfn{association list} is a list representing a mapping from
+one set of values to another; any list whose elements are cons
+cells is an association list.
+
+@defun assoc* item a-list @t{&key :test :test-not :key}
+This function searches the association list @var{a-list} for an
+element whose @code{car} matches (in the sense of @code{:test},
+@code{:test-not}, and @code{:key}, or by comparison with @code{eql})
+a given @var{item}. It returns the matching element, if any,
+otherwise @code{nil}. It ignores elements of @var{a-list} which
+are not cons cells. (This corresponds to the behavior of
+@code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
+@code{assoc} ignores @code{nil}s but considers any other non-cons
+elements of @var{a-list} to be an error.)
+@end defun
+
+@defun rassoc* item a-list @t{&key :test :test-not :key}
+This function searches for an element whose @code{cdr} matches
+@var{item}. If @var{a-list} represents a mapping, this applies
+the inverse of the mapping to @var{item}.
+@end defun
+
+@defun rassoc item a-list
+This function searches like @code{rassoc*} with a @code{:test}
+argument of @code{equal}. It is analogous to Emacs Lisp's
+standard @code{assoc} function, which derives from the MacLisp
+rather than the Common Lisp tradition.
+@end defun
+
+@findex assoc-if
+@findex assoc-if-not
+@findex rassoc-if
+@findex rassoc-if-not
+The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if},
+and @code{rassoc-if-not} functions are defined similarly.
+
+Two simple functions for constructing association lists are:
+
+@defun acons key value alist
+This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
+@end defun
+
+@defun pairlis keys values &optional alist
+This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values})
+@var{alist})}.
+@end defun
+
+@node Hash Tables, Structures, Lists, Top
+@chapter Hash Tables
+
+@noindent
+A @dfn{hash table} is a data structure that maps ``keys'' onto
+``values.'' Keys and values can be arbitrary Lisp data objects.
+Hash tables have the property that the time to search for a given
+key is roughly constant; simpler data structures like association
+lists take time proportional to the number of entries in the list.
+
+@defun make-hash-table @t{&key :test :size}
+This function creates and returns a hash-table object whose
+function for comparing elements is @code{:test} (@code{eql}
+by default), and which is allocated to fit about @code{:size}
+elements. The @code{:size} argument is purely advisory; the
+table will stretch automatically if you store more elements in
+it. If @code{:size} is omitted, a reasonable default is used.
+
+Common Lisp allows only @code{eq}, @code{eql}, @code{equal},
+and @code{equalp} as legal values for the @code{:test} argument.
+In this package, any reasonable predicate function will work,
+though if you use something else you should check the details of
+the hashing function described below to make sure it is suitable
+for your predicate.
+
+Some versions of Emacs (like Lucid Emacs 19) include a built-in
+hash table type; in these versions, @code{make-hash-table} with
+a test of @code{eq} will use these built-in hash tables. In all
+other cases, it will return a hash-table object which takes the
+form of a list with an identifying ``tag'' symbol at the front.
+All of the hash table functions in this package can operate on
+both types of hash table; normally you will never know which
+type is being used.
+
+This function accepts the additional Common Lisp keywords
+@code{:rehash-size} and @code{:rehash-threshold}, but it ignores
+their values.
+@end defun
+
+@defun gethash key table &optional default
+This function looks up @var{key} in @var{table}. If @var{key}
+exists in the table, in the sense that it matches any of the existing
+keys according to the table's test function, then the associated value
+is returned. Otherwise, @var{default} (or @code{nil}) is returned.
+
+To store new data in the hash table, use @code{setf} on a call to
+@code{gethash}. If @var{key} already exists in the table, the
+corresponding value is changed to the stored value. If @var{key}
+does not already exist, a new entry is added to the table and the
+table is reallocated to a larger size if necessary. The @var{default}
+argument is allowed but ignored in this case. The situation is
+exactly analogous to that of @code{get*}; @pxref{Property Lists}.
+@end defun
+
+@defun remhash key table
+This function removes the entry for @var{key} from @var{table}.
+If an entry was removed, it returns @code{t}. If @var{key} does
+not appear in the table, it does nothing and returns @code{nil}.
+@end defun
+
+@defun clrhash table
+This function removes all the entries from @var{table}, leaving
+an empty hash table.
+@end defun
+
+@defun maphash function table
+This function calls @var{function} for each entry in @var{table}.
+It passes two arguments to @var{function}, the key and the value
+of the given entry. The return value of @var{function} is ignored;
+@var{maphash} itself returns @code{nil}. @xref{Loop Facility}, for
+an alternate way of iterating over hash tables.
+@end defun
+
+@defun hash-table-count table
+This function returns the number of entries in @var{table}.
+@strong{Warning:} The current implementation of Lucid Emacs 19
+hash-tables does not decrement the stored @code{count} when
+@code{remhash} removes an entry. Therefore, the return value of
+this function is not dependable if you have used @code{remhash}
+on the table and the table's test is @code{eq}. A slower, but
+reliable, way to count the entries is @code{(loop for x being the
+hash-keys of @var{table} count t)}.
+@end defun
+
+@defun hash-table-p object
+This function returns @code{t} if @var{object} is a hash table,
+@code{nil} otherwise. It recognizes both types of hash tables
+(both Lucid Emacs built-in tables and tables implemented with
+special lists.)
+@end defun
+
+Sometimes when dealing with hash tables it is useful to know the
+exact ``hash function'' that is used. This package implements
+hash tables using Emacs Lisp ``obarrays,'' which are the same
+data structure that Emacs Lisp uses to keep track of symbols.
+Each hash table includes an embedded obarray. Key values given
+to @code{gethash} are converted by various means into strings,
+which are then looked up in the obarray using @code{intern} and
+@code{intern-soft}. The symbol, or ``bucket,'' corresponding to
+a given key string includes as its @code{symbol-value} an association
+list of all key-value pairs which hash to that string. Depending
+on the test function, it is possible for many entries to hash to
+the same bucket. For example, if the test is @code{eql}, then the
+symbol @code{foo} and two separately built strings @code{"foo"} will
+create three entries in the same bucket. Search time is linear
+within buckets, so hash tables will be most effective if you arrange
+not to store too many things that hash the same.
+
+The following algorithm is used to convert Lisp objects to hash
+strings:
+
+@itemize @bullet
+@item
+Strings are used directly as hash strings. (However, if the test
+function is @code{equalp}, strings are @code{downcase}d first.)
+
+@item
+Symbols are hashed according to their @code{symbol-name}.
+
+@item
+Integers are hashed into one of 16 buckets depending on their value
+modulo 16. Floating-point numbers are truncated to integers and
+hashed modulo 16.
+
+@item
+Cons cells are hashed according to their @code{car}s; nonempty vectors
+are hashed according to their first element.
+
+@item
+All other types of objects hash into a single bucket named @code{"*"}.
+@end itemize
+
+@noindent
+Thus, for example, searching among many buffer objects in a hash table
+will devolve to a (still fairly fast) linear-time search through a
+single bucket, whereas searching for different symbols will be very
+fast since each symbol will, in general, hash into its own bucket.
+
+The size of the obarray in a hash table is automatically adjusted
+as the number of elements increases.
+
+As a special case, @code{make-hash-table} with a @code{:size} argument
+of 0 or 1 will create a hash-table object that uses a single association
+list rather than an obarray of many lists. For very small tables this
+structure will be more efficient since lookup does not require
+converting the key to a string or looking it up in an obarray.
+However, such tables are guaranteed to take time proportional to
+their size to do a search.
+
+@iftex
+@chapno=18
+@end iftex
+
+@node Structures, Assertions, Hash Tables, Top
+@chapter Structures
+
+@noindent
+The Common Lisp @dfn{structure} mechanism provides a general way
+to define data types similar to C's @code{struct} types. A
+structure is a Lisp object containing some number of @dfn{slots},
+each of which can hold any Lisp data object. Functions are
+provided for accessing and setting the slots, creating or copying
+structure objects, and recognizing objects of a particular structure
+type.
+
+In true Common Lisp, each structure type is a new type distinct
+from all existing Lisp types. Since the underlying Emacs Lisp
+system provides no way to create new distinct types, this package
+implements structures as vectors (or lists upon request) with a
+special ``tag'' symbol to identify them.
+
+@defspec defstruct name slots@dots{}
+The @code{defstruct} form defines a new structure type called
+@var{name}, with the specified @var{slots}. (The @var{slots}
+may begin with a string which documents the structure type.)
+In the simplest case, @var{name} and each of the @var{slots}
+are symbols. For example,
+
+@example
+(defstruct person name age sex)
+@end example
+
+@noindent
+defines a struct type called @code{person} which contains three
+slots. Given a @code{person} object @var{p}, you can access those
+slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
+and @code{(person-sex @var{p})}. You can also change these slots by
+using @code{setf} on any of these place forms:
+
+@example
+(incf (person-age birthday-boy))
+@end example
+
+You can create a new @code{person} by calling @code{make-person},
+which takes keyword arguments @code{:name}, @code{:age}, and
+@code{:sex} to specify the initial values of these slots in the
+new object. (Omitting any of these arguments leaves the corresponding
+slot ``undefined,'' according to the Common Lisp standard; in Emacs
+Lisp, such uninitialized slots are filled with @code{nil}.)
+
+Given a @code{person}, @code{(copy-person @var{p})} makes a new
+object of the same type whose slots are @code{eq} to those of @var{p}.
+
+Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
+true if @var{x} looks like a @code{person}, false otherwise. (Again,
+in Common Lisp this predicate would be exact; in Emacs Lisp the
+best it can do is verify that @var{x} is a vector of the correct
+length which starts with the correct tag symbol.)
+
+Accessors like @code{person-name} normally check their arguments
+(effectively using @code{person-p}) and signal an error if the
+argument is the wrong type. This check is affected by
+@code{(optimize (safety @dots{}))} declarations. Safety level 1,
+the default, uses a somewhat optimized check that will detect all
+incorrect arguments, but may use an uninformative error message
+(e.g., ``expected a vector'' instead of ``expected a @code{person}'').
+Safety level 0 omits all checks except as provided by the underlying
+@code{aref} call; safety levels 2 and 3 do rigorous checking that will
+always print a descriptive error message for incorrect inputs.
+@xref{Declarations}.
+
+@example
+(setq dave (make-person :name "Dave" :sex 'male))
+ @result{} [cl-struct-person "Dave" nil male]
+(setq other (copy-person dave))
+ @result{} [cl-struct-person "Dave" nil male]
+(eq dave other)
+ @result{} nil
+(eq (person-name dave) (person-name other))
+ @result{} t
+(person-p dave)
+ @result{} t
+(person-p [1 2 3 4])
+ @result{} nil
+(person-p "Bogus")
+ @result{} nil
+(person-p '[cl-struct-person counterfeit person object])
+ @result{} t
+@end example
+
+In general, @var{name} is either a name symbol or a list of a name
+symbol followed by any number of @dfn{struct options}; each @var{slot}
+is either a slot symbol or a list of the form @samp{(@var{slot-name}
+@var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
+is a Lisp form which is evaluated any time an instance of the
+structure type is created without specifying that slot's value.
+
+Common Lisp defines several slot options, but the only one
+implemented in this package is @code{:read-only}. A non-@code{nil}
+value for this option means the slot should not be @code{setf}-able;
+the slot's value is determined when the object is created and does
+not change afterward.
+
+@example
+(defstruct person
+ (name nil :read-only t)
+ age
+ (sex 'unknown))
+@end example
+
+Any slot options other than @code{:read-only} are ignored.
+
+For obscure historical reasons, structure options take a different
+form than slot options. A structure option is either a keyword
+symbol, or a list beginning with a keyword symbol possibly followed
+by arguments. (By contrast, slot options are key-value pairs not
+enclosed in lists.)
+
+@example
+(defstruct (person (:constructor create-person)
+ (:type list)
+ :named)
+ name age sex)
+@end example
+
+The following structure options are recognized.
+
+@table @code
+@iftex
+@itemmax=0 in
+@advance@leftskip-.5@tableindent
+@end iftex
+@item :conc-name
+The argument is a symbol whose print name is used as the prefix for
+the names of slot accessor functions. The default is the name of
+the struct type followed by a hyphen. The option @code{(:conc-name p-)}
+would change this prefix to @code{p-}. Specifying @code{nil} as an
+argument means no prefix, so that the slot names themselves are used
+to name the accessor functions.
+
+@item :constructor
+In the simple case, this option takes one argument which is an
+alternate name to use for the constructor function. The default
+is @code{make-@var{name}}, e.g., @code{make-person}. The above
+example changes this to @code{create-person}. Specifying @code{nil}
+as an argument means that no standard constructor should be
+generated at all.
+
+In the full form of this option, the constructor name is followed
+by an arbitrary argument list. @xref{Program Structure}, for a
+description of the format of Common Lisp argument lists. All
+options, such as @code{&rest} and @code{&key}, are supported.
+The argument names should match the slot names; each slot is
+initialized from the corresponding argument. Slots whose names
+do not appear in the argument list are initialized based on the
+@var{default-value} in their slot descriptor. Also, @code{&optional}
+and @code{&key} arguments which don't specify defaults take their
+defaults from the slot descriptor. It is legal to include arguments
+which don't correspond to slot names; these are useful if they are
+referred to in the defaults for optional, keyword, or @code{&aux}
+arguments which @emph{do} correspond to slots.
+
+You can specify any number of full-format @code{:constructor}
+options on a structure. The default constructor is still generated
+as well unless you disable it with a simple-format @code{:constructor}
+option.
+
+@example
+(defstruct
+ (person
+ (:constructor nil) ; no default constructor
+ (:constructor new-person (name sex &optional (age 0)))
+ (:constructor new-hound (&key (name "Rover")
+ (dog-years 0)
+ &aux (age (* 7 dog-years))
+ (sex 'canine))))
+ name age sex)
+@end example
+
+The first constructor here takes its arguments positionally rather
+than by keyword. (In official Common Lisp terminology, constructors
+that work By Order of Arguments instead of by keyword are called
+``BOA constructors.'' No, I'm not making this up.) For example,
+@code{(new-person "Jane" 'female)} generates a person whose slots
+are @code{"Jane"}, 0, and @code{female}, respectively.
+
+The second constructor takes two keyword arguments, @code{:name},
+which initializes the @code{name} slot and defaults to @code{"Rover"},
+and @code{:dog-years}, which does not itself correspond to a slot
+but which is used to initialize the @code{age} slot. The @code{sex}
+slot is forced to the symbol @code{canine} with no syntax for
+overriding it.
+
+@item :copier
+The argument is an alternate name for the copier function for
+this type. The default is @code{copy-@var{name}}. @code{nil}
+means not to generate a copier function. (In this implementation,
+all copier functions are simply synonyms for @code{copy-sequence}.)
+
+@item :predicate
+The argument is an alternate name for the predicate which recognizes
+objects of this type. The default is @code{@var{name}-p}. @code{nil}
+means not to generate a predicate function. (If the @code{:type}
+option is used without the @code{:named} option, no predicate is
+ever generated.)
+
+In true Common Lisp, @code{typep} is always able to recognize a
+structure object even if @code{:predicate} was used. In this
+package, @code{typep} simply looks for a function called
+@code{@var{typename}-p}, so it will work for structure types
+only if they used the default predicate name.
+
+@item :include
+This option implements a very limited form of C++-style inheritance.
+The argument is the name of another structure type previously
+created with @code{defstruct}. The effect is to cause the new
+structure type to inherit all of the included structure's slots
+(plus, of course, any new slots described by this struct's slot
+descriptors). The new structure is considered a ``specialization''
+of the included one. In fact, the predicate and slot accessors
+for the included type will also accept objects of the new type.
+
+If there are extra arguments to the @code{:include} option after
+the included-structure name, these options are treated as replacement
+slot descriptors for slots in the included structure, possibly with
+modified default values. Borrowing an example from Steele:
+
+@example
+(defstruct person name (age 0) sex)
+ @result{} person
+(defstruct (astronaut (:include person (age 45)))
+ helmet-size
+ (favorite-beverage 'tang))
+ @result{} astronaut
+
+(setq joe (make-person :name "Joe"))
+ @result{} [cl-struct-person "Joe" 0 nil]
+(setq buzz (make-astronaut :name "Buzz"))
+ @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
+
+(list (person-p joe) (person-p buzz))
+ @result{} (t t)
+(list (astronaut-p joe) (astronaut-p buzz))
+ @result{} (nil t)
+
+(person-name buzz)
+ @result{} "Buzz"
+(astronaut-name joe)
+ @result{} error: "astronaut-name accessing a non-astronaut"
+@end example
+
+Thus, if @code{astronaut} is a specialization of @code{person},
+then every @code{astronaut} is also a @code{person} (but not the
+other way around). Every @code{astronaut} includes all the slots
+of a @code{person}, plus extra slots that are specific to
+astronauts. Operations that work on people (like @code{person-name})
+work on astronauts just like other people.
+
+@item :print-function
+In full Common Lisp, this option allows you to specify a function
+which is called to print an instance of the structure type. The
+Emacs Lisp system offers no hooks into the Lisp printer which would
+allow for such a feature, so this package simply ignores
+@code{:print-function}.
+
+@item :type
+The argument should be one of the symbols @code{vector} or @code{list}.
+This tells which underlying Lisp data type should be used to implement
+the new structure type. Vectors are used by default, but
+@code{(:type list)} will cause structure objects to be stored as
+lists instead.
+
+The vector representation for structure objects has the advantage
+that all structure slots can be accessed quickly, although creating
+vectors is a bit slower in Emacs Lisp. Lists are easier to create,
+but take a relatively long time accessing the later slots.
+
+@item :named
+This option, which takes no arguments, causes a characteristic ``tag''
+symbol to be stored at the front of the structure object. Using
+@code{:type} without also using @code{:named} will result in a
+structure type stored as plain vectors or lists with no identifying
+features.
+
+The default, if you don't specify @code{:type} explicitly, is to
+use named vectors. Therefore, @code{:named} is only useful in
+conjunction with @code{:type}.
+
+@example
+(defstruct (person1) name age sex)
+(defstruct (person2 (:type list) :named) name age sex)
+(defstruct (person3 (:type list)) name age sex)
+
+(setq p1 (make-person1))
+ @result{} [cl-struct-person1 nil nil nil]
+(setq p2 (make-person2))
+ @result{} (person2 nil nil nil)
+(setq p3 (make-person3))
+ @result{} (nil nil nil)
+
+(person1-p p1)
+ @result{} t
+(person2-p p2)
+ @result{} t
+(person3-p p3)
+ @result{} error: function person3-p undefined
+@end example
+
+Since unnamed structures don't have tags, @code{defstruct} is not
+able to make a useful predicate for recognizing them. Also,
+accessors like @code{person3-name} will be generated but they
+will not be able to do any type checking. The @code{person3-name}
+function, for example, will simply be a synonym for @code{car} in
+this case. By contrast, @code{person2-name} is able to verify
+that its argument is indeed a @code{person2} object before
+proceeding.
+
+@item :initial-offset
+The argument must be a nonnegative integer. It specifies a
+number of slots to be left ``empty'' at the front of the
+structure. If the structure is named, the tag appears at the
+specified position in the list or vector; otherwise, the first
+slot appears at that position. Earlier positions are filled
+with @code{nil} by the constructors and ignored otherwise. If
+the type @code{:include}s another type, then @code{:initial-offset}
+specifies a number of slots to be skipped between the last slot
+of the included type and the first new slot.
+@end table
+@end defspec
+
+Except as noted, the @code{defstruct} facility of this package is
+entirely compatible with that of Common Lisp.
+
+@iftex
+@chapno=23
+@end iftex
+
+@node Assertions, Efficiency Concerns, Structures, Top
+@chapter Assertions and Errors
+
+@noindent
+This section describes two macros that test @dfn{assertions}, i.e.,
+conditions which must be true if the program is operating correctly.
+Assertions never add to the behavior of a Lisp program; they simply
+make ``sanity checks'' to make sure everything is as it should be.
+
+If the optimization property @code{speed} has been set to 3, and
+@code{safety} is less than 3, then the byte-compiler will optimize
+away the following assertions. Because assertions might be optimized
+away, it is a bad idea for them to include side-effects.
+
+@defspec assert test-form [show-args string args@dots{}]
+This form verifies that @var{test-form} is true (i.e., evaluates to
+a non-@code{nil} value). If so, it returns @code{nil}. If the test
+is not satisfied, @code{assert} signals an error.
+
+A default error message will be supplied which includes @var{test-form}.
+You can specify a different error message by including a @var{string}
+argument plus optional extra arguments. Those arguments are simply
+passed to @code{error} to signal the error.
+
+If the optional second argument @var{show-args} is @code{t} instead
+of @code{nil}, then the error message (with or without @var{string})
+will also include all non-constant arguments of the top-level
+@var{form}. For example:
+
+@example
+(assert (> x 10) t "x is too small: %d")
+@end example
+
+This usage of @var{show-args} is an extension to Common Lisp. In
+true Common Lisp, the second argument gives a list of @var{places}
+which can be @code{setf}'d by the user before continuing from the
+error. Since Emacs Lisp does not support continuable errors, it
+makes no sense to specify @var{places}.
+@end defspec
+
+@defspec check-type form type [string]
+This form verifies that @var{form} evaluates to a value of type
+@var{type}. If so, it returns @code{nil}. If not, @code{check-type}
+signals a @code{wrong-type-argument} error. The default error message
+lists the erroneous value along with @var{type} and @var{form}
+themselves. If @var{string} is specified, it is included in the
+error message in place of @var{type}. For example:
+
+@example
+(check-type x (integer 1 *) "a positive integer")
+@end example
+
+@xref{Type Predicates}, for a description of the type specifiers
+that may be used for @var{type}.
+
+Note that in Common Lisp, the first argument to @code{check-type}
+must be a @var{place} suitable for use by @code{setf}, because
+@code{check-type} signals a continuable error that allows the
+user to modify @var{place}.
+@end defspec
+
+The following error-related macro is also defined:
+
+@defspec ignore-errors forms@dots{}
+This executes @var{forms} exactly like a @code{progn}, except that
+errors are ignored during the @var{forms}. More precisely, if
+an error is signaled then @code{ignore-errors} immediately
+aborts execution of the @var{forms} and returns @code{nil}.
+If the @var{forms} complete successfully, @code{ignore-errors}
+returns the result of the last @var{form}.
+@end defspec
+
+@node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top
+@appendix Efficiency Concerns
+
+@appendixsec Macros
+
+@noindent
+Many of the advanced features of this package, such as @code{defun*},
+@code{loop}, and @code{setf}, are implemented as Lisp macros. In
+byte-compiled code, these complex notations will be expanded into
+equivalent Lisp code which is simple and efficient. For example,
+the forms
+
+@example
+(incf i n)
+(push x (car p))
+@end example
+
+@noindent
+are expanded at compile-time to the Lisp forms
+
+@example
+(setq i (+ i n))
+(setcar p (cons x (car p)))
+@end example
+
+@noindent
+which are the most efficient ways of doing these respective operations
+in Lisp. Thus, there is no performance penalty for using the more
+readable @code{incf} and @code{push} forms in your compiled code.
+
+@emph{Interpreted} code, on the other hand, must expand these macros
+every time they are executed. For this reason it is strongly
+recommended that code making heavy use of macros be compiled.
+(The features labeled ``Special Form'' instead of ``Function'' in
+this manual are macros.) A loop using @code{incf} a hundred times
+will execute considerably faster if compiled, and will also
+garbage-collect less because the macro expansion will not have
+to be generated, used, and thrown away a hundred times.
+
+You can find out how a macro expands by using the
+@code{cl-prettyexpand} function.
+
+@defun cl-prettyexpand form &optional full
+This function takes a single Lisp form as an argument and inserts
+a nicely formatted copy of it in the current buffer (which must be
+in Lisp mode so that indentation works properly). It also expands
+all Lisp macros which appear in the form. The easiest way to use
+this function is to go to the @code{*scratch*} buffer and type, say,
+
+@example
+(cl-prettyexpand '(loop for x below 10 collect x))
+@end example
+
+@noindent
+and type @kbd{C-x C-e} immediately after the closing parenthesis;
+the expansion
+
+@example
+(block nil
+ (let* ((x 0)
+ (G1004 nil))
+ (while (< x 10)
+ (setq G1004 (cons x G1004))
+ (setq x (+ x 1)))
+ (nreverse G1004)))
+@end example
+
+@noindent
+will be inserted into the buffer. (The @code{block} macro is
+expanded differently in the interpreter and compiler, so
+@code{cl-prettyexpand} just leaves it alone. The temporary
+variable @code{G1004} was created by @code{gensym}.)
+
+If the optional argument @var{full} is true, then @emph{all}
+macros are expanded, including @code{block}, @code{eval-when},
+and compiler macros. Expansion is done as if @var{form} were
+a top-level form in a file being compiled. For example,
+
+@example
+(cl-prettyexpand '(pushnew 'x list))
+ @print{} (setq list (adjoin 'x list))
+(cl-prettyexpand '(pushnew 'x list) t)
+ @print{} (setq list (if (memq 'x list) list (cons 'x list)))
+(cl-prettyexpand '(caddr (member* 'a list)) t)
+ @print{} (car (cdr (cdr (memq 'a list))))
+@end example
+
+Note that @code{adjoin}, @code{caddr}, and @code{member*} all
+have built-in compiler macros to optimize them in common cases.
+@end defun
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@appendixsec Error Checking
+
+@noindent
+Common Lisp compliance has in general not been sacrificed for the
+sake of efficiency. A few exceptions have been made for cases
+where substantial gains were possible at the expense of marginal
+incompatibility. One example is the use of @code{memq} (which is
+treated very efficiently by the byte-compiler) to scan for keyword
+arguments; this can become confused in rare cases when keyword
+symbols are used as both keywords and data values at once. This
+is extremely unlikely to occur in practical code, and the use of
+@code{memq} allows functions with keyword arguments to be nearly
+as fast as functions that use @code{&optional} arguments.
+
+The Common Lisp standard (as embodied in Steele's book) uses the
+phrase ``it is an error if'' to indicate a situation which is not
+supposed to arise in complying programs; implementations are strongly
+encouraged but not required to signal an error in these situations.
+This package sometimes omits such error checking in the interest of
+compactness and efficiency. For example, @code{do} variable
+specifiers are supposed to be lists of one, two, or three forms;
+extra forms are ignored by this package rather than signaling a
+syntax error. The @code{endp} function is simply a synonym for
+@code{null} in this package. Functions taking keyword arguments
+will accept an odd number of arguments, treating the trailing
+keyword as if it were followed by the value @code{nil}.
+
+Argument lists (as processed by @code{defun*} and friends)
+@emph{are} checked rigorously except for the minor point just
+mentioned; in particular, keyword arguments are checked for
+validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
+are fully implemented. Keyword validity checking is slightly
+time consuming (though not too bad in byte-compiled code);
+you can use @code{&allow-other-keys} to omit this check. Functions
+defined in this package such as @code{find} and @code{member*}
+do check their keyword arguments for validity.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@appendixsec Optimizing Compiler
+
+@noindent
+The byte-compiler that comes with Emacs 18 normally fails to expand
+macros that appear in top-level positions in the file (i.e., outside
+of @code{defun}s or other enclosing forms). This would have
+disastrous consequences to programs that used such top-level macros
+as @code{defun*}, @code{eval-when}, and @code{defstruct}. To
+work around this problem, the @dfn{CL} package patches the Emacs
+18 compiler to expand top-level macros. This patch will apply to
+your own macros, too, if they are used in a top-level context.
+The patch will not harm versions of the Emacs 18 compiler which
+have already had a similar patch applied, nor will it affect the
+optimizing Emacs 19 byte-compiler written by Jamie Zawinski and
+Hallvard Furuseth. The patch is applied to the byte compiler's
+code in Emacs' memory, @emph{not} to the @file{bytecomp.elc} file
+stored on disk.
+
+The Emacs 19 compiler (for Emacs 18) is available from various
+Emacs Lisp archive sites such as @code{archive.cis.ohio-state.edu}.
+Its use is highly recommended; many of the Common Lisp macros emit
+code which can be improved by optimization. In particular,
+@code{block}s (whether explicit or implicit in constructs like
+@code{defun*} and @code{loop}) carry a fair run-time penalty; the
+optimizing compiler removes @code{block}s which are not actually
+referenced by @code{return} or @code{return-from} inside the block.
+
+@node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top
+@appendix Common Lisp Compatibility
+
+@noindent
+Following is a list of all known incompatibilities between this
+package and Common Lisp as documented in Steele (2nd edition).
+
+Certain function names, such as @code{member}, @code{assoc}, and
+@code{floor}, were already taken by (incompatible) Emacs Lisp
+functions; this package appends @samp{*} to the names of its
+Common Lisp versions of these functions.
+
+The word @code{defun*} is required instead of @code{defun} in order
+to use extended Common Lisp argument lists in a function. Likewise,
+@code{defmacro*} and @code{function*} are versions of those forms
+which understand full-featured argument lists. The @code{&whole}
+keyword does not work in @code{defmacro} argument lists (except
+inside recursive argument lists).
+
+In order to allow an efficient implementation, keyword arguments use
+a slightly cheesy parser which may be confused if a keyword symbol
+is passed as the @emph{value} of another keyword argument.
+(Specifically, @code{(memq :@var{keyword} @var{rest-of-arguments})}
+is used to scan for @code{:@var{keyword}} among the supplied
+keyword arguments.)
+
+The @code{eql} and @code{equal} predicates do not distinguish
+between IEEE floating-point plus and minus zero. The @code{equalp}
+predicate has several differences with Common Lisp; @pxref{Predicates}.
+
+The @code{setf} mechanism is entirely compatible, except that
+setf-methods return a list of five values rather than five
+values directly. Also, the new ``@code{setf} function'' concept
+(typified by @code{(defun (setf foo) @dots{})}) is not implemented.
+
+The @code{do-all-symbols} form is the same as @code{do-symbols}
+with no @var{obarray} argument. In Common Lisp, this form would
+iterate over all symbols in all packages. Since Emacs obarrays
+are not a first-class package mechanism, there is no way for
+@code{do-all-symbols} to locate any but the default obarray.
+
+The @code{loop} macro is complete except that @code{loop-finish}
+and type specifiers are unimplemented.
+
+The multiple-value return facility treats lists as multiple
+values, since Emacs Lisp cannot support multiple return values
+directly. The macros will be compatible with Common Lisp if
+@code{values} or @code{values-list} is always used to return to
+a @code{multiple-value-bind} or other multiple-value receiver;
+if @code{values} is used without @code{multiple-value-@dots{}}
+or vice-versa the effect will be different from Common Lisp.
+
+Many Common Lisp declarations are ignored, and others match
+the Common Lisp standard in concept but not in detail. For
+example, local @code{special} declarations, which are purely
+advisory in Emacs Lisp, do not rigorously obey the scoping rules
+set down in Steele's book.
+
+The variable @code{*gensym-counter*} starts out with a pseudo-random
+value rather than with zero. This is to cope with the fact that
+generated symbols become interned when they are written to and
+loaded back from a file.
+
+The @code{defstruct} facility is compatible, except that structures
+are of type @code{:type vector :named} by default rather than some
+special, distinct type. Also, the @code{:type} slot option is ignored.
+
+The second argument of @code{check-type} is treated differently.
+
+@node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top
+@appendix Old CL Compatibility
+
+@noindent
+Following is a list of all known incompatibilities between this package
+and the older Quiroz @file{cl.el} package.
+
+This package's emulation of multiple return values in functions is
+incompatible with that of the older package. That package attempted
+to come as close as possible to true Common Lisp multiple return
+values; unfortunately, it could not be 100% reliable and so was prone
+to occasional surprises if used freely. This package uses a simpler
+method, namely replacing multiple values with lists of values, which
+is more predictable though more noticeably different from Common Lisp.
+
+The @code{defkeyword} form and @code{keywordp} function are not
+implemented in this package.
+
+The @code{member}, @code{floor}, @code{ceiling}, @code{truncate},
+@code{round}, @code{mod}, and @code{rem} functions are suffixed
+by @samp{*} in this package to avoid collision with existing
+functions in Emacs 18 or Emacs 19. The older package simply
+redefined these functions, overwriting the built-in meanings and
+causing serious portability problems with Emacs 19. (Some more
+recent versions of the Quiroz package changed the names to
+@code{cl-member}, etc.; this package defines the latter names as
+aliases for @code{member*}, etc.)
+
+Certain functions in the old package which were buggy or inconsistent
+with the Common Lisp standard are incompatible with the conforming
+versions in this package. For example, @code{eql} and @code{member}
+were synonyms for @code{eq} and @code{memq} in that package, @code{setf}
+failed to preserve correct order of evaluation of its arguments, etc.
+
+Finally, unlike the older package, this package is careful to
+prefix all of its internal names with @code{cl-}. Except for a
+few functions which are explicitly defined as additional features
+(such as @code{floatp-safe} and @code{letf}), this package does not
+export any non-@samp{cl-} symbols which are not also part of Common
+Lisp.
+
+@ifinfo
+@example
+
+@end example
+@end ifinfo
+@appendixsec The @code{cl-compat} package
+
+@noindent
+The @dfn{CL} package includes emulations of some features of the
+old @file{cl.el}, in the form of a compatibility package
+@code{cl-compat}. To use it, put @code{(require 'cl-compat)} in
+your program.
+
+The old package defined a number of internal routines without
+@code{cl-} prefixes or other annotations. Call to these routines
+may have crept into existing Lisp code. @code{cl-compat}
+provides emulations of the following internal routines:
+@code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists},
+@code{reassemble-arglists}, @code{duplicate-symbols-p},
+@code{safe-idiv}.
+
+Some @code{setf} forms translated into calls to internal
+functions that user code might call directly. The functions
+@code{setnth}, @code{setnthcdr}, and @code{setelt} fall in
+this category; they are defined by @code{cl-compat}, but the
+best fix is to change to use @code{setf} properly.
+
+The @code{cl-compat} file defines the keyword functions
+@code{keywordp}, @code{keyword-of}, and @code{defkeyword},
+which are not defined by the new @dfn{CL} package because the
+use of keywords as data is discouraged.
+
+The @code{build-klist} mechanism for parsing keyword arguments
+is emulated by @code{cl-compat}; the @code{with-keyword-args}
+macro is not, however, and in any case it's best to change to
+use the more natural keyword argument processing offered by
+@code{defun*}.
+
+Multiple return values are treated differently by the two
+Common Lisp packages. The old package's method was more
+compatible with true Common Lisp, though it used heuristics
+that caused it to report spurious multiple return values in
+certain cases. The @code{cl-compat} package defines a set
+of multiple-value macros that are compatible with the old
+CL package; again, they are heuristic in nature, but they
+are guaranteed to work in any case where the old package's
+macros worked. To avoid name collision with the ``official''
+multiple-value facilities, the ones in @code{cl-compat} have
+capitalized names: @code{Values}, @code{Values-list},
+@code{Multiple-value-bind}, etc.
+
+The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate},
+and @code{cl-round} are defined by @code{cl-compat} to use the
+old-style multiple-value mechanism, just as they did in the old
+package. The newer @code{floor*} and friends return their two
+results in a list rather than as multiple values. Note that
+older versions of the old package used the unadorned names
+@code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use
+these names because they conflict with Emacs 19 built-ins.
+
+@node Porting Common Lisp, Function Index, Old CL Compatibility, Top
+@appendix Porting Common Lisp
+
+@noindent
+This package is meant to be used as an extension to Emacs Lisp,
+not as an Emacs implementation of true Common Lisp. Some of the
+remaining differences between Emacs Lisp and Common Lisp make it
+difficult to port large Common Lisp applications to Emacs. For
+one, some of the features in this package are not fully compliant
+with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
+are also quite a few features that this package does not provide
+at all. Here are some major omissions that you will want watch out
+for when bringing Common Lisp code into Emacs.
+
+@itemize @bullet
+@item
+Case-insensitivity. Symbols in Common Lisp are case-insensitive
+by default. Some programs refer to a function or variable as
+@code{foo} in one place and @code{Foo} or @code{FOO} in another.
+Emacs Lisp will treat these as three distinct symbols.
+
+Some Common Lisp code is written entirely in upper case. While Emacs
+is happy to let the program's own functions and variables use
+this convention, calls to Lisp builtins like @code{if} and
+@code{defun} will have to be changed to lower case.
+
+@item
+Lexical scoping. In Common Lisp, function arguments and @code{let}
+bindings apply only to references physically within their bodies
+(or within macro expansions in their bodies). Emacs Lisp, by
+contrast, uses @dfn{dynamic scoping} wherein a binding to a
+variable is visible even inside functions called from the body.
+
+Variables in Common Lisp can be made dynamically scoped by
+declaring them @code{special} or using @code{defvar}. In Emacs
+Lisp it is as if all variables were declared @code{special}.
+
+Often you can use code that was written for lexical scoping
+even in a dynamically scoped Lisp, but not always. Here is
+an example of a Common Lisp code fragment that would fail in
+Emacs Lisp:
+
+@example
+(defun map-odd-elements (func list)
+ (loop for x in list
+ for flag = t then (not flag)
+ collect (if flag x (funcall func x))))
+
+(defun add-odd-elements (list x)
+ (map-odd-elements (function (lambda (a) (+ a x))) list))
+@end example
+
+@noindent
+In Common Lisp, the two functions' usages of @code{x} are completely
+independent. In Emacs Lisp, the binding to @code{x} made by
+@code{add-odd-elements} will have been hidden by the binding
+in @code{map-odd-elements} by the time the @code{(+ a x)} function
+is called.
+
+(This package avoids such problems in its own mapping functions
+by using names like @code{cl-x} instead of @code{x} internally;
+as long as you don't use the @code{cl-} prefix for your own
+variables no collision can occur.)
+
+@xref{Lexical Bindings}, for a description of the @code{lexical-let}
+form which establishes a Common Lisp-style lexical binding, and some
+examples of how it differs from Emacs' regular @code{let}.
+
+@item
+Reader macros. Common Lisp includes a second type of macro that
+works at the level of individual characters. For example, Common
+Lisp implements the quote notation by a reader macro called @code{'},
+whereas Emacs Lisp's parser just treats quote as a special case.
+Some Lisp packages use reader macros to create special syntaxes
+for themselves, which the Emacs parser is incapable of reading.
+
+The lack of reader macros, incidentally, is the reason behind
+Emacs Lisp's unusual backquote syntax. Since backquotes are
+implemented as a Lisp package and not built-in to the Emacs
+parser, they are forced to use a regular macro named @code{`}
+which is used with the standard function/macro call notation.
+
+@item
+Other syntactic features. Common Lisp provides a number of
+notations beginning with @code{#} that the Emacs Lisp parser
+won't understand. For example, @samp{#| ... |#} is an
+alternate comment notation, and @samp{#+lucid (foo)} tells
+the parser to ignore the @code{(foo)} except in Lucid Common
+Lisp.
+
+@item
+Packages. In Common Lisp, symbols are divided into @dfn{packages}.
+Symbols that are Lisp built-ins are typically stored in one package;
+symbols that are vendor extensions are put in another, and each
+application program would have a package for its own symbols.
+Certain symbols are ``exported'' by a package and others are
+internal; certain packages ``use'' or import the exported symbols
+of other packages. To access symbols that would not normally be
+visible due to this importing and exporting, Common Lisp provides
+a syntax like @code{package:symbol} or @code{package::symbol}.
+
+Emacs Lisp has a single namespace for all interned symbols, and
+then uses a naming convention of putting a prefix like @code{cl-}
+in front of the name. Some Emacs packages adopt the Common Lisp-like
+convention of using @code{cl:} or @code{cl::} as the prefix.
+However, the Emacs parser does not understand colons and just
+treats them as part of the symbol name. Thus, while @code{mapcar}
+and @code{lisp:mapcar} may refer to the same symbol in Common
+Lisp, they are totally distinct in Emacs Lisp. Common Lisp
+programs which refer to a symbol by the full name sometimes
+and the short name other times will not port cleanly to Emacs.
+
+Emacs Lisp does have a concept of ``obarrays,'' which are
+package-like collections of symbols, but this feature is not
+strong enough to be used as a true package mechanism.
+
+@item
+The @code{format} function is quite different between Common
+Lisp and Emacs Lisp. It takes an additional ``destination''
+argument before the format string. A destination of @code{nil}
+means to format to a string as in Emacs Lisp; a destination
+of @code{t} means to write to the terminal (similar to
+@code{message} in Emacs). Also, format control strings are
+utterly different; @code{~} is used instead of @code{%} to
+introduce format codes, and the set of available codes is
+much richer. There are no notations like @code{\n} for
+string literals; instead, @code{format} is used with the
+``newline'' format code, @code{~%}. More advanced formatting
+codes provide such features as paragraph filling, case
+conversion, and even loops and conditionals.
+
+While it would have been possible to implement most of Common
+Lisp @code{format} in this package (under the name @code{format*},
+of course), it was not deemed worthwhile. It would have required
+a huge amount of code to implement even a decent subset of
+@code{format*}, yet the functionality it would provide over
+Emacs Lisp's @code{format} would rarely be useful.
+
+@item
+Vector constants use square brackets in Emacs Lisp, but
+@code{#(a b c)} notation in Common Lisp. To further complicate
+matters, Emacs 19 introduces its own @code{#(} notation for
+something entirely different---strings with properties.
+
+@item
+Characters are distinct from integers in Common Lisp. The
+notation for character constants is also different: @code{#\A}
+instead of @code{?A}. Also, @code{string=} and @code{string-equal}
+are synonyms in Emacs Lisp whereas the latter is case-insensitive
+in Common Lisp.
+
+@item
+Data types. Some Common Lisp data types do not exist in Emacs
+Lisp. Rational numbers and complex numbers are not present,
+nor are large integers (all integers are ``fixnums''). All
+arrays are one-dimensional. There are no readtables or pathnames;
+streams are a set of existing data types rather than a new data
+type of their own. Hash tables, random-states, structures, and
+packages (obarrays) are built from Lisp vectors or lists rather
+than being distinct types.
+
+@item
+The Common Lisp Object System (CLOS) is not implemented,
+nor is the Common Lisp Condition System. However, the EIEIO package
+from @uref{ftp://ftp.ultranet.com/pub/zappo} does implement some
+CLOS functionality.
+
+@item
+Common Lisp features that are completely redundant with Emacs
+Lisp features of a different name generally have not been
+implemented. For example, Common Lisp writes @code{defconstant}
+where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
+takes its arguments in different ways in the two Lisps but does
+exactly the same thing, so this package has not bothered to
+implement a Common Lisp-style @code{make-list}.
+
+@item
+A few more notable Common Lisp features not included in this
+package: @code{compiler-let}, @code{tagbody}, @code{prog},
+@code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
+
+@item
+Recursion. While recursion works in Emacs Lisp just like it
+does in Common Lisp, various details of the Emacs Lisp system
+and compiler make recursion much less efficient than it is in
+most Lisps. Some schools of thought prefer to use recursion
+in Lisp over other techniques; they would sum a list of
+numbers using something like
+
+@example
+(defun sum-list (list)
+ (if list
+ (+ (car list) (sum-list (cdr list)))
+ 0))
+@end example
+
+@noindent
+where a more iteratively-minded programmer might write one of
+these forms:
+
+@example
+(let ((total 0)) (dolist (x my-list) (incf total x)) total)
+(loop for x in my-list sum x)
+@end example
+
+While this would be mainly a stylistic choice in most Common Lisps,
+in Emacs Lisp you should be aware that the iterative forms are
+much faster than recursion. Also, Lisp programmers will want to
+note that the current Emacs Lisp compiler does not optimize tail
+recursion.
+@end itemize
+
+@node Function Index, Variable Index, Porting Common Lisp, Top
+@unnumbered Function Index
+
+@printindex fn
+
+@node Variable Index, , Function Index, Top
+@unnumbered Variable Index
+
+@printindex vr
+
+@contents
+@bye
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Command Arguments, Antinews, Service, Top
+@appendix Command Line Arguments
+@cindex command line arguments
+@cindex arguments (command line)
+@cindex options (command line)
+@cindex switches (command line)
+@cindex startup (command line arguments)
+
+ GNU Emacs supports command line arguments to request various actions
+when invoking Emacs. These are for compatibility with other editors and
+for sophisticated activities. We don't recommend using them for
+ordinary editing.
+
+ Arguments starting with @samp{-} are @dfn{options}. Other arguments
+specify files to visit. Emacs visits the specified files while it
+starts up. The last file name on your command line becomes the current
+buffer; the other files are also present in other buffers. As usual,
+the special argument @samp{--} says that all subsequent arguments
+are file names, not options, even if they start with @samp{-}.
+
+ Emacs command options can specify many things, such as the size and
+position of the X window Emacs uses, its colors, and so on. A few
+options support advanced usage, such as running Lisp functions on files
+in batch mode. The sections of this chapter describe the available
+options, arranged according to their purpose.
+
+ There are two ways of writing options: the short forms that start with
+a single @samp{-}, and the long forms that start with @samp{--}. For
+example, @samp{-d} is a short form and @samp{--display} is the
+corresponding long form.
+
+ The long forms with @samp{--} are easier to remember, but longer to
+type. However, you don't have to spell out the whole option name; any
+unambiguous abbreviation is enough. When a long option takes an
+argument, you can use either a space or an equal sign to separate the
+option name and the argument. Thus, you can write either
+@samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}.
+We recommend an equal sign because it makes the relationship clearer,
+and the tables below always show an equal sign.
+
+@cindex initial options (command line)
+@cindex action options (command line)
+ Most options specify how to initialize Emacs, or set parameters for
+the Emacs session. We call them @dfn{initial options}. A few options
+specify things to do: for example, load libraries, call functions, or
+exit Emacs. These are called @dfn{action options}. These and file
+names together are called @dfn{action arguments}. Emacs processes all
+the action arguments in the order they are written.
+
+@menu
+* Action Arguments:: Arguments to visit files, load libraries,
+ and call functions.
+* Initial Options:: Arguments that take effect while starting Emacs.
+* Command Example:: Examples of using command line arguments.
+* Resume Arguments:: Specifying arguments when you resume a running Emacs.
+* Environment:: Environment variables that Emacs uses.
+
+* Display X:: Changing the default display and using remote login.
+* Font X:: Choosing a font for text, under X.
+* Colors X:: Choosing colors, under X.
+* Window Size X:: Start-up window size, under X.
+* Borders X:: Internal and external borders, under X.
+* Title X:: Specifying the initial frame's title.
+* Icons X:: Choosing what sort of icon to use, under X.
+* Resources X:: Advanced use of classes and resources, under X.
+* Lucid Resources:: X resources for Lucid menus.
+* Motif Resources:: X resources for Motif menus.
+@end menu
+
+@node Action Arguments
+@appendixsec Action Arguments
+
+ Here is a table of the action arguments and options:
+
+@table @samp
+@item @var{file}
+Visit @var{file} using @code{find-file}. @xref{Visiting}.
+
+@item +@var{linenum} @var{file}
+Visit @var{file} using @code{find-file}, then go to line number
+@var{linenum} in it.
+
+@need 3000
+@item -l @var{file}
+@itemx --load=@var{file}
+Load a Lisp library named @var{file} with the function @code{load}.
+@xref{Lisp Libraries}. The library can be found either in the current
+directory, or in the Emacs library search path as specified
+with @code{EMACSLOADPATH} (@pxref{General Variables}).
+
+@item -f @var{function}
+@itemx --funcall=@var{function}
+Call Lisp function @var{function} with no arguments.
+
+@item --eval @var{expression}
+Evaluate Lisp expression @var{expression}.
+
+@item --insert=@var{file}
+Insert the contents of @var{file} into the current buffer. This is like
+what @kbd{M-x insert-file} does. @xref{Misc File Ops}.
+
+@item --kill
+Exit from Emacs without asking for confirmation.
+@end table
+
+@vindex command-line-args
+ The init file can access the values of the action arguments as the
+elements of a list in the variable @code{command-line-args}. The init
+file can override the normal processing of the action arguments, or
+define new ones, by reading and setting this variable.
+
+@node Initial Options
+@appendixsec Initial Options
+
+ The initial options specify parameters for the Emacs session. This
+section describes the more general initial options; some other options
+specifically related to X Windows appear in the following sections.
+
+ Some initial options affect the loading of init files. The normal
+actions of Emacs are to first load @file{site-start.el} if it exists,
+then your own init file @file{~/.emacs} if it exists, and finally
+@file{default.el} if it exists; certain options prevent loading of some
+of these files or substitute other files for them.
+
+@table @samp
+@item -t @var{device}
+@itemx --terminal=@var{device}
+Use @var{device} as the device for terminal input and output.
+
+@item -d @var{display}
+@itemx --display=@var{display}
+Use the X Window System and use the display named @var{display} to open
+the initial Emacs frame.
+
+@item -nw
+@itemx --no-windows
+Don't communicate directly with X, disregarding the @code{DISPLAY}
+environment variable even if it is set.
+
+@need 3000
+@cindex batch mode
+@item -batch
+@itemx --batch
+Run Emacs in @dfn{batch mode}, which means that the text being edited is
+not displayed and the standard terminal interrupt characters such as
+@kbd{C-z} and @kbd{C-c} continue to have their normal effect. Emacs in
+batch mode outputs to @code{stderr} only what would normally be printed
+in the echo area under program control.
+
+Batch mode is used for running programs written in Emacs Lisp from
+shell scripts, makefiles, and so on. Normally the @samp{-l} option
+or @samp{-f} option will be used as well, to invoke a Lisp program
+to do the batch processing.
+
+@samp{-batch} implies @samp{-q} (do not load an init file). It also causes
+Emacs to kill itself after all command options have been processed. In
+addition, auto-saving is not done except in buffers for which it has been
+explicitly requested.
+
+@item -q
+@itemx --no-init-file
+Do not load your Emacs init file @file{~/.emacs}, or @file{default.el}
+either.
+
+@item --no-site-file
+Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u}
+and @samp{-batch} have no effect on the loading of this file---this is
+the only option that blocks it.
+
+@item -u @var{user}
+@itemx --user=@var{user}
+Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
+your own.
+
+@item --debug-init
+Enable the Emacs Lisp debugger for errors in the init file.
+
+@item --unibyte
+@cindex unibyte operation
+Set up to do almost everything with single-byte buffers and strings.
+All buffers and strings are unibyte unless you (or a Lisp program)
+explicitly ask for a multibyte buffer or string. Setting the
+environment variable @code{EMACS_UNIBYTE} has the same effect.
+
+@item --multibyte
+Inhibit the effect of @code{EMACS_UNIBYTE}, so that Emacs
+uses multibyte characters by default, as usual.
+@end table
+
+@node Command Example
+@appendixsec Command Argument Example
+
+ Here is an example of using Emacs with arguments and options. It
+assumes you have a Lisp program file called @file{hack-c.el} which, when
+loaded, performs some useful operation on the current buffer, expected
+to be a C program.
+
+@example
+emacs -batch foo.c -l hack-c -f save-buffer >& log
+@end example
+
+@noindent
+This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
+changes in the visited file), save @file{foo.c} (note that
+@code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
+then exit back to the shell (because of @samp{-batch}). @samp{-batch}
+also guarantees there will be no problem redirecting output to
+@file{log}, because Emacs will not assume that it has a display terminal
+to work with.
+
+@node Resume Arguments
+@appendixsec Resuming Emacs with Arguments
+
+ You can specify action arguments for Emacs when you resume it after
+a suspension. To prepare for this, put the following code in your
+@file{.emacs} file (@pxref{Hooks}):
+
+@example
+(add-hook 'suspend-hook 'resume-suspend-hook)
+(add-hook 'suspend-resume-hook 'resume-process-args)
+@end example
+
+ As further preparation, you must execute the shell script
+@file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash} (if
+you use bash as your shell). These scripts define an alias named
+@code{edit}, which will resume Emacs giving it new command line
+arguments such as files to visit.
+
+ Only action arguments work properly when you resume Emacs. Initial
+arguments are not recognized---it's too late to execute them anyway.
+
+ Note that resuming Emacs (with or without arguments) must be done from
+within the shell that is the parent of the Emacs job. This is why
+@code{edit} is an alias rather than a program or a shell script. It is
+not possible to implement a resumption command that could be run from
+other subjobs of the shell; no way to define a command that could be
+made the value of @code{EDITOR}, for example. Therefore, this feature
+does not take the place of the Emacs Server feature (@pxref{Emacs
+Server}).
+
+ The aliases use the Emacs Server feature if you appear to have a
+server Emacs running. However, they cannot determine this with complete
+accuracy. They may think that a server is still running when in
+actuality you have killed that Emacs, because the file
+@file{/tmp/.esrv@dots{}} still exists. If this happens, find that
+file and delete it.
+
+@node Environment
+@appendixsec Environment Variables
+@cindex environment variables
+
+This appendix describes how Emacs uses environment variables. An
+environment variable is a string passed from the operating system to
+Emacs, and the collection of environment variables is known as the
+environment. Environment variable names are case sensitive and it is
+conventional to use upper case letters only.
+
+Because environment variables come from the operating system there is no
+general way to set them; it depends on the operating system and
+especially the shell that you are using. For example, here's how to set
+the environment variable @code{ORGANIZATION} to @samp{not very much}
+using bash:
+
+@example
+export ORGANIZATION="not very much"
+@end example
+
+@noindent
+and here's how to do it in csh or tcsh:
+
+@example
+setenv ORGANIZATION "not very much"
+@end example
+
+When Emacs is set-up to use the X windowing system, it inherits the
+use of a large number of environment variables from the X library. See
+the X documentation for more information.
+
+@menu
+* General Variables:: Environment variables that all versions of Emacs use.
+* Misc Variables:: Certain system-specific variables.
+@end menu
+
+@node General Variables
+@appendixsubsec General Variables
+
+@table @code
+@item AUTHORCOPY
+The name of a file used to archive news articles posted with the @sc{gnus}
+package.
+@item CDPATH
+Used by the @code{cd} command to search for the directory you specify,
+when you specify a relative directory name.
+@item DOMAINNAME
+The name of the Internet domain that the machine running Emacs is
+located in. Used by the @sc{gnus} package.
+@item EMACS_UNIBYTE
+@cindex unibyte operation
+Defining this environment variable directs Emacs to do almost everything
+with single-byte buffers and strings. It is equivalent to using the
+@samp{--unibyte} command-line option on each invocation. @xref{Initial
+Options}.
+@item EMACSDATA
+Used to initialize the variable @code{data-directory} used to locate the
+architecture-independent files that come with Emacs. Setting this
+variable overrides the setting in @file{paths.h} when Emacs was built.
+@item EMACSLOADPATH
+A colon-separated list of directories from which to load Emacs Lisp
+files. Setting this variable overrides the setting in @file{paths.h}
+when Emacs was built.
+@item EMACSLOCKDIR
+The directory that Emacs places lock files---files used to protect
+users from editing the same files simultaneously. Setting this variable
+overrides the setting in @file{paths.h} when Emacs was built.
+@item EMACSPATH
+The location of Emacs-specific binaries. Setting this variable
+overrides the setting in @file{paths.h} when Emacs was built.
+@item ESHELL
+Used for shell-mode to override the @code{SHELL} environment variable.
+@item HISTFILE
+The name of the file that shell commands are saved in between logins.
+This variable defaults to @file{~/.history} if you use (t)csh as shell,
+to @file{~/.bash_history} if you use bash, to @file{~/.sh_history} if
+you use ksh, and to @file{~/.history} otherwise.
+@item HOME
+The location of the user's files in the directory tree; used for
+expansion of file names starting with a tilde (@file{~}). On MS-DOS, it
+defaults to the directory from which Emacs was started, with @samp{/bin}
+removed from the end if it was present.
+@item HOSTNAME
+The name of the machine that Emacs is running on.
+@item INCPATH
+A colon-separated list of directories. Used by the @code{complete} package
+to search for files.
+@item INFOPATH
+A colon-separated list of directories holding info files. Setting this
+variable overrides the setting in @file{paths.el} when Emacs was built.
+@item LANG
+@itemx LC_ALL
+@itemx LC_CTYPE
+The user's preferred locale. A locale name which contains
+@samp{8859-@var{n}}, @samp{8859_@var{n}} or @samp{8859@var{n}}, where
+@var{n} is between 1 and 4, automatically specifies the
+@samp{Latin-@var{n}} language environment when Emacs starts up. If
+@var{n} is 9, that specifies @samp{Latin-5}.
+@item LOGNAME
+The user's login name. See also @code{USER}.
+@item MAIL
+The name of the user's system mail inbox.
+@item MAILRC
+Name of file containing mail aliases. This defaults to
+@file{~/.mailrc}.
+@item MH
+Name of setup file for the mh system. This defaults to
+@file{~/.mh_profile}.
+@item NAME
+The real-world name of the user.
+@item NNTPSERVER
+The name of the news server. Used by the mh and @sc{gnus} packages.
+@item ORGANIZATION
+The name of the organization to which you belong. Used for setting the
+`Organization:' header in your posts from the @sc{gnus} package.
+@item PATH
+A colon-separated list of directories in which executables reside. (On
+MS-DOS, it is semicolon-separated instead.) This variable is used to
+set the Emacs Lisp variable @code{exec-path} which you should consider
+to use instead.
+@item PWD
+If set, this should be the default directory when Emacs was started.
+@item REPLYTO
+If set, this specifies an initial value for the variable
+@code{mail-default-reply-to}. @xref{Mail Headers}.
+@item SAVEDIR
+The name of a directory in which news articles are saved by default.
+Used by the @sc{gnus} package.
+@item SHELL
+The name of an interpreter used to parse and execute programs run from
+inside Emacs.
+@item TERM
+The name of the terminal that Emacs is running on. The variable must be
+set unless Emacs is run in batch mode. On MS-DOS, it defaults to
+@samp{internal}, which specifies a built-in terminal emulation that
+handles the machine's own display.
+@item TERMCAP
+The name of the termcap library file describing how to program the
+terminal specified by the @code{TERM} variable. This defaults to
+@file{/etc/termcap}.
+@item TMPDIR
+Used by the Emerge package as a prefix for temporary files.
+@item TZ
+This specifies the current time zone and possibly also daylight savings
+information. On MS-DOS, the default is based on country code; see the
+file @file{msdos.c} for details.
+@item USER
+The user's login name. See also @code{LOGNAME}. On MS-DOS, this
+defaults to @samp{root}.
+@item VERSION_CONTROL
+Used to initialize the @code{version-control} variable (@pxref{Backup
+Names}).
+@end table
+
+@node Misc Variables
+@appendixsubsec Miscellaneous Variables
+
+These variables are used only on particular configurations:
+
+@table @code
+@item COMSPEC
+On MS-DOS, the name of the command interpreter to use. This is used to
+make a default value for the @code{SHELL} environment variable.
+
+@item NAME
+On MS-DOS, this variable defaults to the value of the @code{USER}
+variable.
+
+@item TEMP
+@itemx TMP
+On MS-DOS, these specify the name of the directory for storing temporary
+files in.
+
+@item EMACSTEST
+On MS-DOS, this specifies a file to use to log the operation of the
+internal terminal emulator. This feature is useful for submitting bug
+reports.
+
+@item EMACSCOLORS
+Used on MS-DOS systems to set screen colors early, so that the screen
+won't momentarily flash the default colors when Emacs starts up. The
+value of this variable should be two-character encoding of the
+foreground (the first character) and the background (the second
+character) colors of the default face. Each character should be the
+hexadecimal code for the desired color on a standard PC text-mode
+display.
+
+The PC display usually supports only eight background colors. However,
+Emacs switches the DOS display to a mode where all 16 colors can be used
+for the background, so all four bits of the background color are
+actually used.
+
+@item WINDOW_GFX
+Used when initializing the Sun windows system.
+@end table
+
+@node Display X
+@appendixsec Specifying the Display Name
+@cindex display name (X Windows)
+@cindex @code{DISPLAY} environment variable
+
+ The environment variable @code{DISPLAY} tells all X clients, including
+Emacs, where to display their windows. Its value is set up by default
+in ordinary circumstances, when you start an X server and run jobs
+locally. Occasionally you may need to specify the display yourself; for
+example, if you do a remote login and want to run a client program
+remotely, displaying on your local screen.
+
+ With Emacs, the main reason people change the default display is to
+let them log into another system, run Emacs on that system, but have the
+window displayed at their local terminal. You might need to use login
+to another system because the files you want to edit are there, or
+because the Emacs executable file you want to run is there.
+
+ The syntax of the @code{DISPLAY} environment variable is
+@samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the
+host name of the X Window System server machine, @var{display} is an
+arbitrarily-assigned number that distinguishes your server (X terminal)
+from other servers on the same machine, and @var{screen} is a
+rarely-used field that allows an X server to control multiple terminal
+screens. The period and the @var{screen} field are optional. If
+included, @var{screen} is usually zero.
+
+ For example, if your host is named @samp{glasperle} and your server is
+the first (or perhaps the only) server listed in the configuration, your
+@code{DISPLAY} is @samp{glasperle:0.0}.
+
+ You can specify the display name explicitly when you run Emacs, either
+by changing the @code{DISPLAY} variable, or with the option @samp{-d
+@var{display}} or @samp{--display=@var{display}}. Here is an example:
+
+@smallexample
+emacs --display=glasperle:0 &
+@end smallexample
+
+ You can inhibit the direct use of X with the @samp{-nw} option. This
+is also an initial option. It tells Emacs to display using ordinary
+ASCII on its controlling terminal.
+
+ Sometimes, security arrangements prevent a program on a remote system
+from displaying on your local system. In this case, trying to run Emacs
+produces messages like this:
+
+@smallexample
+Xlib: connection to "glasperle:0.0" refused by server
+@end smallexample
+
+@noindent
+You might be able to overcome this problem by using the @code{xhost}
+command on the local system to give permission for access from your
+remote machine.
+
+@node Font X
+@appendixsec Font Specification Options
+@cindex font name (X Windows)
+
+ By default, Emacs displays text in the font named @samp{9x15}, which
+makes each character nine pixels wide and fifteen pixels high. You can
+specify a different font on your command line through the option
+@samp{-fn @var{name}}.
+
+@table @samp
+@item -fn @var{name}
+Use font @var{name} as the default font.
+
+@item --font=@var{name}
+@samp{--font} is an alias for @samp{-fn}.
+@end table
+
+ Under X, each font has a long name which consists of eleven words or
+numbers, separated by dashes. Some fonts also have shorter
+nicknames---@samp{9x15} is such a nickname. You can use either kind of
+name. You can use wildcard patterns for the font name; then Emacs lets
+X choose one of the fonts that match the pattern. Here is an example,
+which happens to specify the font whose nickname is @samp{6x13}:
+
+@smallexample
+emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" &
+@end smallexample
+
+@noindent
+You can also specify the font in your @file{.Xdefaults} file:
+
+@smallexample
+emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
+@end smallexample
+
+ A long font name has the following form:
+
+@smallexample
+-@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
+@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset}
+@end smallexample
+
+@table @var
+@item family
+This is the name of the font family---for example, @samp{courier}.
+@item weight
+This is normally @samp{bold}, @samp{medium} or @samp{light}. Other
+words may appear here in some font names.
+@item slant
+This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique),
+@samp{ri} (reverse italic), or @samp{ot} (other).
+@item widthtype
+This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed}
+or @samp{normal}. Other words may appear here in some font names.
+@item style
+This is an optional additional style name. Usually it is empty---most
+long font names have two hyphens in a row at this point.
+@item pixels
+This is the font height, in pixels.
+@item height
+This is the font height on the screen, measured in tenths of a printer's
+point---approximately 1/720 of an inch. In other words, it is the point
+size of the font, times ten. For a given vertical resolution,
+@var{height} and @var{pixels} are proportional; therefore, it is common
+to specify just one of them and use @samp{*} for the other.
+@item horiz
+This is the horizontal resolution, in pixels per inch, of the screen for
+which the font is intended.
+@item vert
+This is the vertical resolution, in dots per inch, of the screen for
+which the font is intended. Normally the resolution of the fonts on
+your system is the right value for your screen; therefore, you normally
+specify @samp{*} for this and @var{horiz}.
+@item spacing
+This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c}
+(character cell). Emacs can use @samp{m} and @samp{c} fonts.
+@item width
+This is the average character width, in pixels, multiplied by ten.
+@item charset
+This is the character set that the font depicts.
+Normally you should use @samp{iso8859-1}.
+@end table
+
+ Use only fixed-width fonts---that is, fonts in which all characters
+have the same width; Emacs cannot yet handle display properly for
+variable-width fonts. Any font with @samp{m} or @samp{c} in the
+@var{spacing} field of the long name is a fixed-width font. Here's how
+to use the @code{xlsfonts} program to list all the fixed-width fonts
+available on your system:
+
+@example
+xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"
+xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
+xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'
+@end example
+
+@noindent
+To see what a particular font looks like, use the @code{xfd} command.
+For example:
+
+@example
+xfd -fn 6x13
+@end example
+
+@noindent
+displays the entire font @samp{6x13}.
+
+ While running Emacs, you can set the font of the current frame
+(@pxref{Frame Parameters}) or for a specific kind of text
+(@pxref{Faces}).
+
+@node Colors X
+@appendixsec Window Color Options
+@cindex color of window (X Windows)
+
+ On a color display, you can specify which color to use for various
+parts of the Emacs display. To find out what colors are available on
+your system, look at the @file{/usr/lib/X11/rgb.txt} file. If you do
+not specify colors, the default for the background is white and the
+default for all other colors is black. On a monochrome display, the
+foreground is black, the background is white, and the border is gray if
+the display supports that.
+
+ Here is a list of the options for specifying colors:
+
+@table @samp
+@item -fg @var{color}
+@itemx --foreground-color=@var{color}
+Specify the foreground color.
+@item -bg @var{color}
+@itemx --background-color=@var{color}
+Specify the background color.
+@item -bd @var{color}
+@itemx --border-color=@var{color}
+Specify the color of the border of the X window.
+@item -cr @var{color}
+@itemx --cursor-color=@var{color}
+Specify the color of the Emacs cursor which indicates where point is.
+@item -ms @var{color}
+@itemx --mouse-color=@var{color}
+Specify the color for the mouse cursor when the mouse is in the Emacs window.
+@item -r
+@itemx --reverse-video
+Reverse video---swap the foreground and background colors.
+@end table
+
+ For example, to use a coral mouse cursor and a slate blue text cursor,
+enter:
+
+@example
+emacs -ms coral -cr 'slate blue' &
+@end example
+
+ You can reverse the foreground and background colors through the
+@samp{-r} option or with the X resource @samp{reverseVideo}.
+
+@node Window Size X
+@appendixsec Options for Window Geometry
+@cindex geometry (X Windows)
+
+ The @samp{-geometry} option controls the size and position of the
+initial Emacs frame. Here is the format for specifying the window
+geometry:
+
+@table @samp
+@item -g @var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
+Specify window size @var{width} and @var{height} (measured in character
+columns and lines), and positions @var{xoffset} and @var{yoffset}
+(measured in pixels).
+
+@item --geometry=@var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
+This is another way of writing the same thing.
+@end table
+
+@noindent
+@code{@r{@{}+-@r{@}}} means either a plus sign or a minus sign. A plus
+sign before @var{xoffset} means it is the distance from the left side of
+the screen; a minus sign means it counts from the right side. A plus
+sign before @var{yoffset} means it is the distance from the top of the
+screen, and a minus sign there indicates the distance from the bottom.
+The values @var{xoffset} and @var{yoffset} may themselves be positive or
+negative, but that doesn't change their meaning, only their direction.
+
+ Emacs uses the same units as @code{xterm} does to interpret the geometry.
+The @var{width} and @var{height} are measured in characters, so a large font
+creates a larger frame than a small font. The @var{xoffset} and
+@var{yoffset} are measured in pixels.
+
+ Since the mode line and the echo area occupy the last 2 lines of the
+frame, the height of the initial text window is 2 less than the height
+specified in your geometry. In non-X-toolkit versions of Emacs,
+the menu bar also takes one line of the specified number.
+
+ You do not have to specify all of the fields in the geometry
+specification.
+
+ If you omit both @var{xoffset} and @var{yoffset}, the window manager
+decides where to put the Emacs frame, possibly by letting you place
+it with the mouse. For example, @samp{164x55} specifies a window 164
+columns wide, enough for two ordinary width windows side by side, and 55
+lines tall.
+
+ The default width for Emacs is 80 characters and the default height is
+40 lines. You can omit either the width or the height or both. If
+you start the geometry with an integer, Emacs interprets it as the
+width. If you start with an @samp{x} followed by an integer, Emacs
+interprets it as the height. Thus, @samp{81} specifies just the width;
+@samp{x45} specifies just the height.
+
+ If you start with @samp{+} or @samp{-}, that introduces an offset,
+which means both sizes are omitted. Thus, @samp{-3} specifies the
+@var{xoffset} only. (If you give just one offset, it is always
+@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the
+@var{yoffset}, placing the frame near the bottom left of the screen.
+
+ You can specify a default for any or all of the fields in
+@file{.Xdefaults} file, and then override selected fields with a
+@samp{--geometry} option.
+
+@node Borders X
+@appendixsec Internal and External Borders
+@cindex borders (X Windows)
+
+ An Emacs frame has an internal border and an external border. The
+internal border is an extra strip of the background color around all
+four edges of the frame. Emacs itself adds the internal border. The
+external border is added by the window manager outside the internal
+border; it may contain various boxes you can click on to move or iconify
+the window.
+
+@table @samp
+@item -ib @var{width}
+@itemx --internal-border=@var{width}
+Specify @var{width} as the width of the internal border.
+
+@item -bw @var{width}
+@itemx --border-width=@var{width}
+Specify @var{width} as the width of the main border.
+@end table
+
+ When you specify the size of the frame, that does not count the
+borders. The frame's position is measured from the outside edge of the
+external border.
+
+ Use the @samp{-ib @var{n}} option to specify an internal border
+@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to
+specify the width of the external border (though the window manager may
+not pay attention to what you specify). The default width of the
+external border is 2.
+
+@node Title X
+@appendixsec Frame Titles
+
+ An Emacs frame may or may not have a specified title. The frame
+title, if specified, appears in window decorations and icons as the name
+of the frame. If an Emacs frame has no specified title, the default
+title is the name of the executable program (if there is only one frame)
+or the selected window's buffer name (if there is more than one frame).
+
+ You can specify a title for the initial Emacs frame with a command
+line option:
+
+@table @samp
+@item -title @var{title}
+@itemx --title=@var{title}
+@itemx -T @var{title}
+Specify @var{title} as the title for the initial Emacs frame.
+@end table
+
+ The @samp{--name} option (@pxref{Resources X}) also specifies the title
+for the initial Emacs frame.
+
+@node Icons X
+@appendixsec Icons
+@cindex icons (X Windows)
+
+ Most window managers allow the user to ``iconify'' a frame, removing
+it from sight, and leaving a small, distinctive ``icon'' window in its
+place. Clicking on the icon window makes the frame itself appear again.
+If you have many clients running at once, you can avoid cluttering up
+the screen by iconifying most of the clients.
+
+@table @samp
+@item -i
+@itemx --icon-type
+Use a picture of a gnu as the Emacs icon.
+
+@item -iconic
+@itemx --iconic
+Start Emacs in iconified state.
+@end table
+
+ The @samp{-i} or @samp{--icon-type} option tells Emacs to use an icon
+window containing a picture of the GNU gnu. If omitted, Emacs lets the
+window manager choose what sort of icon to use---usually just a small
+rectangle containing the frame's title.
+
+ The @samp{-iconic} option tells Emacs to begin running as an icon,
+rather than opening a frame right away. In this situation, the icon
+window provides only indication that Emacs has started; the usual text
+frame doesn't appear until you deiconify it.
+
+@node Resources X
+@appendixsec X Resources
+@cindex resources
+
+ Programs running under the X Window System organize their user options
+under a hierarchy of classes and resources. You can specify default
+values for these options in your X resources file, usually named
+@file{~/.Xdefaults}.
+
+ Each line in the file specifies a value for one option or for a
+collection of related options, for one program or for several programs
+(optionally even for all programs).
+
+ Programs define named resources with particular meanings. They also
+define how to group resources into named classes. For instance, in
+Emacs, the @samp{internalBorder} resource controls the width of the
+internal border, and the @samp{borderWidth} resource controls the width
+of the external border. Both of these resources are part of the
+@samp{BorderWidth} class. Case distinctions are significant in these
+names.
+
+ In @file{~/.Xdefaults}, you can specify a value for a single resource
+on one line, like this:
+
+@example
+emacs.borderWidth: 2
+@end example
+
+@noindent
+Or you can use a class name to specify the same value for all resources
+in that class. Here's an example:
+
+@example
+emacs.BorderWidth: 2
+@end example
+
+ If you specify a value for a class, it becomes the default for all
+resources in that class. You can specify values for individual
+resources as well; these override the class value, for those particular
+resources. Thus, this example specifies 2 as the default width for all
+borders, but overrides this value with 4 for the external border:
+
+@example
+emacs.Borderwidth: 2
+emacs.borderwidth: 4
+@end example
+
+ The order in which the lines appear in the file does not matter.
+Also, command-line options always override the X resources file.
+
+ The string @samp{emacs} in the examples above is also a resource
+name. It actually represents the name of the executable file that you
+invoke to run Emacs. If Emacs is installed under a different name, it
+looks for resources under that name instead of @samp{emacs}.
+
+@table @samp
+@item -name @var{name}
+@itemx --name=@var{name}
+Use @var{name} as the resource name (and the title) for the initial
+Emacs frame. This option does not affect subsequent frames, but Lisp
+programs can specify frame names when they create frames.
+
+If you don't specify this option, the default is to use the Emacs
+executable's name as the resource name.
+
+@item -xrm @var{resource-values}
+@itemx --xrm=@var{resource-values}
+Specify X resource values for this Emacs job (see below).
+@end table
+
+ For consistency, @samp{-name} also specifies the name to use for
+other resource values that do not belong to any particular frame.
+
+ The resources that name Emacs invocations also belong to a class; its
+name is @samp{Emacs}. If you write @samp{Emacs} instead of
+@samp{emacs}, the resource applies to all frames in all Emacs jobs,
+regardless of frame titles and regardless of the name of the executable
+file. Here is an example:
+
+@example
+Emacs.BorderWidth: 2
+Emacs.borderWidth: 4
+@end example
+
+ You can specify a string of additional resource values for Emacs to
+use with the command line option @samp{-xrm @var{resources}}. The text
+@var{resources} should have the same format that you would use inside a file
+of X resources. To include multiple resource specifications in
+@var{data}, put a newline between them, just as you would in a file.
+You can also use @samp{#include "@var{filename}"} to include a file full
+of resource specifications. Resource values specified with @samp{-xrm}
+take precedence over all other resource specifications.
+
+ The following table lists the resource names that designate options
+for Emacs, each with the class that it belongs to:
+
+@table @asis
+@item @code{background} (class @code{Background})
+Background color name.
+
+@item @code{bitmapIcon} (class @code{BitmapIcon})
+Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
+manager choose an icon if @samp{off}.
+
+@item @code{borderColor} (class @code{BorderColor})
+Color name for the external border.
+
+@item @code{borderWidth} (class @code{BorderWidth})
+Width in pixels of the external border.
+
+@item @code{cursorColor} (class @code{Foreground})
+Color name for text cursor (point).
+
+@item @code{font} (class @code{Font})
+Font name for text (or fontset name, @pxref{Fontsets}).
+
+@item @code{foreground} (class @code{Foreground})
+Color name for text.
+
+@item @code{geometry} (class @code{Geometry})
+Window size and position. Be careful not to specify this resource as
+@samp{emacs*geometry}, because that may affect individual menus as well
+as the Emacs frame itself.
+
+If this resource specifies a position, that position applies only to the
+initial Emacs frame (or, in the case of a resource for a specific frame
+name, only that frame). However, the size if specified here applies to
+all frames.
+
+@item @code{iconName} (class @code{Title})
+Name to display in the icon.
+
+@item @code{internalBorder} (class @code{BorderWidth})
+Width in pixels of the internal border.
+
+@item @code{menuBar} (class @code{MenuBar})
+Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}.
+
+@item @code{minibuffer} (class @code{Minibuffer})
+If @samp{none}, don't make a minibuffer in this frame.
+It will use a separate minibuffer frame instead.
+
+@item @code{paneFont} (class @code{Font})
+Font name for menu pane titles, in non-toolkit versions of Emacs.
+
+@item @code{pointerColor} (class @code{Foreground})
+Color of the mouse cursor.
+
+@item @code{reverseVideo} (class @code{ReverseVideo})
+Switch foreground and background default colors if @samp{on}, use colors as
+specified if @samp{off}.
+
+@item @code{verticalScrollBars} (class @code{ScrollBars})
+Give frames scroll bars if @samp{on}; don't have scroll bars if
+@samp{off}.
+
+@item @code{selectionFont} (class @code{Font})
+Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
+toolkit versions, see @ref{Lucid Resources}, also see @ref{Motif
+Resources}.)
+
+@item @code{title} (class @code{Title})
+Name to display in the title bar of the initial Emacs frame.
+@end table
+
+ Here are resources for controlling the appearance of particular faces
+(@pxref{Faces}):
+
+@table @code
+@item @var{face}.attributeFont
+Font for face @var{face}.
+@item @var{face}.attributeForeground
+Foreground color for face @var{face}.
+@item @var{face}.attributeBackground
+Background color for face @var{face}.
+@item @var{face}.attributeUnderline
+Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
+yes.
+@end table
+
+@node Lucid Resources
+@section Lucid Menu X Resources
+@cindex Menu X Resources (Lucid widgets)
+@cindex Lucid Widget X Resources
+
+ If the Emacs installed at your site was built to use the X toolkit
+with the Lucid menu widgets, then the menu bar is a separate widget and
+has its own resources. The resource names contain @samp{pane.menubar}
+(following, as always, the name of the Emacs invocation or @samp{Emacs}
+which stands for all Emacs invocations). Specify them like this:
+
+@example
+Emacs.pane.menubar.@var{resource}: @var{value}
+@end example
+
+@noindent
+For example, to specify the font @samp{8x16} for the menu-bar items,
+write this:
+
+@example
+Emacs.pane.menubar.font: 8x16
+@end example
+
+@noindent
+Resources for @emph{non-menubar} toolkit pop-up menus have
+@samp{menu*}, in like fashion. For example, to specify the font
+@samp{8x16} for the pop-up menu items, write this:
+
+@example
+Emacs.menu*.font: 8x16
+@end example
+
+@noindent
+For dialog boxes, use @samp{dialog} instead of @samp{menu}:
+
+@example
+Emacs.dialog*.font: 8x16
+@end example
+
+@noindent
+Experience shows that on some systems you may need to add
+@samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
+some other systems, you must not add @samp{shell.}.
+
+ Here is a list of the specific resources for menu bars and pop-up menus:
+
+@table @code
+@item font
+Font for menu item text.
+@item foreground
+Color of the foreground.
+@item background
+Color of the background.
+@item buttonForeground
+In the menu bar, the color of the foreground for a selected item.
+@item horizontalSpacing
+Horizontal spacing in pixels between items. Default is 3.
+@item verticalSpacing
+Vertical spacing in pixels between items. Default is 1.
+@item arrowSpacing
+Horizontal spacing between the arrow (which indicates a submenu) and
+the associated text. Default is 10.
+@item shadowThickness
+Thickness of shadow line around the widget.
+@end table
+
+@node Motif Resources
+@section Motif Menu X Resources
+@cindex Menu X Resources (Motif widgets)
+@cindex Motif Widget X Resources
+
+ If the Emacs installed at your site was built to use the X toolkit
+with the Motif widgets, then the menu bar is a separate widget and has
+its own resources. The resource names contain @samp{pane.menubar}
+(following, as always, the name of the Emacs invocation or @samp{Emacs}
+which stands for all Emacs invocations). Specify them like this:
+
+@smallexample
+Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value}
+@end smallexample
+
+ Each individual string in the menu bar is a subwidget; the subwidget's
+name is the same as the menu item string. For example, the word
+@samp{Files} in the menu bar is part of a subwidget named
+@samp{emacs.pane.menubar.Files}. Most likely, you want to specify the
+same resources for the whole menu bar. To do this, use @samp{*} instead
+of a specific subwidget name. For example, to specify the font
+@samp{8x16} for the menu-bar items, write this:
+
+@smallexample
+Emacs.pane.menubar.*.fontList: 8x16
+@end smallexample
+
+@noindent
+This also specifies the resource value for submenus.
+
+ Each item in a submenu in the menu bar also has its own name for X
+resources; for example, the @samp{Files} submenu has an item named
+@samp{Save Buffer}. A resource specification for a submenu item looks
+like this:
+
+@smallexample
+Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
+@end smallexample
+
+@noindent
+For example, here's how to specify the font for the @samp{Save Buffer}
+item:
+
+@smallexample
+Emacs.pane.menubar.popup_*.Files.Save Buffer.fontList: 8x16
+@end smallexample
+
+@noindent
+For an item in a second-level submenu, such as @samp{Check Message}
+under @samp{Spell} under @samp{Edit}, the resource fits this template:
+
+@smallexample
+Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
+@end smallexample
+
+@noindent
+For example,
+
+@smallexample
+Emacs.pane.menubar.popup_*.popup_*.Spell.Check Message: @var{value}
+@end smallexample
+
+ It's impossible to specify a resource for all the menu-bar items
+without also specifying it for the submenus as well. So if you want the
+submenu items to look different from the menu bar itself, you must ask
+for that in two steps. First, specify the resource for all of them;
+then, override the value for submenus alone. Here is an example:
+
+@smallexample
+Emacs.pane.menubar.*.fontList: 8x16
+Emacs.pane.menubar.popup_*.fontList: 8x16
+@end smallexample
+
+@noindent
+For toolkit pop-up menus, use @samp{menu*} instead of
+@samp{pane.menubar}. For example, to specify the font @samp{8x16} for
+the pop-up menu items, write this:
+
+@smallexample
+Emacs.menu*.fontList: 8x16
+@end smallexample
+
+@iftex
+@medbreak
+@end iftex
+ Here is a list of the specific resources for menu bars and pop-up menus:
+
+@table @code
+@item armColor
+The color to show in an armed button.
+@item fontList
+The font to use.
+@item marginBottom
+@itemx marginHeight
+@itemx marginLeft
+@itemx marginRight
+@itemx marginTop
+@itemx marginWidth
+Amount of space to leave around the item, within the border.
+@item borderWidth
+The width of border around the menu item, on all sides.
+@item shadowThickness
+The width of the border shadow.
+@item bottomShadowColor
+The color for the border shadow, on the bottom and the right.
+@item topShadowColor
+The color for the border shadow, on the top and the left.
+@end table
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@iftex
+@chapter Characters, Keys and Commands
+
+ This chapter explains the character sets used by Emacs for input
+commands and for the contents of files, and also explains the concepts
+of @dfn{keys} and @dfn{commands}, which are fundamental for understanding
+how Emacs interprets your keyboard and mouse input.
+@end iftex
+
+@node User Input, Keys, Screen, Top
+@section Kinds of User Input
+@cindex input with the keyboard
+@cindex keyboard input
+@cindex character set (keyboard)
+@cindex ASCII
+@cindex C-
+@cindex Control
+@cindex control characters
+
+ GNU Emacs uses an extension of the ASCII character set for keyboard
+input; it also accepts non-character input events including function
+keys and mouse button actions.
+
+ ASCII consists of 128 character codes. Some of these codes are
+assigned graphic symbols such as @samp{a} and @samp{=}; the rest are
+control characters, such as @kbd{Control-a} (usually written @kbd{C-a}
+for short). @kbd{C-a} gets its name from the fact that you type it by
+holding down the @key{CTRL} key while pressing @kbd{a}.
+
+ Some ASCII control characters have special names, and most terminals
+have special keys you can type them with: for example, @key{RET},
+@key{TAB}, @key{DEL} and @key{ESC}. The space character is usually
+referred to below as @key{SPC}, even though strictly speaking it is a
+graphic character whose graphic happens to be blank. Some keyboards
+have a key labeled ``linefeed'' which is an alias for @kbd{C-j}.
+
+ Emacs extends the ASCII character set with thousands more printing
+characters (@pxref{International}), additional control characters, and a
+few more modifiers that can be combined with any character.
+
+ On ASCII terminals, there are only 32 possible control characters.
+These are the control variants of letters and @samp{@@[]\^_}. In
+addition, the shift key is meaningless with control characters:
+@kbd{C-a} and @kbd{C-A} are the same character, and Emacs cannot
+distinguish them.
+
+ But the Emacs character set has room for control variants of all
+printing characters, and for distinguishing between @kbd{C-a} and
+@kbd{C-A}. X Windows makes it possible to enter all these characters.
+For example, @kbd{C--} (that's Control-Minus) and @kbd{C-5} are
+meaningful Emacs commands under X.
+
+ Another Emacs character-set extension is additional modifier bits.
+Only one modifier bit is commonly used; it is called Meta. Every
+character has a Meta variant; examples include @kbd{Meta-a} (normally
+written @kbd{M-a}, for short), @kbd{M-A} (not the same character as
+@kbd{M-a}, but those two characters normally have the same meaning in
+Emacs), @kbd{M-@key{RET}}, and @kbd{M-C-a}. For reasons of tradition,
+we usually write @kbd{C-M-a} rather than @kbd{M-C-a}; logically
+speaking, the order in which the modifier keys @key{CTRL} and @key{META}
+are mentioned does not matter.
+
+@cindex Meta
+@cindex M-
+@cindex @key{ESC} replacing @key{META} key
+ Some terminals have a @key{META} key, and allow you to type Meta
+characters by holding this key down. Thus, @kbd{Meta-a} is typed by
+holding down @key{META} and pressing @kbd{a}. The @key{META} key works
+much like the @key{SHIFT} key. Such a key is not always labeled
+@key{META}, however, as this function is often a special option for a key
+with some other primary purpose.@refill
+
+ If there is no @key{META} key, you can still type Meta characters
+using two-character sequences starting with @key{ESC}. Thus, to enter
+@kbd{M-a}, you could type @kbd{@key{ESC} a}. To enter @kbd{C-M-a}, you
+would type @kbd{@key{ESC} C-a}. @key{ESC} is allowed on terminals with
+@key{META} keys, too, in case you have formed a habit of using it.
+
+ X Windows provides several other modifier keys that can be applied to
+any input character. These are called @key{SUPER}, @key{HYPER} and
+@key{ALT}. We write @samp{s-}, @samp{H-} and @samp{A-} to say that a
+character uses these modifiers. Thus, @kbd{s-H-C-x} is short for
+@kbd{Super-Hyper-Control-x}. Not all X terminals actually provide keys
+for these modifier flags---in fact, many terminals have a key labeled
+@key{ALT} which is really a @key{META} key. The standard key bindings
+of Emacs do not include any characters with these modifiers. But you
+can assign them meanings of your own by customizing Emacs.
+
+ Keyboard input includes keyboard keys that are not characters at all:
+for example function keys and arrow keys. Mouse buttons are also
+outside the gamut of characters. You can modify these events with the
+modifier keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and
+@key{ALT}, just like keyboard characters.
+
+@cindex input event
+ Input characters and non-character inputs are collectively called
+@dfn{input events}. @xref{Input Events,,, elisp, The Emacs Lisp
+Reference Manual}, for more information. If you are not doing Lisp
+programming, but simply want to redefine the meaning of some characters
+or non-character events, see @ref{Customization}.
+
+ ASCII terminals cannot really send anything to the computer except
+ASCII characters. These terminals use a sequence of characters to
+represent each function key. But that is invisible to the Emacs user,
+because the keyboard input routines recognize these special sequences
+and convert them to function key events before any other part of Emacs
+gets to see them.
+
+@node Keys, Commands, User Input, Top
+@section Keys
+
+@cindex key sequence
+@cindex key
+ A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input
+events that are meaningful as a unit---as ``a single command.''
+Some Emacs command sequences are just one character or one event; for
+example, just @kbd{C-f} is enough to move forward one character. But
+Emacs also has commands that take two or more events to invoke.
+
+@cindex complete key
+@cindex prefix key
+ If a sequence of events is enough to invoke a command, it is a
+@dfn{complete key}. Examples of complete keys include @kbd{C-a},
+@kbd{X}, @key{RET}, @key{NEXT} (a function key), @key{DOWN} (an arrow
+key), @kbd{C-x C-f}, and @kbd{C-x 4 C-f}. If it isn't long enough to be
+complete, we call it a @dfn{prefix key}. The above examples show that
+@kbd{C-x} and @kbd{C-x 4} are prefix keys. Every key sequence is either
+a complete key or a prefix key.
+
+ Most single characters constitute complete keys in the standard Emacs
+command bindings. A few of them are prefix keys. A prefix key combines
+with the following input event to make a longer key sequence, which may
+itself be complete or a prefix. For example, @kbd{C-x} is a prefix key,
+so @kbd{C-x} and the next input event combine to make a two-character
+key sequence. Most of these key sequences are complete keys, including
+@kbd{C-x C-f} and @kbd{C-x b}. A few, such as @kbd{C-x 4} and @kbd{C-x
+r}, are themselves prefix keys that lead to three-character key
+sequences. There's no limit to the length of a key sequence, but in
+practice people rarely use sequences longer than four events.
+
+ By contrast, you can't add more events onto a complete key. For
+example, the two-character sequence @kbd{C-f C-k} is not a key, because
+the @kbd{C-f} is a complete key in itself. It's impossible to give
+@kbd{C-f C-k} an independent meaning as a command. @kbd{C-f C-k} is two
+key sequences, not one.@refill
+
+ All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h},
+@kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x n}, @w{@kbd{C-x
+r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x 6}, @key{ESC},
+@kbd{M-g} and @kbd{M-j}. But this list is not cast in concrete; it is
+just a matter of Emacs's standard key bindings. If you customize Emacs,
+you can make new prefix keys, or eliminate these. @xref{Key Bindings}.
+
+ If you do make or eliminate prefix keys, that changes the set of
+possible key sequences. For example, if you redefine @kbd{C-f} as a
+prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless you
+define it too as a prefix). Conversely, if you remove the prefix
+definition of @kbd{C-x 4}, then @kbd{C-x 4 f} (or @kbd{C-x 4
+@var{anything}}) is no longer a key.
+
+ Typing the help character (@kbd{C-h} or @key{F1}) after a prefix
+character displays a list of the commands starting with that prefix.
+There are a few prefix characters for which @kbd{C-h} does not
+work---for historical reasons, they have other meanings for @kbd{C-h}
+which are not easy to change. But @key{F1} should work for all prefix
+characters.
+
+@node Commands, Text Characters, Keys, Top
+@section Keys and Commands
+
+@cindex binding
+@cindex function
+@cindex command
+@cindex function definition
+ This manual is full of passages that tell you what particular keys
+do. But Emacs does not assign meanings to keys directly. Instead,
+Emacs assigns meanings to named @dfn{commands}, and then gives keys
+their meanings by @dfn{binding} them to commands.
+
+ Every command has a name chosen by a programmer. The name is usually
+made of a few English words separated by dashes; for example,
+@code{next-line} or @code{forward-word}. A command also has a
+@dfn{function definition} which is a Lisp program; this is what makes
+the command do what it does. In Emacs Lisp, a command is actually a
+special kind of Lisp function; one which specifies how to read arguments
+for it and call it interactively. For more information on commands and
+functions, see @ref{What Is a Function,, What Is a Function, elisp, The
+Emacs Lisp Reference Manual}. (The definition we use in this manual is
+simplified slightly.)
+
+ The bindings between keys and commands are recorded in various tables
+called @dfn{keymaps}. @xref{Keymaps}.
+
+ When we say that ``@kbd{C-n} moves down vertically one line'' we are
+glossing over a distinction that is irrelevant in ordinary use but is vital
+in understanding how to customize Emacs. It is the command
+@code{next-line} that is programmed to move down vertically. @kbd{C-n} has
+this effect @emph{because} it is bound to that command. If you rebind
+@kbd{C-n} to the command @code{forward-word} then @kbd{C-n} will move
+forward by words instead. Rebinding keys is a common method of
+customization.@refill
+
+ In the rest of this manual, we usually ignore this subtlety to keep
+things simple. To give the information needed for customization, we
+state the name of the command which really does the work in parentheses
+after mentioning the key that runs it. For example, we will say that
+``The command @kbd{C-n} (@code{next-line}) moves point vertically
+down,'' meaning that @code{next-line} is a command that moves vertically
+down and @kbd{C-n} is a key that is standardly bound to it.
+
+ While we are on the subject of information for customization only,
+it's a good time to tell you about @dfn{variables}. Often the
+description of a command will say, ``To change this, set the variable
+@code{mumble-foo}.'' A variable is a name used to remember a value.
+Most of the variables documented in this manual exist just to facilitate
+customization: some command or other part of Emacs examines the variable
+and behaves differently according to the value that you set. Until you
+are interested in customizing, you can ignore the information about
+variables. When you are ready to be interested, read the basic
+information on variables, and then the information on individual
+variables will make sense. @xref{Variables}.
+
+@node Text Characters, Entering Emacs, Commands, Top
+@section Character Set for Text
+@cindex characters (in text)
+
+ Text in Emacs buffers is a sequence of 8-bit bytes. Each byte can
+hold a single ASCII character. Both ASCII control characters (octal
+codes 000 through 037, and 0177) and ASCII printing characters (codes
+040 through 0176) are allowed; however, non-ASCII control characters
+cannot appear in a buffer. The other modifier flags used in keyboard
+input, such as Meta, are not allowed in buffers either.
+
+ Some ASCII control characters serve special purposes in text, and have
+special names. For example, the newline character (octal code 012) is
+used in the buffer to end a line, and the tab character (octal code 011)
+is used for indenting to the next tab stop column (normally every 8
+columns). @xref{Text Display}.
+
+ Non-ASCII printing characters can also appear in buffers. When
+multibyte characters are enabled, you can use any of the non-ASCII
+printing characters that Emacs supports. They have character codes
+starting at 256, octal 0400, and each one is represented as a sequence
+of two or more bytes. @xref{International}.
+
+ If you disable multibyte characters, then you can use only one
+alphabet of non-ASCII characters, but they all fit in one byte. They
+use codes 0200 through 0377. @xref{Single-Byte European Support}.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Customization, Quitting, Amusements, Top
+@chapter Customization
+@cindex customization
+
+ This chapter talks about various topics relevant to adapting the
+behavior of Emacs in minor ways. See @cite{The Emacs Lisp Reference
+Manual} for how to make more far-reaching changes.
+
+ All kinds of customization affect only the particular Emacs session
+that you do them in. They are completely lost when you kill the Emacs
+session, and have no effect on other Emacs sessions you may run at the
+same time or later. The only way an Emacs session can affect anything
+outside of it is by writing a file; in particular, the only way to make
+a customization ``permanent'' is to put something in your @file{.emacs}
+file or other appropriate file to do the customization in each session.
+@xref{Init File}.
+
+@menu
+* Minor Modes:: Each minor mode is one feature you can turn on
+ independently of any others.
+* Variables:: Many Emacs commands examine Emacs variables
+ to decide what to do; by setting variables,
+ you can control their functioning.
+* Keyboard Macros:: A keyboard macro records a sequence of
+ keystrokes to be replayed with a single
+ command.
+* Key Bindings:: The keymaps say what command each key runs.
+ By changing them, you can "redefine keys".
+* Keyboard Translations::
+ If your keyboard passes an undesired code
+ for a key, you can tell Emacs to
+ substitute another code.
+* Syntax:: The syntax table controls how words and
+ expressions are parsed.
+* Init File:: How to write common customizations in the
+ @file{.emacs} file.
+@end menu
+
+@node Minor Modes
+@section Minor Modes
+@cindex minor modes
+@cindex mode, minor
+
+ Minor modes are optional features which you can turn on or off. For
+example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines
+between words as you type. All the minor modes are independent of each
+other and of the selected major mode. Most minor modes say in the mode
+line when they are on; for example, @samp{Fill} in the mode line means
+that Auto Fill mode is on.
+
+ Append @code{-mode} to the name of a minor mode to get the name of a
+command function that turns the mode on or off. Thus, the command to
+enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
+commands are usually invoked with @kbd{M-x}, but you can bind keys to them
+if you wish. With no argument, the function turns the mode on if it was
+off and off if it was on. This is known as @dfn{toggling}. A positive
+argument always turns the mode on, and an explicit zero argument or a
+negative argument always turns it off.
+
+ Enabling or disabling some minor modes applies only to the current
+buffer; each buffer is independent of the other buffers. Therefore, you
+can enable the mode in particular buffers and disable it in others. The
+per-buffer minor modes include Abbrev mode, Auto Fill mode, Auto Save
+mode, Font-Lock mode, Hscroll mode, ISO Accents mode, Outline minor
+mode, Overwrite mode, and Binary Overwrite mode.
+
+ Abbrev mode allows you to define abbreviations that automatically expand
+as you type them. For example, @samp{amd} might expand to @samp{abbrev
+mode}. @xref{Abbrevs}, for full information.
+
+ Auto Fill mode allows you to enter filled text without breaking lines
+explicitly. Emacs inserts newlines as necessary to prevent lines from
+becoming too long. @xref{Filling}.
+
+ Auto Save mode causes the contents of a buffer to be saved
+periodically to reduce the amount of work you can lose in case of a
+system crash. @xref{Auto Save}.
+
+ Enriched mode enables editing and saving of formatted text.
+@xref{Formatted Text}.
+
+ Flyspell mode automatically highlights misspelled words.
+@xref{Spelling}.
+
+ Font-Lock mode automatically highlights certain textual units found in
+programs, such as comments, strings, and function names being defined.
+This requires a window system that can display multiple fonts.
+@xref{Faces}.
+
+ Hscroll mode performs horizontal scrolling automatically
+to keep point on the screen. @xref{Horizontal Scrolling}.
+
+ ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"},
+@samp{^}, @samp{/} and @samp{~} combine with the following letter, to
+produce an accented letter in the ISO Latin-1 character set.
+@xref{Single-Byte European Support}.
+
+ Outline minor mode provides the same facilities as the major mode
+called Outline mode; but since it is a minor mode instead, you can
+combine it with any major mode. @xref{Outline Mode}.
+
+@cindex Overwrite mode
+@cindex mode, Overwrite
+@findex overwrite-mode
+@findex binary-overwrite-mode
+ Overwrite mode causes ordinary printing characters to replace existing
+text instead of shoving it to the right. For example, if point is in
+front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a
+@kbd{G} changes it to @samp{FOOGAR}, instead of producing @samp{FOOGBAR}
+as usual. In Overwrite mode, the command @kbd{C-q} inserts the next
+character whatever it may be, even if it is a digit---this gives you a
+way to insert a character instead of replacing an existing character.
+
+ Binary Overwrite mode is a variant of Overwrite mode for editing
+binary files; it treats newlines and tabs like other characters, so that
+they overwrite other characters and can be overwritten by them.
+
+ The following minor modes normally apply to all buffers at once.
+Since each is enabled or disabled by the value of a variable, you
+@emph{can} set them differently for particular buffers, by explicitly
+making the corresponding variables local in those buffers.
+@xref{Locals}.
+
+ Icomplete mode displays an indication of available completions when
+you are in the minibuffer and completion is active. @xref{Completion
+Options}.
+
+ Line Number mode enables continuous display in the mode line of the
+line number of point. @xref{Mode Line}.
+
+ Resize-Minibuffer mode makes the minibuffer expand as necessary to
+hold the text that you put in it. @xref{Minibuffer Edit}.
+
+ Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}).
+Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of
+these modes are enabled by default when you use the X Window System.
+
+ In Transient Mark mode, every change in the buffer contents
+``deactivates'' the mark, so that commands that operate on the region
+will get an error. This means you must either set the mark, or
+explicitly ``reactivate'' it, before each command that uses the region.
+The advantage of Transient Mark mode is that Emacs can display the
+region highlighted (currently only when using X). @xref{Setting Mark}.
+
+ For most minor modes, the command name is also the name of a variable
+which directly controls the mode. The mode is enabled whenever this
+variable's value is non-@code{nil}, and the minor-mode command works by
+setting the variable. For example, the command
+@code{outline-minor-mode} works by setting the value of
+@code{outline-minor-mode} as a variable; it is this variable that
+directly turns Outline minor mode on and off. To check whether a given
+minor mode works this way, use @kbd{C-h v} to ask for documentation on
+the variable name.
+
+ These minor-mode variables provide a good way for Lisp programs to turn
+minor modes on and off; they are also useful in a file's local variables
+list. But please think twice before setting minor modes with a local
+variables list, because most minor modes are matter of user
+preference---other users editing the same file might not want the same
+minor modes you prefer.
+
+@node Variables
+@section Variables
+@cindex variable
+@cindex option, user
+@cindex user option
+
+ A @dfn{variable} is a Lisp symbol which has a value. The symbol's
+name is also called the name of the variable. A variable name can
+contain any characters that can appear in a file, but conventionally
+variable names consist of words separated by hyphens. A variable can
+have a documentation string which describes what kind of value it should
+have and how the value will be used.
+
+ Lisp allows any variable to have any kind of value, but most variables
+that Emacs uses require a value of a certain type. Often the value should
+always be a string, or should always be a number. Sometimes we say that a
+certain feature is turned on if a variable is ``non-@code{nil},'' meaning
+that if the variable's value is @code{nil}, the feature is off, but the
+feature is on for @emph{any} other value. The conventional value to use to
+turn on the feature---since you have to pick one particular value when you
+set the variable---is @code{t}.
+
+ Emacs uses many Lisp variables for internal record keeping, as any
+Lisp program must, but the most interesting variables for you are the
+ones that exist for the sake of customization. Emacs does not (usually)
+change the values of these variables; instead, you set the values, and
+thereby alter and control the behavior of certain Emacs commands. These
+variables are called @dfn{user options}. Most user options are
+documented in this manual, and appear in the Variable Index
+(@pxref{Variable Index}).
+
+ One example of a variable which is a user option is @code{fill-column}, which
+specifies the position of the right margin (as a number of characters from
+the left margin) to be used by the fill commands (@pxref{Filling}).
+
+@menu
+* Examining:: Examining or setting one variable's value.
+* Easy Customization::
+ Convenient and easy customization of variables.
+* Hooks:: Hook variables let you specify programs for parts
+ of Emacs to run on particular occasions.
+* Locals:: Per-buffer values of variables.
+* File Variables:: How files can specify variable values.
+@end menu
+
+@node Examining
+@subsection Examining and Setting Variables
+@cindex setting variables
+
+@table @kbd
+@item C-h v @var{var} @key{RET}
+Display the value and documentation of variable @var{var}
+(@code{describe-variable}).
+@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
+Change the value of variable @var{var} to @var{value}.
+@end table
+
+ To examine the value of a single variable, use @kbd{C-h v}
+(@code{describe-variable}), which reads a variable name using the
+minibuffer, with completion. It displays both the value and the
+documentation of the variable. For example,
+
+@example
+C-h v fill-column @key{RET}
+@end example
+
+@noindent
+displays something like this:
+
+@smallexample
+fill-column's value is 75
+
+Documentation:
+*Column beyond which automatic line-wrapping should happen.
+Automatically becomes buffer-local when set in any fashion.
+@end smallexample
+
+@noindent
+The star at the beginning of the documentation indicates that this
+variable is a user option. @kbd{C-h v} is not restricted to user
+options; it allows any variable name.
+
+@findex set-variable
+ The most convenient way to set a specific user option is with @kbd{M-x
+set-variable}. This reads the variable name with the minibuffer (with
+completion), and then reads a Lisp expression for the new value using
+the minibuffer a second time. For example,
+
+@example
+M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
+@end example
+
+@noindent
+sets @code{fill-column} to 75.
+
+ @kbd{M-x set-variable} is limited to user option variables, but you can
+set any variable with a Lisp expression, using the function @code{setq}.
+Here is a @code{setq} expression to set @code{fill-column}:
+
+@example
+(setq fill-column 75)
+@end example
+
+ To execute an expression like this one, go to the @samp{*scratch*}
+buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp
+Interaction}.
+
+ Setting variables, like all means of customizing Emacs except where
+otherwise stated, affects only the current Emacs session.
+
+@node Easy Customization
+@subsection Easy Customization Interface
+
+@findex customize
+@cindex customization buffer
+ A convenient way to find the user option variables that you want to
+change, and then change them, is with @kbd{M-x customize}. This command
+creates a @dfn{customization buffer} with which you can browse through
+the Emacs user options in a logically organized structure, then edit and
+set their values. You can also use the customization buffer to save
+settings permanently. (Not all Emacs user options are included in this
+structure as of yet, but we are adding the rest.)
+
+@menu
+* Groups: Customization Groups.
+ How options are classified in a structure.
+* Changing an Option:: How to edit a value and set an option.
+* Face Customization:: How to edit the attributes of a face.
+* Specific Customization:: Making a customization buffer for specific
+ options, faces, or groups.
+@end menu
+
+@node Customization Groups
+@subsubsection Customization Groups
+@cindex customization groups
+
+ For customization purposes, user options are organized into
+@dfn{groups} to help you find them. Groups are collected into bigger
+groups, all the way up to a master group called @code{Emacs}.
+
+ @kbd{M-x customize} creates a customization buffer that shows the
+top-level @code{Emacs} group and the second-level groups immediately
+under it. It looks like this, in part:
+
+@smallexample
+/- Emacs group: ---------------------------------------------------\
+ [State]: visible group members are all at standard settings.
+ Customization of the One True Editor.
+ See also [Manual].
+
+Editing group: [Go to Group]
+Basic text editing facilities.
+
+External group: [Go to Group]
+Interfacing to external utilities.
+
+@var{more second-level groups}
+
+\- Emacs group end ------------------------------------------------/
+
+@end smallexample
+
+@noindent
+This says that the buffer displays the contents of the @code{Emacs}
+group. The other groups are listed because they are its contents. But
+they are listed differently, without indentation and dashes, because
+@emph{their} contents are not included. Each group has a single-line
+documentation string; the @code{Emacs} group also has a @samp{[State]}
+line.
+
+@cindex editable fields (customization buffer)
+@cindex active fields (customization buffer)
+ Most of the text in the customization buffer is read-only, but it
+typically includes some @dfn{editable fields} that you can edit. There
+are also @dfn{active fields}; this means a field that does something
+when you @dfn{invoke} it. To invoke an active field, either click on it
+with @kbd{Mouse-1}, or move point to it and type @key{RET}.
+
+ For example, the phrase @samp{[Go to Group]} that appears in a
+second-level group is an active field. Invoking the @samp{[Go to
+Group]} field for a group creates a new customization buffer, which
+shows that group and its contents. This field is a kind of hypertext
+link to another group.
+
+ The @code{Emacs} group does not include any user options itself, but
+other groups do. By examining various groups, you will eventually find
+the options and faces that belong to the feature you are interested in
+customizing. Then you can use the customization buffer to set them.
+
+@findex customize-browse
+ You can view the structure of customization groups on a larger scale
+with @kbd{M-x customize-browse}. This command creates a special kind of
+customization buffer which shows only the names of the groups (and
+options and faces), and their structure.
+
+ In this buffer, you can show the contents of a group by invoking
+@samp{[+]}. When the group contents are visible, this button changes to
+@samp{[-]}; invoking that hides the group contents.
+
+ Each group, option or face name in this buffer has an active field
+which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking
+that active field creates an ordinary customization buffer showing just
+that group and its contents, just that option, or just that face.
+This is the way to set values in it.
+
+@node Changing an Option
+@subsubsection Changing an Option
+
+ Here is an example of what a user option looks like in the
+customization buffer:
+
+@smallexample
+Kill Ring Max: [Hide] 30
+ [State]: this option is unchanged from its standard setting.
+Maximum length of kill ring before oldest elements are thrown away.
+@end smallexample
+
+ The text following @samp{[Hide]}, @samp{30} in this case, indicates
+the current value of the option. If you see @samp{[Show]} instead of
+@samp{[Hide]}, it means that the value is hidden; the customization
+buffer initially hides values that take up several lines. Invoke
+@samp{[Show]} to show the value.
+
+ The line after the option name indicates the @dfn{customization state}
+of the option: in the example above, it says you have not changed the
+option yet. The word @samp{[State]} at the beginning of this line is
+active; you can get a menu of various operations by invoking it with
+@kbd{Mouse-1} or @key{RET}. These operations are essential for
+customizing the variable.
+
+ The line after the @samp{[State]} line displays the beginning of the
+option's documentation string. If there are more lines of
+documentation, this line ends with @samp{[More]}; invoke this to show
+the full documentation string.
+
+ To enter a new value for @samp{Kill Ring Max}, move point to the value
+and edit it textually. For example, you can type @kbd{M-d}, then insert
+another number.
+
+ When you begin to alter the text, you will see the @samp{[State]} line
+change to say that you have edited the value:
+
+@smallexample
+[State]: you have edited the value as text, but not set the option.
+@end smallexample
+
+@cindex setting option value
+ Editing the value does not actually set the option variable. To do
+that, you must @dfn{set} the option. To do this, invoke the word
+@samp{[State]} and choose @samp{Set for Current Session}.
+
+ The state of the option changes visibly when you set it:
+
+@smallexample
+[State]: you have set this option, but not saved it for future sessions.
+@end smallexample
+
+ You don't have to worry about specifying a value that is not valid;
+setting the option checks for validity and will not really install an
+unacceptable value.
+
+@kindex M-TAB @r{(customization buffer)}
+@findex widget-complete
+ While editing a value or field that is a file name, directory name,
+command name, or anything else for which completion is defined, you can
+type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
+
+ Some options have a small fixed set of possible legitimate values.
+These options don't let you edit the value textually. Instead, an
+active field @samp{[Value Menu]} appears before the value; invoke this
+field to edit the value. For a boolean ``on or off'' value, the active
+field says @samp{[Toggle]}, and it changes to the other value.
+@samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
+take effect when you use the @samp{Set for Current Session} operation.
+
+ Some options have values with complex structure. For example, the
+value of @code{load-path} is a list of directories. Here is how it
+appears in the customization buffer:
+
+@smallexample
+Load Path:
+[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/site-lisp
+[INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
+[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/leim
+[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/lisp
+[INS] [DEL] [Current dir?]: /build/emacs/e20/lisp
+[INS] [DEL] [Current dir?]: /build/emacs/e20/lisp/gnus
+[INS]
+ [State]: this item has been changed outside the customization buffer.
+List of directories to search for files to load....
+@end smallexample
+
+@noindent
+Each directory in the list appears on a separate line, and each line has
+several editable or active fields.
+
+ You can edit any of the directory names. To delete a directory from
+the list, invoke @samp{[DEL]} on that line. To insert a new directory in
+the list, invoke @samp{[INS]} at the point where you want to insert it.
+
+ You can also invoke @samp{[Current dir?]} to switch between including
+a specific named directory in the path, and including @code{nil} in the
+path. (@code{nil} in a search path means ``try the current
+directory.'')
+
+@kindex TAB @r{(customization buffer)}
+@kindex S-TAB @r{(customization buffer)}
+@findex widget-forward
+@findex widget-backward
+ Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for
+moving through the customization buffer. @key{TAB}
+(@code{widget-forward}) moves forward to the next active or editable
+field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the
+previous active or editable field.
+
+ Typing @key{RET} on an editable field also moves forward, just like
+@key{TAB}. The reason for this is that people have a tendency to type
+@key{RET} when they are finished editing a field. If you have occasion
+to insert a newline in an editable field, use @kbd{C-o} or @kbd{C-q
+C-j}.
+
+@cindex saving option value
+ Setting the option changes its value in the current Emacs session;
+@dfn{saving} the value changes it for future sessions as well. This
+works by writing code into your @file{~/.emacs} file so as to set the
+option variable again each time you start Emacs. To save the option,
+invoke @samp{[State]} and select the @samp{Save for Future Sessions}
+operation.
+
+ You can also restore the option to its standard value by invoking
+@samp{[State]} and selecting the @samp{Reset to Standard Settings}
+operation. There are actually three reset operations:
+
+@table @samp
+@item Reset
+If you have made some modifications and not yet set the option,
+this restores the text in the customization buffer to match
+the actual value.
+
+@item Reset to Saved
+This restores the value of the option to the last saved value,
+and updates the text accordingly.
+
+@item Reset to Standard Settings
+This sets the option to its standard value, and updates the text
+accordingly. This also eliminates any saved value for the option,
+so that you will get the standard value in future Emacs sessions.
+@end table
+
+ The state of a group indicates whether anything in that group has been
+edited, set or saved. You can select @samp{Set for Current Session},
+@samp{Save for Future Sessions} and the various kinds of @samp{Reset}
+operation for the group; these operations on the group apply to all
+options in the group and its subgroups.
+
+ Near the top of the customization buffer there are two lines
+containing several active fields:
+
+@smallexample
+ [Set for Current Session] [Save for Future Sessions]
+ [Reset] [Reset to Saved] [Reset to Standard] [Bury Buffer]
+@end smallexample
+
+@noindent
+Invoking @samp{[Bury Buffer]} buries this customization buffer. Each of
+the other fields performs an operation---set, save or reset---on each of
+the items in the buffer that could meaningfully be set, saved or reset.
+
+@node Face Customization
+@subsubsection Customizing Faces
+@cindex customizing faces
+@cindex bold font
+@cindex italic font
+@cindex fonts and faces
+
+ In addition to user options, some customization groups also include
+faces. When you show the contents of a group, both the user options and
+the faces in the group appear in the customization buffer. Here is an
+example of how a face looks:
+
+@smallexample
+Custom Changed Face: (sample)
+ [State]: this face is unchanged from its standard setting.
+Face used when the customize item has been changed.
+Attributes: [ ] Bold: [toggle] off
+ [X] Italic: [toggle] on
+ [ ] Underline: [toggle] off
+ [ ] Inverse-Video: [toggle] on
+ [ ] Foreground: black (sample)
+ [ ] Background: white (sample)
+ [ ] Stipple:
+@end smallexample
+
+ Each face attribute has its own line. The @samp{[@var{x}]} field
+before the attribute name indicates whether the attribute is
+@dfn{enabled}; @samp{X} means that it is. You can enable or disable the
+attribute by invoking that field. When the attribute is enabled, you
+can change the attribute value in the usual ways.
+
+ On a black-and-white display, the colors you can use for the
+background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1},
+and @samp{gray3}. Emacs supports these shades of gray by using
+background stipple patterns instead of a color.
+
+ Setting, saving and resetting a face work like the same operations for
+options (@pxref{Changing an Option}).
+
+ A face can specify different appearances for different types of
+display. For example, a face can make text red on a color display, but
+use a bold font on a monochrome display. To specify multiple
+appearances for a face, select @samp{Show Display Types} in the menu you
+get from invoking @samp{[State]}.
+
+@findex modify-face
+ Another more basic way to set the attributes of a specific face is
+with @kbd{M-x modify-face}. This command reads the name of a face, then
+reads the attributes one by one. For the color and stipple attributes,
+the attribute's current value is the default---type just @key{RET} if
+you don't want to change that attribute. Type @samp{none} if you want
+to clear out the attribute.
+
+@node Specific Customization
+@subsubsection Customizing Specific Items
+
+ Instead of finding the options you want to change by moving down
+through the structure of groups, you can specify the particular option,
+face or group that you want to customize.
+
+@table @kbd
+@item M-x customize-option @key{RET} @var{option} @key{RET}
+Set up a customization buffer with just one option, @var{option}.
+@item M-x customize-face @key{RET} @var{face} @key{RET}
+Set up a customization buffer with just one face, @var{face}.
+@item M-x customize-group @key{RET} @var{group} @key{RET}
+Set up a customization buffer with just one group, @var{group}.
+@item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
+Set up a customization buffer with all the options, faces and groups
+that match @var{regexp}.
+@item M-x customize-changed-options @key{RET} @var{version} @key{RET}
+Set up a customization buffer with all the options, faces and groups
+whose meaning has changed since Emacs version @var{version}.
+@item M-x customize-saved
+Set up a customization buffer containing all options and faces that you
+have saved with customization buffers.
+@item M-x customize-customized
+Set up a customization buffer containing all options and faces that you
+have customized but not saved.
+@end table
+
+@findex customize-option
+ If you want to alter a particular user option variable with the
+customization buffer, and you know its name, you can use the command
+@kbd{M-x customize-option} and specify the option name. This sets up
+the customization buffer with just one option---the one that you asked
+for. Editing, setting and saving the value work as described above, but
+only for the specified option.
+
+@findex customize-face
+ Likewise, you can modify a specific face, chosen by name, using
+@kbd{M-x customize-face}.
+
+@findex customize-group
+ You can also set up the customization buffer with a specific group,
+using @kbd{M-x customize-group}. The immediate contents of the chosen
+group, including option variables, faces, and other groups, all appear
+as well. However, these subgroups' own contents start out hidden. You
+can show their contents in the usual way, by invoking @samp{[Show]}.
+
+@findex customize-apropos
+ To control more precisely what to customize, you can use @kbd{M-x
+customize-apropos}. You specify a regular expression as argument; then
+all options, faces and groups whose names match this regular expression
+are set up in the customization buffer. If you specify an empty regular
+expression, this includes @emph{all} groups, options and faces in the
+customization buffer (but that takes a long time).
+
+@findex customize-changed-options
+ When you upgrade to a new Emacs version, you might want to customize
+new options and options whose meanings or default values have changed.
+To do this, use @kbd{M-x customize-changed-options} and specify a
+previous Emacs version number using the minibuffer. It creates a
+customization buffer which shows all the options (and groups) whose
+definitions have been changed since the specified version.
+
+@findex customize-saved
+@findex customize-customized
+ If you change option values and then decide the change was a mistake,
+you can use two special commands to revisit your previous changes. Use
+@kbd{customize-saved} to look at the options and faces that you have
+saved. Use @kbd{M-x customize-customized} to look at the options and
+faces that you have set but not saved.
+
+@node Hooks
+@subsection Hooks
+@cindex hook
+@cindex hook function
+@cindex running a hook
+
+ @dfn{Hooks} are an important mechanism for customization of Emacs. A
+hook is a Lisp variable which holds a list of functions, to be called on
+some well-defined occasion. (This is called @dfn{running the hook}.)
+The individual functions in the list are called the @dfn{hook functions}
+of the hook. With rare exceptions, hooks in Emacs are empty when Emacs
+starts up, so the only hook functions in any given hook are the ones you
+explicitly put there as customization.
+
+ Most major modes run one or more @dfn{mode hooks} as the last step of
+initialization. This makes it easy for you to customize the behavior of
+the mode, by setting up a hook function to override the local variable
+assignments already made by the mode. But hooks are also used in other
+contexts. For example, the hook @code{suspend-hook} runs just before
+Emacs suspends itself (@pxref{Exiting}).
+
+@cindex normal hook
+ Most Emacs hooks are @dfn{normal hooks}. This means that running the
+hook operates by calling all the hook functions, unconditionally, with
+no arguments. We have made an effort to keep most hooks normal so that
+you can use them in a uniform way. Every variable in Emacs whose name
+ends in @samp{-hook} is a normal hook.
+
+@cindex abnormal hook
+ There are also a few @dfn{abnormal hooks}. These variables' names end
+in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What
+makes these hooks abnormal is that there is something peculiar about the
+way its functions are called---perhaps they are given arguments, or
+perhaps the values they return are used in some way. For example,
+@code{find-file-not-found-hooks} (@pxref{Visiting}) is abnormal because
+as soon as one hook function returns a non-@code{nil} value, the rest
+are not called at all. The documentation of each abnormal hook variable
+explains in detail what is peculiar about it.
+
+ The recommended way to add a hook function to a hook (either normal or
+abnormal) is by calling @code{add-hook}. You can use any valid Lisp
+function as the hook function, provided it can handle the proper number
+of arguments (zero arguments, in the case of a normal hook). Of course,
+not every Lisp function is @emph{useful} in any particular hook.
+
+ For example, here's how to set up a hook to turn on Auto Fill mode
+when entering Text mode and other modes based on Text mode:
+
+@example
+(add-hook 'text-mode-hook 'turn-on-auto-fill)
+@end example
+
+ The next example shows how to use a hook to customize the indentation
+of C code. (People often have strong personal preferences for one
+format compared to another.) Here the hook function is an anonymous
+lambda expression.
+
+@example
+@group
+(setq my-c-style
+ '((c-comment-only-line-offset . 4)
+@end group
+@group
+ (c-cleanup-list . (scope-operator
+ empty-defun-braces
+ defun-close-semi))
+@end group
+@group
+ (c-offsets-alist . ((arglist-close . c-lineup-arglist)
+ (substatement-open . 0)))))
+@end group
+
+@group
+(add-hook 'c-mode-common-hook
+ (function (lambda ()
+ (c-add-style "my-style" my-c-style t))))
+@end group
+@end example
+
+ It is best to design your hook functions so that the order in which
+they are executed does not matter. Any dependence on the order is
+``asking for trouble.'' However, the order is predictable: the most
+recently added hook functions are executed first.
+
+@node Locals
+@subsection Local Variables
+
+@table @kbd
+@item M-x make-local-variable @key{RET} @var{var} @key{RET}
+Make variable @var{var} have a local value in the current buffer.
+@item M-x kill-local-variable @key{RET} @var{var} @key{RET}
+Make variable @var{var} use its global value in the current buffer.
+@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET}
+Mark variable @var{var} so that setting it will make it local to the
+buffer that is current at that time.
+@end table
+
+@cindex local variables
+ Almost any variable can be made @dfn{local} to a specific Emacs
+buffer. This means that its value in that buffer is independent of its
+value in other buffers. A few variables are always local in every
+buffer. Every other Emacs variable has a @dfn{global} value which is in
+effect in all buffers that have not made the variable local.
+
+@findex make-local-variable
+ @kbd{M-x make-local-variable} reads the name of a variable and makes it
+local to the current buffer. Further changes in this buffer will not
+affect others, and further changes in the global value will not affect this
+buffer.
+
+@findex make-variable-buffer-local
+@cindex per-buffer variables
+ @kbd{M-x make-variable-buffer-local} reads the name of a variable and
+changes the future behavior of the variable so that it will become local
+automatically when it is set. More precisely, once a variable has been
+marked in this way, the usual ways of setting the variable automatically
+do @code{make-local-variable} first. We call such variables
+@dfn{per-buffer} variables.
+
+ Major modes (@pxref{Major Modes}) always make variables local to the
+buffer before setting the variables. This is why changing major modes
+in one buffer has no effect on other buffers. Minor modes also work by
+setting variables---normally, each minor mode has one controlling
+variable which is non-@code{nil} when the mode is enabled (@pxref{Minor
+Modes}). For most minor modes, the controlling variable is per buffer.
+
+ Emacs contains a number of variables that are always per-buffer.
+These include @code{abbrev-mode}, @code{auto-fill-function},
+@code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
+@code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
+@code{left-margin}, @code{mode-line-format}, @code{overwrite-mode},
+@code{selective-display-ellipses}, @code{selective-display},
+@code{tab-width}, and @code{truncate-lines}. Some other variables are
+always local in every buffer, but they are used for internal
+purposes.@refill
+
+ A few variables cannot be local to a buffer because they are always
+local to each display instead (@pxref{Multiple Displays}). If you try to
+make one of these variables buffer-local, you'll get an error message.
+
+@findex kill-local-variable
+ @kbd{M-x kill-local-variable} reads the name of a variable and makes
+it cease to be local to the current buffer. The global value of the
+variable henceforth is in effect in this buffer. Setting the major mode
+kills all the local variables of the buffer except for a few variables
+specially marked as @dfn{permanent locals}.
+
+@findex setq-default
+ To set the global value of a variable, regardless of whether the
+variable has a local value in the current buffer, you can use the Lisp
+construct @code{setq-default}. This construct is used just like
+@code{setq}, but it sets variables' global values instead of their local
+values (if any). When the current buffer does have a local value, the
+new global value may not be visible until you switch to another buffer.
+Here is an example:
+
+@example
+(setq-default fill-column 75)
+@end example
+
+@noindent
+@code{setq-default} is the only way to set the global value of a variable
+that has been marked with @code{make-variable-buffer-local}.
+
+@findex default-value
+ Lisp programs can use @code{default-value} to look at a variable's
+default value. This function takes a symbol as argument and returns its
+default value. The argument is evaluated; usually you must quote it
+explicitly. For example, here's how to obtain the default value of
+@code{fill-column}:
+
+@example
+(default-value 'fill-column)
+@end example
+
+@node File Variables
+@subsection Local Variables in Files
+@cindex local variables in files
+@cindex file local variables
+
+ A file can specify local variable values for use when you edit the
+file with Emacs. Visiting the file checks for local variable
+specifications; it automatically makes these variables local to the
+buffer, and sets them to the values specified in the file.
+
+ There are two ways to specify local variable values: in the first
+line, or with a local variables list. Here's how to specify them in the
+first line:
+
+@example
+-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
+@end example
+
+@noindent
+You can specify any number of variables/value pairs in this way, each
+pair with a colon and semicolon as shown above. @code{mode:
+@var{modename};} specifies the major mode; this should come first in the
+line. The @var{value}s are not evaluated; they are used literally.
+Here is an example that specifies Lisp mode and sets two variables with
+numeric values:
+
+@smallexample
+;; -*-mode: Lisp; fill-column: 75; comment-column: 50; -*-
+@end smallexample
+
+ You can also specify the coding system for a file in this way: just
+specify a value for the ``variable'' named @code{coding}. The ``value''
+must be a coding system name that Emacs recognizes. @xref{Coding
+Systems}.
+
+ A @dfn{local variables list} goes near the end of the file, in the
+last page. (It is often best to put it on a page by itself.) The local
+variables list starts with a line containing the string @samp{Local
+Variables:}, and ends with a line containing the string @samp{End:}. In
+between come the variable names and values, one set per line, as
+@samp{@var{variable}:@: @var{value}}. The @var{value}s are not
+evaluated; they are used literally. If a file has both a local
+variables list and a @samp{-*-} line, Emacs processes @emph{everything}
+in the @samp{-*-} line first, and @emph{everything} in the local
+variables list afterward.
+
+Here is an example of a local variables list:
+
+@example
+;;; Local Variables: ***
+;;; mode:lisp ***
+;;; comment-column:0 ***
+;;; comment-start: ";;; " ***
+;;; comment-end:"***" ***
+;;; End: ***
+@end example
+
+ As you see, each line starts with the prefix @samp{;;; } and each line
+ends with the suffix @samp{ ***}. Emacs recognizes these as the prefix
+and suffix based on the first line of the list, by finding them
+surrounding the magic string @samp{Local Variables:}; then it
+automatically discards them from the other lines of the list.
+
+ The usual reason for using a prefix and/or suffix is to embed the
+local variables list in a comment, so it won't confuse other programs
+that the file is intended as input for. The example above is for a
+language where comment lines start with @samp{;;; } and end with
+@samp{***}; the local values for @code{comment-start} and
+@code{comment-end} customize the rest of Emacs for this unusual syntax.
+Don't use a prefix (or a suffix) if you don't need one.
+
+ Two ``variable names'' have special meanings in a local variables
+list: a value for the variable @code{mode} really sets the major mode,
+and a value for the variable @code{eval} is simply evaluated as an
+expression and the value is ignored. @code{mode} and @code{eval} are
+not real variables; setting variables named @code{mode} and @code{eval}
+in any other context has no special meaning. If @code{mode} is used to
+set a major mode, it should be the first ``variable'' in the list.
+
+ You can use the @code{mode} ``variable'' to set minor modes as well as
+major modes; in fact, you can use it more than once, first to set the
+major mode and then to set minor modes which are specific to particular
+buffers. But most minor modes should not be specified in the file in
+any fashion, because they represent user preferences.
+
+ For example, you may be tempted to try to turn on Auto Fill mode with
+a local variable list. That is a mistake. The choice of Auto Fill mode
+or not is a matter of individual taste, not a matter of the contents of
+particular files. If you want to use Auto Fill, set up major mode hooks
+with your @file{.emacs} file to turn it on (when appropriate) for you
+alone (@pxref{Init File}). Don't use a local variable list to impose
+your taste on everyone.
+
+ The start of the local variables list must be no more than 3000
+characters from the end of the file, and must be in the last page if the
+file is divided into pages. Otherwise, Emacs will not notice it is
+there. The purpose of this rule is so that a stray @samp{Local
+Variables:}@: not in the last page does not confuse Emacs, and so that
+visiting a long file that is all one page and has no local variables
+list need not take the time to search the whole file.
+
+ Use the command @code{normal-mode} to reset the local variables and
+major mode of a buffer according to the file name and contents,
+including the local variables list if any. @xref{Choosing Modes}.
+
+@findex enable-local-variables
+ The variable @code{enable-local-variables} controls whether to process
+local variables in files, and thus gives you a chance to override them.
+Its default value is @code{t}, which means do process local variables in
+files. If you set the value to @code{nil}, Emacs simply ignores local
+variables in files. Any other value says to query you about each file
+that has local variables, showing you the local variable specifications
+so you can judge.
+
+@findex enable-local-eval
+ The @code{eval} ``variable,'' and certain actual variables, create a
+special risk; when you visit someone else's file, local variable
+specifications for these could affect your Emacs in arbitrary ways.
+Therefore, the option @code{enable-local-eval} controls whether Emacs
+processes @code{eval} variables, as well variables with names that end
+in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions},
+and certain other variables. The three possibilities for the option's
+value are @code{t}, @code{nil}, and anything else, just as for
+@code{enable-local-variables}. The default is @code{maybe}, which is
+neither @code{t} nor @code{nil}, so normally Emacs does ask for
+confirmation about file settings for these variables.
+
+@node Keyboard Macros
+@section Keyboard Macros
+
+@cindex defining keyboard macros
+@cindex keyboard macro
+ A @dfn{keyboard macro} is a command defined by the user to stand for
+another sequence of keys. For example, if you discover that you are
+about to type @kbd{C-n C-d} forty times, you can speed your work by
+defining a keyboard macro to do @kbd{C-n C-d} and calling it with a
+repeat count of forty.
+
+@c widecommands
+@table @kbd
+@item C-x (
+Start defining a keyboard macro (@code{start-kbd-macro}).
+@item C-x )
+End the definition of a keyboard macro (@code{end-kbd-macro}).
+@item C-x e
+Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
+@item C-u C-x (
+Re-execute last keyboard macro, then add more keys to its definition.
+@item C-x q
+When this point is reached during macro execution, ask for confirmation
+(@code{kbd-macro-query}).
+@item M-x name-last-kbd-macro
+Give a command name (for the duration of the session) to the most
+recently defined keyboard macro.
+@item M-x insert-kbd-macro
+Insert in the buffer a keyboard macro's definition, as Lisp code.
+@item C-x C-k
+Edit a previously defined keyboard macro (@code{edit-kbd-macro}).
+@item M-x apply-macro-to-region-lines
+Run the last keyboard macro on each complete line in the region.
+@end table
+
+ Keyboard macros differ from ordinary Emacs commands in that they are
+written in the Emacs command language rather than in Lisp. This makes it
+easier for the novice to write them, and makes them more convenient as
+temporary hacks. However, the Emacs command language is not powerful
+enough as a programming language to be useful for writing anything
+intelligent or general. For such things, Lisp must be used.
+
+ You define a keyboard macro while executing the commands which are the
+definition. Put differently, as you define a keyboard macro, the
+definition is being executed for the first time. This way, you can see
+what the effects of your commands are, so that you don't have to figure
+them out in your head. When you are finished, the keyboard macro is
+defined and also has been, in effect, executed once. You can then do the
+whole thing over again by invoking the macro.
+
+@menu
+* Basic Kbd Macro:: Defining and running keyboard macros.
+* Save Kbd Macro:: Giving keyboard macros names; saving them in files.
+* Kbd Macro Query:: Making keyboard macros do different things each time.
+@end menu
+
+@node Basic Kbd Macro
+@subsection Basic Use
+
+@kindex C-x (
+@kindex C-x )
+@kindex C-x e
+@findex start-kbd-macro
+@findex end-kbd-macro
+@findex call-last-kbd-macro
+ To start defining a keyboard macro, type the @kbd{C-x (} command
+(@code{start-kbd-macro}). From then on, your keys continue to be
+executed, but also become part of the definition of the macro. @samp{Def}
+appears in the mode line to remind you of what is going on. When you are
+finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
+definition (without becoming part of it!). For example,
+
+@example
+C-x ( M-f foo C-x )
+@end example
+
+@noindent
+defines a macro to move forward a word and then insert @samp{foo}.
+
+ The macro thus defined can be invoked again with the @kbd{C-x e}
+command (@code{call-last-kbd-macro}), which may be given a repeat count
+as a numeric argument to execute the macro many times. @kbd{C-x )} can
+also be given a repeat count as an argument, in which case it repeats
+the macro that many times right after defining it, but defining the
+macro counts as the first repetition (since it is executed as you define
+it). Therefore, giving @kbd{C-x )} an argument of 4 executes the macro
+immediately 3 additional times. An argument of zero to @kbd{C-x e} or
+@kbd{C-x )} means repeat the macro indefinitely (until it gets an error
+or you type @kbd{C-g} or, on MS-DOS, @kbd{C-@key{BREAK}}).
+
+ If you wish to repeat an operation at regularly spaced places in the
+text, define a macro and include as part of the macro the commands to move
+to the next place you want to use it. For example, if you want to change
+each line, you should position point at the start of a line, and define a
+macro to change that line and leave point at the start of the next line.
+Then repeating the macro will operate on successive lines.
+
+ After you have terminated the definition of a keyboard macro, you can add
+to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
+to plain @kbd{C-x (} followed by retyping the whole definition so far. As
+a consequence it re-executes the macro as previously defined.
+
+ You can use function keys in a keyboard macro, just like keyboard
+keys. You can even use mouse events, but be careful about that: when
+the macro replays the mouse event, it uses the original mouse position
+of that event, the position that the mouse had while you were defining
+the macro. The effect of this may be hard to predict. (Using the
+current mouse position would be even less predictable.)
+
+ One thing that doesn't always work well in a keyboard macro is the
+command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command
+exits a recursive edit that started within the macro, it works as you'd
+expect. But if it exits a recursive edit that started before you
+invoked the keyboard macro, it also necessarily exits the keyboard macro
+as part of the process.
+
+@findex edit-kbd-macro
+@kindex C-x C-k
+ You can edit a keyboard macro already defined by typing @kbd{C-x C-k}
+(@code{edit-kbd-macro}). Follow that with the keyboard input that you
+would use to invoke the macro---@kbd{C-x e} or @kbd{M-x @var{name}} or
+some other key sequence. This formats the macro definition in a buffer
+and enters a specialized major mode for editing it. Type @kbd{C-h m}
+once in that buffer to display details of how to edit the macro. When
+you are finished editing, type @kbd{C-c C-c}.
+
+@findex apply-macro-to-region-lines
+ The command @kbd{M-x apply-macro-to-region-lines} repeats the last
+defined keyboard macro on each complete line within the current region.
+It does this line by line, by moving point to the beginning of the line
+and then executing the macro.
+
+@node Save Kbd Macro
+@subsection Naming and Saving Keyboard Macros
+
+@cindex saving keyboard macros
+@findex name-last-kbd-macro
+ If you wish to save a keyboard macro for longer than until you define the
+next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
+This reads a name as an argument using the minibuffer and defines that name
+to execute the macro. The macro name is a Lisp symbol, and defining it in
+this way makes it a valid command name for calling with @kbd{M-x} or for
+binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you
+specify a name that has a prior definition other than another keyboard
+macro, an error message is printed and nothing is changed.
+
+@findex insert-kbd-macro
+ Once a macro has a command name, you can save its definition in a file.
+Then it can be used in another editing session. First, visit the file
+you want to save the definition in. Then use this command:
+
+@example
+M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
+@end example
+
+@noindent
+This inserts some Lisp code that, when executed later, will define the
+same macro with the same definition it has now. (You need not
+understand Lisp code to do this, because @code{insert-kbd-macro} writes
+the Lisp code for you.) Then save the file. You can load the file
+later with @code{load-file} (@pxref{Lisp Libraries}). If the file you
+save in is your init file @file{~/.emacs} (@pxref{Init File}) then the
+macro will be defined each time you run Emacs.
+
+ If you give @code{insert-kbd-macro} a numeric argument, it makes
+additional Lisp code to record the keys (if any) that you have bound to the
+keyboard macro, so that the macro will be reassigned the same keys when you
+load the file.
+
+@node Kbd Macro Query
+@subsection Executing Macros with Variations
+
+@kindex C-x q
+@findex kbd-macro-query
+ Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect
+similar to that of @code{query-replace}, where the macro asks you each
+time around whether to make a change. While defining the macro,
+type @kbd{C-x q} at the point where you want the query to occur. During
+macro definition, the @kbd{C-x q} does nothing, but when you run the
+macro later, @kbd{C-x q} asks you interactively whether to continue.
+
+ The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}),
+@key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}.
+The answers are the same as in @code{query-replace}, though not all of
+the @code{query-replace} options are meaningful.
+
+ These responses include @key{SPC} to continue, and @key{DEL} to skip
+the remainder of this repetition of the macro and start right away with
+the next repetition. @key{RET} means to skip the remainder of this
+repetition and cancel further repetitions. @kbd{C-l} redraws the screen
+and asks you again for a character to say what to do.
+
+ @kbd{C-r} enters a recursive editing level, in which you can perform
+editing which is not part of the macro. When you exit the recursive
+edit using @kbd{C-M-c}, you are asked again how to continue with the
+keyboard macro. If you type a @key{SPC} at this time, the rest of the
+macro definition is executed. It is up to you to leave point and the
+text in a state such that the rest of the macro will do what you
+want.@refill
+
+ @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument,
+performs a completely different function. It enters a recursive edit
+reading input from the keyboard, both when you type it during the
+definition of the macro, and when it is executed from the macro. During
+definition, the editing you do inside the recursive edit does not become
+part of the macro. During macro execution, the recursive edit gives you
+a chance to do some particularized editing on each repetition.
+@xref{Recursive Edit}.
+
+ Another way to vary the behavior of a keyboard macro is to use a
+register as a counter, incrementing it on each repetition of the macro.
+@xref{RegNumbers}.
+
+@node Key Bindings
+@section Customizing Key Bindings
+@cindex key bindings
+
+ This section describes @dfn{key bindings}, which map keys to commands,
+and @dfn{keymaps}, which record key bindings. It also explains how
+to customize key bindings.
+
+ Recall that a command is a Lisp function whose definition provides for
+interactive use. Like every Lisp function, a command has a function
+name which usually consists of lower-case letters and hyphens.
+
+@menu
+* Keymaps:: Generalities. The global keymap.
+* Prefix Keymaps:: Keymaps for prefix keys.
+* Local Keymaps:: Major and minor modes have their own keymaps.
+* Minibuffer Maps:: The minibuffer uses its own local keymaps.
+* Rebinding:: How to redefine one key's meaning conveniently.
+* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}.
+* Function Keys:: Rebinding terminal function keys.
+* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on.
+* Non-ASCII Rebinding:: Rebinding non-ASCII characters such as Latin-1.
+* Mouse Buttons:: Rebinding mouse buttons in Emacs.
+* Disabling:: Disabling a command means confirmation is required
+ before it can be executed. This is done to protect
+ beginners from surprises.
+@end menu
+
+@node Keymaps
+@subsection Keymaps
+@cindex keymap
+
+ The bindings between key sequences and command functions are recorded
+in data structures called @dfn{keymaps}. Emacs has many of these, each
+used on particular occasions.
+
+ Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence
+of @dfn{input events} that have a meaning as a unit. Input events
+include characters, function keys and mouse buttons---all the inputs
+that you can send to the computer with your terminal. A key sequence
+gets its meaning from its @dfn{binding}, which says what command it
+runs. The function of keymaps is to record these bindings.
+
+@cindex global keymap
+ The @dfn{global} keymap is the most important keymap because it is
+always in effect. The global keymap defines keys for Fundamental mode;
+most of these definitions are common to most or all major modes. Each
+major or minor mode can have its own keymap which overrides the global
+definitions of some keys.
+
+ For example, a self-inserting character such as @kbd{g} is
+self-inserting because the global keymap binds it to the command
+@code{self-insert-command}. The standard Emacs editing characters such
+as @kbd{C-a} also get their standard meanings from the global keymap.
+Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work
+by storing the new binding in the proper place in the global map.
+@xref{Rebinding}.
+
+ Meta characters work differently; Emacs translates each Meta
+character into a pair of characters starting with @key{ESC}. When you
+type the character @kbd{M-a} in a key sequence, Emacs replaces it with
+@kbd{@key{ESC} a}. A meta key comes in as a single input event, but
+becomes two events for purposes of key bindings. The reason for this is
+historical, and we might change it someday.
+
+@cindex function key
+ Most modern keyboards have function keys as well as character keys.
+Function keys send input events just as character keys do, and keymaps
+can have bindings for them.
+
+ On many terminals, typing a function key actually sends the computer a
+sequence of characters; the precise details of the sequence depends on
+which function key and on the model of terminal you are using. (Often
+the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your
+terminal type properly, it recognizes the character sequences forming
+function keys wherever they occur in a key sequence (not just at the
+beginning). Thus, for most purposes, you can pretend the function keys
+reach Emacs directly and ignore their encoding as character sequences.
+
+@cindex mouse
+ Mouse buttons also produce input events. These events come with other
+data---the window and position where you pressed or released the button,
+and a time stamp. But only the choice of button matters for key
+bindings; the other data matters only if a command looks at it.
+(Commands designed for mouse invocation usually do look at the other
+data.)
+
+ A keymap records definitions for single events. Interpreting a key
+sequence of multiple events involves a chain of keymaps. The first
+keymap gives a definition for the first event; this definition is
+another keymap, which is used to look up the second event in the
+sequence, and so on.
+
+ Key sequences can mix function keys and characters. For example,
+@kbd{C-x @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix
+key, then @kbd{@key{SELECT} C-n} makes sense. You can even mix mouse
+events with keyboard events, but we recommend against it, because such
+sequences are inconvenient to type in.
+
+ As a user, you can redefine any key; but it might be best to stick to
+key sequences that consist of @kbd{C-c} followed by a letter. These
+keys are ``reserved for users,'' so they won't conflict with any
+properly designed Emacs extension. The function keys @key{F5} through
+@key{F9} are also reserved for users. If you redefine some other key,
+your definition may be overridden by certain extensions or major modes
+which redefine the same key.
+
+@node Prefix Keymaps
+@subsection Prefix Keymaps
+
+ A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap,
+which holds the definition for the event that immediately follows
+that prefix.
+
+ The definition of a prefix key is usually the keymap to use for
+looking up the following event. The definition can also be a Lisp
+symbol whose function definition is the following keymap; the effect is
+the same, but it provides a command name for the prefix key that can be
+used as a description of what the prefix key is for. Thus, the binding
+of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
+definition is the keymap for @kbd{C-x} commands. The definitions of
+@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in
+the global map, so these prefix keys are always available.
+
+ Aside from ordinary prefix keys, there is a fictitious ``prefix key''
+which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp
+Reference Manual}, for special information about menu bar key bindings.
+Mouse button events that invoke pop-up menus are also prefix keys; see
+@ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more
+details.
+
+ Some prefix keymaps are stored in variables with names:
+
+@itemize @bullet
+@item
+@vindex ctl-x-map
+@code{ctl-x-map} is the variable name for the map used for characters that
+follow @kbd{C-x}.
+@item
+@vindex help-map
+@code{help-map} is for characters that follow @kbd{C-h}.
+@item
+@vindex esc-map
+@code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta
+characters are actually defined by this map.
+@item
+@vindex ctl-x-4-map
+@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
+@item
+@vindex mode-specific-map
+@code{mode-specific-map} is for characters that follow @kbd{C-c}.
+@end itemize
+
+@node Local Keymaps
+@subsection Local Keymaps
+
+@cindex local keymap
+ So far we have explained the ins and outs of the global map. Major
+modes customize Emacs by providing their own key bindings in @dfn{local
+keymaps}. For example, C mode overrides @key{TAB} to make it indent the
+current line for C code. Portions of text in the buffer can specify
+their own keymaps to substitute for the keymap of the buffer's major
+mode.
+
+@cindex minor mode keymap
+ Minor modes can also have local keymaps. Whenever a minor mode is
+in effect, the definitions in its keymap override both the major
+mode's local keymap and the global keymap.
+
+@vindex c-mode-map
+@vindex lisp-mode-map
+ The local keymaps for Lisp mode and several other major modes always
+exist even when not in use. These are kept in variables named
+@code{lisp-mode-map} and so on. For major modes less often used, the
+local keymap is normally constructed only when the mode is used for the
+first time in a session. This is to save space. If you wish to change
+one of these keymaps, you must use the major mode's @dfn{mode
+hook}---see below.
+
+ All minor mode keymaps are created in advance. There is no way to
+defer their creation until the first time the minor mode is enabled.
+
+ A local keymap can locally redefine a key as a prefix key by defining
+it as a prefix keymap. If the key is also defined globally as a prefix,
+then its local and global definitions (both keymaps) effectively
+combine: both of them are used to look up the event that follows the
+prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as
+another keymap, and that keymap defines @kbd{C-z} as a command, this
+provides a local meaning for @kbd{C-c C-z}. This does not affect other
+sequences that start with @kbd{C-c}; if those sequences don't have their
+own local bindings, their global bindings remain in effect.
+
+ Another way to think of this is that Emacs handles a multi-event key
+sequence by looking in several keymaps, one by one, for a binding of the
+whole key sequence. First it checks the minor mode keymaps for minor
+modes that are enabled, then it checks the major mode's keymap, and then
+it checks the global keymap. This is not precisely how key lookup
+works, but it's good enough for understanding ordinary circumstances.
+
+@cindex rebinding major mode keys
+ To change the local bindings of a major mode, you must change the
+mode's local keymap. Normally you must wait until the first time the
+mode is used, because most major modes don't create their keymaps until
+then. If you want to specify something in your @file{~/.emacs} file to
+change a major mode's bindings, you must use the mode's mode hook to
+delay the change until the mode is first used.
+
+ For example, the command @code{texinfo-mode} to select Texinfo mode
+runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook
+to add local bindings (not very useful, we admit) for @kbd{C-c n} and
+@kbd{C-c p} in Texinfo mode:
+
+@example
+(add-hook 'texinfo-mode-hook
+ '(lambda ()
+ (define-key texinfo-mode-map
+ "\C-cp"
+ 'backward-paragraph)
+ (define-key texinfo-mode-map
+ "\C-cn"
+ 'forward-paragraph)
+ ))
+@end example
+
+ @xref{Hooks}.
+
+@node Minibuffer Maps
+@subsection Minibuffer Keymaps
+
+@cindex minibuffer keymaps
+@vindex minibuffer-local-map
+@vindex minibuffer-local-ns-map
+@vindex minibuffer-local-completion-map
+@vindex minibuffer-local-must-match-map
+ The minibuffer has its own set of local keymaps; they contain various
+completion and exit commands.
+
+@itemize @bullet
+@item
+@code{minibuffer-local-map} is used for ordinary input (no completion).
+@item
+@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
+just like @key{RET}. This is used mainly for Mocklisp compatibility.
+@item
+@code{minibuffer-local-completion-map} is for permissive completion.
+@item
+@code{minibuffer-local-must-match-map} is for strict completion and
+for cautious completion.
+@end itemize
+
+@node Rebinding
+@subsection Changing Key Bindings Interactively
+@cindex key rebinding, this session
+@cindex rebinding keys, this session
+
+ The way to redefine an Emacs key is to change its entry in a keymap.
+You can change the global keymap, in which case the change is effective in
+all major modes (except those that have their own overriding local
+definitions for the same key). Or you can change the current buffer's
+local map, which affects all buffers using the same major mode.
+
+@findex global-set-key
+@findex local-set-key
+@findex global-unset-key
+@findex local-unset-key
+@table @kbd
+@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
+Define @var{key} globally to run @var{cmd}.
+@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
+Define @var{key} locally (in the major mode now in effect) to run
+@var{cmd}.
+@item M-x global-unset-key @key{RET} @var{key}
+Make @var{key} undefined in the global map.
+@item M-x local-unset-key @key{RET} @var{key}
+Make @var{key} undefined locally (in the major mode now in effect).
+@end table
+
+ For example, suppose you like to execute commands in a subshell within
+an Emacs buffer, instead of suspending Emacs and executing commands in
+your login shell. Normally, @kbd{C-z} is bound to the function
+@code{suspend-emacs} (when not using the X Window System), but you can
+change @kbd{C-z} to invoke an interactive subshell within Emacs, by
+binding it to @code{shell} as follows:
+
+@example
+M-x global-set-key @key{RET} C-z shell @key{RET}
+@end example
+
+@noindent
+@code{global-set-key} reads the command name after the key. After you
+press the key, a message like this appears so that you can confirm that
+you are binding the key you want:
+
+@example
+Set key C-z to command:
+@end example
+
+ You can redefine function keys and mouse events in the same way; just
+type the function key or click the mouse when it's time to specify the
+key to rebind.
+
+ You can rebind a key that contains more than one event in the same
+way. Emacs keeps reading the key to rebind until it is a complete key
+(that is, not a prefix key). Thus, if you type @kbd{C-f} for
+@var{key}, that's the end; the minibuffer is entered immediately to
+read @var{cmd}. But if you type @kbd{C-x}, another character is read;
+if that is @kbd{4}, another character is read, and so on. For
+example,
+
+@example
+M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
+@end example
+
+@noindent
+redefines @kbd{C-x 4 $} to run the (fictitious) command
+@code{spell-other-window}.
+
+ The two-character keys consisting of @kbd{C-c} followed by a letter
+are reserved for user customizations. Lisp programs are not supposed to
+define these keys, so the bindings you make for them will be available
+in all major modes and will never get in the way of anything.
+
+ You can remove the global definition of a key with
+@code{global-unset-key}. This makes the key @dfn{undefined}; if you
+type it, Emacs will just beep. Similarly, @code{local-unset-key} makes
+a key undefined in the current major mode keymap, which makes the global
+definition (or lack of one) come back into effect in that major mode.
+
+ If you have redefined (or undefined) a key and you subsequently wish
+to retract the change, undefining the key will not do the job---you need
+to redefine the key with its standard definition. To find the name of
+the standard definition of a key, go to a Fundamental mode buffer and
+use @kbd{C-h c}. The documentation of keys in this manual also lists
+their command names.
+
+ If you want to prevent yourself from invoking a command by mistake, it
+is better to disable the command than to undefine the key. A disabled
+command is less work to invoke when you really want to.
+@xref{Disabling}.
+
+@node Init Rebinding
+@subsection Rebinding Keys in Your Init File
+
+@findex define-key
+@findex substitute-key-definition
+ If you have a set of key bindings that you like to use all the time,
+you can specify them in your @file{.emacs} file by using their Lisp
+syntax.
+
+ The simplest method for doing this works for ASCII characters and
+Meta-modified ASCII characters only. This method uses a string to
+represent the key sequence you want to rebind. For example, here's how
+to bind @kbd{C-z} to @code{shell}:
+
+@example
+(global-set-key "\C-z" 'shell)
+@end example
+
+@noindent
+This example uses a string constant containing one character, @kbd{C-z}.
+The single-quote before the command name, @code{shell}, marks it as a
+constant symbol rather than a variable. If you omit the quote, Emacs
+would try to evaluate @code{shell} immediately as a variable. This
+probably causes an error; it certainly isn't what you want.
+
+ Here is another example that binds a key sequence two characters long:
+
+@example
+(global-set-key "\C-xl" 'make-symbolic-link)
+@end example
+
+ When the key sequence includes function keys or mouse button events,
+or non-ASCII characters such as @code{C-=} or @code{H-a}, you must use
+the more general method of rebinding, which uses a vector to specify the
+key sequence.
+
+ The way to write a vector in Emacs Lisp is with square brackets around
+the vector elements. Use spaces to separate the elements. If an
+element is a symbol, simply write the symbol's name---no other
+delimiters or punctuation are needed. If a vector element is a
+character, write it as a Lisp character constant: @samp{?} followed by
+the character as it would appear in a string.
+
+ Here are examples of using vectors to rebind @kbd{C-=} (a control
+character outside of ASCII), @kbd{H-a} (a Hyper character; ASCII doesn't
+have Hyper at all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
+keyboard-modified mouse button):
+
+@example
+(global-set-key [?\C-=] 'make-symbolic-link)
+(global-set-key [?\H-a] 'make-symbolic-link)
+(global-set-key [f7] 'make-symbolic-link)
+(global-set-key [C-mouse-1] 'make-symbolic-link)
+@end example
+
+ You can use a vector for the simple cases too. Here's how to rewrite
+the first two examples, above, to use vectors:
+
+@example
+(global-set-key [?\C-z] 'shell)
+
+(global-set-key [?\C-x ?l] 'make-symbolic-link)
+@end example
+
+@node Function Keys
+@subsection Rebinding Function Keys
+
+ Key sequences can contain function keys as well as ordinary
+characters. Just as Lisp characters (actually integers) represent
+keyboard characters, Lisp symbols represent function keys. If the
+function key has a word as its label, then that word is also the name of
+the corresponding Lisp symbol. Here are the conventional Lisp names for
+common function keys:
+
+@table @asis
+@item @code{left}, @code{up}, @code{right}, @code{down}
+Cursor arrow keys.
+
+@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior}
+Other cursor repositioning keys.
+
+@item @code{select}, @code{print}, @code{execute}, @code{backtab}
+@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline}
+@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar},
+Miscellaneous function keys.
+
+@item @code{f1}, @code{f2}, @dots{} @code{f35}
+Numbered function keys (across the top of the keyboard).
+
+@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide}
+@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter}
+@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal}
+Keypad keys (to the right of the regular keyboard), with names or punctuation.
+
+@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9}
+Keypad keys with digits.
+
+@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
+Keypad PF keys.
+@end table
+
+ These names are conventional, but some systems (especially when using
+X windows) may use different names. To make certain what symbol is used
+for a given function key on your terminal, type @kbd{C-h c} followed by
+that key.
+
+ A key sequence which contains function key symbols (or anything but
+ASCII characters) must be a vector rather than a string. The vector
+syntax uses spaces between the elements, and square brackets around the
+whole vector. Thus, to bind function key @samp{f1} to the command
+@code{rmail}, write the following:
+
+@example
+(global-set-key [f1] 'rmail)
+@end example
+
+@noindent
+To bind the right-arrow key to the command @code{forward-char}, you can
+use this expression:
+
+@example
+(global-set-key [right] 'forward-char)
+@end example
+
+@noindent
+This uses the Lisp syntax for a vector containing the symbol
+@code{right}. (This binding is present in Emacs by default.)
+
+ @xref{Init Rebinding}, for more information about using vectors for
+rebinding.
+
+ You can mix function keys and characters in a key sequence. This
+example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}.
+
+@example
+(global-set-key [?\C-x next] 'forward-page)
+@end example
+
+@noindent
+where @code{?\C-x} is the Lisp character constant for the character
+@kbd{C-x}. The vector element @code{next} is a symbol and therefore
+does not take a question mark.
+
+ You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER},
+@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. To represent
+these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-},
+@samp{s-}, @samp{A-} and @samp{S-} at the front of the symbol name.
+Thus, here is how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a
+word:
+
+@example
+(global-set-key [H-M-right] 'forward-word)
+@end example
+
+@node Named ASCII Chars
+@subsection Named ASCII Control Characters
+
+ @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL}
+started out as names for certain ASCII control characters, used so often
+that they have special keys of their own. Later, users found it
+convenient to distinguish in Emacs between these keys and the ``same''
+control characters typed with the @key{CTRL} key.
+
+ Emacs distinguishes these two kinds of input, when used with the X
+Window System. It treats the ``special'' keys as function keys named
+@code{tab}, @code{return}, @code{backspace}, @code{linefeed},
+@code{escape}, and @code{delete}. These function keys translate
+automatically into the corresponding ASCII characters @emph{if} they
+have no bindings of their own. As a result, neither users nor Lisp
+programs need to pay attention to the distinction unless they care to.
+
+ If you do not want to distinguish between (for example) @key{TAB} and
+@kbd{C-i}, make just one binding, for the ASCII character @key{TAB}
+(octal code 011). If you do want to distinguish, make one binding for
+this ASCII character, and another for the ``function key'' @code{tab}.
+
+ With an ordinary ASCII terminal, there is no way to distinguish
+between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
+because the terminal sends the same character in both cases.
+
+@node Non-ASCII Rebinding
+@subsection Non-ASCII Characters on the Keyboard
+
+If your keyboard has keys that send non-ASCII characters, such as
+accented letters, rebinding these keys is a bit tricky. There are
+two solutions you can use. One is to specify a keyboard coding system,
+using @code{set-keyboard-coding-system} (@pxref{Specify Coding}).
+Then you can bind these keys in the usual way, but writing
+
+@example
+(global-set-key [?@var{char}] 'some-function)
+@end example
+
+@noindent
+and typing the key you want to bind to insert @var{char}.
+
+If you don't specify the keyboard coding system, that approach won't
+work. Instead, you need to find out the actual code that the terminal
+sends. The easiest way to do this in Emacs is to create an empty buffer
+with @kbd{C-x b temp @key{RET}}, make it unibyte with @kbd{M-x
+toggle-enable-multibyte-characters @key{RET}}, then type the key to
+insert the character into this buffer.
+
+Move point before the character, then type @kbd{C-x =}. This
+displays a message in the minibuffer, showing the character code in
+three ways, octal, decimal and hexadecimal, all within a set of
+parentheses. Use the second of the three numbers, the decimal one,
+inside the vector to bind:
+
+@example
+(global-set-key [@var{decimal-code}] 'some-function)
+@end example
+
+@node Mouse Buttons
+@subsection Rebinding Mouse Buttons
+@cindex mouse button events
+@cindex rebinding mouse buttons
+@cindex click events
+@cindex drag events
+@cindex down events
+@cindex button down events
+
+ Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary
+mouse events in Emacs are @dfn{click} events; these happen when you
+press a button and release it without moving the mouse. You can also
+get @dfn{drag} events, when you move the mouse while holding the button
+down. Drag events happen when you finally let go of the button.
+
+ The symbols for basic click events are @code{mouse-1} for the leftmost
+button, @code{mouse-2} for the next, and so on. Here is how you can
+redefine the second mouse button to split the current window:
+
+@example
+(global-set-key [mouse-2] 'split-window-vertically)
+@end example
+
+ The symbols for drag events are similar, but have the prefix
+@samp{drag-} before the word @samp{mouse}. For example, dragging the
+first button generates a @code{drag-mouse-1} event.
+
+ You can also define bindings for events that occur when a mouse button
+is pressed down. These events start with @samp{down-} instead of
+@samp{drag-}. Such events are generated only if they have key bindings.
+When you get a button-down event, a corresponding click or drag event
+will always follow.
+
+@cindex double clicks
+@cindex triple clicks
+ If you wish, you can distinguish single, double, and triple clicks. A
+double click means clicking a mouse button twice in approximately the
+same place. The first click generates an ordinary click event. The
+second click, if it comes soon enough, generates a double-click event
+instead. The event type for a double-click event starts with
+@samp{double-}: for example, @code{double-mouse-3}.
+
+ This means that you can give a special meaning to the second click at
+the same place, but it must act on the assumption that the ordinary
+single click definition has run when the first click was received.
+
+ This constrains what you can do with double clicks, but user interface
+designers say that this constraint ought to be followed in any case. A
+double click should do something similar to the single click, only
+``more so.'' The command for the double-click event should perform the
+extra work for the double click.
+
+ If a double-click event has no binding, it changes to the
+corresponding single-click event. Thus, if you don't define a
+particular double click specially, it executes the single-click command
+twice.
+
+ Emacs also supports triple-click events whose names start with
+@samp{triple-}. Emacs does not distinguish quadruple clicks as event
+types; clicks beyond the third generate additional triple-click events.
+However, the full number of clicks is recorded in the event list, so you
+can distinguish if you really want to. We don't recommend distinct
+meanings for more than three clicks, but sometimes it is useful for
+subsequent clicks to cycle through the same set of three meanings, so
+that four clicks are equivalent to one click, five are equivalent to
+two, and six are equivalent to three.
+
+ Emacs also records multiple presses in drag and button-down events.
+For example, when you press a button twice, then move the mouse while
+holding the button, Emacs gets a @samp{double-drag-} event. And at the
+moment when you press it down for the second time, Emacs gets a
+@samp{double-down-} event (which is ignored, like all button-down
+events, if it has no binding).
+
+@vindex double-click-time
+ The variable @code{double-click-time} specifies how long may elapse
+between clicks that are recognized as a pair. Its value is measured
+in milliseconds. If the value is @code{nil}, double clicks are not
+detected at all. If the value is @code{t}, then there is no time
+limit.
+
+ The symbols for mouse events also indicate the status of the modifier
+keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
+@samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-}
+or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
+
+ A frame includes areas that don't show text from the buffer, such as
+the mode line and the scroll bar. You can tell whether a mouse button
+comes from a special area of the screen by means of dummy ``prefix
+keys.'' For example, if you click the mouse in the mode line, you get
+the prefix key @code{mode-line} before the ordinary mouse-button symbol.
+Thus, here is how to define the command for clicking the first button in
+a mode line to run @code{scroll-up}:
+
+@example
+(global-set-key [mode-line mouse-1] 'scroll-up)
+@end example
+
+ Here is the complete list of these dummy prefix keys and their
+meanings:
+
+@table @code
+@item mode-line
+The mouse was in the mode line of a window.
+@item vertical-line
+The mouse was in the vertical line separating side-by-side windows. (If
+you use scroll bars, they appear in place of these vertical lines.)
+@item vertical-scroll-bar
+The mouse was in a vertical scroll bar. (This is the only kind of
+scroll bar Emacs currently supports.)
+@ignore
+@item horizontal-scroll-bar
+The mouse was in a horizontal scroll bar. Horizontal scroll bars do
+horizontal scrolling, and people don't use them often.
+@end ignore
+@end table
+
+ You can put more than one mouse button in a key sequence, but it isn't
+usual to do so.
+
+@node Disabling
+@subsection Disabling Commands
+@cindex disabled command
+
+ Disabling a command marks the command as requiring confirmation before it
+can be executed. The purpose of disabling a command is to prevent
+beginning users from executing it by accident and being confused.
+
+ An attempt to invoke a disabled command interactively in Emacs
+displays a window containing the command's name, its documentation, and
+some instructions on what to do immediately; then Emacs asks for input
+saying whether to execute the command as requested, enable it and
+execute it, or cancel. If you decide to enable the command, you are
+asked whether to do this permanently or just for the current session.
+Enabling permanently works by automatically editing your @file{.emacs}
+file.
+
+ The direct mechanism for disabling a command is to put a
+non-@code{nil} @code{disabled} property on the Lisp symbol for the
+command. Here is the Lisp program to do this:
+
+@example
+(put 'delete-region 'disabled t)
+@end example
+
+ If the value of the @code{disabled} property is a string, that string
+is included in the message printed when the command is used:
+
+@example
+(put 'delete-region 'disabled
+ "It's better to use `kill-region' instead.\n")
+@end example
+
+@findex disable-command
+@findex enable-command
+ You can make a command disabled either by editing the @file{.emacs}
+file directly or with the command @kbd{M-x disable-command}, which edits
+the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command}
+edits @file{.emacs} to enable a command permanently. @xref{Init File}.
+
+ Whether a command is disabled is independent of what key is used to
+invoke it; disabling also applies if the command is invoked using
+@kbd{M-x}. Disabling a command has no effect on calling it as a
+function from Lisp programs.
+
+@node Keyboard Translations
+@section Keyboard Translations
+
+ Some keyboards do not make it convenient to send all the special
+characters that Emacs uses. The most common problem case is the
+@key{DEL} character. Some keyboards provide no convenient way to type
+this very important character---usually because they were designed to
+expect the character @kbd{C-h} to be used for deletion. On these
+keyboards, if you press the key normally used for deletion, Emacs handles
+the @kbd{C-h} as a prefix character and offers you a list of help
+options, which is not what you want.
+
+@cindex keyboard translations
+@findex keyboard-translate
+ You can work around this problem within Emacs by setting up keyboard
+translations to turn @kbd{C-h} into @key{DEL} and @key{DEL} into
+@kbd{C-h}, as follows:
+
+@example
+;; @r{Translate @kbd{C-h} to @key{DEL}.}
+(keyboard-translate ?\C-h ?\C-?)
+
+@need 3000
+;; @r{Translate @key{DEL} to @kbd{C-h}.}
+(keyboard-translate ?\C-? ?\C-h)
+@end example
+
+ Keyboard translations are not the same as key bindings in keymaps
+(@pxref{Keymaps}). Emacs contains numerous keymaps that apply in
+different situations, but there is only one set of keyboard
+translations, and it applies to every character that Emacs reads from
+the terminal. Keyboard translations take place at the lowest level of
+input processing; the keys that are looked up in keymaps contain the
+characters that result from keyboard translation.
+
+ Under X, the keyboard key named @key{DELETE} is a function key and is
+distinct from the ASCII character named @key{DEL}. @xref{Named ASCII
+Chars}. Keyboard translations affect only ASCII character input, not
+function keys; thus, the above example used under X does not affect the
+@key{DELETE} key. However, the translation above isn't necessary under
+X, because Emacs can also distinguish between the @key{BACKSPACE} key
+and @kbd{C-h}; and it normally treats @key{BACKSPACE} as @key{DEL}.
+
+ For full information about how to use keyboard translations, see
+@ref{Translating Input,,,elisp, The Emacs Lisp Reference Manual}.
+
+@node Syntax
+@section The Syntax Table
+@cindex syntax table
+
+ All the Emacs commands which parse words or balance parentheses are
+controlled by the @dfn{syntax table}. The syntax table says which
+characters are opening delimiters, which are parts of words, which are
+string quotes, and so on. Each major mode has its own syntax table
+(though sometimes related major modes use the same one) which it
+installs in each buffer that uses that major mode. The syntax table
+installed in the current buffer is the one that all commands use, so we
+call it ``the'' syntax table. A syntax table is a Lisp object, a
+char-table, whose elements are numbers.
+
+@kindex C-h s
+@findex describe-syntax
+ To display a description of the contents of the current syntax table,
+type @kbd{C-h s} (@code{describe-syntax}). The description of each
+character includes both the string you would have to give to
+@code{modify-syntax-entry} to set up that character's current syntax,
+and some English to explain that string if necessary.
+
+ For full information on the syntax table, see @ref{Syntax Tables,,
+Syntax Tables, elisp, The Emacs Lisp Reference Manual}.
+
+@node Init File
+@section The Init File, @file{~/.emacs}
+@cindex init file
+@cindex Emacs initialization file
+@cindex key rebinding, permanent
+@cindex rebinding keys, permanently
+@cindex startup (init file)
+
+ When Emacs is started, it normally loads a Lisp program from the file
+@file{.emacs} or @file{.emacs.el} in your home directory. We call this
+file your @dfn{init file} because it specifies how to initialize Emacs
+for you. You can use the command line switch @samp{-q} to prevent
+loading your init file, and @samp{-u} (or @samp{--user}) to specify a
+different user's init file (@pxref{Entering Emacs}).
+
+ There can also be a @dfn{default init file}, which is the library
+named @file{default.el}, found via the standard search path for
+libraries. The Emacs distribution contains no such library; your site
+may create one for local customizations. If this library exists, it is
+loaded whenever you start Emacs (except when you specify @samp{-q}).
+But your init file, if any, is loaded first; if it sets
+@code{inhibit-default-init} non-@code{nil}, then @file{default} is not
+loaded.
+
+ Your site may also have a @dfn{site startup file}; this is named
+@file{site-start.el}, if it exists. Emacs loads this library before it
+loads your init file. To inhibit loading of this library, use the
+option @samp{-no-site-file}.
+
+ If you have a large amount of code in your @file{.emacs} file, you
+should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte
+Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual},
+for more information about compiling Emacs Lisp programs.
+
+ If you are going to write actual Emacs Lisp programs that go beyond
+minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
+@ifinfo
+@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
+Manual}.
+@end ifinfo
+
+@menu
+* Init Syntax:: Syntax of constants in Emacs Lisp.
+* Init Examples:: How to do some things with an init file.
+* Terminal Init:: Each terminal type can have an init file.
+* Find Init:: How Emacs finds the init file.
+@end menu
+
+@node Init Syntax
+@subsection Init File Syntax
+
+ The @file{.emacs} file contains one or more Lisp function call
+expressions. Each of these consists of a function name followed by
+arguments, all surrounded by parentheses. For example, @code{(setq
+fill-column 60)} calls the function @code{setq} to set the variable
+@code{fill-column} (@pxref{Filling}) to 60.
+
+ The second argument to @code{setq} is an expression for the new value of
+the variable. This can be a constant, a variable, or a function call
+expression. In @file{.emacs}, constants are used most of the time. They can be:
+
+@table @asis
+@item Numbers:
+Numbers are written in decimal, with an optional initial minus sign.
+
+@item Strings:
+@cindex Lisp string syntax
+@cindex string syntax
+Lisp string syntax is the same as C string syntax with a few extra
+features. Use a double-quote character to begin and end a string constant.
+
+In a string, you can include newlines and special characters literally.
+But often it is cleaner to use backslash sequences for them: @samp{\n}
+for newline, @samp{\b} for backspace, @samp{\r} for carriage return,
+@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for
+escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or
+@samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
+Backslash and double-quote are the only characters for which backslash
+sequences are mandatory.
+
+@samp{\C-} can be used as a prefix for a control character, as in
+@samp{\C-s} for ASCII control-S, and @samp{\M-} can be used as a prefix for
+a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
+@kbd{Control-Meta-A}.@refill
+
+@item Characters:
+Lisp character constant syntax consists of a @samp{?} followed by
+either a character or an escape sequence starting with @samp{\}.
+Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
+strings and characters are not interchangeable in Lisp; some contexts
+require one and some contexts require the other.
+
+@item True:
+@code{t} stands for `true'.
+
+@item False:
+@code{nil} stands for `false'.
+
+@item Other Lisp objects:
+Write a single-quote (') followed by the Lisp object you want.
+@end table
+
+@node Init Examples
+@subsection Init File Examples
+
+ Here are some examples of doing certain commonly desired things with
+Lisp expressions:
+
+@itemize @bullet
+@item
+Make @key{TAB} in C mode just insert a tab if point is in the middle of a
+line.
+
+@example
+(setq c-tab-always-indent nil)
+@end example
+
+Here we have a variable whose value is normally @code{t} for `true'
+and the alternative is @code{nil} for `false'.
+
+@item
+Make searches case sensitive by default (in all buffers that do not
+override this).
+
+@example
+(setq-default case-fold-search nil)
+@end example
+
+This sets the default value, which is effective in all buffers that do
+not have local values for the variable. Setting @code{case-fold-search}
+with @code{setq} affects only the current buffer's local value, which
+is not what you probably want to do in an init file.
+
+@item
+@vindex user-mail-address
+Specify your own email address, if Emacs can't figure it out correctly.
+
+@example
+(setq user-mail-address "coon@@yoyodyne.com")
+@end example
+
+Various Emacs packages that need your own email address use the value of
+@code{user-mail-address}.
+
+@item
+Make Text mode the default mode for new buffers.
+
+@example
+(setq default-major-mode 'text-mode)
+@end example
+
+Note that @code{text-mode} is used because it is the command for
+entering Text mode. The single-quote before it makes the symbol a
+constant; otherwise, @code{text-mode} would be treated as a variable
+name.
+
+@need 1500
+@item
+Set up defaults for the Latin-1 character set
+which supports most of the languages of Western Europe.
+
+@example
+(set-language-environment "Latin-1")
+@end example
+
+@need 1500
+@item
+Turn on Auto Fill mode automatically in Text mode and related modes.
+
+@example
+(add-hook 'text-mode-hook
+ '(lambda () (auto-fill-mode 1)))
+@end example
+
+This shows how to add a hook function to a normal hook variable
+(@pxref{Hooks}). The function we supply is a list starting with
+@code{lambda}, with a single-quote in front of it to make it a list
+constant rather than an expression.
+
+It's beyond the scope of this manual to explain Lisp functions, but for
+this example it is enough to know that the effect is to execute
+@code{(auto-fill-mode 1)} when Text mode is entered. You can replace
+that with any other expression that you like, or with several
+expressions in a row.
+
+Emacs comes with a function named @code{turn-on-auto-fill} whose
+definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler
+way to write the above example is as follows:
+
+@example
+(add-hook 'text-mode-hook 'turn-on-auto-fill)
+@end example
+
+@item
+Load the installed Lisp library named @file{foo} (actually a file
+@file{foo.elc} or @file{foo.el} in a standard Emacs directory).
+
+@example
+(load "foo")
+@end example
+
+When the argument to @code{load} is a relative file name, not starting
+with @samp{/} or @samp{~}, @code{load} searches the directories in
+@code{load-path} (@pxref{Lisp Libraries}).
+
+@item
+Load the compiled Lisp file @file{foo.elc} from your home directory.
+
+@example
+(load "~/foo.elc")
+@end example
+
+Here an absolute file name is used, so no searching is done.
+
+@item
+Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
+
+@example
+(global-set-key "\C-xl" 'make-symbolic-link)
+@end example
+
+or
+
+@example
+(define-key global-map "\C-xl" 'make-symbolic-link)
+@end example
+
+Note once again the single-quote used to refer to the symbol
+@code{make-symbolic-link} instead of its value as a variable.
+
+@item
+Do the same thing for Lisp mode only.
+
+@example
+(define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
+@end example
+
+@item
+Redefine all keys which now run @code{next-line} in Fundamental mode
+so that they run @code{forward-line} instead.
+
+@example
+(substitute-key-definition 'next-line 'forward-line
+ global-map)
+@end example
+
+@item
+Make @kbd{C-x C-v} undefined.
+
+@example
+(global-unset-key "\C-x\C-v")
+@end example
+
+One reason to undefine a key is so that you can make it a prefix.
+Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a
+prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix
+definition.
+
+@item
+Make @samp{$} have the syntax of punctuation in Text mode.
+Note the use of a character constant for @samp{$}.
+
+@example
+(modify-syntax-entry ?\$ "." text-mode-syntax-table)
+@end example
+
+@item
+Enable the use of the command @code{narrow-to-region} without confirmation.
+
+@example
+(put 'narrow-to-region 'disabled nil)
+@end example
+@end itemize
+
+@node Terminal Init
+@subsection Terminal-specific Initialization
+
+ Each terminal type can have a Lisp library to be loaded into Emacs when
+it is run on that type of terminal. For a terminal type named
+@var{termtype}, the library is called @file{term/@var{termtype}} and it is
+found by searching the directories @code{load-path} as usual and trying the
+suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
+subdirectory @file{term} of the directory where most Emacs libraries are
+kept.@refill
+
+ The usual purpose of the terminal-specific library is to map the
+escape sequences used by the terminal's function keys onto more
+meaningful names, using @code{function-key-map}. See the file
+@file{term/lk201.el} for an example of how this is done. Many function
+keys are mapped automatically according to the information in the
+Termcap data base; the terminal-specific library needs to map only the
+function keys that Termcap does not specify.
+
+ When the terminal type contains a hyphen, only the part of the name
+before the first hyphen is significant in choosing the library name.
+Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
+the library @file{term/aaa}. The code in the library can use
+@code{(getenv "TERM")} to find the full terminal type name.@refill
+
+@vindex term-file-prefix
+ The library's name is constructed by concatenating the value of the
+variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
+file can prevent the loading of the terminal-specific library by setting
+@code{term-file-prefix} to @code{nil}.
+
+@vindex term-setup-hook
+ Emacs runs the hook @code{term-setup-hook} at the end of
+initialization, after both your @file{.emacs} file and any
+terminal-specific library have been read in. Add hook functions to this
+hook if you wish to override part of any of the terminal-specific
+libraries and to define initializations for terminals that do not have a
+library. @xref{Hooks}.
+
+@node Find Init
+@subsection How Emacs Finds Your Init File
+
+ Normally Emacs uses the environment variable @code{HOME} to find
+@file{.emacs}; that's what @samp{~} means in a file name. But if you
+have done @code{su}, Emacs tries to find your own @file{.emacs}, not
+that of the user you are currently pretending to be. The idea is
+that you should get your own editor customizations even if you are
+running as the super user.
+
+ More precisely, Emacs first determines which user's init file to use.
+It gets the user name from the environment variables @code{LOGNAME} and
+@code{USER}; if neither of those exists, it uses effective user-ID.
+If that user name matches the real user-ID, then Emacs uses @code{HOME};
+otherwise, it looks up the home directory corresponding to that user
+name in the system's data base of users.
+@c LocalWords: backtab
--- /dev/null
+\input texinfo @comment -*-texinfo-*-
+
+@c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs19
+@c
+@c Author: Sebastian Kremer <sk@thp.uni-koeln.de>
+@c Lawrence R. Dodd <dodd@roebling.poly.edu>
+@c Maintainer: Lawrence R. Dodd <dodd@roebling.poly.edu>
+@c Version: 2.52
+@c Date: 1994/08/09 16:51:31
+@c Keywords: dired extensions
+@c dired-x.el REVISION NUMBER: 2
+
+@c State: Released
+@c Ident: dired-x.texi,v 2.52 1994/08/09 16:51:31 dodd Released
+
+@comment %**start of header (This is for running Texinfo on a region.)
+@c FOR GNU EMACS USE ../info/dired-x BELOW
+@setfilename ../info/dired-x
+@c dired-x.el REVISION NUMBER
+@settitle Dired Extra Version 2 User's Manual
+
+@dircategory Editors
+@direntry
+* Dired-X: (dired-x). Dired Extra Features.
+@end direntry
+
+@iftex
+@finalout
+@end iftex
+@c @setchapternewpage odd % For book style double sided manual.
+@comment %**end of header (This is for running Texinfo on a region.)
+@c @smallbook
+@tex
+\overfullrule=0pt
+%\global\baselineskip 30pt % For printing in double spaces
+@end tex
+
+@ifinfo
+@node Copyright, Top, (dir), (dir)
+@comment node-name, next, previous, up
+This documents the ``extra'' features for Dired Mode for GNU Emacs 19 found in
+the file @file{dired-x.el}.
+
+Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of
+a permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for
+modified versions, except that this permission notice may be stated
+in a translation approved by the Free Software Foundation.
+
+The file used to create this is called @file{dired-x.texi}, but the
+original work that was altered to make that file was called
+@file{dired.texi} written by Sebastian Kremer.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+@end ifinfo
+
+@c
+@titlepage
+@sp 6
+@c dired-x.el REVISION NUMBER
+@center @titlefont{Dired Extra Version 2}
+@sp 2
+@center @titlefont{For The GNU Emacs 19}
+@sp 1
+@center @titlefont{Directory Editor}
+@sp 4
+@center Manual Revision: 2.52
+@center 1994/08/09 16:51:31
+@sp 5
+@center Lawrence R@. Dodd
+@center @t{dodd@@roebling.poly.edu}
+@sp 5
+@center (Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de>)
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1993, 1994 Free Software Foundation
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of
+a permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for
+modified versions, except that this permission notice may be stated
+in a translation approved by the Free Software Foundation.
+
+The file used to create this is called @file{dired-x.texi}, but the
+original work that was altered to make that file was called
+@file{dired.texi} written by Sebastian Kremer.
+
+@end titlepage
+
+@page
+
+@ifinfo
+
+@node Top, Introduction, Copyright, (dir)
+@comment node-name, next, previous, up
+
+@noindent
+This documents the ``extra'' features for Dired Mode for GNU Emacs 19 that are
+provided by the file @file{dired-x.el}.
+
+@itemize @bullet
+
+@item
+Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de>
+
+@c dired-x.el REVISION NUMBER
+@item
+For @file{dired-x.el} revision 2
+
+@item
+Revision of this manual: 2.52 (1994/08/09 16:51:31)
+
+@item
+Bugs to Lawrence R. Dodd <dodd@@roebling.poly.edu>. @emph{Please} type
+@kbd{M-x dired-x-submit-report} to submit a bug report (@xref{Bugs}).
+
+@item
+You can obtain a copy of this package via anonymous ftp in
+@t{/roebling.poly.edu:/pub/packages/dired-x.tar.gz}
+
+@end itemize
+
+@menu
+* Introduction::
+* Installation::
+* Omitting Files in Dired::
+* Local Variables::
+* Shell Command Guessing::
+* Virtual Dired::
+* Advanced Mark Commands::
+* Multiple Dired Directories::
+* Find File At Point::
+* Miscellaneous Commands::
+* Bugs::
+
+* Concept Index::
+* Command Index::
+* Key Index::
+* Variable Index::
+
+@end menu
+
+@end ifinfo
+
+@node Introduction, Features, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+
+This documents the @emph{extra} features for Dired Mode for GNU Emacs 19. It
+is derived from version 1.191 of Sebastian Kremer's @file{dired-x.el} and is
+GNU Emacs v19 compatible.
+
+In adopting this @file{dired-x.el} to GNU Emacs v19 some material that has
+been incorporated into @file{dired.el} and @file{dired-aux.el} of the GNU Emacs
+19 distribution has been removed and some material was modified for agreement
+with the functions in @file{dired.el} and @file{dired-aux.el}. For example,
+the code using @code{gmhist} history functions was replaced with code using
+the mini-buffer history now built into GNU Emacs 19. Finally, a few other
+features have been added and a few more functions have been bound to keys.
+
+Please note that @file{dired-x.el} and this texinfo file @file{dired-x.texi}
+are bundled with GNU Emacs versions 19.23 and later.
+
+@ifinfo
+@menu
+* Features::
+* Technical Details::
+@end menu
+@end ifinfo
+
+@node Features, Technical Details, Introduction, Introduction
+@comment node-name, next, previous, up
+@section Features
+@cindex Features
+
+Some features provided by Dired Extra
+
+@enumerate
+@item
+Omitting of uninteresting files from dired listing.
+@itemize @bullet
+@xref{Omitting Files in Dired}
+@end itemize
+@item
+Local variables for dired directories.
+@itemize @bullet
+@xref{Local Variables}
+@end itemize
+@item
+Guessing shell commands in dired buffers.
+@itemize @bullet
+@xref{Shell Command Guessing}
+@end itemize
+@item
+Running dired command in non-dired buffers.
+@itemize @bullet
+@xref{Virtual Dired}
+@end itemize
+@item
+Finding a file mentioned in a buffer
+@itemize @bullet
+@xref{Find File At Point}
+@end itemize
+@item
+Commands using file marking.
+@itemize @bullet
+@xref{Advanced Mark Commands}
+@end itemize
+@end enumerate
+
+@noindent
+@file{dired-x.el} binds some functions to keys in Dired Mode (@xref{Key
+Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to
+@code{dired-jump} (@xref{Miscellaneous Commands}). It may also bind @kbd{C-x
+C-f} and @kbd{C-x 4 C-f} to @code{dired-x-find-file} and
+@code{dired-x-find-file-other-window}, respectively (@xref{Find File At
+Point}).
+
+@node Technical Details, Installation, Features, Introduction
+@comment node-name, next, previous, up
+@section Technical Details
+@cindex Redefined functions
+@cindex @file{dired-aux.el}
+
+When loaded this code @emph{redefines} the following functions of GNU Emacs
+from @file{dired.el}
+
+@itemize @bullet
+@item
+@code{dired-clean-up-after-deletion}
+@item
+@code{dired-find-buffer-nocreate}
+@item
+@code{dired-initial-position}
+@item
+@code{dired-up-directory}
+@end itemize
+
+@noindent
+and the following functions from @file{dired-aux.el}
+
+@itemize @bullet
+@item
+@code{dired-add-entry}
+@item
+@code{dired-read-shell-command}
+@end itemize
+
+One drawback is that @file{dired-x.el} will load @file{dired-aux.el} as soon
+as dired is loaded. Thus, the advantage of separating out non-essential dired
+stuff into @file{dired-aux.el} and only loading when necessary will be lost
+when @file{dired-x.el} is used.
+
+@node Installation, Optional Installation Dired Jump, Technical Details, Top
+@comment node-name, next, previous, up
+@chapter Installation
+
+@noindent
+This manual describes the dired features provided by the file
+@file{dired-x.el}. To take advantage of these features, you must load the
+file and (optionally) set some variables.
+
+@noindent
+In your @file{.emacs} file in your home directory, or in the system-wide
+initialization file @file{default.el} in the @file{site-lisp} directory, put
+
+@example
+(add-hook 'dired-load-hook
+ (function (lambda ()
+ (load "dired-x")
+ ;; Set dired-x global variables here. For example:
+ ;; (setq dired-guess-shell-gnutar "gtar")
+ ;; (setq dired-x-hands-off-my-keys nil)
+ )))
+(add-hook 'dired-mode-hook
+ (function (lambda ()
+ ;; Set dired-x buffer-local variables here. For example:
+ ;; (setq dired-omit-files-p t)
+ )))
+@end example
+
+@noindent
+This will load @file{dired-x.el} when dired is first invoked (for example,
+when you first do @kbd{C-x d}).
+
+@ifinfo
+@menu
+* Optional Installation Dired Jump::
+* Optional Installation File At Point::
+* Special Notes::
+@end menu
+@end ifinfo
+
+@node Optional Installation Dired Jump, Optional Installation File At Point, Installation, Installation
+@comment node-name, next, previous, up
+@section Optional Installation Dired Jump
+
+@cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window}
+
+In order to have @code{dired-jump} and @code{dired-jump-other-window}
+(@xref{Miscellaneous Commands}) work @emph{before} @code{dired} and
+@code{dired-x} have been properly loaded the user should set-up an autoload
+for these functions. In your @file{.emacs} file put
+
+@example
+;;; Autoload `dired-jump' and `dired-jump-other-window'.
+;;; We autoload from FILE dired.el. This will then load dired-x.el
+;;; and hence define `dired-jump' and `dired-jump-other-window'.
+(define-key global-map "\C-x\C-j" 'dired-jump)
+(define-key global-map "\C-x4\C-j" 'dired-jump-other-window)
+
+(autoload (quote dired-jump) "dired" "\
+Jump to dired buffer corresponding to current buffer.
+If in a file, dired the current directory and move to file's line.
+If in dired already, pop up a level and goto old directory's line.
+In case the proper dired file line cannot be found, refresh the dired
+buffer and try again." t nil)
+
+(autoload (quote dired-jump-other-window) "dired" "\
+Like \\[dired-jump] (dired-jump) but in other window." t nil)
+@end example
+
+Note that in recent releases of GNU Emacs 19 (i.e., 19.25 or later) the file
+@file{../lisp/loaddefs.el} of the Emacs distribution already contains the
+proper auto-loading for @code{dired-jump} so you need only put
+
+@example
+(define-key global-map "\C-x\C-j" 'dired-jump)
+@end example
+
+@noindent in your @file{.emacs} file in order to have @kbd{C-x C-j} work
+before @code{dired} is loaded.
+
+@node Optional Installation File At Point, Special Notes, Optional Installation Dired Jump, Installation
+@comment node-name, next, previous, up
+@section Optional Installation File At Point
+
+@cindex Binding @code{dired-x-find-file}
+If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over
+@code{find-file} (@xref{Find File At Point}), then you will need to set
+@code{dired-x-hands-off-my-keys} and make a call to the function
+@code{dired-x-bind-find-file} in the @code{dired-load-hook}:
+
+@example
+(add-hook 'dired-load-hook
+ (function (lambda ()
+ (load "dired-x")
+ ;; Bind dired-x-find-file.
+ (setq dired-x-hands-off-my-keys nil)
+ ;; Make sure our binding preference is invoked.
+ (dired-x-bind-find-file)
+ )))
+@end example
+
+Alternatively, you can set the variable @emph{before} @file{dired-x.el} is
+loaded
+
+@example
+(add-hook 'dired-load-hook
+ (function (lambda ()
+ ;; Bind dired-x-find-file.
+ (setq dired-x-hands-off-my-keys nil)
+ (load "dired-x")
+ )))
+@end example
+
+@node Special Notes, Omitting Files in Dired, Optional Installation File At Point, Installation
+@comment node-name, next, previous, up
+@section Special Notes
+
+If @file{dired-x.el} was @emph{not} bundled with the version of GNU Emacs
+installed at your site (i.e., not in the default @file{../lisp} directory)
+then you must put the file @file{dired-x.el} in a directory known to GNU
+Emacs. Examine the variable @code{load-path} for a list of these directories.
+If you wish to add a new directory on this list of directories use something
+like this in your @file{.emacs} file
+
+@example
+;;; LOAD PATH
+(setq load-path (append
+ load-path ; default at top
+ (list
+ "/the/directory/where/you/put/dired-x")))
+@end example
+
+@noindent If you wish to put the new directory at the head of the list (where
+it will be found first) then you should use instead
+
+@example
+;;; LOAD PATH
+(setq load-path (append
+ (list
+ "/the/directory/where/you/put/dired-x")
+ load-path)) ; default at bottom
+@end example
+
+You must also byte compile the file (for example, hitting @kbd{B} in
+@code{dired-mode}). When byte-compiling @file{dired-x.el} you may get
+messages about functions @code{vm-visit-folder}, @code{Man-notify-when-ready},
+and @code{reporter-submit-bug-report} not being defined. These are warnings
+and should be ignored.
+
+@noindent CAUTION: If you are using a version of GNU Emacs earlier than 19.20
+than you may have to edit @file{dired.el}. The copy of @file{dired.el} in GNU
+Emacs versions earlier than 19.20 incorrectly had the call to @code{run-hooks}
+@emph{before} the call to @code{provide}. In such a case, it is possible that
+byte-compiling and/or loading dired can cause an infinite loop. To prevent
+this, make sure the line of code
+
+@example
+ (run-hooks 'dired-load-hook)
+@end example
+
+@noindent is the @emph{last} executable line in the file @file{dired.el}.
+That is, make sure it comes @emph{after} the line
+
+@example
+ (provide 'dired)
+@end example
+
+@node Omitting Files in Dired, Omitting Variables, Special Notes, Top
+@comment node-name, next, previous, up
+@chapter Omitting Files in Dired
+
+@cindex Omitting Files in Dired
+@dfn{Omitting} a file means removing it from the directory listing. Omitting
+is useful for keeping Dired buffers free of ``uninteresting'' files (for
+instance, auto-save, auxiliary, backup, and revision control files) so that
+the user can concentrate on the interesting files. Like hidden files, omitted
+files are never seen by Dired. Omitting differs from hiding in several
+respects:
+
+@itemize @bullet
+
+@item
+Omitting works on individual files, not on directories; an entire directory
+cannot be omitted (though each of its files could be).
+
+@item
+Omitting is wholesale; if omitting is turned on for a dired buffer, then all
+uninteresting files listed in that buffer are omitted. The user does not omit
+(or unomit) files one at a time.
+
+@item
+Omitting can be automatic; uninteresting file lines in the buffer can be
+removed before the user ever sees them.
+
+@item
+Marked files are never omitted.
+@end itemize
+
+@table @kbd
+@item M-o
+@kindex M-o
+@findex dired-omit-toggle
+(@code{dired-omit-toggle}) Toggle between displaying and omitting
+``uninteresting'' files. With a prefix argument, don't toggle and just mark
+the files, but don't actually omit them.
+@end table
+
+@noindent
+In order to make Dired Omit work you first need to load @file{dired-x.el}
+inside @code{dired-load-hook} (@xref{Installation}) and then set
+@code{dired-omit-files-p} in some way (@xref{Omitting Variables}).
+
+@ifinfo
+@menu
+* Omitting Variables::
+* Omitting Examples::
+* Omitting Technical::
+@end menu
+@end ifinfo
+
+@node Omitting Variables, Omitting Examples, Omitting Files in Dired, Omitting Files in Dired
+@comment node-name, next, previous, up
+
+@section Omitting Variables
+
+The following variables can be used to customize omitting.
+
+@table @code
+
+@vindex dired-omit-files-p
+@item dired-omit-files-p
+
+Default: @code{nil}
+
+@cindex How to make omitting the default in Dired
+If non-@code{nil}, ``uninteresting'' files are not listed. Uninteresting
+files are those whose filenames match regexp @code{dired-omit-files}, plus
+those ending with extensions in @code{dired-omit-extensions}. @kbd{M-o}
+(@code{dired-omit-toggle}) toggles its value, which is buffer-local. Put
+
+@example
+(setq dired-omit-files-p t)
+@end example
+
+inside your @code{dired-mode-hook} to have omitting initially turned on in
+@emph{every} Dired buffer (@xref{Installation}). You can then use @kbd{M-o} to
+unomit in that buffer.
+
+To enable omitting automatically only in certain directories one can use Dired
+Local Variables and put
+
+@example
+Local Variables:
+dired-omit-files-p: t
+End:
+@end example
+
+@noindent
+into a file @file{.dired} (the default value of
+@code{dired-local-variables-file}) in that directory (@xref{Local Variables}).
+
+@table @code
+@findex dired-omit-here-always
+@item dired-omit-here-always
+
+This is an interactive function that creates a local variables file exactly
+like the example above (if it does not already exist) in the file
+@code{dired-local-variables-file} in the current directory and then refreshes
+the directory listing (@xref{Local Variables}).
+@end table
+
+@vindex dired-omit-files
+@item dired-omit-files
+
+Default: @code{"^#\\|\\.$"}
+
+Filenames matching this buffer-local regexp will not be displayed.
+This only has effect when @code{dired-omit-files-p} is t.
+
+The default value omits the special directories @file{.} and @file{..} and
+autosave files (plus other files ending in ``.'') (@xref{Omitting Examples}).
+
+@vindex dired-omit-extensions
+@item dired-omit-extensions
+
+Default: The elements of @code{completion-ignored-extensions} (as defined in
+the file @file{loaddefs.el} of the GNU Emacs distribution),
+@code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions}
+and @code{dired-texinfo-unclean-extensions}.
+
+If non-@code{nil}, a list of extensions (strings) to omit from Dired listings.
+Its format is the same as that of @code{completion-ignored-extensions}.
+
+@vindex dired-omit-localp
+@item dired-omit-localp
+
+Default: @code{'no-dir}
+
+The @var{localp} argument @code{dired-omit-expunge} passes to
+@code{dired-get-filename}. If it is @code{'no-dir}, omitting is much faster,
+but you can only match against the non-directory part of the filename. Set it
+to @code{nil} if you need to match the whole pathname or @code{t} to match the
+pathname relative to the buffer's top-level directory.
+
+@item dired-omit-marker-char
+@vindex dired-omit-marker-char
+@cindex Omitting additional files
+Default: @kbd{C-o}
+
+Temporary marker used by by Dired to implement omitting. Should never be used
+as marker by the user or other packages. There is one exception to this rule:
+by doing
+
+@example
+(setq dired-mark-keys "\C-o")
+;; i.e., the value of dired-omit-marker-char
+;; (which is not defined yet)
+@end example
+
+anywhere in your @file{~/.emacs}, you will bind the @kbd{C-o} key to insert a
+@kbd{C-o} marker, thus causing these files to be omitted in addition to the
+usually omitted files. Unfortunately the files you omitted manually this way
+will show up again after reverting the buffer, unlike the others.
+
+@end table
+
+@node Omitting Examples, Omitting Technical, Omitting Variables, Omitting Files in Dired
+@comment node-name, next, previous, up
+@section Examples of Omitting Various File Types
+
+@itemize @bullet
+
+@item
+@cindex RCS files, how to omit them in Dired
+@cindex Omitting RCS files in Dired
+If you wish to avoid seeing RCS files and the RCS directory, then put
+
+@example
+(setq dired-omit-files
+ (concat dired-omit-files "\\|^RCS$\\|,v$"))
+@end example
+@noindent
+in the @code{dired-load-hook} (@xref{Installation}). This assumes
+@code{dired-omit-localp} has its default value of @code{'no-dir} to make the
+@code{^}-anchored matches work. As a slower alternative, with
+@code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of
+@code{^} in the regexp.
+
+@item
+@cindex Tib files, how to omit them in Dired
+@cindex Omitting tib files in Dired
+If you use tib, the bibliography program for use with @TeX{} and La@TeX{}, you
+might want to omit the @file{INDEX} and the @file{-t.tex} files, then put
+
+@example
+(setq dired-omit-files
+ (concat dired-omit-files "\\|^INDEX$\\|-t\\.tex$"))
+@end example
+
+@noindent
+in the @code{dired-load-hook} (@xref{Installation}).
+
+@item
+@cindex Dot files, how to omit them in Dired
+@cindex Omitting dot files in Dired
+If you do not wish to see @samp{dot} files (files starting with a @samp{.}),
+then put
+
+@example
+(setq dired-omit-files
+ (concat dired-omit-files "\\|^\\..+$"))
+@end example
+
+@noindent
+in the @code{dired-load-hook} (@xref{Installation}).
+
+@end itemize
+
+@node Omitting Technical, Local Variables, Omitting Examples, Omitting Files in Dired
+@comment node-name, next, previous, up
+@section Some Technical Details of Omitting
+
+Loading @file{dired-x.el} will install Dired Omit by putting
+@code{dired-omit-expunge} on your @code{dired-after-readin-hook}, and will
+call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup}
+in your @code{dired-mode-hook}.
+
+@node Local Variables, Shell Command Guessing, Omitting Technical, Top
+@comment node-name, next, previous, up
+@chapter Local Variables for Dired Directories
+
+@cindex Local Variables for Dired Directories
+@vindex dired-local-variables-file
+@vindex dired-enable-local-variables
+@noindent
+When Dired visits a directory, it looks for a file whose name is the value of
+variable @code{dired-local-variables-file} (default: @file{.dired}). If such
+a file is found, Dired will temporarily insert it into the Dired buffer and
+run @code{hack-local-variables}.
+
+@noindent
+For example, if the user puts
+
+@example
+Local Variables:
+dired-actual-switches: "-lat"
+dired-omit-files-p: t
+End:
+@end example
+
+@noindent
+into a file called @file{.dired} in a directory then when that directory is
+viewed it will be
+
+@enumerate
+@item
+sorted by date
+@item
+omitted automatically
+@end enumerate
+
+@noindent
+You can set @code{dired-local-variables-file} to @code{nil} to suppress this.
+The value of @code{dired-enable-local-variables} controls if and how these
+local variables are read. This variable exists so that if may override the
+default value of @code{enable-local-variables}.
+
+@noindent
+Please see the GNU Emacs Manual to learn more about local variables.
+@xref{File Variables,Local Variables in Files,Local Variables in
+Files,emacs,The GNU Emacs Manual}.
+
+@noindent
+The following variables affect Dired Local Variables
+
+@table @code
+@vindex dired-local-variables-file
+@item dired-local-variables-file
+Default: @code{".dired"}
+
+If non-@code{nil}, filename for local variables for Dired. If Dired finds a
+file with that name in the current directory, it will temporarily insert it
+into the dired buffer and run `hack-local-variables'.
+
+@vindex dired-enable-local-variables
+@item dired-enable-local-variables
+Default: @code{t}
+
+Controls use of local-variables lists in dired. The value can be @code{t},
+@code{nil}, or something else. A value of @code{t} means local-variables
+lists are obeyed in the @code{dired-local-variables-file}; @code{nil} means
+they are ignored; anything else means query. This variable temporarily
+overrides the value of @code{enable-local-variables} when the Dired Local
+Variables are hacked.
+@end table
+
+@node Shell Command Guessing, Virtual Dired, Local Variables, Top
+@comment node-name, next, previous, up
+@chapter Shell Command Guessing
+@cindex Guessing shell commands for files.
+
+Based upon the name of a filename, Dired tries to guess what shell
+command you might want to apply to it. For example, if you have point
+on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess
+you want to @samp{tar xvf} it and suggest that as the default shell
+command.
+
+The default will be mentioned in brackets and you can type @kbd{M-p} to get
+the default into the minibuffer so that you can edit it, e.g., changing
+@samp{tar xvf} to @samp{tar tvf}. If there are several commands for a given
+file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type
+@kbd{M-p} several times to see each of the matching commands.
+
+Dired only tries to guess a command for a single file, never for a list
+of marked files.
+
+@table @code
+@item dired-guess-shell-alist-default
+@vindex dired-guess-shell-alist-default
+Predefined rules for shell commands. Set this to @code{nil} to turn guessing off.
+The elements of @code{dired-guess-shell-alist-user} (defined by the
+user) will override these rules.@refill
+
+@item dired-guess-shell-alist-user
+@vindex dired-guess-shell-alist-user
+If non-@code{nil}, a user-defined alist of file regexps and their suggested
+commands. These rules take precedence over the predefined rules in the
+variable @code{dired-guess-shell-alist-default} (to which they are prepended)
+when @code{dired-do-shell-command} is run).
+@refill
+
+Each element of the alist looks like
+
+@example
+(@var{regexp} @var{command}@dots{})
+@end example
+
+where each @var{command} can either be a string or a lisp expression
+that evaluates to a string. If several @var{COMMAND}s are given, all
+will temporarily be pushed on the history.
+
+You can set this variable in your @file{~/.emacs}. For example,
+to add rules for @samp{.foo} and @samp{.bar} file extensions, write
+
+@example
+(setq dired-guess-shell-alist-user
+ (list
+ (list "\\.foo$" "@var{foo-command}");; fixed rule
+ ;; possibly more rules...
+ (list "\\.bar$";; rule with condition test
+ '(if @var{condition}
+ "@var{bar-command-1}"
+ "@var{bar-command-2}"))))
+@end example
+
+@noindent
+This will override any predefined rules for the same extensions.
+
+@item dired-guess-shell-gnutar
+@vindex dired-guess-shell-gnutar
+@cindex Passing GNU tar its `z' switch.
+Default: @code{nil}
+
+If non-@code{nil}, name of the GNU tar executable (e.g., @samp{"tar"} or
+@samp{"gnutar"}). GNU tar's @samp{z} switch is used for compressed tar files.
+If you don't have GNU tar, set this to @code{nil}: a pipe using @samp{zcat} is
+then used.
+
+@item dired-guess-shell-gzip-quiet
+@vindex dired-guess-shell-gzip-quiet
+@cindex GNU zip.
+Default: @code{t}
+
+A non-@code{nil} value means that @code{-q} is passed to gzip overriding a
+verbose GNU zip's @samp{GZIP} environment variable.
+
+@item dired-guess-shell-znew-switches nil
+@vindex dired-guess-shell-znew-switches nil
+@cindex GNU zip.
+Default: @code{nil}
+
+A string of switches passed to GNU zip's @file{znew}. An example is
+@samp{"-K"} which will make @file{znew} keep a .Z file when it is smaller than
+the .gz file.
+
+@item dired-shell-command-history nil
+@vindex dired-shell-command-history nil
+
+History list for commands that read dired-shell commands.
+@end table
+
+@node Virtual Dired, Advanced Mark Commands, Shell Command Guessing, Top
+@comment node-name, next, previous, up
+@chapter Virtual Dired
+
+@cindex Virtual Dired
+@cindex Perusing ls listings
+@cindex ls listings, how to peruse them in Dired
+Using @dfn{Virtual Dired} means putting a buffer with Dired-like
+contents in Dired mode. The files described by the buffer contents need
+not actually exist. This is useful if you want to peruse an @samp{ls -lR}
+output file, for example one you got from an FTP server. You can use
+all motion commands usually available in Dired. You can also use
+it to save a Dired buffer in a file and resume it in a later session.
+
+@findex dired-virtual
+@kindex g
+@findex dired-virtual-revert
+Type @kbd{M-x dired-virtual} to put the current buffer into virtual
+Dired mode. You will be prompted for the top level directory of this
+buffer, with a default value guessed from the buffer contents. To
+convert the virtual to a real Dired buffer again, type @kbd{g} (which
+calls @code{dired-virtual-revert}) in the virtual Dired buffer and
+answer @samp{y}. You don't have to do this, though: you can relist
+single subdirectories using @kbd{l} (@code{dired-do-redisplay}) on the subdirectory
+headerline, leaving the buffer in virtual Dired mode all the time.
+
+@findex dired-virtual-mode
+@vindex auto-mode-alist
+The function @samp{dired-virtual-mode} is specially designed to turn on
+virtual Dired mode from the @code{auto-mode-alist}. To edit all
+@file{*.dired} files automatically in virtual Dired mode, put this into your
+@file{~/.emacs}:
+
+@example
+(setq auto-mode-alist (cons '("[^/]\\.dired$" . dired-virtual-mode)
+ auto-mode-alist))
+@end example
+
+The regexp is a bit more complicated than usual to exclude ".dired"
+local variable files.
+
+@node Advanced Mark Commands, Advanced Cleaning Functions, Virtual Dired, Top
+@comment node-name, next, previous, up
+@chapter Advanced Mark Commands
+
+@table @kbd
+@item F
+@kindex F
+@cindex Visiting several files at once
+@cindex Simultaneous visiting of several files
+@findex dired-do-find-marked-files
+(@code{dired-do-find-marked-files}) Find all marked files at once displaying
+simultaneously. If optional NOSELECT is non-@code{nil} then just find the
+files but do not select. If you want to keep the dired buffer displayed, type
+@kbd{C-x 2} first. If you want just the marked files displayed and nothing
+else, type @kbd{C-x 1} first.
+
+The current window is split across all files marked, as evenly as possible.
+Remaining lines go to the bottom-most window. The number of files that can be
+displayed this way is restricted by the height of the current window and the
+variable @code{window-min-height}.
+@end table
+
+@table @code
+@item dired-mark-extension
+@findex dired-mark-extension
+Mark all files with a certain extension for use in later commands. A @samp{.}
+is not automatically prepended to the string entered.
+
+When called from lisp, @var{extension} may also be a list of extensions
+and an optional argument @var{marker-char} specifies the marker used.
+
+@item dired-flag-extension
+@findex dired-flag-extension
+Flag all files with a certain extension for deletion. A @samp{.} is
+@emph{not} automatically prepended to the string entered.
+@end table
+
+@ifinfo
+@menu
+* Advanced Cleaning Functions::
+* Advanced Cleaning Variables::
+* Special Marking Function::
+@end menu
+@end ifinfo
+
+@node Advanced Cleaning Functions, Advanced Cleaning Variables, Advanced Mark Commands, Advanced Mark Commands
+@comment node-name, next, previous, up
+
+@section Advanced Cleaning Functions
+
+@table @code
+@item dired-clean-patch
+@findex dired-clean-patch
+Flag dispensable files created by the @samp{patch} program for deletion. See
+variable @code{dired-patch-unclean-extensions}.
+
+@item dired-clean-tex
+@findex dired-clean-tex
+Flag dispensable files created by @TeX{}, La@TeX{}, and @samp{texinfo} for
+deletion. See the following variables (@xref{Advanced Cleaning Variables})
+
+@itemize @bullet
+@item
+@code{dired-tex-unclean-extensions}
+@item
+@code{dired-texinfo-unclean-extensions}
+@item
+@code{dired-latex-unclean-extensions}
+@item
+@code{dired-bibtex-unclean-extensions}
+@end itemize
+
+@item dired-very-clean-tex
+@findex dired-very-clean-tex
+Flag dispensable files created by @TeX{}, La@TeX{}, @samp{texinfo}, and ".dvi"
+files for deletion.
+@end table
+
+@node Advanced Cleaning Variables, Special Marking Function, Advanced Cleaning Functions, Advanced Mark Commands
+@comment node-name, next, previous, up
+
+@section Advanced Cleaning Variables
+
+@noindent Variables used by the above cleaning commands (and in the default value for
+variable @code{dired-omit-extensions}, @xref{Omitting Variables})
+
+@table @code
+@item dired-patch-unclean-extensions
+@vindex dired-patch-unclean-extensions
+Default: @code{'(".rej" ".orig")}
+
+List of extensions of dispensable files created by the @samp{patch} program.
+
+@item dired-tex-unclean-extensions
+@vindex dired-tex-unclean-extensions
+Default: @code{'(".toc" ".log" ".aux")}
+
+List of extensions of dispensable files created by @TeX{}.
+
+@item dired-texinfo-unclean-extensions
+@vindex dired-texinfo-unclean-extensions
+Default: @code{'(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"}
+@code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")}
+
+List of extensions of dispensable files created by @samp{texinfo}.
+
+@item dired-latex-unclean-extensions
+@vindex dired-latex-unclean-extensions
+Default: @code{'(".idx" ".lof" ".lot" ".glo")}
+
+List of extensions of dispensable files created by La@TeX{}.
+
+@item dired-bibtex-unclean-extensions
+@vindex dired-bibtex-unclean-extensions
+Default: @code{'(".blg" ".bbl")}
+
+List of extensions of dispensable files created by Bib@TeX{}.
+@end table
+
+@node Special Marking Function, Multiple Dired Directories, Advanced Cleaning Variables, Advanced Mark Commands
+@comment node-name, next, previous, up
+
+@section Special Marking Function
+
+@table @kbd
+@item M-(
+@kindex M-(
+@findex dired-mark-sexp
+@cindex Lisp expression, marking files with in Dired
+@cindex Mark file by lisp expression
+(@code{dired-mark-sexp}) Mark files for which @var{predicate} returns
+non-@code{nil}. With a prefix argument, unflag those files instead.
+
+The @var{predicate} is a lisp expression that can refer to the following
+symbols:
+@table @code
+@item inode
+[@i{integer}] the inode of the file (only for @samp{ls -i} output)
+@item s
+[@i{integer}] the size of the file for @samp{ls -s} output (usually in blocks or,
+with @samp{-k}, in KBytes)
+@item mode
+[@i{string}] file permission bits, e.g., @samp{"-rw-r--r--"}
+@item nlink
+[@i{integer}] number of links to file
+@item uid
+[@i{string}] owner
+@item gid
+[@i{string}] group (If the gid is not displayed by @samp{ls}, this
+will still be set (to the same as uid))
+@item size
+[@i{integer}] file size in bytes
+@item time
+[@i{string}] the time that @samp{ls} displays, e.g., @samp{"Feb 12 14:17"}
+@item name
+[@i{string}] the name of the file
+@item sym
+[@i{string}] if file is a symbolic link, the linked-to name, else @samp{""}
+@end table
+
+@noindent
+For example, use
+@example
+(equal 0 size)
+@end example
+to mark all zero length files.
+
+To find out all not yet compiled Emacs lisp files in a directory, dired
+all @file{.el} files in the lisp directory using the wildcard
+@samp{*.el}. Then use @kbd{M-(} with
+@example
+(not (file-exists-p (concat name "c")))
+@end example
+to mark all @file{.el} files without a corresponding @file{.elc} file.
+
+@end table
+
+@node Multiple Dired Directories, Find File At Point, Special Marking Function, Top
+@comment node-name, next, previous, up
+@chapter Multiple Dired Directories and Non-Dired Commands
+
+@cindex Multiple Dired directories
+@cindex Working directory
+An Emacs buffer can have but one working directory, stored in the
+buffer-local variable @code{default-directory}. A Dired buffer may have
+several subdirectories inserted, but still has but one working
+directory: that of the top level Dired directory in that buffer. For
+some commands it is appropriate that they use the current Dired
+directory instead of @code{default-directory}, e.g., @code{find-file} and
+@code{compile}.
+
+A general mechanism is provided for special handling of the working
+directory in special major modes:
+
+@table @code
+@item default-directory-alist
+@vindex default-directory-alist
+Default: @code{((dired-mode . (dired-current-directory)))}
+
+Alist of major modes and their opinion on @code{default-directory}, as a
+lisp expression to evaluate. A resulting value of @code{nil} is ignored
+in favor of @code{default-directory}.
+
+@item default-directory
+@findex default-directory
+Function with usage like variable @code{default-directory}, but knows about the
+special cases in variable @code{default-directory-alist}.
+@end table
+
+@node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top
+@comment node-name, next, previous, up
+
+@section Find File At Point
+@cindex Visiting a file mentioned in a buffer
+@cindex Finding a file at point
+
+@file{dired-x} provides a method of visiting or editing a file mentioned in
+the buffer you are viewing (e.g., a mail buffer, a news article, a README
+file, etc.) or to test if that file exists. You can then modify this in the
+minibuffer after snatching the filename.
+
+When installed @file{dired-x} will substitute @code{dired-x-find-file} for
+@code{find-file} (normally bound to @kbd{C-x C-f}) and
+@code{dired-x-find-file-other-window} for @code{find-file-other-window}
+(normally bound to @kbd{C-x 4 C-f}).
+
+In order to use this feature, you will need to set
+@code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook}
+(@xref{Optional Installation File At Point}).
+
+@table @code
+@item dired-x-find-file
+@findex dired-x-find-file
+@kindex C-x C-f
+
+@code{dired-x-find-file} behaves exactly like @code{find-file} (normally bound
+to @kbd{C-x C-f}) unless a prefix argument is passed to the function in which
+case it will use the filename at point as a guess for the file to visit.
+
+For example, if the buffer you were reading contained the words
+
+@example
+Available via anonymous ftp in
+
+ /roebling.poly.edu:/pub/lisp/crypt++.el.gz
+@end example
+
+then you could move your cursor to the line containing the ftp address and
+type @kbd{C-u C-x C-f} (the @kbd{C-u} is a universal argument). The
+minibuffer would read
+
+@example
+Find file: /roebling.poly.edu:/pub/lisp/crypt++.el.gz
+@end example
+
+with the point after the last @code{/}. If you hit return emacs will visit
+the file at that address. This also works with files on your own computer.
+
+@item dired-x-find-file-other-window
+@findex dired-x-find-file-other-window
+@kindex C-x 4 C-f
+
+@code{dired-x-find-file-other-window} behaves exactly like
+@code{find-file-other-window} (normally bound to @kbd{C-x 4 C-f}) unless a
+prefix argument is used. See @code{dired-x-find-file} for more information.
+
+@item dired-x-hands-off-my-keys
+@vindex dired-x-hands-off-my-keys
+If set to @code{t}, then it means that @file{dired-x} should @emph{not} bind
+@code{dired-x-find-file} over @code{find-file} on keyboard. Similarly, it
+should not bind @code{dired-x-find-file-other-window} over
+@code{find-file-other-window}. If you change this variable after
+@file{dired-x.el} is loaded then do @kbd{M-x dired-x-bind-find-file}. The
+default value of this variable is @kbd{t}; by default, the binding is not
+done. See @xref{Optional Installation File At Point}.
+
+@item dired-x-bind-find-file
+@findex dired-x-bind-find-file
+A function, which can be called interactively or in your @file{~/.emacs} file,
+that uses the value of @code{dired-x-hands-off-my-keys} to determine if
+@code{dired-x-find-file} should be bound over @code{find-file} and
+@code{dired-x-find-file-other-window} bound over
+@code{find-file-other-window}. See @xref{Optional Installation File At Point}.
+@end table
+
+@node Miscellaneous Commands, Bugs, Find File At Point, Top
+@comment node-name, next, previous, up
+@chapter Miscellaneous Commands
+
+Miscellaneous features not fitting anywhere else:
+
+@table @code
+@item dired-find-subdir
+@vindex dired-find-subdir
+Default: @code{nil}
+
+If non-@code{nil}, Dired does not make a new buffer for a directory if it can
+be found (perhaps as subdirectory) in some existing Dired buffer.
+
+If there are several Dired buffers for a directory, the most recently
+used is chosen.
+
+Dired avoids switching to the current buffer, so that if you have a
+normal and a wildcard buffer for the same directory, @kbd{C-x d RET}
+will toggle between those two.
+@end table
+
+@table @kbd
+@findex dired-goto-file
+@kindex M-g
+@item M-g
+(@code{dired-goto-file}) Goto file line of a file (or directory).
+
+@findex dired-goto-subdir
+@kindex M-G
+@item M-G
+(@code{dired-goto-subdir}) Goto headerline of an inserted directory.
+This commands reads its argument with completion over the names of the
+inserted subdirectories.
+@end table
+
+@table @kbd
+@item w
+@cindex Adding to the kill ring in dired.
+@kindex w
+@findex dired-copy-filename-as-kill
+(@code{dired-copy-filename-as-kill}) The @kbd{w} command puts the names
+of the marked (or next @var{N}) files into the kill ring, as if you had
+killed them with @kbd{C-w}. With a zero prefix argument @var{N}=0, use the
+complete pathname of each file. With a raw (just @kbd{C-u}) prefix argument,
+use the relative pathname of each marked file. As a special case, if no
+prefix argument is given and point is on a directory headerline, it
+gives you the name of that directory, without looking for marked files.
+
+@vindex dired-marked-files
+The list of names is also stored onto the variable @code{dired-marked-files}
+for use, e.g., in the @kbd{M-:} (@code{eval-expression}) command.
+
+As this command also displays what was pushed onto the kill ring you can
+use it to display the list of currently marked files in the
+echo area (unless you happen to be on a subdirectory headerline).
+
+You can then feed the file name to other Emacs commands with @kbd{C-y}.
+For example, say you want to rename a long filename to a slightly
+different name. First type @kbd{w} to push the old name onto the kill
+ring. Then type @kbd{R} to rename it and use @kbd{C-y} inside @kbd{R}'s
+minibuffer prompt to insert the old name at a convenient place.
+
+@item T
+@kindex T
+@cindex Toggling marks.
+@findex dired-do-toggle
+(@code{dired-do-toggle}) Toggle marks. That is, currently marked
+files become unmarked and vice versa. Files marked with other flags
+(such as `D') are not affected. The special directories `.' and `..'
+are never toggled.
+@end table
+
+@table @code
+@item dired-smart-shell-command
+@findex dired-smart-shell-command
+@findex shell-command
+@kindex M-!
+Like function @code{shell-command}, but in the current Dired directory.
+Bound to @kbd{M-!} in Dired buffers.
+
+@item dired-jump
+@findex dired-jump
+@kindex C-x C-j
+@cindex Jumping to dired listing containing file.
+Bound to @kbd{C-x C-j}. Jump back to dired: If in a file, dired the current
+directory and move to file's line. If in Dired already, pop up a level and
+goto old directory's line. In case the proper Dired file line cannot be
+found, refresh the Dired buffer and try again.
+
+@item dired-jump-other-window
+@findex dired-jump-other-window
+@kindex C-x 4 C-j
+Bound to @kbd{C-x 4 C-j}. Like @code{dired-jump}, but to other window.
+
+These functions can be autoloaded so they work even though @file{dired-x.el}
+has not been loaded yet (@xref{Optional Installation Dired Jump}).
+
+@vindex dired-bind-jump
+If the variable @code{dired-bind-jump} is @code{nil}, @code{dired-jump} will not be
+bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to
+@kbd{C-x 4 C-j}.
+
+@item dired-vm
+@cindex Reading mail.
+@kindex V
+@findex dired-vm
+Bound to @kbd{V} if @code{dired-bind-vm} is t. Run VM on this file (assumed
+to be a UNIX mail folder).
+
+@vindex dired-vm-read-only-folders
+If you give this command a prefix argument, it will visit the folder
+read-only. This only works in VM~5, not VM~4.
+
+If the variable @code{dired-vm-read-only-folders} is t, @code{dired-vm} will
+visit all folders read-only. If it is neither @code{nil} nor @code{t}, e.g.,
+the symbol @code{'if-file-read-only}, only files not writable by you are
+visited read-only. This is the recommended value if you run VM 5.
+
+@vindex dired-bind-vm
+If the variable @code{dired-bind-vm} is t, @code{dired-vm} will be bound to
+@kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound.
+
+@item dired-rmail
+@cindex Reading mail.
+@findex dired-rmail
+Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this
+file (assumed to be mail folder in Rmail/BABYL format).
+
+@item dired-info
+@kindex I
+@cindex Running info.
+@findex dired-info
+Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info
+format).
+
+@vindex dired-bind-info
+If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will
+not be bound to I.
+
+@item dired-man
+@cindex Running man.
+@kindex N
+@findex dired-man
+Bound to @kbd{N}. Run man on this file (assumed to be a file in nroff
+format).
+
+@vindex dired-bind-man
+If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not
+be bound to N.
+
+@item dired-do-relative-symlink
+@cindex Relative symbolic links.
+@kindex Y
+@findex dired-do-relative-symlink
+Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a
+directory, or make a relative symbolic link to the current file. This creates
+relative symbolic links like
+
+ foo -> ../bar/foo
+
+not absolute ones like
+
+ foo -> /ugly/path/that/may/change/any/day/bar/foo
+
+@item dired-do-relative-symlink-regexp
+@kindex %Y
+@findex dired-do-relative-symlink-regexp
+Bound to @kbd{%Y}. Relative symlink all marked files containing REGEXP to
+NEWNAME. See functions `dired-do-rename-regexp' and `dired-do-relsymlink' for
+more info.
+@end table
+
+@node Bugs, Concept Index, Miscellaneous Commands, Top
+@comment node-name, next, previous, up
+@chapter Bugs
+@cindex Bugs
+@findex dired-x-submit-report
+
+@noindent
+If you encounter a bug in this package, wish to suggest an
+enhancement, or want to make a smart remark, then type
+
+@example
+@kbd{M-x dired-x-submit-report}
+@end example
+
+@noindent
+to set up an outgoing mail buffer, with the proper address to the
+@file{dired-x.el} maintainer automatically inserted in the @samp{To:@:} field.
+This command also inserts information that the Dired X maintainer can use to
+recreate your exact setup, making it easier to verify your bug or social
+maladjustment.
+
+Lawrence R. Dodd <dodd@@roebling.poly.edu>
+
+@node Concept Index, Command Index, Bugs, Top
+@comment node-name, next, previous, up
+@unnumbered Concept Index
+@printindex cp
+
+@node Command Index, Key Index, Concept Index, Top
+@comment node-name, next, previous, up
+@unnumbered Function Index
+@printindex fn
+
+@node Key Index, Variable Index, Command Index, Top
+@comment node-name, next, previous, up
+@unnumbered Key Index
+@printindex ky
+
+@node Variable Index, , Key Index, Top
+@comment node-name, next, previous, up
+@unnumbered Variable Index
+@printindex vr
+
+@c @summarycontents
+@contents
+
+@bye
+@c dired-x.texi ends here.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Dired, Calendar/Diary, Rmail, Top
+@chapter Dired, the Directory Editor
+@cindex Dired
+
+ Dired makes an Emacs buffer containing a listing of a directory, and
+optionally some of its subdirectories as well. You can use the normal
+Emacs commands to move around in this buffer, and special Dired commands
+to operate on the files listed.
+
+@menu
+* Enter: Dired Enter. How to invoke Dired.
+* Commands: Dired Commands. Commands in the Dired buffer.
+* Deletion: Dired Deletion. Deleting files with Dired.
+* Flagging Many Files:: Flagging files based on their names.
+* Visit: Dired Visiting. Other file operations through Dired.
+* Marks vs Flags:: Flagging for deletion vs marking.
+* Operating on Files:: How to copy, rename, print, compress, etc.
+ either one file or several files.
+* Shell Commands in Dired:: Running a shell command on the marked files.
+* Transforming File Names:: Using patterns to rename multiple files.
+* Comparison in Dired:: Running `diff' by way of Dired.
+* Subdirectories in Dired:: Adding subdirectories to the Dired buffer.
+* Subdirectory Motion:: Moving across subdirectories, and up and down.
+* Hiding Subdirectories:: Making subdirectories visible or invisible.
+* Updating: Dired Updating. Discarding lines for files of no interest.
+* Find: Dired and Find. Using `find' to choose the files for Dired.
+@end menu
+
+@node Dired Enter
+@section Entering Dired
+
+@findex dired
+@kindex C-x d
+@vindex dired-listing-switches
+ To invoke Dired, do @kbd{C-x d} or @kbd{M-x dired}. The command reads
+a directory name or wildcard file name pattern as a minibuffer argument
+to specify which files to list. Where @code{dired} differs from
+@code{list-directory} is in putting the buffer into Dired mode so that
+the special commands of Dired are available.
+
+ The variable @code{dired-listing-switches} specifies the options to
+give to @code{ls} for listing directory; this string @emph{must} contain
+@samp{-l}. If you use a numeric prefix argument with the @code{dired}
+command, you can specify the @code{ls} switches with the minibuffer
+before you enter the directory specification.
+
+@findex dired-other-window
+@kindex C-x 4 d
+@findex dired-other-frame
+@kindex C-x 5 d
+ To display the Dired buffer in another window rather than in the
+selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead
+of @kbd{C-x d}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a
+separate frame to display the Dired buffer.
+
+@node Dired Commands
+@section Commands in the Dired Buffer
+
+ The Dired buffer is ``read-only,'' and inserting text in it is not
+useful, so ordinary printing characters such as @kbd{d} and @kbd{x} are
+used for special Dired commands. Some Dired commands @dfn{mark} or
+@dfn{flag} the @dfn{current file} (that is, the file on the current
+line); other commands operate on the marked files or on the flagged
+files.
+
+@kindex C-n @r{(Dired)}
+@kindex C-p @r{(Dired)}
+ All the usual Emacs cursor motion commands are available in Dired
+buffers. Some special-purpose cursor motion commands are also
+provided. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the
+cursor at the beginning of the file name on the line, rather than at the
+beginning of the line.
+
+@kindex SPC @r{(Dired)}
+ For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent
+to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines is
+so common in Dired that it deserves to be easy to type.) @key{DEL}
+(move up and unflag) is often useful simply for moving up.
+
+@node Dired Deletion
+@section Deleting Files with Dired
+@cindex flagging files (in Dired)
+@cindex deleting files (in Dired)
+
+ The primary use of Dired is to @dfn{flag} files for deletion and then
+delete the files previously flagged.
+
+@table @kbd
+@item d
+Flag this file for deletion.
+@item u
+Remove deletion flag on this line.
+@item @key{DEL}
+Move point to previous line and remove the deletion flag on that line.
+@item x
+Delete the files that are flagged for deletion.
+@end table
+
+@kindex d @r{(Dired)}
+@findex dired-flag-file-deletion
+ You can flag a file for deletion by moving to the line describing the
+file and typing @kbd{d} (@code{dired-flag-file-deletion}). The deletion flag is visible as a @samp{D} at
+the beginning of the line. This command moves point to the next line,
+so that repeated @kbd{d} commands flag successive files. A numeric
+argument serves as a repeat count.
+
+@kindex u @r{(Dired deletion)}
+@kindex DEL @r{(Dired)}
+ The files are flagged for deletion rather than deleted immediately to
+reduce the danger of deleting a file accidentally. Until you direct
+Dired to expunge the flagged files, you can remove deletion flags using
+the commands @kbd{u} and @key{DEL}. @kbd{u} (@code{dired-unmark}) works
+just like @kbd{d}, but removes flags rather than making flags.
+@key{DEL} (@code{dired-unmark-backward}) moves upward, removing flags;
+it is like @kbd{u} with argument @minus{}1.
+
+@kindex x @r{(Dired)}
+@findex dired-expunge
+@cindex expunging (Dired)
+ To delete the flagged files, type @kbd{x} (@code{dired-expunge}).
+This command first displays a list of all the file names flagged for
+deletion, and requests confirmation with @kbd{yes}. If you confirm,
+Dired deletes the flagged files, then deletes their lines from the text
+of the Dired buffer. The shortened Dired buffer remains selected.
+
+ If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you
+return immediately to Dired, with the deletion flags still present in
+the buffer, and no files actually deleted.
+
+@node Flagging Many Files
+@section Flagging Many Files at Once
+
+@table @kbd
+@item #
+Flag all auto-save files (files whose names start and end with @samp{#})
+for deletion (@pxref{Auto Save}).
+
+@item ~
+Flag all backup files (files whose names end with @samp{~}) for deletion
+(@pxref{Backup}).
+
+@item &
+Flag for deletion all files with certain kinds of names, names that
+suggest you could easily create the files again.
+
+@item .@: @r{(Period)}
+Flag excess numeric backup files for deletion. The oldest and newest
+few backup files of any one file are exempt; the middle ones are
+flagged.
+
+@item % d @var{regexp} @key{RET}
+Flag for deletion all files whose names match the regular expression
+@var{regexp}.
+@end table
+
+ The @kbd{#}, @kbd{~}, @kbd{&}, and @kbd{.} commands flag many files for
+deletion, based on their file names. These commands are useful
+precisely because they do not themselves delete any files; you can
+remove the deletion flags from any flagged files that you really wish to
+keep.@refill
+
+@kindex & @r{(Dired)}
+@findex dired-flag-garbage-files
+@vindex dired-garbage-files-regexp
+ @kbd{&} (@code{dired-flag-garbage-files}) flags files whose names
+match the regular expression specified by the variable
+@code{dired-garbage-files-regexp}. By default, this matches certain
+files produced by @TeX{}, and the @samp{.orig} and @samp{.rej} files
+produced by @code{patch}.
+
+@kindex # @r{(Dired)}
+@kindex ~ @r{(Dired)}
+@findex dired-flag-auto-save-files
+@findex dired-flag-backup-files
+ @kbd{#} (@code{dired-flag-auto-save-files}) flags for deletion all
+files whose names look like auto-save files (@pxref{Auto Save})---that
+is, files whose names begin and end with @samp{#}. @kbd{~}
+(@code{dired-flag-backup-files}) flags for deletion all files whose
+names say they are backup files (@pxref{Backup})---that is, whose names
+end in @samp{~}.
+
+@kindex . @r{(Dired)}
+@vindex dired-kept-versions
+@findex dired-clean-directory
+ @kbd{.} (period, @code{dired-clean-directory}) flags just some of the
+backup files for deletion: all but the oldest few and newest few backups
+of any one file. Normally @code{dired-kept-versions} (@strong{not}
+@code{kept-new-versions}; that applies only when saving) specifies the
+number of newest versions of each file to keep, and
+@code{kept-old-versions} specifies the number of oldest versions to
+keep.
+
+ Period with a positive numeric argument, as in @kbd{C-u 3 .},
+specifies the number of newest versions to keep, overriding
+@code{dired-kept-versions}. A negative numeric argument overrides
+@code{kept-old-versions}, using minus the value of the argument to
+specify the number of oldest versions of each file to keep.
+
+@findex dired-flag-files-regexp
+@kindex % d @r{(Dired)}
+ The @kbd{% d} command flags all files whose names match a specified
+regular expression (@code{dired-flag-files-regexp}). Only the
+non-directory part of the file name is used in matching. You can use
+@samp{^} and @samp{$} to anchor matches. You can exclude subdirectories
+by hiding them (@pxref{Hiding Subdirectories}).
+
+@node Dired Visiting
+@section Visiting Files in Dired
+
+ There are several Dired commands for visiting or examining the files
+listed in the Dired buffer. All of them apply to the current line's
+file; if that file is really a directory, these commands invoke Dired on
+that subdirectory (making a separate Dired buffer).
+
+@table @kbd
+@item f
+@kindex f @r{(Dired)}
+@findex dired-find-file
+Visit the file described on the current line, like typing @kbd{C-x C-f}
+and supplying that file name (@code{dired-find-file}). @xref{Visiting}.
+
+@item @key{RET}
+@kindex RET @r{(Dired)}
+Equivalent to @kbd{f}.
+
+@item o
+@kindex o @r{(Dired)}
+@findex dired-find-file-other-window
+Like @kbd{f}, but uses another window to display the file's buffer
+(@code{dired-find-file-other-window}). The Dired buffer remains visible
+in the first window. This is like using @kbd{C-x 4 C-f} to visit the
+file. @xref{Windows}.
+
+@item C-o
+@kindex C-o @r{(Dired)}
+@findex dired-display-file
+Visit the file described on the current line, and display the buffer in
+another window, but do not select that window (@code{dired-display-file}).
+
+@item Mouse-2
+@findex dired-mouse-find-file-other-window
+Visit the file named by the line you click on
+(@code{dired-mouse-find-file-other-window}). This uses another window
+to display the file, like the @kbd{o} command.
+
+@item v
+@kindex v @r{(Dired)}
+@findex dired-view-file
+View the file described on the current line, using @kbd{M-x view-file}
+(@code{dired-view-file}).
+
+Viewing a file is like visiting it, but is slanted toward moving around
+in the file conveniently and does not allow changing the file.
+@xref{Misc File Ops,View File}.
+@end table
+
+@node Marks vs Flags
+@section Dired Marks vs. Flags
+
+@cindex marking in Dired
+ Instead of flagging a file with @samp{D}, you can @dfn{mark} the file
+with some other character (usually @samp{*}). Most Dired commands to
+operate on files, aside from ``expunge'' (@kbd{x}), look for files
+marked with @samp{*}.
+
+ Here are some commands for marking with @samp{*}, or for unmarking or
+operating on marks. (@xref{Dired Deletion}, for commands to flag and
+unflag files.)
+
+@table @kbd
+@item m
+@itemx * m
+@kindex m @r{(Dired)}
+@kindex * m @r{(Dired)}
+@findex dired-mark
+Mark the current file with @samp{*} (@code{dired-mark}). With a numeric
+argument @var{n}, mark the next @var{n} files starting with the current
+file. (If @var{n} is negative, mark the previous @minus{}@var{n}
+files.)
+
+@item * *
+@kindex * * @r{(Dired)}
+@findex dired-mark-executables
+Mark all executable files with @samp{*}
+(@code{dired-mark-executables}). With a numeric argument, unmark all
+those files.
+
+@item * @@
+@kindex * @@ @r{(Dired)}
+@findex dired-mark-symlinks
+Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}).
+With a numeric argument, unmark all those files.
+
+@item * /
+@kindex * / @r{(Dired)}
+@findex dired-mark-directories
+Mark with @samp{*} all files which are actually directories, except for
+@file{.} and @file{..} (@code{dired-mark-directories}). With a numeric
+argument, unmark all those files.
+
+@item * s
+@kindex * s @r{(Dired)}
+@findex dired-mark-subdir-files
+Mark all the files in the current subdirectory, aside from @file{.}
+and @file{..} (@code{dired-mark-subdir-files}).
+
+@item u
+@itemx * u
+@kindex u @r{(Dired)}
+@kindex * u @r{(Dired)}
+@findex dired-unmark
+Remove any mark on this line (@code{dired-unmark}).
+
+@item @key{DEL}
+@itemx * @key{DEL}
+@kindex * DEL @r{(Dired)}
+@findex dired-unmark-backward
+Move point to previous line and remove any mark on that line
+(@code{dired-unmark-backward}).
+
+@item * !
+@kindex * ! @r{(Dired)}
+@findex dired-unmark-all-files-no-query
+Remove all marks from all the files in this Dired buffer
+(@code{dired-unmark-all-files-no-query}).
+
+@item * ? @var{markchar}
+@kindex * ? @r{(Dired)}
+@findex dired-unmark-all-files
+Remove all marks that use the character @var{markchar}
+(@code{dired-unmark-all-files}). The argument is a single
+character---do not use @key{RET} to terminate it.
+
+With a numeric argument, this command queries about each marked file,
+asking whether to remove its mark. You can answer @kbd{y} meaning yes,
+@kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining
+files without asking about them.
+
+@item * C-n
+@findex dired-next-marked-file
+@kindex * C-n @r{(Dired)}
+Move down to the next marked file (@code{dired-next-marked-file})
+A file is ``marked'' if it has any kind of mark.
+
+@item * C-p
+@findex dired-prev-marked-file
+@kindex * C-p @r{(Dired)}
+Move up to the previous marked file (@code{dired-prev-marked-file})
+
+@item * t
+@kindex * t @r{(Dired)}
+@findex dired-do-toggle
+Toggle all marks (@code{dired-do-toggle}): files marked with @samp{*}
+become unmarked, and unmarked files are marked with @samp{*}. Files
+marked in any other way are not affected.
+
+@item * c @var{old} @var{new}
+@kindex * c @r{(Dired)}
+@findex dired-change-marks
+Replace all marks that use the character @var{old} with marks that use
+the character @var{new} (@code{dired-change-marks}). This command is
+the primary way to create or use marks other than @samp{*} or @samp{D}.
+The arguments are single characters---do not use @key{RET} to terminate
+them.
+
+You can use almost any character as a mark character by means of this
+command, to distinguish various classes of files. If @var{old} is a
+space (@samp{ }), then the command operates on all unmarked files; if
+@var{new} is a space, then the command unmarks the files it acts on.
+
+To illustrate the power of this command, here is how to put @samp{D}
+flags on all the files that have no marks, while unflagging all those
+that already have @samp{D} flags:
+
+@example
+* c D t * c SPC D * c t SPC
+@end example
+
+This assumes that no files are marked with @samp{t}.
+
+@item % m @var{regexp} @key{RET}
+@itemx * % @var{regexp} @key{RET}
+@findex dired-mark-files-regexp
+@kindex % m @r{(Dired)}
+@kindex * % @r{(Dired)}
+Mark (with @samp{*}) all files whose names match the regular expression
+@var{regexp} (@code{dired-mark-files-regexp}). This command is like
+@kbd{% d}, except that it marks files with @samp{*} instead of flagging
+with @samp{D}. @xref{Flagging Many Files}.
+
+Only the non-directory part of the file name is used in matching. Use
+@samp{^} and @samp{$} to anchor matches. Exclude subdirectories by
+hiding them (@pxref{Hiding Subdirectories}).
+
+@item % g @var{regexp} @key{RET}
+@findex dired-mark-files-containing-regexp
+@kindex % m @r{(Dired)}
+Mark (with @samp{*}) all files whose @emph{contents} contain a match for
+the regular expression @var{regexp}
+(@code{dired-mark-files-containing-regexp}). This command is like
+@kbd{% m}, except that it searches the file contents instead of the file
+name.
+
+@item C-_
+@kindex C-_ @r{(Dired)}
+@findex dired-undo
+Undo changes in the Dired buffer, such as adding or removing
+marks (@code{dired-undo}).
+@end table
+
+@node Operating on Files
+@section Operating on Files
+@cindex operating on files in Dired
+
+ This section describes the basic Dired commands to operate on one file
+or several files. All of these commands are capital letters; all of
+them use the minibuffer, either to read an argument or to ask for
+confirmation, before they act. All of them give you several ways to
+specify which files to manipulate:
+
+@itemize @bullet
+@item
+If you give the command a numeric prefix argument @var{n}, it operates
+on the next @var{n} files, starting with the current file. (If @var{n}
+is negative, the command operates on the @minus{}@var{n} files preceding
+the current line.)
+
+@item
+Otherwise, if some files are marked with @samp{*}, the command operates
+on all those files.
+
+@item
+Otherwise, the command operates on the current file only.
+@end itemize
+
+ Here are the file-manipulating commands that operate on files in this
+way. (Some other Dired commands, such as @kbd{!} and the @samp{%}
+commands, also use these conventions to decide which files to work on.)
+
+@table @kbd
+@findex dired-do-copy
+@kindex C @r{(Dired)}
+@item C @var{new} @key{RET}
+Copy the specified files (@code{dired-do-copy}). The argument @var{new}
+is the directory to copy into, or (if copying a single file) the new
+name.
+
+@vindex dired-copy-preserve-time
+If @code{dired-copy-preserve-time} is non-@code{nil}, then copying with
+this command sets the modification time of the new file to be the same
+as that of the old file.
+
+@item D
+@findex dired-do-delete
+@kindex D @r{(Dired)}
+Delete the specified files (@code{dired-do-delete}). Like the other
+commands in this section, this command operates on the @emph{marked}
+files, or the next @var{n} files. By contrast, @kbd{x}
+(@code{dired-expunge}) deletes all @dfn{flagged} files.
+
+@findex dired-do-rename
+@kindex R @r{(Dired)}
+@item R @var{new} @key{RET}
+Rename the specified files (@code{dired-do-rename}). The argument
+@var{new} is the directory to rename into, or (if renaming a single
+file) the new name.
+
+Dired automatically changes the visited file name of buffers associated
+with renamed files so that they refer to the new names.
+
+@findex dired-do-hardlink
+@kindex H @r{(Dired)}
+@item H @var{new} @key{RET}
+Make hard links to the specified files (@code{dired-do-hardlink}). The
+argument @var{new} is the directory to make the links in, or (if making
+just one link) the name to give the link.
+
+@findex dired-do-symlink
+@kindex S @r{(Dired)}
+@item S @var{new} @key{RET}
+Make symbolic links to the specified files (@code{dired-do-symlink}).
+The argument @var{new} is the directory to make the links in, or (if
+making just one link) the name to give the link.
+
+@findex dired-do-chmod
+@kindex M @r{(Dired)}
+@item M @var{modespec} @key{RET}
+Change the mode (also called ``permission bits'') of the specified files
+(@code{dired-do-chmod}). This uses the @code{chmod} program, so
+@var{modespec} can be any argument that @code{chmod} can handle.
+
+@findex dired-do-chgrp
+@kindex G @r{(Dired)}
+@item G @var{newgroup} @key{RET}
+Change the group of the specified files to @var{newgroup}
+(@code{dired-do-chgrp}).
+
+@findex dired-do-chown
+@kindex O @r{(Dired)}
+@item O @var{newowner} @key{RET}
+Change the owner of the specified files to @var{newowner}
+(@code{dired-do-chown}). (On most systems, only the superuser can do
+this.)
+
+@vindex dired-chown-program
+The variable @code{dired-chown-program} specifies the name of the
+program to use to do the work (different systems put @code{chown} in
+different places).
+
+@findex dired-do-print
+@kindex P @r{(Dired)}
+@item P @var{command} @key{RET}
+Print the specified files (@code{dired-do-print}). You must specify the
+command to print them with, but the minibuffer starts out with a
+suitable guess made using the variables @code{lpr-command} and
+@code{lpr-switches} (the same variables that @code{lpr-buffer} uses;
+@pxref{Hardcopy}).
+
+@findex dired-do-compress
+@kindex Z @r{(Dired)}
+@item Z
+Compress the specified files (@code{dired-do-compress}). If the file
+appears to be a compressed file already, it is uncompressed instead.
+
+@findex dired-do-load
+@kindex L @r{(Dired)}
+@item L
+Load the specified Emacs Lisp files (@code{dired-do-load}).
+@xref{Lisp Libraries}.
+
+@findex dired-do-byte-compile
+@kindex B @r{(Dired)}
+@item B
+Byte compile the specified Emacs Lisp files
+(@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte
+Compilation, elisp, The Emacs Lisp Reference Manual}.
+
+@kindex A @r{(Dired)}
+@findex dired-do-search
+@item A @var{regexp} @key{RET}
+Search all the specified files for the regular expression @var{regexp}
+(@code{dired-do-search}).
+
+This command is a variant of @code{tags-search}. The search stops at
+the first match it finds; use @kbd{M-,} to resume the search and find
+the next match. @xref{Tags Search}.
+
+@kindex Q @r{(Dired)}
+@findex dired-do-query-replace
+@item Q @var{from} @key{RET} @var{to} @key{RET}
+Perform @code{query-replace-regexp} on each of the specified files,
+replacing matches for @var{from} (a regular expression) with the string
+@var{to} (@code{dired-do-query-replace}).
+
+This command is a variant of @code{tags-query-replace}. If you exit the
+query replace loop, you can use @kbd{M-,} to resume the scan and replace
+more matches. @xref{Tags Search}.
+@end table
+
+@kindex + @r{(Dired)}
+@findex dired-create-directory
+ One special file-operation command is @kbd{+}
+(@code{dired-create-directory}). This command reads a directory name and
+creates the directory if it does not already exist.
+
+@node Shell Commands in Dired
+@section Shell Commands in Dired
+@cindex shell commands, Dired
+
+@findex dired-do-shell-command
+@kindex ! @r{(Dired)}
+The dired command @kbd{!} (@code{dired-do-shell-command}) reads a shell
+command string in the minibuffer and runs that shell command on all the
+specified files. You can specify the files to operate on in the usual
+ways for Dired commands (@pxref{Operating on Files}). There are two
+ways of applying a shell command to multiple files:
+
+@itemize @bullet
+@item
+If you use @samp{*} in the shell command, then it runs just once, with
+the list of file names substituted for the @samp{*}. The order of file
+names is the order of appearance in the Dired buffer.
+
+Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire
+list of file names, putting them into one tar file @file{foo.tar}.
+
+@item
+If the command string doesn't contain @samp{*}, then it runs once
+@emph{for each file}, with the file name added at the end.
+
+For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each
+file.
+@end itemize
+
+What if you want to run the shell command once for each file but with
+the file name inserted in the middle? Or if you want to use the file
+names in a more complicated fashion? Use a shell loop. For example,
+this shell command would run @code{uuencode} on each of the specified
+files, writing the output into a corresponding @file{.uu} file:
+
+@example
+for file in *; do uuencode $file $file >$file.uu; done
+@end example
+
+The working directory for the shell command is the top-level directory
+of the Dired buffer.
+
+The @kbd{!} command does not attempt to update the Dired buffer to show
+new or modified files, because it doesn't really understand shell
+commands, and does not know what files the shell command changed. Use
+the @kbd{g} command to update the Dired buffer (@pxref{Dired
+Updating}).
+
+@node Transforming File Names
+@section Transforming File Names in Dired
+
+ Here are commands that alter file names in a systematic way:
+
+@table @kbd
+@findex dired-upcase
+@kindex % u @r{(Dired)}
+@item % u
+Rename each of the selected files to an upper-case name
+(@code{dired-upcase}). If the old file names are @file{Foo}
+and @file{bar}, the new names are @file{FOO} and @file{BAR}.
+
+@item % l
+@findex dired-downcase
+@kindex % l @r{(Dired)}
+Rename each of the selected files to a lower-case name
+(@code{dired-downcase}). If the old file names are @file{Foo} and
+@file{bar}, the new names are @file{foo} and @file{bar}.
+
+@item % R @var{from} @key{RET} @var{to} @key{RET}
+@kindex % R @r{(Dired)}
+@findex dired-do-rename-regexp
+@itemx % C @var{from} @key{RET} @var{to} @key{RET}
+@kindex % C @r{(Dired)}
+@findex dired-do-copy-regexp
+@itemx % H @var{from} @key{RET} @var{to} @key{RET}
+@kindex % H @r{(Dired)}
+@findex dired-do-hardlink-regexp
+@itemx % S @var{from} @key{RET} @var{to} @key{RET}
+@kindex % S @r{(Dired)}
+@findex dired-do-symlink-regexp
+These four commands rename, copy, make hard links and make soft links,
+in each case computing the new name by regular-expression substitution
+from the name of the old file.
+@end table
+
+ The four regular-expression substitution commands effectively perform
+a search-and-replace on the selected file names in the Dired buffer.
+They read two arguments: a regular expression @var{from}, and a
+substitution pattern @var{to}.
+
+ The commands match each ``old'' file name against the regular
+expression @var{from}, and then replace the matching part with @var{to}.
+You can use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to
+all or part of what the pattern matched in the old file name, as in
+@code{replace-regexp} (@pxref{Regexp Replace}). If the regular expression
+matches more than once in a file name, only the first match is replaced.
+
+ For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each
+selected file by prepending @samp{x-} to its name. The inverse of this,
+removing @samp{x-} from the front of each file name, is also possible:
+one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is
+@kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor
+matches that should span the whole filename.)
+
+ Normally, the replacement process does not consider the files'
+directory names; it operates on the file name within the directory. If
+you specify a numeric argument of zero, then replacement affects the
+entire absolute file name including directory name.
+
+ Often you will want to select the set of files to operate on using the
+same @var{regexp} that you will use to operate on them. To do this,
+mark those files with @kbd{% m @var{regexp} @key{RET}}, then use the
+same regular expression in the command to operate on the files. To make
+this easier, the @kbd{%} commands to operate on files use the last
+regular expression specified in any @kbd{%} command as a default.
+
+@node Comparison in Dired
+@section File Comparison with Dired
+
+ Here are two Dired commands that compare specified files using
+@code{diff}.
+
+@table @kbd
+@item =
+@findex dired-diff
+@kindex = @r{(Dired)}
+Compare the current file (the file at point) with another file (the file
+at the mark) using the @code{diff} program (@code{dired-diff}). The
+file at the mark is the first argument of @code{diff}, and the file at
+point is the second argument.
+
+@findex dired-backup-diff
+@kindex M-= @r{(Dired)}
+@item M-=
+Compare the current file with its latest backup file
+(@code{dired-backup-diff}). If the current file is itself a backup,
+compare it with the file it is a backup of; this way, you can compare
+a file with any backup version of your choice.
+
+The backup file is the first file given to @code{diff}.
+@end table
+
+@node Subdirectories in Dired
+@section Subdirectories in Dired
+@cindex subdirectories in Dired
+@cindex expanding subdirectories in Dired
+
+ A Dired buffer displays just one directory in the normal case;
+but you can optionally include its subdirectories as well.
+
+ The simplest way to include multiple directories in one Dired buffer is
+to specify the options @samp{-lR} for running @code{ls}. (If you give a
+numeric argument when you run Dired, then you can specify these options
+in the minibuffer.) That produces a recursive directory listing showing
+all subdirectories at all levels.
+
+ But usually all the subdirectories are too many; usually you will
+prefer to include specific subdirectories only. You can do this with
+the @kbd{i} command:
+
+@table @kbd
+@findex dired-maybe-insert-subdir
+@kindex i @r{(Dired)}
+@item i
+@cindex inserted subdirectory (Dired)
+@cindex in-situ subdirectory (Dired)
+Insert the contents of a subdirectory later in the buffer.
+@end table
+
+Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line
+that describes a file which is a directory. It inserts the contents of
+that directory into the same Dired buffer, and moves there. Inserted
+subdirectory contents follow the top-level directory of the Dired
+buffer, just as they do in @samp{ls -lR} output.
+
+If the subdirectory's contents are already present in the buffer, the
+@kbd{i} command just moves to it.
+
+In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u
+C-@key{SPC}} takes you back to the old position in the buffer (the line
+describing that subdirectory).
+
+Use the @kbd{l} command (@code{dired-do-redisplay}) to update the
+subdirectory's contents. Use @kbd{k} to delete the subdirectory.
+@xref{Dired Updating}.
+
+@node Subdirectory Motion
+@section Moving Over Subdirectories
+
+ When a Dired buffer lists subdirectories, you can use the page motion
+commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories.
+
+@cindex header line (Dired)
+@cindex directory header lines
+ The following commands move across, up and down in the tree of
+directories within one Dired buffer. They move to @dfn{directory header
+lines}, which are the lines that give a directory's name, at the
+beginning of the directory's contents.
+
+@table @kbd
+@findex dired-next-subdir
+@kindex C-M-n @r{(Dired)}
+@item C-M-n
+Go to next subdirectory header line, regardless of level
+(@code{dired-next-subdir}).
+
+@findex dired-prev-subdir
+@kindex C-M-p @r{(Dired)}
+@item C-M-p
+Go to previous subdirectory header line, regardless of level
+(@code{dired-prev-subdir}).
+
+@findex dired-tree-up
+@kindex C-M-u @r{(Dired)}
+@item C-M-u
+Go up to the parent directory's header line (@code{dired-tree-up}).
+
+@findex dired-tree-down
+@kindex C-M-d @r{(Dired)}
+@item C-M-d
+Go down in the directory tree, to the first subdirectory's header line
+(@code{dired-tree-down}).
+
+@findex dired-prev-dirline
+@kindex < @r{(Dired)}
+@item <
+Move up to the previous directory-file line (@code{dired-prev-dirline}).
+These lines are the ones that describe a directory as a file in its
+parent directory.
+
+@findex dired-next-dirline
+@kindex > @r{(Dired)}
+@item >
+Move down to the next directory-file line (@code{dired-prev-dirline}).
+@end table
+
+@node Hiding Subdirectories
+@section Hiding Subdirectories
+
+@cindex hiding in Dired (Dired)
+ @dfn{Hiding} a subdirectory means to make it invisible, except for its
+header line, via selective display (@pxref{Selective Display}).
+
+@table @kbd
+@item $
+@findex dired-hide-subdir
+@kindex $ @r{(Dired)}
+Hide or reveal the subdirectory that point is in, and move point to the
+next subdirectory (@code{dired-hide-subdir}). A numeric argument serves
+as a repeat count.
+
+@item M-$
+@findex dired-hide-all
+@kindex M-$ @r{(Dired)}
+Hide all subdirectories in this Dired buffer, leaving only their header
+lines (@code{dired-hide-all}). Or, if any subdirectory is currently
+hidden, make all subdirectories visible again. You can use this command
+to get an overview in very deep directory trees or to move quickly to
+subdirectories far away.
+@end table
+
+ Ordinary Dired commands never consider files inside a hidden
+subdirectory. For example, the commands to operate on marked files
+ignore files in hidden directories even if they are marked. Thus you
+can use hiding to temporarily exclude subdirectories from operations
+without having to remove the markers.
+
+ The subdirectory hiding commands toggle; that is, they hide what was
+visible, and show what was hidden.
+
+@node Dired Updating
+@section Updating the Dired Buffer
+
+ This section describes commands to update the Dired buffer to reflect
+outside (non-Dired) changes in the directories and files, and to delete
+part of the Dired buffer.
+
+@table @kbd
+@item g
+Update the entire contents of the Dired buffer (@code{revert-buffer}).
+
+@item l
+Update the specified files (@code{dired-do-redisplay}).
+
+@item k
+Delete the specified @emph{file lines}---not the files, just the lines
+(@code{dired-do-kill-lines}).
+
+@item s
+Toggle between alphabetical order and date/time order
+(@code{dired-sort-toggle-or-edit}).
+
+@item C-u s @var{switches} @key{RET}
+Refresh the Dired buffer using @var{switches} as
+@code{dired-listing-switches}.
+@end table
+
+@kindex g @r{(Dired)}
+@findex revert-buffer @r{(Dired)}
+ Type @kbd{g} (@code{revert-buffer}) to update the contents of the
+Dired buffer, based on changes in the files and directories listed.
+This preserves all marks except for those on files that have vanished.
+Hidden subdirectories are updated but remain hidden.
+
+@kindex l @r{(Dired)}
+@findex dired-do-redisplay
+ To update only some of the files, type @kbd{l}
+(@code{dired-do-redisplay}). This command applies to the next @var{n}
+files, or to the marked files if any, or to the current file. Updating
+them means reading their current status from the file system and
+changing the buffer to reflect it properly.
+
+ If you use @kbd{l} on a subdirectory header line, it updates the
+contents of the corresponding subdirectory.
+
+@kindex k @r{(Dired)}
+@findex dired-do-kill-lines
+ To delete the specified @emph{file lines}---not the files, just the
+lines---type @kbd{k} (@code{dired-do-kill-lines}). With a numeric
+argument @var{n}, this command applies to the next @var{n} files;
+otherwise, it applies to the marked files.
+
+ If you kill the line for a file that is a directory, the directory's
+contents are also deleted from the buffer. Typing @kbd{C-u k} on the
+header line for a subdirectory is another way to delete a subdirectory
+from the Dired buffer.
+
+ The @kbd{g} command brings back any individual lines that you have
+killed in this way, but not subdirectories---you must use @kbd{i} to
+reinsert each subdirectory.
+
+@cindex Dired sorting
+@cindex sorting Dired buffer
+@kindex s @r{(Dired)}
+@findex dired-sort-toggle-or-edit
+ The files in a Dired buffers are normally listed in alphabetical order
+by file names. Alternatively Dired can sort them by date/time. The
+Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches
+between these two sorting modes. The mode line in a Dired buffer
+indicates which way it is currently sorted---by name, or by date.
+
+ @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for
+@code{dired-listing-switches}.
+
+@node Dired and Find
+@section Dired and @code{find}
+@cindex @code{find} and Dired
+
+ You can select a set of files for display in a Dired buffer more
+flexibly by using the @code{find} utility to choose the files.
+
+@findex find-name-dired
+ To search for files with names matching a wildcard pattern use
+@kbd{M-x find-name-dired}. It reads arguments @var{directory} and
+@var{pattern}, and chooses all the files in @var{directory} or its
+subdirectories whose individual names match @var{pattern}.
+
+ The files thus chosen are displayed in a Dired buffer in which the
+ordinary Dired commands are available.
+
+@findex find-grep-dired
+ If you want to test the contents of files, rather than their names,
+use @kbd{M-x find-grep-dired}. This command reads two minibuffer
+arguments, @var{directory} and @var{regexp}; it chooses all the files in
+@var{directory} or its subdirectories that contain a match for
+@var{regexp}. It works by running the programs @code{find} and
+@code{grep}. See also @kbd{M-x grep-find}, in @ref{Compilation}.
+Remember to write the regular expression for @code{grep}, not for Emacs.
+
+@findex find-dired
+ The most general command in this series is @kbd{M-x find-dired}, which
+lets you specify any condition that @code{find} can test. It takes two
+minibuffer arguments, @var{directory} and @var{find-args}; it runs
+@code{find} in @var{directory}, passing @var{find-args} to tell
+@code{find} what condition to test. To use this command, you need to
+know how to use @code{find}.
+
+@vindex find-ls-option
+ The format of listing produced by these commands is controlled by the
+variable @code{find-ls-option}, whose default value specifies using
+options @samp{-ld} for @code{ls}. If your listings are corrupted, you
+may need to change the value of this variable.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Display, Search, Registers, Top
+@chapter Controlling the Display
+
+ Since only part of a large buffer fits in the window, Emacs tries to
+show a part that is likely to be interesting. Display-control commands
+allow you to specify which part of the text you want to see, and how to
+display it.
+
+@menu
+* Scrolling:: Moving text up and down in a window.
+* Horizontal Scrolling:: Moving text left and right in a window.
+* Follow Mode:: Follow mode lets two windows scroll as one.
+* Selective Display:: Hiding lines with lots of indentation.
+* Optional Mode Line:: Optional mode line display features.
+* Text Display:: How text characters are normally displayed.
+* Display Vars:: Information on variables for customizing display.
+@end menu
+
+@node Scrolling
+@section Scrolling
+
+ If a buffer contains text that is too large to fit entirely within a
+window that is displaying the buffer, Emacs shows a contiguous portion of
+the text. The portion shown always contains point.
+
+@cindex scrolling
+ @dfn{Scrolling} means moving text up or down in the window so that
+different parts of the text are visible. Scrolling forward means that text
+moves up, and new text appears at the bottom. Scrolling backward moves
+text down and new text appears at the top.
+
+ Scrolling happens automatically if you move point past the bottom or top
+of the window. You can also explicitly request scrolling with the commands
+in this section.
+
+@table @kbd
+@item C-l
+Clear screen and redisplay, scrolling the selected window to center
+point vertically within it (@code{recenter}).
+@item C-v
+Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
+@item @key{NEXT}
+Likewise, scroll forward.
+@item M-v
+Scroll backward (@code{scroll-down}).
+@item @key{PRIOR}
+Likewise, scroll backward.
+@item @var{arg} C-l
+Scroll so point is on line @var{arg} (@code{recenter}).
+@item C-M-l
+Scroll heuristically to bring useful information onto the screen
+(@code{reposition-window}).
+@end table
+
+@kindex C-l
+@findex recenter
+ The most basic scrolling command is @kbd{C-l} (@code{recenter}) with
+no argument. It clears the entire screen and redisplays all windows.
+In addition, it scrolls the selected window so that point is halfway
+down from the top of the window.
+
+@kindex C-v
+@kindex M-v
+@kindex NEXT
+@kindex PRIOR
+@findex scroll-up
+@findex scroll-down
+ The scrolling commands @kbd{C-v} and @kbd{M-v} let you move all the text
+in the window up or down a few lines. @kbd{C-v} (@code{scroll-up}) with an
+argument shows you that many more lines at the bottom of the window, moving
+the text and point up together as @kbd{C-l} might. @kbd{C-v} with a
+negative argument shows you more lines at the top of the window.
+@kbd{M-v} (@code{scroll-down}) is like @kbd{C-v}, but moves in the
+opposite direction. The function keys @key{NEXT} and @key{PRIOR} are
+equivalent to @kbd{C-v} and @kbd{M-v}.
+
+ The names of scroll commands are based on the direction that the text
+moves in the window. Thus, the command to scroll forward is called
+@code{scroll-up} because it moves the text upward on the screen.
+
+@vindex next-screen-context-lines
+ To read the buffer a windowful at a time, use @kbd{C-v} with no argument.
+It takes the last two lines at the bottom of the window and puts them at
+the top, followed by nearly a whole windowful of lines not previously
+visible. If point was in the text scrolled off the top, it moves to the
+new top of the window. @kbd{M-v} with no argument moves backward with
+overlap similarly. The number of lines of overlap across a @kbd{C-v} or
+@kbd{M-v} is controlled by the variable @code{next-screen-context-lines}; by
+default, it is 2.
+
+@vindex scroll-preserve-screen-position
+ Some users like the full-screen scroll commands to keep point at the
+same screen line. To enable this behavior, set the variable
+@code{scroll-preserve-screen-position} to a non-@code{nil} value. This
+mode is convenient for browsing through a file by scrolling by
+screenfuls; if you come back to the screen where you started, point goes
+back to the line where it started. However, this mode is inconvenient
+when you move to the next screen in order to move point to the text
+there.
+
+ Another way to do scrolling is with @kbd{C-l} with a numeric argument.
+@kbd{C-l} does not clear the screen when given an argument; it only scrolls
+the selected window. With a positive argument @var{n}, it repositions text
+to put point @var{n} lines down from the top. An argument of zero puts
+point on the very top line. Point does not move with respect to the text;
+rather, the text and point move rigidly on the screen. @kbd{C-l} with a
+negative argument puts point that many lines from the bottom of the window.
+For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u
+- 5 C-l} puts it five lines from the bottom. Just @kbd{C-u} as argument,
+as in @kbd{C-u C-l}, scrolls point to the center of the selected window.
+
+@kindex C-M-l
+@findex reposition-window
+ The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current
+window heuristically in a way designed to get useful information onto
+the screen. For example, in a Lisp file, this command tries to get the
+entire current defun onto the screen if possible.
+
+@vindex scroll-conservatively
+ Scrolling happens automatically if point has moved out of the visible
+portion of the text when it is time to display. Normally, automatic
+scrolling centers point vertically within the window. However, if you
+set @code{scroll-conservatively} to a small number @var{n}, then if you
+move point just a little off the screen---less than @var{n} lines---then
+Emacs scrolls the text just far enough to bring point back on screen.
+By default, @code{scroll-conservatively} is 0.
+
+@vindex scroll-margin
+ The variable @code{scroll-margin} restricts how close point can come
+to the top or bottom of a window. Its value is a number of screen
+lines; if point comes within that many lines of the top or bottom of the
+window, Emacs recenters the window. By default, @code{scroll-margin} is
+0.
+
+@node Horizontal Scrolling
+@section Horizontal Scrolling
+@cindex horizontal scrolling
+
+ @dfn{Horizontal scrolling} means shifting all the lines sideways
+within a window---so that some of the text near the left margin
+is not displayed at all.
+
+@table @kbd
+@item C-x <
+Scroll text in current window to the left (@code{scroll-left}).
+@item C-x >
+Scroll to the right (@code{scroll-right}).
+@end table
+
+ When a window has been scrolled horizontally, text lines are truncated
+rather than continued (@pxref{Continuation Lines}), with a @samp{$}
+appearing in the first column when there is text truncated to the left,
+and in the last column when there is text truncated to the right.
+
+@kindex C-x <
+@kindex C-x >
+@findex scroll-left
+@findex scroll-right
+ The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected
+window to the left by @var{n} columns with argument @var{n}. This moves
+part of the beginning of each line off the left edge of the window.
+With no argument, it scrolls by almost the full width of the window (two
+columns less, to be precise).
+
+ @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. The
+window cannot be scrolled any farther to the right once it is displayed
+normally (with each line starting at the window's left margin);
+attempting to do so has no effect. This means that you don't have to
+calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large
+argument will restore the normal display.
+
+@cindex Hscroll mode
+@cindex mode, Hscroll
+@findex hscroll-mode
+ You can request automatic horizontal scrolling by enabling Hscroll
+mode. When this mode is enabled, Emacs scrolls a window horizontally
+whenever that is necessary to keep point visible and not too far from
+the left or right edge. The command to enable or disable this mode is
+@kbd{M-x hscroll-mode}.
+
+@node Follow Mode
+@section Follow Mode
+@cindex Follow mode
+@cindex mode, Follow
+
+ @dfn{Follow mode} is a minor mode that makes two windows showing the
+same buffer scroll as one tall ``virtual window.'' To use Follow mode,
+go to a frame with just one window, split it into two side-by-side
+windows using @kbd{C-x 3}, and then type @kbd{M-x follow-mode}. From
+then on, you can edit the buffer in either of the two windows, or scroll
+either one; the other window follows it.
+
+ To turn off Follow mode, type @kbd{M-x follow-mode} a second time.
+
+@node Selective Display
+@section Selective Display
+@findex set-selective-display
+@kindex C-x $
+
+ Emacs has the ability to hide lines indented more than a certain number
+of columns (you specify how many columns). You can use this to get an
+overview of a part of a program.
+
+ To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a
+numeric argument @var{n}. Then lines with at least @var{n} columns of
+indentation disappear from the screen. The only indication of their
+presence is that three dots (@samp{@dots{}}) appear at the end of each
+visible line that is followed by one or more hidden ones.
+
+ The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as
+if they were not there.
+
+ The hidden lines are still present in the buffer, and most editing
+commands see them as usual, so you may find point in the middle of the
+hidden text. When this happens, the cursor appears at the end of the
+previous line, after the three dots. If point is at the end of the
+visible line, before the newline that ends it, the cursor appears before
+the three dots.
+
+ To make all lines visible again, type @kbd{C-x $} with no argument.
+
+@vindex selective-display-ellipses
+ If you set the variable @code{selective-display-ellipses} to
+@code{nil}, the three dots do not appear at the end of a line that
+precedes hidden lines. Then there is no visible indication of the
+hidden lines. This variable becomes local automatically when set.
+
+@node Optional Mode Line
+@section Optional Mode Line Features
+
+@cindex Line Number mode
+@cindex mode, Line Number
+@findex line-number-mode
+ The current line number of point appears in the mode line when Line
+Number mode is enabled. Use the command @kbd{M-x line-number-mode} to
+turn this mode on and off; normally it is on. The line number appears
+before the buffer percentage @var{pos}, with the letter @samp{L} to
+indicate what it is. @xref{Minor Modes}, for more information about
+minor modes and about how to use this command.
+
+@vindex line-number-display-limit
+ If the buffer is very large (larger than the value of
+@code{line-number-display-limit}), then the line number doesn't appear.
+Emacs doesn't compute the line number when the buffer is large, because
+that would be too slow. If you have narrowed the buffer
+(@pxref{Narrowing}), the displayed line number is relative to the
+accessible portion of the buffer.
+
+@cindex Column Number mode
+@cindex mode, Column Number
+@findex column-number-mode
+ You can also display the current column number by turning on Column
+Number mode. It displays the current column number preceded by the
+letter @samp{C}. Type @kbd{M-x column-number-mode} to toggle this mode.
+
+@findex display-time
+@cindex time (on mode line)
+ Emacs can optionally display the time and system load in all mode
+lines. To enable this feature, type @kbd{M-x display-time}. The
+information added to the mode line usually appears after the buffer
+name, before the mode names and their parentheses. It looks like this:
+
+@example
+@var{hh}:@var{mm}pm @var{l.ll}
+@end example
+
+@noindent
+@vindex display-time-24hr-format
+Here @var{hh} and @var{mm} are the hour and minute, followed always by
+@samp{am} or @samp{pm}. @var{l.ll} is the average number of running
+processes in the whole system recently. (Some fields may be missing if
+your operating system cannot support them.) If you prefer time display
+in 24-hour format, set the variable @code{display-time-24hr-format}
+to @code{t}.
+
+@cindex mail (on mode line)
+ The word @samp{Mail} appears after the load level if there is mail
+for you that you have not read yet.
+
+@node Text Display
+@section How Text Is Displayed
+@cindex characters (in text)
+
+ ASCII printing characters (octal codes 040 through 0176) in Emacs
+buffers are displayed with their graphics. So are non-ASCII multibyte
+printing characters (octal codes above 0400).
+
+ Some ASCII control characters are displayed in special ways. The
+newline character (octal code 012) is displayed by starting a new line.
+The tab character (octal code 011) is displayed by moving to the next
+tab stop column (normally every 8 columns).
+
+ Other ASCII control characters are normally displayed as a caret
+(@samp{^}) followed by the non-control version of the character; thus,
+control-A is displayed as @samp{^A}.
+
+ Non-ASCII characters 0200 through 0377 are displayed with octal escape
+sequences; thus, character code 0243 (octal) is displayed as
+@samp{\243}. However, if you enable European display, most of these
+characters become non-ASCII printing characters, and are displayed using
+their graphics (assuming your terminal supports them).
+@xref{Single-Byte European Support}.
+
+@node Display Vars
+@section Variables Controlling Display
+
+ This section contains information for customization only. Beginning
+users should skip it.
+
+@vindex mode-line-inverse-video
+ The variable @code{mode-line-inverse-video} controls whether the mode
+line is displayed in inverse video (assuming the terminal supports it);
+@code{nil} means don't do so. @xref{Mode Line}. If you specify the
+foreground color for the @code{modeline} face, and
+@code{mode-line-inverse-video} is non-@code{nil}, then the default
+background color for that face is the usual foreground color.
+@xref{Faces}.
+
+@vindex inverse-video
+ If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
+to invert all the lines of the display from what they normally are.
+
+@vindex visible-bell
+ If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
+to make the whole screen blink when it would normally make an audible bell
+sound. This variable has no effect if your terminal does not have a way
+to make the screen blink.@refill
+
+@vindex no-redraw-on-reenter
+ When you reenter Emacs after suspending, Emacs normally clears the
+screen and redraws the entire display. On some terminals with more than
+one page of memory, it is possible to arrange the termcap entry so that
+the @samp{ti} and @samp{te} strings (output to the terminal when Emacs
+is entered and exited, respectively) switch between pages of memory so
+as to use one page for Emacs and another page for other output. Then
+you might want to set the variable @code{no-redraw-on-reenter}
+non-@code{nil}; this tells Emacs to assume, when resumed, that the
+screen page it is using still contains what Emacs last wrote there.
+
+@vindex echo-keystrokes
+ The variable @code{echo-keystrokes} controls the echoing of multi-character
+keys; its value is the number of seconds of pause required to cause echoing
+to start, or zero meaning don't echo at all. @xref{Echo Area}.
+
+@vindex ctl-arrow
+ If the variable @code{ctl-arrow} is @code{nil}, control characters in
+the buffer are displayed with octal escape sequences, except for newline
+and tab. Altering the value of @code{ctl-arrow} makes it local to the
+current buffer; until that time, the default value is in effect. The
+default is initially @code{t}. @xref{Display Tables,, Display Tables,
+elisp, The Emacs Lisp Reference Manual}.
+
+@vindex tab-width
+ Normally, a tab character in the buffer is displayed as whitespace which
+extends to the next display tab stop position, and display tab stops come
+at intervals equal to eight spaces. The number of spaces per tab is
+controlled by the variable @code{tab-width}, which is made local by
+changing it, just like @code{ctl-arrow}. Note that how the tab character
+in the buffer is displayed has nothing to do with the definition of
+@key{TAB} as a command. The variable @code{tab-width} must have an
+integer value between 1 and 1000, inclusive.
+
+@c @vindex truncate-lines @c No index entry here, because we have one
+@c in the continuation section.
+ If the variable @code{truncate-lines} is non-@code{nil}, then each
+line of text gets just one screen line for display; if the text line is
+too long, display shows only the part that fits. If
+@code{truncate-lines} is @code{nil}, then long text lines display as
+more than one screen line, enough to show the whole text of the line.
+@xref{Continuation Lines}. Altering the value of @code{truncate-lines}
+makes it local to the current buffer; until that time, the default value
+is in effect. The default is initially @code{nil}.
+
+@c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows.
+ If the variable @code{truncate-partial-width-windows} is
+non-@code{nil}, it forces truncation rather than continuation in any
+window less than the full width of the screen or frame, regardless of
+the value of @code{truncate-lines}. For information about side-by-side
+windows, see @ref{Split Window}. See also @ref{Display,, Display,
+elisp, The Emacs Lisp Reference Manual}.
+
+@vindex baud-rate
+ The variable @code{baud-rate} holds the output speed of the
+terminal, as far as Emacs knows. Setting this variable does not change
+the speed of actual data transmission, but the value is used for
+calculations such as padding. It also affects decisions about whether
+to scroll part of the screen or redraw it instead---even when using a
+window system. (We designed it this way, despite the fact that a window
+system has no true ``output speed,'' to give you a way to tune these
+decisions.)
+
+ You can customize the way any particular character code is displayed
+by means of a display table. @xref{Display Tables,, Display Tables,
+elisp, The Emacs Lisp Reference Manual}.
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c documentation for Ediff
+@c Written by Michael Kifer
+
+@comment %**start of header (This is for running Texinfo on a region.)
+
+@comment Using ediff.info instead of ediff in setfilename breaks DOS.
+@comment @setfilename ediff
+@comment @setfilename ediff.info
+@setfilename ../info/ediff
+
+@settitle Ediff User's Manual
+@synindex vr cp
+@synindex fn cp
+@synindex pg cp
+
+@dircategory Editors
+@direntry
+* Ediff: (ediff). A visual interface for comparing and merging programs.
+@end direntry
+
+@iftex
+@finalout
+@end iftex
+@c @smallbook
+@comment %**end of header (This is for running Texinfo on a region.)
+
+@ifinfo
+This file documents Ediff, a comprehensive visual interface to Unix diff
+and patch utilities.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+@end ifinfo
+
+@iftex
+@titlepage
+@title Ediff User's Manual
+@sp 4
+@subtitle Ediff version 2.70
+@sp 1
+@subtitle March 1998
+@sp 5
+@author Michael Kifer
+@page
+
+@vskip 0pt plus 1filll
+@noindent
+Copyright @copyright{} 1995, 1996, 1997 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+@end titlepage
+@page
+@end iftex
+
+@node Top, Introduction, (dir), (dir)
+
+
+@menu
+* Introduction:: About Ediff.
+* Major Entry Points:: How to use Ediff.
+* Session Commands:: Ediff commands used within a session.
+* Registry of Ediff Sessions:: Keeping track of multiple Ediff sessions.
+* Session Groups:: Comparing and merging directories.
+* Remote and Compressed Files:: You may want to know about this.
+* Customization:: How to make Ediff work the way YOU want.
+* Credits:: Thanks to those who helped.
+* Index::
+@end menu
+
+@node Introduction, Major Entry Points, Top, Top
+@chapter Introduction
+
+@cindex Comparing files and buffers
+@cindex Merging files and buffers
+@cindex Patching files and buffers
+@cindex Finding differences
+
+Ediff provides a convenient way for simultaneous browsing through
+the differences between a pair (or a triple) of files or buffers
+(which are called @samp{variants} for our purposes). The
+files being compared, file-A, file-B, and file-C (if applicable) are
+shown in separate windows (side by side, one above the another, or in
+separate frames), and the differences are highlighted as you step
+through them. You can also copy difference regions from one buffer to
+another (and recover old differences if you change your mind).
+
+Another powerful feature is the ability to merge a pair of files into a
+third buffer. Merging with an ancestor file is also supported.
+Furthermore, Ediff is equipped with directory-level capabilities that
+allow the user to conveniently launch browsing or merging sessions on
+groups of files in two (or three) different directories.
+
+In addition, Ediff can apply a patch to a file and then let you step though
+both files, the patched and the original one, simultaneously,
+difference-by-difference. You can even apply a patch right out of a mail
+buffer, i.e., patches received by mail don't even have to be saved. Since
+Ediff lets you copy differences between variants, you can, in effect, apply
+patches selectively (i.e., you can copy a difference region from
+@file{file.orig} to @file{file}, thereby undoing any particular patch that
+you don't like).
+
+Ediff even understands multi-file patches and can apply them interactively!
+(Ediff can recognize multi-file patches only if they are in the context
+format or GNU unified format. All other patches are treated as 1-file
+patches. Ediff is [hopefully] using the same algorithm as @file{patch} to
+determine which files need to be patched.)
+
+Ediff is aware of version control, which lets you compare
+files with their older versions. Ediff also works with remote and
+compressed files, automatically ftp'ing them over and uncompressing them.
+@xref{Remote and Compressed Files}, for details.
+
+This package builds upon ideas borrowed from Emerge, and several of Ediff's
+functions are adaptations from Emerge. Although Ediff subsumes and greatly
+extends Emerge, much of the functionality in Ediff is influenced by Emerge.
+The architecture and the interface are, of course, drastically different.
+
+@node Major Entry Points, Session Commands, Introduction, Top
+@chapter Major Entry Points
+
+Ediff can be invoked interactively using the following functions, which can
+be run either from the minibuffer or from the menu bar. In the menu bar,
+all Ediff's entry points belong to three submenus of the Tools menu:
+Compare, Merge, and Apply Patch.
+
+@table @code
+@item ediff-files
+@itemx ediff
+@findex ediff-files
+@findex ediff
+Compare two files.
+
+@item ediff-buffers
+@findex ediff-buffers
+Compare two buffers.
+
+@item ediff-files3
+@itemx ediff3
+@findex ediff-files3
+@findex ediff3
+Compare three files.
+
+@item ediff-buffers3
+@findex ediff-buffers3
+Compare three buffers.
+
+@item edirs
+@itemx ediff-directories
+@findex edirs
+@findex ediff-directories
+ Compare files common to two directories.
+@item edirs3
+@itemx ediff-directories3
+@findex edirs3
+@findex ediff-directories3
+ Compare files common to three directories.
+@item edir-revisions
+@itemx ediff-directory-revisions
+@findex ediff-directory-revisions
+@findex edir-revisions
+ Compare versions of files in a given directory. Ediff selects only the
+files that are under version control.
+@item edir-merge-revisions
+@itemx ediff-merge-directory-revisions
+@findex edir-merge-revisions
+@findex ediff-merge-directory-revisions
+ Merge versions of files in a given directory. Ediff selects only the
+files that are under version control.
+@item edir-merge-revisions-with-ancestor
+@itemx ediff-merge-directory-revisions-with-ancestor
+@findex edir-merge-revisions-with-ancestor
+@findex ediff-merge-directory-revisions-with-ancestor
+ Merge versions of files in a given directory using other versions as
+ancestors. Ediff selects only the files that are under version control.
+
+@item ediff-windows-wordwise
+@findex ediff-windows-wordwise
+Compare windows word-by-word.
+
+@item ediff-windows-linewise
+@findex ediff-windows-linewise
+Compare windows line-by-line.
+
+@item ediff-regions-wordwise
+@findex ediff-regions-wordwise
+Compare regions word-by-word.
+
+@item ediff-regions-linewise
+@findex ediff-regions-linewise
+Compare regions line-by-line.
+
+@item ediff-revision
+@findex ediff-revision
+ Compare versions of the current buffer, if the buffer is visiting
+ a file under version control.
+
+@item ediff-patch-file
+@itemx epatch
+@findex ediff-patch-file
+@findex epatch
+
+Patch a file or multiple files, then compare. If the patch applies to just
+one file, Ediff will invoke a regular comparison session. If it is a
+multi-file patch, then a session group interface will be used and the user
+will be able to patch the files selectively. @xref{Session Groups}, for
+more details.
+
+Note that @code{ediff-patch-file} will actually use the @file{patch}
+utility to change the the original files on disk. This is not that
+dangerous, since you will always have the original contents of the file
+saved in another file that has the extension @file{.orig}.
+Furthermore, if the file is under version control, then you can always back
+out to one of the previous versions (see the section on Version Countrol in
+Emacs manual).
+
+@code{ediff-patch-file} is careful about versions control: if the file
+to be patched is checked in, then Ediff will offer to check it out, because
+failing to do so may result in the loss of the changes when the file is
+checked out the next time.
+
+If you don't intend to modify the file via the patch and just want to see
+what the patch is all about (and decide later), then
+@code{ediff-patch-buffer} might be a better choice.
+
+@item ediff-patch-buffer
+@itemx epatch-buffer
+@findex ediff-patch-buffer
+@findex epatch-buffer
+Patch a buffer, then compare. The buffer being patched and the file visited
+by that buffer (if any) is @emph{not} modified. The result of the patch
+appears in some other buffer that has the name ending with @emph{_patched}.
+
+This function would refuse to apply a multifile patch to a buffer. Use
+@code{ediff-patch-file} for that (and when you want the original file to be
+modified by the @file{patch} utility).
+
+@item ediff-merge-files
+@itemx ediff-merge
+@findex ediff-merge-files
+@findex ediff-merge
+Merge two files.
+
+@item ediff-merge-files-with-ancestor
+@itemx ediff-merge-with-ancestor
+@findex ediff-merge-files-with-ancestor
+@findex ediff-merge-with-ancestor
+Like @code{ediff-merge}, but with a third ancestor file.
+
+@item ediff-merge-buffers
+@findex ediff-merge-buffers
+Merge two buffers.
+
+@item ediff-merge-buffers-with-ancestor
+@findex ediff-merge-buffers-with-ancestor
+Same but with ancestor.
+
+
+@item edirs-merge
+@itemx ediff-merge-directories
+@findex edirs-merge
+@findex ediff-merge-directories
+ Merge files common to two directories.
+@item edirs-merge-with-ancestor
+@itemx ediff-merge-directories-with-ancestor
+@findex edirs-merge-with-ancestor
+@findex ediff-merge-directories-with-ancestor
+ Same but using files in a third directory as ancestors.
+ If a pair of files doesn't have an ancestor in the ancestor-directory, you
+ will still be able to merge them without the ancestor.
+
+@item ediff-merge-revisions
+@findex ediff-merge-revisions
+Merge two versions of the file visited by the current buffer.
+
+@item ediff-merge-revisions-with-ancestor
+@findex ediff-merge-revisions-with-ancestor
+Same but with ancestor.
+
+@item ediff-documentation
+@findex ediff-documentation
+Brings up this manual.
+
+@item ediff-show-registry
+@itemx eregistry
+Brings up Ediff session registry. This feature enables you to quickly find
+and restart active Ediff sessions.
+@end table
+
+@noindent
+If you want Ediff to be loaded from the very beginning of your Emacs
+session, you should put this line in your @file{~/.emacs} file:
+
+@example
+(require 'ediff)
+@end example
+
+@noindent
+Otherwise, Ediff will be loaded automatically when you use one of the
+above functions, either directly or through the menus.
+
+When the above functions are invoked, the user is prompted for all the
+necessary information---typically the files or buffers to compare, merge, or
+patch. Ediff tries to be smart about these prompts. For instance, in
+comparing/merging files, it will offer the visible buffers as defaults. In
+prompting for files, if the user enters a directory, the previously input
+file name will be appended to that directory. In addition, if the variable
+@code{ediff-use-last-dir} is not @code{nil}, Ediff will offer
+previously entered directories as defaults (which will be maintained
+separately for each type of file, A, B, or C).
+@vindex @code{ediff-use-last-dir}
+
+All the above functions use the POSIX @code{diff} or @code{diff3} programs
+to find differences between two files. They process the @code{diff} output
+and display it in a convenient form. At present, Ediff understands only
+the plain output from diff. Options such as @samp{-c} are not supported,
+nor is the format produced by incompatible file comparison programs such as
+the VMS version of @code{diff}.
+
+The functions @code{ediff-files}, @code{ediff-buffers},
+@code{ediff-files3}, @code{ediff-buffers3} first display the coarse,
+line-based difference regions, as reported by the @file{diff} program. The
+total number of difference regions and the current difference number are
+always displayed in the mode line of the control window.
+
+Since @code{diff} may report fairly large chunks of text as being different,
+even though the difference may be localized to just a few words or even
+to the white space or line breaks, Ediff further @emph{refines} the
+regions to indicate which exact words differ. If the only difference is
+in the white space and line breaks, Ediff says so.
+
+On a color display, fine differences are highlighted with color; on a
+monochrome display, they are underlined. @xref{Highlighting Difference
+Regions}, for information on how to customize this.
+
+The functions @code{ediff-windows-wordwise},
+@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and
+@code{ediff-regions-linewise} do comparison on parts of existing Emacs
+buffers. Since @code{ediff-windows-wordwise} and
+@code{ediff-regions-wordwise} are intended for relatively small segments
+of buffers, comparison is done on the basis of words rather than lines.
+No refinement is necessary in this case. These commands are recommended
+only for relatively small regions (perhaps, up to 100 lines), because
+these functions have a relatively slow startup.
+
+To compare large regions, use @code{ediff-regions-linewise}. This
+command displays differences much like @code{ediff-files} and
+@code{ediff-buffers}.
+
+The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a
+patch to a file or a buffer and then run Ediff on the appropriate
+files/buffers, displaying the difference regions.
+
+The entry points @code{ediff-directories}, @code{ediff-merge-directories},
+etc., provide a convenient interface for comparing and merging files in
+different directories. The user is presented with Dired-like interface from
+which one can run a group of related Ediff sessions.
+
+For files under version control, @code{ediff-revision} lets you compare
+the file visited by the current buffer to one of its checked-in versions.
+You can also compare two checked-in versions of the visited file.
+Moreover, the functions @code{ediff-directory-revisions},
+@code{ediff-merge-directory-revisions}, etc., let you run a group of
+related Ediff sessions by taking a directory and comparing (or merging)
+versions of files in that directory.
+
+@node Session Commands, Registry of Ediff Sessions, Major Entry Points, Top
+@chapter Session Commands
+
+All Ediff commands are displayed in a Quick Help window, unless you type
+@kbd{?} to shrink the window to just one line. You can redisplay the help
+window by typing @kbd{?} again. The Quick Help commands are detailed below.
+
+Many Ediff commands take numeric prefix arguments. For instance, if you
+type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}),
+Ediff moves to the third difference region. Typing 3 and then @kbd{a}
+(@code{ediff-diff-to-diff}) copies the 3d difference region from variant A
+to variant B. Likewise, 4 followed by @kbd{ra} restores the 4th difference
+region in buffer A (if it was previously written over via the command
+@kbd{a}).
+
+Some commands take negative prefix arguments as well. For instance, typing
+@kbd{-} and then @kbd{j} will make the last difference region
+current. Typing @kbd{-2} then @kbd{j} makes the penultimate difference
+region current, etc.
+
+Without the prefix argument, all commands operate on the currently
+selected difference region. You can make any difference region
+current using the various commands explained below.
+
+For some commands, the actual value of the prefix argument is
+immaterial. However, if supplied, the prefix argument may modify the
+command (see @kbd{ga}, @kbd{gb}, and @kbd{gc}).
+
+@menu
+* Quick Help Commands:: Frequently used commands.
+* Other Session Commands:: Commands that are not bound to keys.
+@end menu
+
+@node Quick Help Commands,Other Session Commands,,Session Commands
+@section Quick Help Commands
+
+@table @kbd
+@item ?
+Toggles the Ediff Quick Help window ON and OFF.
+@item G
+Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer.
+
+@item E
+Brings up the top node of this manual, where you can find further
+information on the various Ediff functions and advanced issues, such as
+customization, session groups, etc.
+
+@item v
+Scrolls up buffers A and B (and buffer C where appropriate) in a
+coordinated fashion.
+@item V
+Scrolls the buffers down.
+
+@item <
+Scrolls the buffers to the left simultaneously.
+@item >
+Scrolls buffers to the right.
+
+@item wd
+Saves the output from the diff utility, for further reference.
+
+With prefix argument, saves the plain output from @file{diff} (see
+@code{ediff-diff-program} and @code{ediff-diff-options}). Without the
+argument, it saves customized @file{diff} output (see
+@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if
+it is available.
+
+@item wa
+Saves buffer A, if it was modified.
+@item wb
+Saves buffer B, if it was modified.
+@item wc
+Saves buffer C, if it was modified (if you are in a session that
+compares three files simultaneously).
+
+@item a
+@emph{In comparison sessions:}
+Copies the current difference region (or the region specified as the prefix
+to this command) from buffer A to buffer B.
+Ediff saves the old contents of buffer B's region; it can
+be restored via the command @kbd{rb}, which see.
+
+@emph{In merge sessions:}
+Copies the current difference region (or the region specified as the prefix
+to this command) from buffer A to the merge buffer. The old contents of
+this region in buffer C can be restored via the command @kbd{r}.
+
+@item b
+Works similarly, but copies the current difference region from buffer B to
+buffer A (in @emph{comparison sessions}) or the merge buffer (in
+@emph{merge sessions}).
+
+Ediff saves the old contents of the difference region copied over; it can
+be reinstated via the command @kbd{ra} in comparison sessions and
+@kbd{r} in merge sessions.
+
+@item ab
+Copies the current difference region (or the region specified as the prefix
+to this command) from buffer A to buffer B. This (and the next five)
+command is enabled only in sessions that compare three files
+simultaneously. The old region in buffer B is saved and can be restored
+via the command @kbd{rb}.
+@item ac
+Copies the difference region from buffer A to buffer C.
+The old region in buffer C is saved and can be restored via the command
+@kbd{rc}.
+@item ba
+Copies the difference region from buffer B to buffer A.
+The old region in buffer A is saved and can be restored via the command
+@kbd{ra}.
+@item bc
+Copies the difference region from buffer B to buffer C.
+The command @kbd{rc} undoes this.
+@item ca
+Copies the difference region from buffer C to buffer A.
+The command @kbd{ra} undoes this.
+@item cb
+Copies the difference region from buffer C to buffer B.
+The command @kbd{rb} undoes this.
+
+@item p
+@itemx DEL
+Makes the previous difference region current.
+@item n
+@itemx SPC
+Makes the next difference region current.
+
+@item j
+@itemx -j
+@itemx Nj
+Makes the very first difference region current.
+
+@kbd{-j} makes the last region current. Typing a number, N, and then `j'
+makes the difference region N current. Typing -N (a negative number) then
+`j' makes current the region Last - N.
+
+@item ga
+Makes current the difference region closest to the position of the point in
+buffer A.
+
+However, with a prefix argument, Ediff would position all variants
+around the area indicated by the current point in buffer A: if
+the point is inside a difference region, then the variants will be
+positioned at this difference region. If the point is not in any difference
+region, then it is in an area where all variants agree with each other. In
+this case, the variants will be positioned so that each would display this
+area (of agreement).
+@item gb
+Makes current the difference region closest to the position of the point in
+buffer B.
+
+With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B.
+@item gc
+@emph{In merge sessions:}
+makes current the difference region closest to the point in the merge buffer.
+
+@emph{In 3-file comparison sessions:}
+makes current the region closest to the point in buffer C.
+
+With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C.
+
+@item !
+Recomputes the difference regions, bringing them up to date. This is often
+needed because it is common to do all sorts of editing during Ediff
+sessions, so after a while, the highlighted difference regions may no
+longer reflect the actual differences among the buffers.
+
+@item *
+Forces refinement of the current difference region, which highlights the exact
+words of disagreement among the buffers. With a negative prefix argument,
+unhighlights the current region.
+
+Forceful refinement may be needed if Ediff encounters a difference region
+that is larger than @code{ediff-auto-refine-limit}. In this situation,
+Ediff doesn't do automatic refinement in order to improve response time.
+(Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} still
+works there. However, the only useful piece of information it can tell you
+is whether or not the difference regions disagree only in the amount of
+white space.)
+
+This command is also useful when the highlighted fine differences are
+no longer current, due to user editing.
+
+@item m
+Displays the current Ediff session in a frame as wide as the physical
+display. This is useful when comparing files side-by-side. Typing `m' again
+restores the original size of the frame.
+
+@item |
+Toggles the horizontal/vertical split of the Ediff display. Horizontal
+split is convenient when it is possible to compare files
+side-by-side. If the frame in which files are displayed is too narrow
+and lines are cut off, typing @kbd{m} may help some.
+
+@item @@
+Toggles auto-refinement of difference regions (i.e., automatic highlighting
+of the exact words that differ among the variants). Auto-refinement is
+turned off on devices where Emacs doesn't support highlighting.
+
+On slow machines, it may be advantageous to turn auto-refinement off. The
+user can always forcefully refine specific difference regions by typing
+@kbd{*}.
+
+@item h
+Cycles between full highlighting, the mode where fine differences are not
+highlighted (but computed), and the mode where highlighting is done with
+ASCII strings. The latter is not really recommended, unless on a dumb TTY.
+
+@item r
+Restores the old contents of the region in the merge buffer.
+(If you copied a difference region from buffer A or B into the merge buffer
+using the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of the
+region in case you change your mind.)
+
+This command is enabled in merge sessions only.
+
+@item ra
+Restores the old contents of the current difference region in buffer A,
+which was previously saved when the user invoked one of these commands:
+@kbd{b}, @kbd{ba}, @kbd{ca}, which see. This command is enabled in
+comparison sessions only.
+@item rb
+Restores the old contents of the current difference region in buffer B,
+which was previously saved when the user invoked one of these commands:
+@kbd{a}, @kbd{ab}, @kbd{cb}, which see. This command is enabled in
+comparison sessions only.
+@item rc
+Restores the old contents of the current difference region in buffer C,
+which was previously saved when the user invoked one of these commands:
+@kbd{ac}, @kbd{bc}, which see. This command is enabled in 3-file
+comparison sessions only.
+
+@item ##
+Tell Ediff to skip over regions that disagree among themselves only in the
+amount of white space and line breaks.
+
+Even though such regions will be skipped over, you can still jump to any
+one of them by typing the region number and then `j'. Typing @kbd{##}
+again puts Ediff back in the original state.
+
+@item #h
+@itemx #f
+Ediff works hard to ameliorate the effects of boredom in the workplace...
+
+Quite often differences are due to identical replacements (e.g., the word
+`foo' is replaced with the word `bar' everywhere). If the number of regions
+with such boring differences exceeds your tolerance threshold, you may be
+tempted to tell Ediff to skip these regions altogether (you will still be able
+to jump to them via the command @kbd{j}). The above commands, @kbd{#h}
+and @kbd{#f}, may well save your day!
+
+@kbd{#h} prompts you to specify regular expressions for each
+variant. Difference regions where each variant's region matches the
+corresponding regular expression will be skipped from then on. (You can
+also tell Ediff to skip regions where at least one variant matches its
+regular expression.)
+
+@kbd{#f} does dual job: it focuses on regions that match the corresponding
+regular expressions. All other regions will be skipped
+over. @xref{Selective Browsing}, for more.
+
+@item A
+Toggles the read-only property in buffer A.
+If file A is under version control and is checked in, it is checked out
+(with your permission).
+@item B
+Toggles the read-only property in buffer B.
+If file B is under version control and is checked in, it is checked out.
+@item C
+Toggles the read-only property in buffer C (in 3-file comparison sessions).
+If file C is under version control and is checked in, it is checked out.
+
+@item ~
+Swaps the windows where buffers A and B are displayed. If you are comparing
+three buffers at once, then this command would rotate the windows among
+buffers A, B, and C.
+
+@item i
+Displays all kinds of useful data about the current Ediff session.
+@item D
+Runs @code{ediff-custom-diff-program} on the variants and displays the
+buffer containing the output. This is useful when you must send the output
+to your Mom.
+
+With a prefix argument, displays the plain @file{diff} output.
+@xref{Patch and Diff Programs}, for details.
+
+@item R
+Displays a list of currently active Ediff sessions---the Ediff Registry.
+You can then restart any of these sessions by either clicking on a session
+record or by putting the cursor over it and then typing the return key.
+
+(Some poor souls leave so many active Ediff sessions around that they loose
+track of them completely... The `R' command is designed to save these
+people from the recently discovered Ediff Proficiency Syndrome.)
+
+Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff
+Control Panel. If you don't have a control panel handy, type this in the
+minibuffer: @kbd{M-x eregistry}. @xref{Registry of Ediff Sessions}.
+
+@item M
+Shows the session group buffer that invoked the current Ediff session.
+@xref{Session Groups}, for more information on session groups.
+
+@item z
+Suspends the current Ediff session. (If you develop a condition known as
+Repetitive Ediff Injury---a serious but curable illness---you must change
+your current activity. This command tries hard to hide all Ediff-related
+buffers.)
+
+The easiest way to resume a suspended Ediff session is through the registry
+of active sessions. @xref{Registry of Ediff Sessions}, for details.
+@item q
+Terminates this Ediff session. With a prefix argument (e.g.,@kbd{1q}), asks
+if you also want to delete the buffers of the variants.
+Modified files and the results of merges are never deleted.
+
+@item %
+Toggles narrowing in Ediff buffers. Ediff buffers may be narrowed if you
+are comparing only parts of these buffers via the commands
+@code{ediff-windows-*} and @code{ediff-regions-*}, which see.
+
+@item C-l
+Restores the usual Ediff window setup. This is the quickest way to resume
+an Ediff session, but it works only if the control panel of that session is
+visible.
+
+@item $
+While merging with an ancestor file, Ediff is determined to reduce user's
+wear and tear by saving him and her much of unproductive, repetitive
+typing. If it notices that, say, file A's difference region is identical to
+the same difference region in the ancestor file, then the merge buffer will
+automatically get the difference region taken from buffer B. The rationale
+is that this difference region in buffer A is as old as that in the
+ancestor buffer, so the contents of that region in buffer B represents real
+change.
+
+You may want to ignore such `obvious' merges and concentrate on difference
+regions where both files `clash' with the ancestor, since this means that
+two different people have been changing this region independently and they
+had different ideas on how to do this.
+
+The above command does this for you by skipping the regions where only one
+of the variants clashes with the ancestor but the other variant agrees with
+it. Typing @kbd{$} again undoes this setting.
+
+@item /
+Displays the ancestor file during merges.
+@item &
+In some situations, such as when one of the files agrees with the ancestor file
+on a difference region and the other doesn't, Ediff knows what to do: it copies
+the current difference region from the second buffer into the merge buffer.
+
+In other cases, the right course of action is not that clearcut, and Ediff
+would use a default action. The above command changes the default action.
+The default action can be @samp{default-A} (choose the region from buffer
+A), @samp{default-B} (choose the region from buffer B), or @samp{combined}
+(combine the regions from the two buffers).
+@xref{Merging and diff3}, for further details.
+
+The command @kbd{&} also affects the regions in the merge buffers that have
+@samp{default-A}, @samp{default-B}, or @samp{combined} status, provided
+they weren't changed with respect to the original. For instance, if such a
+region has the status @samp{default-A} then changing the default action to
+@samp{default-B} will also replace this merge-buffer's region with the
+corresponding region from buffer B.
+
+@item s
+Causes the merge window shrink to its minimum size, thereby exposing as much
+of the variant buffers as possible. Typing `s' again restores
+the original size of that window.
+
+With a positive prefix argument, this command enlarges the merge window.
+E.g., @kbd{4s} increases the size of the window by about 4 lines, if
+possible. With a negative numeric argument, the size of the merge window
+shrinks by that many lines, if possible. Thus, @kbd{-s} shrinks the window
+by about 1 line and @kbd{-3s} by about 3 lines.
+
+This command is intended only for temporary viewing; therefore, Ediff
+restores window C to its original size whenever it makes any other change
+in the window configuration. However, redisplaying (@kbd{C-l}) or jumping
+to another difference does not affect window C's size.
+
+The split between the merge window and the variant windows is controlled by
+the variable @code{ediff-merge-window-share}, which see.
+
+@item +
+Combines the difference regions from buffers A and B and copies the
+result into the merge buffer. @xref{Merging and diff3}, and the
+variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}.
+
+
+@item =
+You may run into situations when a large chunk of text in one file has been
+edited and then moved to a different place in another file. In such a case,
+these two chunks of text are unlikely to belong to the same difference
+region, so the refinement feature of Ediff will not be able to tell you
+what exactly differs inside these chunks. Since eyeballing large pieces of
+text is contrary to human nature, Ediff has a special command to help
+reduce the risk of developing a cataract.
+
+The above command compares regions within Ediff buffers. This creates a
+child Ediff session for comparing current Emacs regions in buffers A, B, or
+C as follows:
+
+@emph{If you are comparing 2 files or buffers:}
+Ediff would compare current Emacs regions in buffers A and B.
+
+@emph{If you are comparing 3 files or buffers simultaneously:} Ediff would
+compare the current Emacs regions in the buffers of your choice (you will
+be asked which two of the three buffers to use).
+
+@emph{If you are merging files or buffers (with or without ancestor):}
+Ediff would take the current region in the merge buffer and compare
+it to the current region in the buffer of your choice (A or B).
+
+Highlighting set by the parent Ediff session is removed, to avoid interference
+with highlighting of the child session. When done with the child session, type
+@kbd{C-l} in the parent's control panel to restore the original highlighting.
+
+If you temporarily switch to the parent session, parent highlighting will be
+restored. If you then come back to the child session, you may want to remove
+parent highlighting, so it won't interfere. Typing @kbd{h} may help here.
+
+@end table
+
+@node Other Session Commands,,Quick Help Commands,Session Commands
+@section Other Session Commands
+
+The following commands can be invoked from within any Ediff session,
+although some of them are not bound to a key.
+
+@table @code
+@item eregistry
+@itemx ediff-show-registry
+@findex eregistry
+@findex ediff-show-registry
+This command brings up the registry of active Ediff sessions. Ediff
+registry is a device that can be used to resume any active Ediff session
+(which may have been postponed because the user switched to some other
+activity). This command is also useful for switching between multiple
+active Ediff sessions that are run at the same time. The function
+@code{eregistry} is an alias for @code{ediff-show-registry}.
+@xref{Registry of Ediff Sessions}, for more information on this registry.
+
+@item ediff-toggle-multiframe
+@findex ediff-toggle-multiframe
+Changes the display from the multi-frame mode (where the quick help window
+is in a separate frame) to the single-frame mode (where all Ediff buffers
+share the same frame), and vice versa. See
+@code{ediff-window-setup-function} for details on how to make either of
+these modes the default one.
+
+This function can also be invoked from the Menubar. However, in some
+cases, the change will take place only after you execute one of the Ediff
+commands, such as going to the next difference or redisplaying.
+
+@item ediff-revert-buffers-then-recompute-diffs
+@findex ediff-revert-buffers-then-recompute-diffs
+This command reverts the buffers you are comparing and recomputes their
+differences. It is useful when, after making changes, you decided to
+make a fresh start, or if at some point you changed the files being
+compared but want to discard any changes to comparison buffers that were
+done since then.
+
+This command normally asks for confirmation before reverting files.
+With a prefix argument, it reverts files without asking.
+
+
+@item ediff-profile
+@findex ediff-profile
+Ediff has an admittedly primitive (but useful) facility for profiling
+Ediff's commands. It is meant for Ediff maintenance---specifically, for
+making it run faster. The function @code{ediff-profile} toggles
+profiling of ediff commands.
+@end table
+
+@node Registry of Ediff Sessions, Session Groups, Session Commands, Top
+@chapter Registry of Ediff Sessions
+
+Ediff maintains a registry of all its invocations that are
+still @emph{active}. This feature is very convenient for switching among
+active Ediff sessions or for quickly restarting a suspended Ediff session.
+
+The focal point of this activity is a buffer
+called @emph{*Ediff Registry*}. You can display this buffer by typing
+@kbd{R} in any Ediff Control Buffer or Session Group Buffer
+(@pxref{Session Groups}), or by typing
+@kbd{M-x eregistry} into the Minibuffer.
+The latter would be the fastest way to bring up the registry
+buffer if no control or group buffer is displayed in any of the visible
+Emacs windows.
+If you are in a habit of running multiple long Ediff sessions and often need to
+suspend, resume, or switch between them, it may be a good idea to have the
+registry buffer permanently displayed in a separate, dedicated window.
+
+The registry buffer has several convenient key bindings.
+For instance, clicking mouse button 2 or typing
+@kbd{RET} or @kbd{v} over any session record resumes that session.
+Session records in the registry buffer provide a fairly complete
+description of each session, so it is usually easy to identify the right
+session to resume.
+
+Other useful commands are bound to @kbd{SPC} (next registry record)
+and @kbd{DEL} (previous registry record). There are other commands as well,
+but you don't need to memorize them, since they are listed at the top of
+the registry buffer.
+
+@node Session Groups, Remote and Compressed Files, Registry of Ediff Sessions, Top
+@chapter Session Groups
+
+Several major entries of Ediff perform comparison and merging on
+directories. On entering @code{ediff-directories},
+@code{ediff-directories3},
+@code{ediff-merge-directories},
+@code{ediff-merge-directories-with-ancestor},
+@code{ediff-directory-revisions},
+@code{ediff-merge-directory-revisions}, or
+@code{ediff-merge-directory-revisions-with-ancestor},
+the user is presented with a
+Dired-like buffer that lists files common to the directories involved along
+with their sizes. (The list of common files can be further filtered through
+a regular expression, which the user is prompted for.) We call this buffer
+@emph{Session Group Panel} because all Ediff sessions associated with the
+listed files will have this buffer as a common focal point.
+
+Clicking button 2 or typing @kbd{RET} or @kbd{v} over a
+record describing files invokes Ediff in the appropriate mode on these
+files. You can come back to the session group buffer associated with a
+particular invocation of Ediff by typing @kbd{M} in Ediff control buffer of
+that invocation.
+
+Many commands are available in the session group buffer; some are
+applicable only to certain types of work. The relevant commands are always
+listed at the top of each session group buffer, so there is no need to
+memorize them.
+
+In directory comparison or merging, a session group panel displays only the
+files common to all directories involved. The differences are kept in a
+separate buffer and are conveniently displayed by typing @kbd{D} to the
+corresponding session group panel. Thus, as an added benefit, Ediff can be
+used to compare the contents of up to three directories.
+
+Session records in session group panels are also marked with @kbd{+}, for
+active sessions, and with @kbd{-}, for finished sessions.
+
+Sometimes, it is convenient to exclude certain sessions from a group.
+Usually this happens when the user doesn't intend to run Ediff of certain
+files in the group, and the corresponding session records just add clutter
+to the session group buffer. To help alleviate this problem, the user can
+type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to
+actually hide the marked sessions. There actions are reversible: with a
+prefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x}
+brings the hidden sessions into the view (@kbd{x} doesn't unmark them,
+though, so the user has to explicitly unmark the sessions of interest).
+
+Group sessions also understand the command @kbd{m}, which marks sessions
+for future operations (other than hiding) on a group of sessions. At present,
+the only such group-level operation is the creation of a multi-file patch.
+
+@vindex ediff-autostore-merges
+For group sessions created to merge files, Ediff can store all merges
+automatically in a directory. The user is asked to specify such directory
+if the value of @code{ediff-autostore-merges} is non-nil. If the value is
+@code{nil}, nothing is done to the merge buffers---it will be the user's
+responsibility to save them. If the value is @code{t}, the user will be
+asked where to save the merge buffers in all merge jobs, even those that do
+not originate from a session group. It the value is neither @code{nil} nor
+@code{t}, the merge buffer is saved @emph{only} if this merge session was
+invoked from a session group. This behavior is implemented in the function
+@code{ediff-maybe-save-and-delete-merge}, which is a hook in
+@code{ediff-quit-merge-hook}. The user can supply a different hook, if
+necessary.
+
+The variable @code{ediff-autostore-merges} is buffer-local, so it can be
+set in a per-buffer manner. Therefore, use @code{setq-default} to globally
+change this variable.
+
+@cindex Multi-file patches
+A multi-file patch is a concatenated output of several runs of the Unix
+@file{diff} command (some versions of @file{diff} let you create a
+multi-file patch in just one run). Ediff facilitates creation of
+multi-file patches as follows. If you are in a session group buffer
+created in response to @code{ediff-directories} or
+@code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) the
+desired Ediff sessions and then type @kbd{P} to create a
+multi-file patch of those marked sessions.
+Ediff will then display a buffer containing the patch.
+The patch is generated by invoking @file{diff} on all marked individual
+sessions (represented by files) and session groups (represented by
+directories). Ediff will also recursively descend into any @emph{unmarked}
+session group and will search for marked sessions there. In this way, you
+can create multi-file patches that span file subtrees that grow out of
+any given directory.
+
+In an @code{ediff-directories} session, it is enough to just mark the
+requisite sessions. In @code{ediff-directory-revisions} revisions, the
+marked sessions must also be active, or else Ediff will refuse to produce a
+multi-file patch. This is because, in the latter-style sessions, there are
+many ways to create diff output, and it is easier to handle by running
+Ediff on the inactive sessions.
+
+Last, but not least, by typing @kbd{=}, you can quickly find out which
+sessions have identical files, so you won't have to run Ediff on those
+sessions. This, however, works only on local, uncompressed files.
+For compressed or remote files, this command won't report anything.
+
+
+@node Remote and Compressed Files, Customization, Session Groups, Top
+@chapter Remote and Compressed Files
+
+Ediff works with remote, compressed, and encrypted files. Ediff
+supports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el}
+and @file{crypt++.el}, but it may work with other similar packages as
+well. This means that you can compare files residing on another
+machine, or you can apply a patch to a file on another machine. Even
+the patch itself can be a remote file!
+
+When patching compressed or remote files, Ediff does not rename the source
+file (unlike what the @code{patch} utility would usually do). Instead, the
+source file retains its name and the result of applying the patch is placed
+in a temporary file that has the suffix @file{_patched} attached.
+Generally, this applies to files that are handled using black magic, such
+as special file handlers (ange-ftp and some compression and encryption
+packages also use this method).
+
+Regular files are treated by the @code{patch} utility in the usual manner,
+i.e., the original is renamed into @file{source-name.orig} and the result
+of the patch is placed into the file source-name (@file{_orig} is used
+on systems like VMS, DOS, etc.)
+
+@node Customization, Credits, Remote and Compressed Files, Top
+@chapter Customization
+
+Ediff has a rather self-explanatory interface, and in most cases you
+won't need to change anything. However, should the need arise, there are
+extensive facilities for changing the default behavior.
+
+Most of the customization can be done by setting various variables in the
+@file{.emacs} file. Some customization (mostly window-related
+customization and faces) can be done by putting appropriate lines in
+@file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use.
+
+With respect to the latter, please note that the X resource
+for Ediff customization is `Ediff', @emph{not} `emacs'.
+@xref{Window and Frame Configuration},
+@xref{Highlighting Difference Regions}, for further details. Please also
+refer to Emacs manual for the information on how to set Emacs X resources.
+
+@menu
+* Hooks:: Customization via the hooks.
+* Quick Help Customization:: How to customize Ediff's quick help feature.
+* Window and Frame Configuration:: Controlling the way Ediff displays things.
+* Selective Browsing:: Advanced browsing through difference regions.
+* Highlighting Difference Regions:: Controlling highlighting.
+* Narrowing:: Comparing regions, windows, etc.
+* Refinement of Difference Regions:: How to control the refinement process.
+* Patch and Diff Programs:: Changing the utilities that compute differences
+ and apply patches.
+* Merging and diff3:: How to customize Ediff in its Merge Mode.
+* Support for Version Control:: Changing the version control package.
+ You are not likely to do that.
+* Customizing the Mode Line:: Changing the look of the mode line in Ediff.
+* Miscellaneous:: Other customization.
+* Notes on Heavy-duty Customization:: Customization for the gurus.
+@end menu
+
+@node Hooks, Quick Help Customization, Customization, Customization
+@section Hooks
+
+The bulk of customization can be done via the following hooks:
+
+@table @code
+@item ediff-load-hook
+@vindex ediff-load-hook
+This hook can be used to change defaults after Ediff is loaded.
+
+@item ediff-keymap-setup-hook
+@vindex ediff-keymap-setup-hook
+@vindex ediff-mode-map
+This hook can be used to alter bindings in Ediff's keymap,
+@code{ediff-mode-map}. These hooks are
+run right after the default bindings are set but before
+@code{ediff-load-hook}. The regular user needs not be concerned with this
+hook---it is provided for implementors of other Emacs packages built on top
+of Ediff.
+
+@item ediff-before-setup-windows-hook
+@itemx ediff-after-setup-windows-hook
+@vindex ediff-before-setup-windows-hook
+@vindex ediff-after-setup-windows-hook
+These two hooks are called before and after Ediff sets up its window
+configuration. Can be used to save the configuration that existed
+before Ediff starts or for whatever other purposes.
+
+@item ediff-suspend-hook
+@itemx ediff-quit-hook
+@vindex ediff-suspend-hook
+@vindex ediff-quit-hook
+These two hooks are run when you suspend or quit Ediff. They can be
+used to set desired window configurations, delete files Ediff didn't
+want to clean up after exiting, etc.
+
+By default, @code{ediff-quit-hook} holds one hook function,
+@code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate in
+most cases. You probably won't want to change it, but you might
+want to add other hook functions.
+
+Keep in mind that hooks executing before @code{ediff-cleanup-mess} start
+in @code{ediff-control-buffer;} they should also leave
+@code{ediff-control-buffer} as the current buffer when they finish.
+Hooks that are executed after @code{ediff-cleanup-mess} should expect
+the current buffer be either buffer A or buffer B.
+@code{ediff-cleanup-mess} doesn't kill the buffers being compared or
+merged (see @code{ediff-cleanup-hook}, below).
+
+@item ediff-cleanup-hook
+@vindex ediff-cleanup-hook
+This hook is run just before @code{ediff-quit-hook}. This is a good
+place to do various cleanups, such as deleting the variant buffers.
+Ediff provides a function, @code{ediff-janitor}, as one such possible
+hook, which you can add to @code{ediff-cleanup-hook} with
+@code{add-hooks}.
+
+@findex ediff-janitor
+This function kills buffers A, B, and, possibly, C, if these buffers aren't
+modified. In merge jobs, buffer C is never deleted. However, the side
+effect of using this function is that you may not be able to compare the
+same buffer in two separate Ediff sessions: quitting one of them will
+delete this buffer in another session as well.
+
+@item ediff-quit-merge-hook
+@vindex ediff-quit-merge-hook
+@vindex ediff-autostore-merges
+@findex ediff-maybe-save-and-delete-merge
+This hook is called when Ediff quits a merge job. By default, the value is
+@code{ediff-maybe-save-and-delete-merge}, which is a function that attempts
+to save the merge buffer according to the value of
+@code{ediff-autostore-merges}, as described later.
+
+@item ediff-before-setup-control-frame-hook
+@itemx ediff-after-setup-control-frame-hook
+@vindex ediff-before-setup-control-frame-hook
+@vindex ediff-after-setup-control-frame-hook
+These two hooks run before and after Ediff sets up the control frame.
+They can be used to relocate Ediff control frame when Ediff runs in a
+multiframe mode (i.e., when the control buffer is in its own dedicated
+frame). Be aware that many variables that drive Ediff are local to
+Ediff Control Panel (@code{ediff-control-buffer}), which requires
+special care in writing these hooks. Take a look at
+@code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to
+see what's involved.
+
+@item ediff-startup-hook
+@vindex ediff-startup-hook
+This hook is run at the end of Ediff startup.
+
+@item ediff-select-hook
+@vindex ediff-select-hook
+This hook is run after Ediff selects the next difference region.
+
+@item ediff-unselect-hook
+@vindex ediff-unselect-hook
+This hook is run after Ediff unselects the current difference region.
+
+@item ediff-prepare-buffer-hook
+@vindex ediff-prepare-buffer-hook
+This hook is run for each Ediff buffer (A, B, C) right after the buffer
+is arranged.
+
+@item ediff-display-help-hook
+@vindex ediff-display-help-hook
+Ediff runs this hook each time after setting up the help message. It
+can be used to alter the help message for custom packages that run on
+top of Ediff.
+
+@item ediff-mode-hook
+@vindex ediff-mode-hook
+This hook is run just after Ediff mode is set up in the control
+buffer. This is done before any Ediff window is created. You can use it to
+set local variables that alter the look of the display.
+
+@item ediff-registry-setup-hook
+@vindex ediff-registry-setup-hook
+Hooks run after setting up the registry for all active Ediff session.
+@xref{Session Groups}, for details.
+@item ediff-session-group-setup-hook
+@vindex ediff-session-group-setup-hook
+Hooks run after setting up a control panel for a group of related Ediff
+sessions. @xref{Session Groups}, for details.
+@item ediff-quit-session-group-hook
+@vindex ediff-quit-session-group-hook
+Hooks run just before exiting a session group.
+@item ediff-meta-buffer-keymap-setup-hook
+@vindex ediff-meta-buffer-keymap-setup-hook
+@vindex ediff-meta-buffer-map
+Hooks run just after setting up the @code{ediff-meta-buffer-map} --- the
+map that controls key bindings in the meta buffer. Since
+@code{ediff-meta-buffer-map} is a local variable, you can set different
+bindings for different kinds of meta buffers.
+@end table
+
+@node Quick Help Customization, Window and Frame Configuration, Hooks, Customization
+@section Quick Help Customization
+@vindex ediff-use-long-help-message
+@vindex ediff-control-buffer
+@vindex ediff-startup-hook
+@vindex ediff-help-message
+
+Ediff provides quick help using its control panel window. Since this window
+takes a fair share of the screen real estate, you can toggle it off by
+typing @kbd{?}. The control window will then shrink to just one line and a
+mode line, displaying a short help message.
+
+The variable @code{ediff-use-long-help-message} tells Ediff whether
+you use the short message or the long one. By default, it
+is set to @code{nil}, meaning that the short message is used.
+Set this to @code{t}, if you want Ediff to use the long
+message by default. This property can always be changed interactively, by
+typing @kbd{?} into Ediff Control Buffer.
+
+If you want to change the appearance of the help message on a per-buffer
+basis, you must use @code{ediff-startup-hook} to change the value of
+the variable @code{ediff-help-message}, which is local to
+@code{ediff-control-buffer}.
+
+@node Window and Frame Configuration, Selective Browsing, Quick Help Customization, Customization
+@section Window and Frame Configuration
+
+On a non-windowing display, Ediff sets things up in one frame, splitting
+it between a small control window and the windows for buffers A, B, and C.
+The split between these windows can be horizontal or
+vertical, which can be changed interactively by typing @kbd{|} while the
+cursor is in the control window.
+
+On a window display, Ediff sets up a dedicated frame for Ediff Control
+Panel and then it chooses windows as follows: If one of the buffers
+is invisible, it is displayed in the currently selected frame. If
+a buffer is visible, it is displayed in the frame where it is visible.
+If, according to the above criteria, the two buffers fall into the same
+frame, then so be it---the frame will be shared by the two. The same
+algorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p}
+(@code{ediff-previous-difference}), @kbd{n}
+(@code{ediff-next-difference}), etc.
+
+The above behavior also depends on whether the current frame is splittable,
+dedicated, etc. Unfortunately, the margin of this book is too narrow to
+present the details of this remarkable algorithm.
+
+The upshot of all this is that you can compare buffers in one frame or
+in different frames. The former is done by default, while the latter can
+be achieved by arranging buffers A, B (and C, if applicable) to be seen in
+different frames. Ediff respects these arrangements, automatically
+adapting itself to the multi-frame mode.
+
+Ediff uses the following variables to set up its control panel
+(a.k.a.@: control buffer, a.k.a.@: quick help window):
+
+@table @code
+@item ediff-control-frame-parameters
+@vindex ediff-control-frame-parameters
+You can change or augment this variable including the font, color,
+etc. The X resource name of Ediff Control Panel frames is @samp{Ediff}. Under
+X-windows, you can use this name to set up preferences in your
+@file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is in
+use. Usually this is preferable to changing
+@code{ediff-control-frame-parameters} directly. For instance, you can
+specify in @file{~/.Xdefaults} the color of the control frame
+using the resource @samp{Ediff*background}.
+
+In general, any X resource pertaining the control frame can be reached
+via the prefix @code{Ediff*}.
+
+@item ediff-control-frame-position-function
+@vindex ediff-control-frame-position-function
+The preferred way of specifying the position of the control frame is by
+setting the variable @code{ediff-control-frame-position-function} to an
+appropriate function.
+The default value of this variable is
+@code{ediff-make-frame-position}. This function places the control frame in
+the vicinity of the North-East corner of the frame displaying buffer A.
+
+@findex ediff-make-frame-position
+@end table
+
+The following variables can be used to adjust the location produced by
+@code{ediff-make-frame-position} and for related customization.
+
+@table @code
+@item ediff-narrow-control-frame-leftward-shift
+@vindex ediff-narrow-control-frame-leftward-shift
+Specifies the number of characters for shifting
+the control frame from the rightmost edge of frame A when the control
+frame is displayed as a small window.
+
+@item ediff-wide-control-frame-rightward-shift
+@vindex ediff-wide-control-frame-rightward-shift
+Specifies the rightward shift of the control frame
+from the left edge of frame A when the control frame shows the full
+menu of options.
+
+@item ediff-control-frame-upward-shift
+@vindex ediff-control-frame-upward-shift
+Specifies the number of pixels for the upward shift
+of the control frame.
+
+@item ediff-prefer-iconified-control-frame
+@vindex ediff-prefer-iconified-control-frame
+If this variable is @code{t}, the control frame becomes iconified
+automatically when you toggle the quick help message off. This saves
+valuable real estate on the screen. Toggling help back will deiconify
+the control frame.
+
+To start Ediff with an iconified Control Panel, you should set this
+variable to @code{t} and @code{ediff-prefer-long-help-message} to
+@code{nil} (@pxref{Quick Help Customization}). This behavior is useful
+only if the window manager is TWM or a derivative.
+@end table
+
+@findex ediff-setup-windows
+To make more creative changes in the way Ediff sets up windows, you can
+rewrite the function @code{ediff-setup-windows}. However, we believe
+that detaching Ediff Control Panel from the rest and making it into a
+separate frame offers an important opportunity by allowing you to
+iconify that frame. The icon will usually accept all of the Ediff
+commands, but will free up valuable real estate on your screen (this may
+depend on your window manager, though).
+
+The following variable controls how windows are set up:
+
+@table @code
+@item ediff-window-setup-function
+@vindex ediff-window-setup-function
+The multiframe setup is done by the
+@code{ediff-setup-windows-multiframe} function, which is the default on
+windowing displays. The plain setup, one where all windows are always
+in one frame, is done by @code{ediff-setup-windows-plain}, which is the
+default on a non-windowing display (or in an xterm window). In fact,
+under Emacs, you can switch freely between these two setups by executing
+the command @code{ediff-toggle-multiframe} using the Minibuffer of the
+Menubar.
+@findex ediff-setup-windows-multiframe
+@findex ediff-setup-windows-plain
+@findex ediff-toggle-multiframe
+
+If you don't like any of these setups, write your own function. See the
+documentation for @code{ediff-window-setup-function} for the basic
+guidelines. However, writing window setups is not easy, so you should
+first take a close look at @code{ediff-setup-windows-plain} and
+@code{ediff-setup-windows-multiframe}.
+@end table
+
+You can run multiple Ediff sessions at once, by invoking Ediff several
+times without exiting previous Ediff sessions. Different sessions
+may even operate on the same pair of files.
+
+Each session has its own Ediff Control Panel and all the regarding a
+particular session is local to the associated control panel buffer. You
+can switch between sessions by suspending one session and then switching
+to another control panel. (Different control panel buffers are
+distinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.)
+
+@node Selective Browsing, Highlighting Difference Regions, Window and Frame Configuration, Customization
+@section Selective Browsing
+
+Sometimes it is convenient to be able to step through only some difference
+regions, those that match certain regular expressions, and to ignore all
+others. On other occasions, you may want to ignore difference regions that
+match some regular expressions, and to look only at the rest.
+
+The commands @kbd{#f} and @kbd{#h} let you do precisely this.
+
+Typing @kbd{#f} lets you specify regular expressions that match difference
+regions you want to focus on.
+We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and
+@var{regexp-C}.
+Ediff will then start stepping through only those difference regions
+where the region in buffer A matches @var{regexp-A} and/or the region in
+buffer B matches @var{regexp-B}, etc. Whether `and' or `or' will be used
+depends on how you respond to a question.
+
+When scanning difference regions for the aforesaid regular expressions,
+Ediff narrows the buffers to those regions. This means that you can use
+the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end
+of the difference regions.
+
+On the other hand, typing @kbd{#h} lets you specify (hide) uninteresting
+regions. That is, if a difference region in buffer A matches
+@var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B}
+and (if applicable) buffer C's region matches @var{regexp-C}, then the
+region will be ignored by the commands @kbd{n}/@key{SPC}
+(@code{ediff-next-difference}) and @kbd{p}/@key{DEL}
+(@code{ediff-previous-difference}) commands.
+
+Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off.
+
+Note that selective browsing affects only @code{ediff-next-difference}
+and @code{ediff-previous-difference}, i.e., the commands
+@kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}. @kbd{#f} and @kbd{#h} do not
+change the position of the point in the buffers. And you can still jump
+directly (using @kbd{j}) to any numbered
+difference.
+
+Users can supply their own functions to specify how Ediff should do
+selective browsing. To change the default Ediff function, add a function to
+@code{ediff-load-hook} which will do the following assignments:
+
+@example
+(setq ediff-hide-regexp-matches-function 'your-hide-function)
+(setq ediff-focus-on-regexp-matches-function 'your-focus-function)
+@end example
+
+@strong{Useful hint}: To specify a regexp that matches everything, don't
+simply type @key{RET} in response to a prompt. Typing @key{RET} tells Ediff
+to accept the default value, which may not be what you want. Instead, you
+should enter something like @key{^} or @key{$}. These match every
+line.
+
+You can use the status command, @kbd{i}, to find out whether
+selective browsing is currently in effect.
+
+The regular expressions you specified are kept in the local variables
+@code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B},
+@code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A},
+@code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}. Their default value
+is the empty string (i.e., nothing is hidden or focused on). To change the
+default, set these variables in @file{.emacs} using @code{setq-default}.
+
+In addition to the ability to ignore regions that match regular
+expressions, Ediff can be ordered to start skipping over certain
+``uninteresting'' difference regions. This is controlled by the following
+variable:
+
+@table @code
+@item ediff-ignore-similar-regions
+@vindex ediff-ignore-similar-regions
+If @code{t}, causes Ediff to skip over "uninteresting" difference regions,
+which are the regions where the variants differ only in the amount of the
+white space and newlines. This feature can be toggled on/off interactively,
+via the command @kbd{##}.
+@end table
+
+@strong{Note:} In order for this feature to work, auto-refining of
+difference regions must be on, since otherwise Ediff won't know if there
+are fine differences between regions. On devices where Emacs can display
+faces, auto-refining is a default, but it is not turned on by default on
+text-only terminals. In that case, you must explicitly turn auto-refining
+on (such as, by typing @kbd{@@}).
+
+@strong{Reassurance:} If many such uninteresting regions appear in a row,
+Ediff may take a long time to skip over them because it has to compute fine
+differences of all intermediate regions. This delay does not indicate any
+problem.
+
+@node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization
+@section Highlighting Difference Regions
+
+The following variables control the way Ediff highlights difference
+regions:
+
+@table @code
+@item ediff-before-flag-bol
+@itemx ediff-after-flag-eol
+@itemx ediff-before-flag-mol
+@itemx ediff-after-flag-mol
+@vindex ediff-before-flag-bol
+@vindex ediff-after-flag-eol
+@vindex ediff-before-flag-mol
+@vindex ediff-after-flag-mol
+These variables hold strings that Ediff uses to mark the beginning and the
+end of the differences found in files A, B, and C on devices where Emacs
+cannot display faces. Ediff uses different flags to highlight regions that
+begin/end at the beginning/end of a line or in a middle of a line.
+
+@item ediff-current-diff-face-A
+@itemx ediff-current-diff-face-B
+@itemx ediff-current-diff-face-C
+@vindex ediff-current-diff-face-A
+@vindex ediff-current-diff-face-B
+@vindex ediff-current-diff-face-C
+Ediff uses these faces to highlight current differences on devices where
+Emacs can display faces. These and subsequently described faces can be set
+either in @file{.emacs} or in @file{.Xdefaults}. The X resource for Ediff
+is @samp{Ediff}, @emph{not} @samp{emacs}. Please refer to Emacs manual for
+the information on how to set X resources.
+@item ediff-fine-diff-face-A
+@itemx ediff-fine-diff-face-B
+@itemx ediff-fine-diff-face-C
+@vindex ediff-fine-diff-face-A
+@vindex ediff-fine-diff-face-B
+@vindex ediff-fine-diff-face-C
+Ediff uses these faces to show the fine differences between the current
+differences regions in buffers A, B, and C, respectively.
+
+@item ediff-even-diff-face-A
+@itemx ediff-even-diff-face-B
+@itemx ediff-even-diff-face-C
+@itemx ediff-odd-diff-face-A
+@itemx ediff-odd-diff-face-B
+@itemx ediff-odd-diff-face-C
+@vindex ediff-even-diff-face-A
+@vindex ediff-even-diff-face-B
+@vindex ediff-even-diff-face-C
+@vindex ediff-odd-diff-face-A
+@vindex ediff-odd-diff-face-B
+@vindex ediff-odd-diff-face-C
+Non-current difference regions are displayed using these alternating
+faces. The odd and the even faces are actually identical on monochrome
+displays, because without colors options are limited.
+So, Ediff uses italics to highlight non-current differences.
+
+@item ediff-force-faces
+@vindex ediff-force-faces
+Ediff generally can detect when Emacs is running on a device where it can
+use highlighting with faces. However, if it fails to determine that faces
+can be used, the user can set this variable to @code{t} to make sure that
+Ediff uses faces to highlight differences.
+
+@item ediff-highlight-all-diffs
+@vindex ediff-highlight-all-diffs
+Indicates whether---on a windowind display---Ediff should highlight
+differences using inserted strings (as on text-only terminals) or using
+colors and highlighting. Normally, Ediff highlights all differences, but
+the selected difference is highlighted more visibly. One can cycle through
+various modes of highlighting by typing @kbd{h}. By default, Ediff starts
+in the mode where all difference regions are highlighted. If you prefer to
+start in the mode where unselected differences are not highlighted, you
+should set @code{ediff-highlight-all-diffs} to @code{nil}. Type @kbd{h} to
+restore highlighting for all differences.
+
+Ediff lets you switch between the two modes of highlighting. That is,
+you can switch interactively from highlighting using faces to
+highlighting using string flags, and back. Of course, switching has
+effect only under a windowing system. On a text-only terminal or in an
+xterm window, the only available option is highlighting with strings.
+@end table
+
+@noindent
+If you want to change the default settings for @code{ediff-force-faces} and
+@code{ediff-highlight-all-diffs}, you must do it @strong{before} Ediff is
+loaded.
+
+You can also change the defaults for the faces used to highlight the
+difference regions. There are two ways to do this. The simplest and the
+preferred way is to use the customization widget accessible from the
+menubar. Ediff's customization group is located under "Tools", which in
+turn is under "Programming". The faces that are used to highlight
+difference regions are located in the "Highlighting" subgroup of the Ediff
+customization group.
+
+The second, much more arcane, method to change default faces is to include
+some Lisp code in @file{~/.emacs}. For instance,
+
+@example
+(setq ediff-current-diff-face-A
+ (copy-face 'bold-italic 'ediff-current-diff-face-A))
+@end example
+
+@noindent
+would use the pre-defined fase @code{bold-italic} to highlight the current
+difference region in buffer A (this face is not a good choice, by the way).
+
+If you are unhappy with just @emph{some} of the aspects of the default
+faces, you can modify them when Ediff is being loaded using
+@code{ediff-load-hook}. For instance:
+
+@smallexample
+(add-hook 'ediff-load-hook
+ (function (lambda ()
+ (set-face-foreground
+ ediff-current-diff-face-B "blue")
+ (set-face-background
+ ediff-current-diff-face-B "red")
+ (make-face-italic
+ ediff-current-diff-face-B))))
+@end smallexample
+
+@strong{Note:} it is not recommended to use @code{internal-get-face}
+when defining Ediff's faces, since this may cause problems when there
+are several frames with different font sizes. Instead, use
+@code{copy-face} or @code{set/make-face-@dots{}} as shown above.
+
+@node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization
+@section Narrowing
+
+If buffers being compared are narrowed at the time of invocation of
+Ediff, @code{ediff-buffers} will preserve the narrowing range. However,
+if @code{ediff-files} is invoked on the files visited by these buffers,
+that would widen the buffers, since this command is defined to compare the
+entire files.
+
+Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise}, or
+the corresponding @samp{-wordwise} commands, narrows the variants to the
+particular regions being compared. The original accessible ranges are
+restored when you quit Ediff. During the command, you can toggle this
+narrowing on and off with the @kbd{%} command.
+
+These two variables control this narrowing behavior:
+
+@table @code
+@item ediff-start-narrowed
+@vindex ediff-start-narrowed
+If @code{t}, Ediff narrows the display to the appropriate range when it
+is invoked with an @samp{ediff-regions@dots{}} or
+@samp{ediff-windows@dots{}} command. If @code{nil}, these commands do
+not automatically narrow, but you can still toggle narrowing on and off
+by typing @kbd{%}.
+
+@item ediff-quit-widened
+@vindex ediff-quit-widened
+Controls whether on quitting Ediff should restore the accessible range
+that existed before the current invocation.
+@end table
+
+@node Refinement of Difference Regions, Patch and Diff Programs, Narrowing, Customization
+@section Refinement of Difference Regions
+
+Ediff has variables to control the way fine differences are
+highlighted. This feature gives you control over the process of refinement.
+Note that refinement ignores spaces, tabs, and newlines.
+
+@table @code
+@item ediff-auto-refine
+@vindex ediff-auto-refine
+This variable controls whether fine differences within regions are
+highlighted automatically (``auto-refining''). The default is yes
+(@samp{on}).
+
+On a slow machine, automatic refinement may be painful. In that case,
+you can turn auto-refining on or off interactively by typing
+@kbd{@@}. You can also turn off display of refining that has
+already been done.
+
+When auto-refining is off, fine differences are shown only for regions
+for which these differences have been computed and saved before. If
+auto-refining and display of refining are both turned off, fine
+differences are not shown at all.
+
+Typing @kbd{*} computes and displays fine differences for the current
+difference region, regardless of whether auto-refining is turned on.
+
+@item ediff-auto-refine-limit
+@vindex ediff-auto-refine-limit
+If auto-refining is on, this variable limits the size of the regions to
+be auto-refined. This guards against the possible slowdown that may be
+caused by extraordinary large difference regions.
+
+You can always refine the current region by typing @kbd{*}.
+
+@item ediff-forward-word-function
+@vindex ediff-forward-word-function
+This variable controls how fine differences are computed. The
+value must be a Lisp function that determines how the current difference
+region should be split into words.
+
+@vindex ediff-diff-program
+@vindex ediff-forward-word-function
+@findex ediff-forward-word
+Fine differences are computed by first splitting the current difference
+region into words and then passing the result to
+@code{ediff-diff-program}. For the default forward word function (which is
+@code{ediff-forward-word}), a word is a string consisting of letters,
+@samp{-}, or @samp{_}; a string of punctuation symbols; a string of digits,
+or a string consisting of symbols that are neither space, nor a letter.
+
+This default behavior is controlled by four variables: @code{ediff-word-1},
+..., @code{ediff-word-4}. See the on-line documentation for these variables
+and for the function @code{ediff-forward-word} for an explanation of how to
+modify these variables.
+@vindex ediff-word-1
+@vindex ediff-word-2
+@vindex ediff-word-3
+@vindex ediff-word-4
+@end table
+
+Sometimes, when a region has too many differences between the variants,
+highlighting of fine differences is inconvenient, especially on
+color displays. If that is the case, type @kbd{*} with a negative
+prefix argument. This unhighlights fine differences for the current
+region.
+
+To unhighlight fine differences in all difference regions, use the
+command @kbd{@@}. Repeated typing of this key cycles through three
+different states: auto-refining, no-auto-refining, and no-highlighting
+of fine differences.
+
+@node Patch and Diff Programs, Merging and diff3, Refinement of Difference Regions, Customization
+@section Patch and Diff Programs
+
+This section describes variables that specify the programs to be used for
+applying patches and for computing the main difference regions (not the
+fine difference regions):
+
+@table @code
+@item ediff-diff-program
+@itemx ediff-diff3-program
+@vindex ediff-patch-program
+@vindex ediff-diff-program
+@vindex ediff-diff3-program
+These variables specify the programs to use to produce differences
+and do patching.
+
+@item ediff-diff-options
+@itemx ediff-diff3-options
+@vindex ediff-patch-options
+@vindex ediff-diff-options
+@vindex ediff-diff3-options
+These variables specify the options to pass to the above utilities.
+
+In @code{ediff-diff-options}, it may be useful to specify options
+such as @samp{-w} that ignore certain kinds of changes. However,
+Ediff does not let you use the option @samp{-c}, as it doesn't recognize this
+format yet.
+
+@item ediff-patch-program
+The program to use to apply patches. Since there are certain
+incompatibilities between the different versions of the patch program, the
+best way to stay out of trouble is to use a GNU-compatible version.
+Otherwise, you may have to tune the values of the variables
+@code{ediff-patch-options}, @code{ediff-backup-specs}, and
+@code{ediff-backup-extension} as described below.
+@item ediff-patch-options
+Options to pass to @code{ediff-patch-program}.
+
+Note: the `-b' and `-z' options should be specified in
+`ediff-backup-specs', not in @code{ediff-patch-options}.
+
+It is recommended to pass the `-f' option to the patch program, so it won't
+ask questions. However, some implementations don't accept this option, in
+which case the default value of this variable should be changed.
+
+@item ediff-backup-extension
+Backup extension used by the patch program. Must be specified, even if
+@code{ediff-backup-specs} is given.
+@item ediff-backup-specs
+Backup directives to pass to the patch program.
+Ediff requires that the old version of the file (before applying the patch)
+is saved in a file named @file{the-patch-file.extension}. Usually
+`extension' is `.orig', but this can be changed by the user, and may also be
+system-dependent. Therefore, Ediff needs to know the backup extension used
+by the patch program.
+
+Some versions of the patch program let the user specify `-b backup-extension'.
+Other versions only permit `-b', which (usually) assumes the extension `.orig'.
+Yet others force you to use `-z<backup-extension>'.
+
+Note that both `ediff-backup-extension' and `ediff-backup-specs' must be
+properly set. If your patch program takes the option `-b', but not
+`-b extension', the variable `ediff-backup-extension' must still
+be set so Ediff will know which extension to use.
+
+@item ediff-custom-diff-program
+@itemx ediff-custom-diff-options
+@vindex ediff-custom-diff-program
+@vindex ediff-custom-diff-options
+@findex ediff-save-buffer
+Because Ediff limits the options you may want to pass to the @code{diff}
+program, it partially makes up for this drawback by letting you save the
+output from @code{diff} in your preferred format, which is specified via
+the above two variables.
+
+The output generated by @code{ediff-custom-diff-program} (which doesn't
+even have to be a standard-style @file{diff}!)@: is not used by Ediff. It is
+provided exclusively so that you can
+refer to
+it later, send it over email, etc. For instance, after reviewing the
+differences, you may want to send context differences to a colleague.
+Since Ediff ignores the @samp{-c} option in
+@code{ediff-diff-program}, you would have to run @code{diff -c} separately
+just to produce the list of differences. Fortunately,
+@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}
+eliminate this nuisance by keeping a copy of a difference list in the
+desired format in a buffer that can be displayed via the command @kbd{D}.
+
+@item ediff-patch-default-directory
+@vindex ediff-patch-default-directory
+Specifies the default directory to look for patches.
+
+@end table
+
+@noindent
+@strong{Warning:} Ediff does not support the output format of VMS
+@code{diff}. Instead, make sure you are using some implementation of POSIX
+@code{diff}, such as @code{gnudiff}.
+
+@node Merging and diff3, Support for Version Control, Patch and Diff Programs, Customization
+@section Merging and diff3
+
+Ediff supports three-way comparison via the functions @code{ediff-files3} and
+@code{ediff-buffers3}. The interface is the same as for two-way comparison.
+In three-way comparison and merging, Ediff reports if any two difference
+regions are identical. For instance, if the current region in buffer A
+is the same as the region in buffer C, then the mode line of buffer A will
+display @samp{[=diff(C)]} and the mode line of buffer C will display
+@samp{[=diff(A)]}.
+
+Merging is done according to the following algorithm.
+
+If a difference region in one of the buffers, say B, differs from the ancestor
+file while the region in the other buffer, A, doesn't, then the merge buffer,
+C, gets B's region. Similarly when buffer A's region differs from
+the ancestor and B's doesn't, A's region is used.
+
+@vindex ediff-default-variant
+If both regions in buffers A and B differ from the ancestor file, Ediff
+chooses the region according to the value of the variable
+@code{ediff-default-variant}. If its value is @code{default-A} then A's
+region is chosen. If it is @code{default-B} then B's region is chosen.
+If it is @code{combined} then the region in buffer C will look like
+this:
+
+@example
+#ifdef NEW /* variant A */
+difference region from buffer A
+#else /* variant B */
+difference region from buffer B
+#endif /* NEW */
+@end example
+
+@vindex ediff-combination-pattern
+The actual strings that separate the regions copied from buffer A and B
+are controlled by the variable @code{ediff-combination-pattern}. Its
+value should be a list of three strings. The first is inserted before
+the difference region of buffer A; the second string goes between the
+regions; the third goes after region B, as shown in the above example.
+
+In addition to the state of the difference, Ediff displays the state of the
+merge for each region. If a difference came from buffer A by default
+(because both regions A and B were different from the ancestor and
+@code{ediff-default-variant} was set to @code{default-A}) then
+@samp{[=diff(A) default-A]} is displayed in the mode line. If the
+difference in buffer C came, say, from buffer B because the difference
+region in that buffer differs from the ancestor, but the region in buffer A
+does not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} is
+displayed. The indicators default-A/B and prefer-A/B are inspired by
+Emerge and have the same meaning.
+
+Another indicator of the state of merge is @samp{combined}. It appears
+with any difference region in buffer C that was obtained by combining
+the difference regions in buffers A and B as explained above.
+
+In addition to the state of merge and state of difference indicators, while
+merging with an ancestor file or buffer, Ediff informs the user when the
+current difference region in the (normally invisible) ancestor buffer is
+empty via the @emph{AncestorEmpty} indicator. This helps determine if the
+changes made to the original in variants A and B represent pure insertion
+or deletion of text: if the mode line shows @emph{AncestorEmpty} and the
+corresponding region in buffers A or B is not empty, this means that new
+text was inserted. If this indicator is not present and the difference
+regions in buffers A or B are non-empty, this means that text was
+modified. Otherwise, the original text was deleted.
+
+Although the ancestor buffer is normally invisible, Ediff maintains
+difference regions there and advances the current difference region
+accordingly. All highlighting of difference regions is provided in the
+ancestor buffer, except for the fine differences. Therefore, if desired, the
+user can put the ancestor buffer in a separate frame and watch it
+there. However, on a TTY, only one frame can be visible at any given time,
+and Ediff doesn't support any single-frame window configuration where all
+buffers, including the ancestor buffer, would be visible. However, the
+ancestor buffer can be displayed by typing @kbd{/} to the control
+window. (Type @kbd{C-l} to hide it again.)
+
+Note that the state-of-difference indicators @samp{=diff(A)} and
+@samp{=diff(B)} above are not redundant, even in the presence of a
+state-of-merge indicator. In fact, the two serve different purposes.
+
+For instance, if the mode line displays @samp{=diff(B) prefer(B)} and
+you copy a difference region from buffer A to buffer C then
+@samp{=diff(B)} will change to @samp{diff-A} and the mode line will
+display @samp{=diff(A) prefer-B}. This indicates that the difference
+region in buffer C is identical to that in buffer A, but originally
+buffer C's region came from buffer B. This is useful to know because
+you can recover the original difference region in buffer C by typing
+@kbd{r}.
+
+
+Ediff never changes the state-of-merge indicator, except in response to
+the @kbd{!} command (see below), in which case the indicator is lost.
+On the other hand, the state-of-difference indicator is changed
+automatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r},
+@kbd{+}.
+
+The @kbd{!} command loses the information about origins of the regions
+in the merge buffer (default-A, prefer-B, or combined). This is because
+recomputing differences in this case means running @code{diff3} on
+buffers A, B, and the merge buffer, not on the ancestor buffer. (It
+makes no sense to recompute differences using the ancestor file, since
+in the merging mode Ediff assumes that you have not edited buffers A and
+B, but that you may have edited buffer C, and these changes are to be
+preserved.) Since some difference regions may disappear as a result of
+editing buffer C and others may arise, there is generally no simple way
+to tell where the various regions in the merge buffer came from.
+
+In three-way comparison, Ediff tries to disregard regions that consist
+entirely of white space. For instance, if, say, the current region in
+buffer A consists of the white space only (or if it is empty), Ediff will
+not take it into account for the purpose of computing fine differences. The
+result is that Ediff can provide a better visual information regarding the
+actual fine differences in the non-white regions in buffers B and
+C. Moreover, if the regions in buffers B and C differ in the white space
+only, then a message to this effect will be displayed.
+
+@vindex ediff-merge-window-share
+In the merge mode, the share of the split between window C (the window
+displaying the merge-buffer) and the windows displaying buffers A and B
+is controlled by the variable @code{ediff-merge-window-share}. Its
+default value is 0.5. To make the merge-buffer window smaller, reduce
+this amount.
+
+We don't recommend increasing the size of the merge-window to more than
+half the frame (i.e., to increase the value of
+@code{ediff-merge-window-share}) to more than 0.5, since it would be
+hard to see the contents of buffers A and B.
+
+You can temporarily shrink the merge window to just one line by
+typing @kbd{s}. This change is temporary, until Ediff finds a reason to
+redraw the screen. Typing @kbd{s} again restores the original window size.
+
+With a positive prefix argument, the @kbd{s} command will make the merge
+window slightly taller. This change is persistent. With `@kbd{-}' or
+with a negative prefix argument, the command @kbd{s} makes the merge
+window slightly shorter. This change also persistent.
+
+@vindex ediff-show-clashes-only
+Ediff lets you automatically ignore the regions where only one of the
+buffers A and B disagrees with the ancestor. To do this, set the
+variable @code{ediff-show-clashes-only} to non-@code{nil}.
+
+You can toggle this feature interactively by typing @kbd{$}.
+
+Note that this variable affects only the show next/previous difference
+commands. You can still jump directly to any difference region directly
+using the command @kbd{j} (with a prefix argument specifying the difference
+number).
+
+@vindex ediff-autostore-merges
+@vindex ediff-quit-merge-hook
+@findex ediff-maybe-save-and-delete-merge
+The variable @code{ediff-autostore-merges} controls what happens to the
+merge buffer when Ediff quits. If the value is @code{nil}, nothing is done
+to the merge buffer---it will be the user's responsibility to save it.
+If the value is @code{t}, the user will be asked where to save the buffer
+and whether to delete it afterwards. It the value is neither @code{nil} nor
+@code{t}, the merge buffer is saved @emph{only} if this merge session was
+invoked from a group of related Ediff session, such as those that result
+from @code{ediff-merge-directories},
+@code{ediff-merge-directory-revisions}, etc.
+@xref{Session Groups}. This behavior is implemented in the function
+@code{ediff-maybe-save-and-delete-merge}, which is a hook in
+@code{ediff-quit-merge-hook}. The user can supply a different hook, if
+necessary.
+
+The variable @code{ediff-autostore-merges} is buffer-local, so it can be
+set in a per-buffer manner. Therefore, use @code{setq-default} to globally
+change this variable.
+
+@node Support for Version Control, Customizing the Mode Line, Merging and diff3, Customization
+@section Support for Version Control
+
+
+Ediff supports version control and lets you compare versions of files
+visited by Emacs buffers via the function @code{ediff-revision}. This
+feature is controlled by the following variables:
+
+@table @code
+@item ediff-version-control-package
+@vindex ediff-version-control-package
+A symbol. The default is @samp{vc}.
+
+If you are like most Emacs users, Ediff will use VC as the version control
+package. This is the standard Emacs interface to RCS, CVS, and SCCS.
+
+However, if your needs are better served by other interfaces, you will
+have to tell Ediff which version control package you are using, e.g.,
+@example
+(setq ediff-version-control-package 'rcs)
+@end example
+
+Apart from the standard @file{vc.el}, Ediff supports three other interfaces
+to version control:
+@file{rcs.el}, @file{pcl-cvs.el}, and @file{generic-sc.el}.
+The package @file{rcs.el} is written by Sebastian Kremer
+<sk@@thp.Uni-Koeln.DE> and is available as
+@example
+@file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z}
+@file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z}
+@end example
+@pindex @file{vc.el}
+@pindex @file{rcs.el}
+@pindex @file{pcl-cvs.el}
+@pindex @file{generic-sc.el}
+@end table
+
+Ediff's interface to the above packages allows the user to compare the
+versions of the current buffer or to merge them (with or without an
+ancestor-version). These operations can also be performed on directories
+containing files under version control.
+
+In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function
+@code{run-ediff-from-cvs-buffer}---see the documentation string for this
+function.
+
+@node Customizing the Mode Line, Miscellaneous, Support for Version Control, Customization
+@section Customizing the Mode Line
+
+When Ediff is running, the mode line of @samp{Ediff Control Panel}
+buffer shows the current difference number and the total number of
+difference regions in the two files.
+
+The mode line of the buffers being compared displays the type of the
+buffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name.
+Ediff tries to be intelligent in choosing the mode line buffer
+identification. In particular, it works well with the
+@file{uniquify.el} and @file{mode-line.el} packages (which improve on
+the default way in which Emacs displays buffer identification). If you
+don't like the way Ediff changes the mode line, you can use
+@code{ediff-prepare-buffer-hook} to modify the mode line.
+@vindex ediff-prepare-buffer-hook
+@pindex @file{uniquify.el}
+@pindex @file{mode-line.el}
+
+@node Miscellaneous, Notes on Heavy-duty Customization, Customizing the Mode Line, Customization
+@section Miscellaneous
+
+Here are a few other variables for customizing Ediff:
+
+@table @code
+@item ediff-split-window-function
+@vindex ediff-split-window-function
+Controls the way you want the window be split between file-A and file-B
+(and file-C, if applicable). It defaults to the vertical split
+(@code{split-window-vertically}, but you can set it to
+@code{split-window-horizontally}, if you so wish.
+Ediff also lets you switch from vertical to horizontal split and back
+interactively.
+
+Note that if Ediff detects that all the buffers it compares are displayed in
+separate frames, it assumes that the user wants them to be so displayed
+and stops splitting windows. Instead, it arranges for each buffer to
+be displayed in a separate frame. You can switch to the one-frame mode
+by hiding one of the buffers A/B/C.
+
+You can also swap the windows where buffers are displayed by typing
+@kbd{~}.
+
+@item ediff-merge-split-window-function
+@vindex ediff-merge-split-window-function
+Controls how windows are
+split between buffers A and B in the merge mode.
+This variable is like @code{ediff-split-window-function}, but it defaults
+to @code{split-window-horizontally} instead of
+@code{split-window-vertically}.
+
+@item ediff-make-wide-display-function
+@vindex ediff-make-wide-display-function
+The value is a function to be called to widen the frame for displaying
+the Ediff buffers. See the on-line documentation for
+@code{ediff-make-wide-display-function} for details. It is also
+recommended to look into the source of the default function
+@code{ediff-make-wide-display}.
+
+You can toggle wide/regular display by typing @kbd{m}. In the wide
+display mode, buffers A, B (and C, when applicable) are displayed in a
+single frame that is as wide as the entire workstation screen. This is
+useful when files are compared side-by-side. By default, the display is
+widened without changing its height.
+
+@item ediff-use-last-dir
+@vindex ediff-use-last-dir
+Controls the way Ediff presents the
+default directory when it prompts the user for files to compare. If
+@code{nil},
+Ediff uses the default directory of the current buffer when it
+prompts the user for file names. Otherwise, it will use the
+directories it had previously used for files A, B, or C, respectively.
+
+@item ediff-no-emacs-help-in-control-buffer
+@vindex ediff-no-emacs-help-in-control-buffer
+If @code{t}, makes @kbd{C-h}
+behave like the @key{DEL} key, i.e., it will move you back to the previous
+difference rather than invoking help. This is useful when, in an xterm
+window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is
+positioned more conveniently than the @key{DEL} key.
+
+@item ediff-toggle-read-only-function
+@vindex ediff-toggle-read-only-function
+This variable's value is a function that Ediff uses to toggle
+the read-only property in its buffers.
+
+The default function that Ediff uses simply toggles the read-only property,
+unless the file is under version control. For a checked-in file under
+version control, Ediff first tries to check the file out.
+
+@item ediff-make-buffers-readonly-at-startup nil
+@vindex ediff-make-buffers-readonly-at-startup
+If t, all variant buffers are made read-only at Ediff startup.
+
+@item ediff-keep-variants
+@vindex @code{ediff-keep-variants}
+The default is @code{t}, meaning that the buffers being compared or merged will
+be preserved when Ediff quits. Setting this to @code{nil} causes Ediff to
+offer the user a chance to delete these buffers (if they are not modified).
+Supplying a prefix argument to the quit command (@code{q}) temporarily
+reverses the meaning of this variable. This is convenient when the user
+prefers one of the behaviors most of the time, but occasionally needs the
+other behavior.
+
+However, Ediff temporarily resets this variable to @code{t} if it is
+invoked via one of the "buffer" jobs, such as @code{ediff-buffers}.
+This is because it is all too easy to loose day's work otherwise.
+Besides, in a "buffer" job, the variant buffers have already been loaded
+prior to starting Ediff, so Ediff just preserves status quo here.
+
+Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants
+unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks).
+@item ediff-grab-mouse
+@vindex @code{ediff-grab-mouse}
+Default is @code{t}. Normally, Ediff grabs mouse and puts it in its
+control frame. This is useful since the user can be sure that when he
+needs to type an Ediff command the focus will be in an appropriate Ediff's
+frame. However, some users prefer to move the mouse by themselves. The
+above variable, if set to @code{maybe}, will prevent Ediff from grabbing
+the mouse in many situations, usually after commands that may take more
+time than usual. In other situation, Ediff will continue grabbing the mouse
+and putting it where it believes is appropriate. If the value is
+@code{nil}, then mouse is entirely user's responsibility.
+Try different settings and see which one is for you.
+@end table
+
+
+@node Notes on Heavy-duty Customization, , Miscellaneous, Customization
+@section Notes on Heavy-duty Customization
+
+Some users need to customize Ediff in rather sophisticated ways, which
+requires different defaults for different kinds of files (e.g., SGML,
+etc.). Ediff supports this kind of customization in several ways. First,
+most customization variables are buffer-local. Those that aren't are
+usually accessible from within Ediff Control Panel, so one can make them
+local to the panel by calling make-local-variable from within
+@code{ediff-startup-hook}.
+
+Second, the function @code{ediff-setup} accepts an optional sixth
+argument which has the form @code{((@var{var-name-1} .@: @var{val-1})
+(@var{var-name-2} .@: @var{val-2}) @dots{})}. The function
+@code{ediff-setup} sets the variables in the list to the respective
+values, locally in the Ediff control buffer. This is an easy way to
+throw in custom variables (which usually should be buffer-local) that
+can then be tested in various hooks.
+
+Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are set
+properly in this case, as some things in Ediff depend on this.
+
+Finally, if you want custom-tailored help messages, you can set the
+variables @code{ediff-brief-help-message-function} and
+@code{ediff-long-help-message-function}
+to functions that return help strings.
+@vindex ediff-startup-hook
+@findex ediff-setup
+@vindex ediff-job-name
+@vindex ediff-word-mode
+@vindex ediff-brief-help-message-function
+@vindex ediff-long-help-message-function
+
+When customizing Ediff, some other variables are useful, although they are
+not user-definable. They are local to the Ediff control buffer, so this
+buffer must be current when you access these variables. The control buffer
+is accessible via the variable @code{ediff-control-buffer}, which is also
+local to that buffer. It is usually used for checking if the current buffer
+is also the control buffer.
+
+Other variables of interest are:
+@table @code
+@item ediff-buffer-A
+The first of the data buffers being compared.
+
+@item ediff-buffer-B
+The second of the data buffers being compared.
+
+@item ediff-buffer-C
+In three-way comparisons, this is the third buffer being compared.
+In merging, this is the merge buffer.
+In two-way comparison, this variable is nil.
+
+@item ediff-window-A
+The window displaying buffer A. If buffer A is not visible, this variable
+is nil or it may be a dead window.
+
+@item ediff-window-B
+The window displaying buffer B.
+
+@item ediff-window-C
+The window displaying buffer C, if any.
+
+@item ediff-control-frame
+A dedicated frame displaying the control buffer, if it exists.
+It is non-nil only if Ediff uses the multiframe display, i.e., when the
+control buffer is in its own frame.
+@end table
+
+@node Credits, Index, Customization, Top
+@chapter Credits
+
+Ediff was written by Michael Kifer <kifer@@cs.sunysb.edu>. It was inspired
+by emerge.el written by Dale R.@: Worley <drw@@math.mit.edu>. An idea due to
+Boris Goldowsky <boris@@cs.rochester.edu> made it possible to highlight
+fine differences in Ediff buffers. Alastair Burt <burt@@dfki.uni-kl.de>
+ported Ediff to XEmacs, Eric Freudenthal <freudent@@jan.ultra.nyu.edu>
+made it work with VC, Marc Paquette <marcpa@@cam.org> wrote the
+toolbar support package for Ediff, and Hrvoje Niksic <hniksic@@srce.hr>
+adapted it to the Emacs customization package.
+
+Many people provided help with bug reports, patches, and advice.
+Without them, Ediff would not be nearly as useful as it is today.
+Here is a full list of contributors (I hope I didn't miss anyone):
+
+@example
+Steve Baur (steve@@xemacs.org),
+Neal Becker (neal@@ctd.comsat.com),
+E.@: Jay Berkenbilt (ejb@@ql.org),
+Alastair Burt (burt@@dfki.uni-kl.de),
+Paul Bibilo (peb@@delcam.co.uk),
+Kevin Broadey (KevinB@@bartley.demon.co.uk),
+Harald Boegeholz (hwb@@machnix.mathematik.uni-stuttgart.de),
+Bradley A.@: Bosch (brad@@lachman.com),
+Michael D.@: Carney (carney@@ltx-tr.com),
+Jin S.@: Choi (jin@@atype.com),
+Scott Cummings (cummings@@adc.com),
+Albert Dvornik (bert@@mit.edu),
+Eric Eide (eeide@@asylum.cs.utah.edu),
+Paul Eggert (eggert@@twinsun.com),
+Kevin Esler (esler@@ch.hp.com),
+Robert Estes (estes@@ece.ucdavis.edu),
+Jay Finger (jayf@@microsoft.com),
+Xavier Fornari (xavier@@europe.cma.fr),
+Eric Freudenthal (freudent@@jan.ultra.nyu.edu),
+Job Ganzevoort (Job.Ganzevoort@@cwi.nl),
+Boris Goldowsky (boris@@cs.rochester.edu),
+Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu),
+Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de),
+Xiaoli Huang (hxl@@epic.com),
+Lars Magne Ingebrigtsen (larsi@@ifi.uio.no),
+Larry Gouge (larry@@itginc.com),
+Karl Heuer (kwzh@@gnu.org),
+(irvine@@lks.csi.com),
+(jaffe@@chipmunk.cita.utoronto.ca),
+David Karr (dkarr@@nmo.gtegsc.com),
+Norbert Kiesel (norbert@@i3.informatik.rwth-aachen.de),
+Leigh L Klotz (klotz@@adoc.xerox.com),
+Fritz Knabe (Fritz.Knabe@@ecrc.de),
+Heinz Knutzen (hk@@informatik.uni-kiel.d400.de),
+Andrew Koenig (ark@@research.att.com),
+Ken Laprade (laprade@@dw3f.ess.harris.com),
+Will C Lauer (wcl@@cadre.com),
+Richard Levitte (levitte@@e.kth.se),
+Mike Long (mike.long@@analog.com),
+Martin Maechler (maechler@@stat.math.ethz.ch),
+Simon Marshall (simon@@gnu.org),
+Richard Mlynarik (mly@@adoc.xerox.com),
+Chris Murphy (murphycm@@sun.aston.ac.uk),
+Erik Naggum (erik@@naggum.no),
+Eyvind Ness (Eyvind.Ness@@hrp.no),
+Ray Nickson (nickson@@cs.uq.oz.au),
+David Petchey (petchey_david@@jpmorgan.com),
+Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk),
+Tibor Polgar (tlp00@@spg.amdahl.com),
+David Prince (dave0d@@fegs.co.uk),
+Paul Raines (raines@@slac.stanford.edu),
+Bill Richter (richter@@math.nwu.edu),
+C.S.@: Roberson (roberson@@aur.alcatel.com),
+Kevin Rodgers (kevin.rodgers@@ihs.com),
+Sandy Rutherford (sandy@@ibm550.sissa.it),
+Heribert Schuetz (schuetz@@ecrc.de),
+Andy Scott (ascott@@pcocd2.intel.com),
+Axel Seibert (axel@@tumbolia.ppp.informatik.uni-muenchen.de),
+Scott O.@: Sherman (Scott.Sherman@@mci.com),
+Richard Stallman (rms@@gnu.org),
+Richard Stanton (stanton@@haas.berkeley.edu),
+Ake Stenhoff (etxaksf@@aom.ericsson.se),
+Stig (stig@@hackvan.com),
+Peter Stout (Peter_Stout@@cs.cmu.edu),
+Chuck Thompson (cthomp@@cs.uiuc.edu),
+Ray Tomlinson (tomlinso@@bbn.com),
+Raymond Toy (toy@@rtp.ericsson.se),
+Jan Vroonhof (vroonhof@@math.ethz.ch),
+Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be),
+Klaus Weber (gizmo@@zork.north.de),
+Ben Wing (wing@@666.com),
+Ilya Zakharevich (ilya@@math.ohio-state.edu),
+Eli Zaretskii (eliz@@is.elta.co.il)
+@end example
+
+@node Index, , Credits, Top
+@unnumbered Index
+@printindex cp
+
+@contents
+@bye
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Entering Emacs, Exiting, Text Characters, Top
+@chapter Entering and Exiting Emacs
+@cindex entering Emacs
+@cindex starting Emacs
+
+ The usual way to invoke Emacs is with the shell command @samp{emacs}.
+Emacs clears the screen and then displays an initial help message and
+copyright notice. Some operating systems discard all type-ahead when
+Emacs starts up; they give Emacs no way to prevent this. Therefore, it
+is advisable to wait until Emacs clears the screen before typing your
+first editing command.
+
+ If you run Emacs from a shell window under the X Window System, run it
+in the background with @samp{emacs&}. This way, Emacs does not tie up
+the shell window, so you can use that to run other shell commands while
+Emacs operates its own X windows. You can begin typing Emacs commands
+as soon as you direct your keyboard input to the Emacs frame.
+
+@vindex initial-major-mode
+ When Emacs starts up, it makes a buffer named @samp{*scratch*}.
+That's the buffer you start out in. The @samp{*scratch*} buffer uses Lisp
+Interaction mode; you can use it to type Lisp expressions and evaluate
+them, or you can ignore that capability and simply doodle. (You can
+specify a different major mode for this buffer by setting the variable
+@code{initial-major-mode} in your init file. @xref{Init File}.)
+
+ It is possible to specify files to be visited, Lisp files to be
+loaded, and functions to be called, by giving Emacs arguments in the
+shell command line. @xref{Command Arguments}. But we don't recommend
+doing this. The feature exists mainly for compatibility with other
+editors.
+
+ Many other editors are designed to be started afresh each time you
+want to edit. You edit one file and then exit the editor. The next
+time you want to edit either another file or the same one, you must run
+the editor again. With these editors, it makes sense to use a
+command-line argument to say which file to edit.
+
+ But starting a new Emacs each time you want to edit a different file
+does not make sense. For one thing, this would be annoyingly slow. For
+another, this would fail to take advantage of Emacs's ability to visit
+more than one file in a single editing session. And it would lose the
+other accumulated context, such as registers, undo history, and the mark
+ring.
+
+ The recommended way to use GNU Emacs is to start it only once, just
+after you log in, and do all your editing in the same Emacs session.
+Each time you want to edit a different file, you visit it with the
+existing Emacs, which eventually comes to have many files in it ready
+for editing. Usually you do not kill the Emacs until you are about to
+log out. @xref{Files}, for more information on visiting more than one
+file.
+
+@node Exiting, Basic, Entering Emacs, Top
+@section Exiting Emacs
+@cindex exiting
+@cindex killing Emacs
+@cindex suspending
+@cindex leaving Emacs
+@cindex quitting Emacs
+
+ There are two commands for exiting Emacs because there are two kinds
+of exiting: @dfn{suspending} Emacs and @dfn{killing} Emacs.
+
+ @dfn{Suspending} means stopping Emacs temporarily and returning
+control to its parent process (usually a shell), allowing you to resume
+editing later in the same Emacs job, with the same buffers, same kill
+ring, same undo history, and so on. This is the usual way to exit.
+
+ @dfn{Killing} Emacs means destroying the Emacs job. You can run Emacs
+again later, but you will get a fresh Emacs; there is no way to resume
+the same editing session after it has been killed.
+
+@table @kbd
+@item C-z
+Suspend Emacs (@code{suspend-emacs}) or iconify a frame
+(@code{iconify-or-deiconify-frame}).
+@item C-x C-c
+Kill Emacs (@code{save-buffers-kill-emacs}).
+@end table
+
+@kindex C-z
+@findex suspend-emacs
+ To suspend Emacs, type @kbd{C-z} (@code{suspend-emacs}). This takes
+you back to the shell from which you invoked Emacs. You can resume
+Emacs with the shell command @samp{%emacs} in most common shells.
+
+ On systems that do not support suspending programs, @kbd{C-z} starts
+an inferior shell that communicates directly with the terminal.
+Emacs waits until you exit the subshell. (The way to do that is
+probably with @kbd{C-d} or @samp{exit}, but it depends on which shell
+you use.) The only way on these systems to get back to the shell from
+which Emacs was run (to log out, for example) is to kill Emacs.
+
+ Suspending also fails if you run Emacs under a shell that doesn't
+support suspending programs, even if the system itself does support it.
+In such a case, you can set the variable @code{cannot-suspend} to a
+non-@code{nil} value to force @kbd{C-z} to start an inferior shell.
+(One might also describe Emacs's parent shell as ``inferior'' for
+failing to support job control properly, but that is a matter of taste.)
+
+ When Emacs communicates directly with an X server and creates its own
+dedicated X windows, @kbd{C-z} has a different meaning. Suspending an
+applications that uses its own X windows is not meaningful or useful.
+Instead, @kbd{C-z} runs the command @code{iconify-or-deiconify-frame},
+which temporarily closes up the selected Emacs frame (@pxref{Frames}).
+The way to get back to a shell window is with the window manager.
+
+@kindex C-x C-c
+@findex save-buffers-kill-emacs
+ To kill Emacs, type @kbd{C-x C-c} (@code{save-buffers-kill-emacs}). A
+two-character key is used for this to make it harder to type. This
+command first offers to save any modified file-visiting buffers. If you
+do not save them all, it asks for reconfirmation with @kbd{yes} before
+killing Emacs, since any changes not saved will be lost forever. Also,
+if any subprocesses are still running, @kbd{C-x C-c} asks for
+confirmation about them, since killing Emacs will kill the subprocesses
+immediately.
+
+ There is no way to restart an Emacs session once you have killed it.
+You can, however, arrange for Emacs to record certain session
+information, such as which files are visited, when you kill it, so that
+the next time you restart Emacs it will try to visit the same files and
+so on. @xref{Saving Emacs Sessions}.
+
+ The operating system usually listens for certain special characters
+whose meaning is to kill or suspend the program you are running.
+@b{This operating system feature is turned off while you are in Emacs.}
+The meanings of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were
+inspired by the use of @kbd{C-z} and @kbd{C-c} on several operating
+systems as the characters for stopping or killing a program, but that is
+their only relationship with the operating system. You can customize
+these keys to run any commands of your choice (@pxref{Keymaps}).
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Files, Buffers, Fixit, Top
+@chapter File Handling
+@cindex files
+
+ The operating system stores data permanently in named @dfn{files}. So
+most of the text you edit with Emacs comes from a file and is ultimately
+stored in a file.
+
+ To edit a file, you must tell Emacs to read the file and prepare a
+buffer containing a copy of the file's text. This is called
+@dfn{visiting} the file. Editing commands apply directly to text in the
+buffer; that is, to the copy inside Emacs. Your changes appear in the
+file itself only when you @dfn{save} the buffer back into the file.
+
+ In addition to visiting and saving files, Emacs can delete, copy,
+rename, and append to files, keep multiple versions of them, and operate
+on file directories.
+
+@menu
+* File Names:: How to type and edit file-name arguments.
+* Visiting:: Visiting a file prepares Emacs to edit the file.
+* Saving:: Saving makes your changes permanent.
+* Reverting:: Reverting cancels all the changes not saved.
+* Auto Save:: Auto Save periodically protects against loss of data.
+* File Aliases:: Handling multiple names for one file.
+* Version Control:: Version control systems (RCS, CVS and SCCS).
+* Directories:: Creating, deleting, and listing file directories.
+* Comparing Files:: Finding where two files differ.
+* Misc File Ops:: Other things you can do on files.
+* Compressed Files:: Accessing compressed files.
+* Remote Files:: Accessing files on other sites.
+* Quoted File Names:: Quoting special characters in file names.
+@end menu
+
+@node File Names
+@section File Names
+@cindex file names
+
+ Most Emacs commands that operate on a file require you to specify the
+file name. (Saving and reverting are exceptions; the buffer knows which
+file name to use for them.) You enter the file name using the
+minibuffer (@pxref{Minibuffer}). @dfn{Completion} is available, to make
+it easier to specify long file names. @xref{Completion}.
+
+ For most operations, there is a @dfn{default file name} which is used
+if you type just @key{RET} to enter an empty argument. Normally the
+default file name is the name of the file visited in the current buffer;
+this makes it easy to operate on that file with any of the Emacs file
+commands.
+
+@vindex default-directory
+ Each buffer has a default directory, normally the same as the
+directory of the file visited in that buffer. When you enter a file
+name without a directory, the default directory is used. If you specify
+a directory in a relative fashion, with a name that does not start with
+a slash, it is interpreted with respect to the default directory. The
+default directory is kept in the variable @code{default-directory},
+which has a separate value in every buffer.
+
+ For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then
+the default directory is @file{/u/rms/gnu/}. If you type just @samp{foo},
+which does not specify a directory, it is short for @file{/u/rms/gnu/foo}.
+@samp{../.login} would stand for @file{/u/rms/.login}. @samp{new/foo}
+would stand for the file name @file{/u/rms/gnu/new/foo}.
+
+@findex cd
+@findex pwd
+ The command @kbd{M-x pwd} prints the current buffer's default
+directory, and the command @kbd{M-x cd} sets it (to a value read using
+the minibuffer). A buffer's default directory changes only when the
+@code{cd} command is used. A file-visiting buffer's default directory
+is initialized to the directory of the file that is visited there. If
+you create a buffer with @kbd{C-x b}, its default directory is copied
+from that of the buffer that was current at the time.
+
+@vindex insert-default-directory
+ The default directory actually appears in the minibuffer when the
+minibuffer becomes active to read a file name. This serves two
+purposes: it @emph{shows} you what the default is, so that you can type
+a relative file name and know with certainty what it will mean, and it
+allows you to @emph{edit} the default to specify a different directory.
+This insertion of the default directory is inhibited if the variable
+@code{insert-default-directory} is set to @code{nil}.
+
+ Note that it is legitimate to type an absolute file name after you
+enter the minibuffer, ignoring the presence of the default directory
+name as part of the text. The final minibuffer contents may look
+invalid, but that is not so. For example, if the minibuffer starts out
+with @samp{/usr/tmp/} and you add @samp{/x1/rms/foo}, you get
+@samp{/usr/tmp//x1/rms/foo}; but Emacs ignores everything through the
+first slash in the double slash; the result is @samp{/x1/rms/foo}.
+@xref{Minibuffer File}.
+
+ @samp{$} in a file name is used to substitute environment variables.
+For example, if you have used the shell command @samp{export
+FOO=rms/hacks} to set up an environment variable named @code{FOO}, then
+you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an
+abbreviation for @file{/u/rms/hacks/test.c}. The environment variable
+name consists of all the alphanumeric characters after the @samp{$};
+alternatively, it may be enclosed in braces after the @samp{$}. Note
+that shell commands to set environment variables affect Emacs only if
+done before Emacs is started.
+
+ To access a file with @samp{$} in its name, type @samp{$$}. This pair
+is converted to a single @samp{$} at the same time as variable
+substitution is performed for single @samp{$}. Alternatively, quote the
+whole file name with @samp{/:} (@pxref{Quoted File Names}).
+
+@findex substitute-in-file-name
+ The Lisp function that performs the substitution is called
+@code{substitute-in-file-name}. The substitution is performed only on
+file names read as such using the minibuffer.
+
+ You can include non-ASCII characters in file names if you set the
+variable @code{file-name-coding-system} to a non-@code{nil} value.
+@xref{Specify Coding}.
+
+@node Visiting
+@section Visiting Files
+@cindex visiting files
+
+@c WideCommands
+@table @kbd
+@item C-x C-f
+Visit a file (@code{find-file}).
+@item C-x C-r
+Visit a file for viewing, without allowing changes to it
+(@code{find-file-read-only}).
+@item C-x C-v
+Visit a different file instead of the one visited last
+(@code{find-alternate-file}).
+@item C-x 4 f
+Visit a file, in another window (@code{find-file-other-window}). Don't
+alter what is displayed in the selected window.
+@item C-x 5 f
+Visit a file, in a new frame (@code{find-file-other-frame}). Don't
+alter what is displayed in the selected frame.
+@item M-x find-file-literally
+Visit a file with no conversion of the contents.
+@end table
+
+@cindex files, visiting and saving
+@cindex visiting files
+@cindex saving files
+ @dfn{Visiting} a file means copying its contents into an Emacs buffer
+so you can edit them. Emacs makes a new buffer for each file that you
+visit. We say that this buffer is visiting the file that it was created
+to hold. Emacs constructs the buffer name from the file name by
+throwing away the directory, keeping just the name proper. For example,
+a file named @file{/usr/rms/emacs.tex} would get a buffer named
+@samp{emacs.tex}. If there is already a buffer with that name, a unique
+name is constructed by appending @samp{<2>}, @samp{<3>}, or so on, using
+the lowest number that makes a name that is not already in use.
+
+ Each window's mode line shows the name of the buffer that is being displayed
+in that window, so you can always tell what buffer you are editing.
+
+ The changes you make with editing commands are made in the Emacs
+buffer. They do not take effect in the file that you visited, or any
+place permanent, until you @dfn{save} the buffer. Saving the buffer
+means that Emacs writes the current contents of the buffer into its
+visited file. @xref{Saving}.
+
+@cindex modified (buffer)
+ If a buffer contains changes that have not been saved, we say the
+buffer is @dfn{modified}. This is important because it implies that
+some changes will be lost if the buffer is not saved. The mode line
+displays two stars near the left margin to indicate that the buffer is
+modified.
+
+@kindex C-x C-f
+@findex find-file
+ To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow
+the command with the name of the file you wish to visit, terminated by a
+@key{RET}.
+
+ The file name is read using the minibuffer (@pxref{Minibuffer}), with
+defaulting and completion in the standard manner (@pxref{File Names}).
+While in the minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}.
+
+ Your confirmation that @kbd{C-x C-f} has completed successfully is the
+appearance of new text on the screen and a new buffer name in the mode
+line. If the specified file does not exist and could not be created, or
+cannot be read, then you get an error, with an error message displayed
+in the echo area.
+
+ If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
+another copy. It selects the existing buffer containing that file.
+However, before doing so, it checks that the file itself has not changed
+since you visited or saved it last. If the file has changed, a warning
+message is printed. @xref{Interlocking,,Simultaneous Editing}.
+
+@cindex creating files
+ What if you want to create a new file? Just visit it. Emacs prints
+@samp{(New File)} in the echo area, but in other respects behaves as if
+you had visited an existing empty file. If you make any changes and
+save them, the file is created.
+
+ Emacs recognizes from the contents of a file which convention it uses
+to separate lines---newline (used on GNU/Linux and on Unix),
+carriage-return linefeed (used on Microsoft systems), or just
+carriage-return (used on the Macintosh)---and automatically converts the
+contents to the normal Emacs convention, which is that the newline
+character separates lines. This is a part of the general feature of
+coding system conversion (@pxref{Coding Systems}), and makes it possible
+to edit files imported from various different operating systems with
+equal convenience. If you change the text and save the file, Emacs
+performs the inverse conversion, changing newlines back into
+carriage-return linefeed or just carriage-return if appropriate.
+
+@vindex find-file-run-dired
+ If the file you specify is actually a directory, @kbd{C-x C-f} invokes
+Dired, the Emacs directory browser, so that you can ``edit'' the contents
+of the directory (@pxref{Dired}). Dired is a convenient way to delete,
+look at, or operate on the files in the directory. However, if the
+variable @code{find-file-run-dired} is @code{nil}, then it is an error
+to try to visit a directory.
+
+ If the file name you specify contains wildcard characters, Emacs
+visits all the files that match it. @xref{Quoted File Names}, if you
+want to visit a file whose name actually contains wildcard characters.
+
+ If you visit a file that the operating system won't let you modify,
+Emacs makes the buffer read-only, so that you won't go ahead and make
+changes that you'll have trouble saving afterward. You can make the
+buffer writable with @kbd{C-x C-q} (@code{vc-toggle-read-only}).
+@xref{Misc Buffer}.
+
+@kindex C-x C-r
+@findex find-file-read-only
+ Occasionally you might want to visit a file as read-only in order to
+protect yourself from entering changes accidentally; do so by visiting
+the file with the command @kbd{C-x C-r} (@code{find-file-read-only}).
+
+@kindex C-x C-v
+@findex find-alternate-file
+ If you visit a nonexistent file unintentionally (because you typed the
+wrong file name), use the @kbd{C-x C-v} command
+(@code{find-alternate-file}) to visit the file you really wanted.
+@kbd{C-x C-v} is similar to @kbd{C-x C-f}, but it kills the current
+buffer (after first offering to save it if it is modified). When it
+reads the file name to visit, it inserts the entire default file name in
+the buffer, with point just after the directory part; this is convenient
+if you made a slight error in typing the name.
+
+ If you find a file which exists but cannot be read, @kbd{C-x C-f}
+signals an error.
+
+@kindex C-x 4 f
+@findex find-file-other-window
+ @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
+except that the buffer containing the specified file is selected in another
+window. The window that was selected before @kbd{C-x 4 f} continues to
+show the same buffer it was already showing. If this command is used when
+only one window is being displayed, that window is split in two, with one
+window showing the same buffer as before, and the other one showing the
+newly requested file. @xref{Windows}.
+
+@kindex C-x 5 f
+@findex find-file-other-frame
+ @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a
+new frame, or makes visible any existing frame showing the file you
+seek. This feature is available only when you are using a window
+system. @xref{Frames}.
+
+@findex find-file-literally
+ If you wish to edit a file as a sequence of characters with no special
+encoding or conversion, use the @kbd{M-x find-file-literally} command.
+It visits a file, like @kbd{C-x C-f}, but does not do format conversion
+(@pxref{Formatted Text}), character code conversion (@pxref{Coding
+Systems}), or automatic uncompression (@pxref{Compressed Files}).
+If you already have visited the same file in the usual (non-literal)
+manner, this command asks you whether to visit it literally instead.
+
+@vindex find-file-hooks
+@vindex find-file-not-found-hooks
+ Two special hook variables allow extensions to modify the operation of
+visiting files. Visiting a file that does not exist runs the functions
+in the list @code{find-file-not-found-hooks}; this variable holds a list
+of functions, and the functions are called one by one (with no
+arguments) until one of them returns non-@code{nil}. This is not a
+normal hook, and the name ends in @samp{-hooks} rather than @samp{-hook}
+to indicate that fact.
+
+ Any visiting of a file, whether extant or not, expects
+@code{find-file-hooks} to contain a list of functions, and calls them
+all, one by one, with no arguments. This variable is really a normal
+hook, but it has an abnormal name for historical compatibility. In the
+case of a nonexistent file, the @code{find-file-not-found-hooks} are run
+first. @xref{Hooks}.
+
+ There are several ways to specify automatically the major mode for
+editing the file (@pxref{Choosing Modes}), and to specify local
+variables defined for that file (@pxref{File Variables}).
+
+@node Saving
+@section Saving Files
+
+ @dfn{Saving} a buffer in Emacs means writing its contents back into the file
+that was visited in the buffer.
+
+@table @kbd
+@item C-x C-s
+Save the current buffer in its visited file (@code{save-buffer}).
+@item C-x s
+Save any or all buffers in their visited files (@code{save-some-buffers}).
+@item M-~
+Forget that the current buffer has been changed (@code{not-modified}).
+@item C-x C-w
+Save the current buffer in a specified file (@code{write-file}).
+@item M-x set-visited-file-name
+Change file the name under which the current buffer will be saved.
+@end table
+
+@kindex C-x C-s
+@findex save-buffer
+ When you wish to save the file and make your changes permanent, type
+@kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
+displays a message like this:
+
+@example
+Wrote /u/rms/gnu/gnu.tasks
+@end example
+
+@noindent
+If the selected buffer is not modified (no changes have been made in it
+since the buffer was created or last saved), saving is not really done,
+because it would have no effect. Instead, @kbd{C-x C-s} displays a message
+like this in the echo area:
+
+@example
+(No changes need to be saved)
+@end example
+
+@kindex C-x s
+@findex save-some-buffers
+ The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any
+or all modified buffers. It asks you what to do with each buffer. The
+possible responses are analogous to those of @code{query-replace}:
+
+@table @kbd
+@item y
+Save this buffer and ask about the rest of the buffers.
+@item n
+Don't save this buffer, but ask about the rest of the buffers.
+@item !
+Save this buffer and all the rest with no more questions.
+@c following generates acceptable underfull hbox
+@item @key{RET}
+Terminate @code{save-some-buffers} without any more saving.
+@item .
+Save this buffer, then exit @code{save-some-buffers} without even asking
+about other buffers.
+@item C-r
+View the buffer that you are currently being asked about. When you exit
+View mode, you get back to @code{save-some-buffers}, which asks the
+question again.
+@item C-h
+Display a help message about these options.
+@end table
+
+ @kbd{C-x C-c}, the key sequence to exit Emacs, invokes
+@code{save-some-buffers} and therefore asks the same questions.
+
+@kindex M-~
+@findex not-modified
+ If you have changed a buffer but you do not want to save the changes,
+you should take some action to prevent it. Otherwise, each time you use
+@kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer by
+mistake. One thing you can do is type @kbd{M-~} (@code{not-modified}),
+which clears out the indication that the buffer is modified. If you do
+this, none of the save commands will believe that the buffer needs to be
+saved. (@samp{~} is often used as a mathematical symbol for `not'; thus
+@kbd{M-~} is `not', metafied.) You could also use
+@code{set-visited-file-name} (see below) to mark the buffer as visiting
+a different file name, one which is not in use for anything important.
+Alternatively, you can cancel all the changes made since the file was
+visited or saved, by reading the text from the file again. This is
+called @dfn{reverting}. @xref{Reverting}. You could also undo all the
+changes by repeating the undo command @kbd{C-x u} until you have undone
+all the changes; but reverting is easier.
+
+@findex set-visited-file-name
+ @kbd{M-x set-visited-file-name} alters the name of the file that the
+current buffer is visiting. It reads the new file name using the
+minibuffer. Then it specifies the visited file name and changes the
+buffer name correspondingly (as long as the new name is not in use).
+@code{set-visited-file-name} does not save the buffer in the newly
+visited file; it just alters the records inside Emacs in case you do
+save later. It also marks the buffer as ``modified'' so that @kbd{C-x
+C-s} in that buffer @emph{will} save.
+
+@kindex C-x C-w
+@findex write-file
+ If you wish to mark the buffer as visiting a different file and save it
+right away, use @kbd{C-x C-w} (@code{write-file}). It is precisely
+equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}.
+@kbd{C-x C-s} used on a buffer that is not visiting a file has the
+same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
+buffer as visiting that file, and saves it there. The default file name in
+a buffer that is not visiting a file is made by combining the buffer name
+with the buffer's default directory.
+
+ If the new file name implies a major mode, then @kbd{C-x C-w} switches
+to that major mode, in most cases. The command
+@code{set-visited-file-name} also does this. @xref{Choosing Modes}.
+
+ If Emacs is about to save a file and sees that the date of the latest
+version on disk does not match what Emacs last read or wrote, Emacs
+notifies you of this fact, because it probably indicates a problem caused
+by simultaneous editing and requires your immediate attention.
+@xref{Interlocking,, Simultaneous Editing}.
+
+@vindex require-final-newline
+ If the variable @code{require-final-newline} is non-@code{nil}, Emacs
+puts a newline at the end of any file that doesn't already end in one,
+every time a file is saved or written. The default is @code{nil}.
+
+@menu
+* Backup:: How Emacs saves the old version of your file.
+* Interlocking:: How Emacs protects against simultaneous editing
+ of one file by two users.
+@end menu
+
+@node Backup
+@subsection Backup Files
+@cindex backup file
+@vindex make-backup-files
+@vindex vc-make-backup-files
+@vindex backup-enable-predicate
+
+ On most operating systems, rewriting a file automatically destroys all
+record of what the file used to contain. Thus, saving a file from Emacs
+throws away the old contents of the file---or it would, except that
+Emacs carefully copies the old contents to another file, called the
+@dfn{backup} file, before actually saving.
+
+ For most files, the variable @code{make-backup-files} determines
+whether to make backup files. On most operating systems, its default
+value is @code{t}, so that Emacs does write backup files.
+
+ For files managed by a version control system (@pxref{Version
+Control}), the variable @code{vc-make-backup-files} determines whether
+to make backup files. By default, it is @code{nil}, since backup files
+are redundant when you store all the previous versions in a version
+control system. @xref{VC Workfile Handling}.
+
+ The default value of the @code{backup-enable-predicate} variable
+prevents backup files being written for files in @file{/tmp}.
+
+ At your option, Emacs can keep either a single backup file or a series of
+numbered backup files for each file that you edit.
+
+ Emacs makes a backup for a file only the first time the file is saved
+from one buffer. No matter how many times you save a file, its backup file
+continues to contain the contents from before the file was visited.
+Normally this means that the backup file contains the contents from before
+the current editing session; however, if you kill the buffer and then visit
+the file again, a new backup file will be made by the next save.
+
+ You can also explicitly request making another backup file from a
+buffer even though it has already been saved at least once. If you save
+the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
+into a backup file if you save the buffer again. @kbd{C-u C-u C-x C-s}
+saves the buffer, but first makes the previous file contents into a new
+backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it makes a
+backup from the previous contents, and arranges to make another from the
+newly saved contents, if you save again.
+
+@menu
+* Names: Backup Names. How backup files are named;
+ choosing single or numbered backup files.
+* Deletion: Backup Deletion. Emacs deletes excess numbered backups.
+* Copying: Backup Copying. Backups can be made by copying or renaming.
+@end menu
+
+@node Backup Names
+@subsubsection Single or Numbered Backups
+
+ If you choose to have a single backup file (this is the default),
+the backup file's name is constructed by appending @samp{~} to the
+file name being edited; thus, the backup file for @file{eval.c} would
+be @file{eval.c~}.
+
+ If you choose to have a series of numbered backup files, backup file
+names are made by appending @samp{.~}, the number, and another @samp{~} to
+the original file name. Thus, the backup files of @file{eval.c} would be
+called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names
+like @file{eval.c.~259~} and beyond.
+
+ If protection stops you from writing backup files under the usual names,
+the backup file is written as @file{%backup%~} in your home directory.
+Only one such file can exist, so only the most recently made such backup is
+available.
+
+@vindex version-control
+ The choice of single backup or numbered backups is controlled by the
+variable @code{version-control}. Its possible values are
+
+@table @code
+@item t
+Make numbered backups.
+@item nil
+Make numbered backups for files that have numbered backups already.
+Otherwise, make single backups.
+@item never
+Do not in any case make numbered backups; always make single backups.
+@end table
+
+@noindent
+You can set @code{version-control} locally in an individual buffer to
+control the making of backups for that buffer's file. For example,
+Rmail mode locally sets @code{version-control} to @code{never} to make sure
+that there is only one backup for an Rmail file. @xref{Locals}.
+
+@cindex @code{VERSION_CONTROL} environment variable
+ If you set the environment variable @code{VERSION_CONTROL}, to tell
+various GNU utilities what to do with backup files, Emacs also obeys the
+environment variable by setting the Lisp variable @code{version-control}
+accordingly at startup. If the environment variable's value is @samp{t}
+or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
+value is @samp{nil} or @samp{existing}, then @code{version-control}
+becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
+@code{version-control} becomes @code{never}.
+
+@node Backup Deletion
+@subsubsection Automatic Deletion of Backups
+
+ To prevent unlimited consumption of disk space, Emacs can delete numbered
+backup versions automatically. Generally Emacs keeps the first few backups
+and the latest few backups, deleting any in between. This happens every
+time a new backup is made.
+
+@vindex kept-old-versions
+@vindex kept-new-versions
+ The two variables @code{kept-old-versions} and
+@code{kept-new-versions} control this deletion. Their values are,
+respectively the number of oldest (lowest-numbered) backups to keep and
+the number of newest (highest-numbered) ones to keep, each time a new
+backup is made. Recall that these values are used just after a new
+backup version is made; that newly made backup is included in the count
+in @code{kept-new-versions}. By default, both variables are 2.
+
+@vindex delete-old-versions
+ If @code{delete-old-versions} is non-@code{nil}, the excess
+middle versions are deleted without a murmur. If it is @code{nil}, the
+default, then you are asked whether the excess middle versions should
+really be deleted.
+
+ Dired's @kbd{.} (Period) command can also be used to delete old versions.
+@xref{Dired Deletion}.
+
+@node Backup Copying
+@subsubsection Copying vs.@: Renaming
+
+ Backup files can be made by copying the old file or by renaming it. This
+makes a difference when the old file has multiple names. If the old file
+is renamed into the backup file, then the alternate names become names for
+the backup file. If the old file is copied instead, then the alternate
+names remain names for the file that you are editing, and the contents
+accessed by those names will be the new contents.
+
+ The method of making a backup file may also affect the file's owner
+and group. If copying is used, these do not change. If renaming is used,
+you become the file's owner, and the file's group becomes the default
+(different operating systems have different defaults for the group).
+
+ Having the owner change is usually a good idea, because then the owner
+always shows who last edited the file. Also, the owners of the backups
+show who produced those versions. Occasionally there is a file whose
+owner should not change; it is a good idea for such files to contain
+local variable lists to set @code{backup-by-copying-when-mismatch}
+locally (@pxref{File Variables}).
+
+@vindex backup-by-copying
+@vindex backup-by-copying-when-linked
+@vindex backup-by-copying-when-mismatch
+ The choice of renaming or copying is controlled by three variables.
+Renaming is the default choice. If the variable
+@code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise,
+if the variable @code{backup-by-copying-when-linked} is non-@code{nil},
+then copying is used for files that have multiple names, but renaming
+may still be used when the file being edited has only one name. If the
+variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then
+copying is used if renaming would cause the file's owner or group to
+change. @code{backup-by-copying-when-mismatch} is @code{t} by default
+if you start Emacs as the superuser.
+
+ When a file is managed with a version control system (@pxref{Version
+Control}), Emacs does not normally make backups in the usual way for
+that file. But check-in and check-out are similar in some ways to
+making backups. One unfortunate similarity is that these operations
+typically break hard links, disconnecting the file name you visited from
+any alternate names for the same file. This has nothing to do with
+Emacs---the version control system does it.
+
+@node Interlocking
+@subsection Protection against Simultaneous Editing
+
+@cindex file dates
+@cindex simultaneous editing
+ Simultaneous editing occurs when two users visit the same file, both
+make changes, and then both save them. If nobody were informed that
+this was happening, whichever user saved first would later find that his
+changes were lost.
+
+ On some systems, Emacs notices immediately when the second user starts
+to change the file, and issues an immediate warning. On all systems,
+Emacs checks when you save the file, and warns if you are about to
+overwrite another user's changes. You can prevent loss of the other
+user's work by taking the proper corrective action instead of saving the
+file.
+
+@findex ask-user-about-lock
+@cindex locking files
+ When you make the first modification in an Emacs buffer that is
+visiting a file, Emacs records that the file is @dfn{locked} by you.
+(It does this by creating a symbolic link in the same directory with a
+different name.) Emacs removes the lock when you save the changes. The
+idea is that the file is locked whenever an Emacs buffer visiting it has
+unsaved changes.
+
+@cindex collision
+ If you begin to modify the buffer while the visited file is locked by
+someone else, this constitutes a @dfn{collision}. When Emacs detects a
+collision, it asks you what to do, by calling the Lisp function
+@code{ask-user-about-lock}. You can redefine this function for the sake
+of customization. The standard definition of this function asks you a
+question and accepts three possible answers:
+
+@table @kbd
+@item s
+Steal the lock. Whoever was already changing the file loses the lock,
+and you gain the lock.
+@item p
+Proceed. Go ahead and edit the file despite its being locked by someone else.
+@item q
+Quit. This causes an error (@code{file-locked}) and the modification you
+were trying to make in the buffer does not actually take place.
+@end table
+
+ Note that locking works on the basis of a file name; if a file has
+multiple names, Emacs does not realize that the two names are the same file
+and cannot prevent two users from editing it simultaneously under different
+names. However, basing locking on names means that Emacs can interlock the
+editing of new files that will not really exist until they are saved.
+
+ Some systems are not configured to allow Emacs to make locks, and
+there are cases where lock files cannot be written. In these cases,
+Emacs cannot detect trouble in advance, but it still can detect the
+collision when you try to save a file and overwrite someone else's
+changes.
+
+ If Emacs or the operating system crashes, this may leave behind lock
+files which are stale. So you may occasionally get warnings about
+spurious collisions. When you determine that the collision is spurious,
+just use @kbd{p} to tell Emacs to go ahead anyway.
+
+ Every time Emacs saves a buffer, it first checks the last-modification
+date of the existing file on disk to verify that it has not changed since the
+file was last visited or saved. If the date does not match, it implies
+that changes were made in the file in some other way, and these changes are
+about to be lost if Emacs actually does save. To prevent this, Emacs
+prints a warning message and asks for confirmation before saving.
+Occasionally you will know why the file was changed and know that it does
+not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should
+cancel the save with @kbd{C-g} and investigate the situation.
+
+ The first thing you should do when notified that simultaneous editing
+has already taken place is to list the directory with @kbd{C-u C-x C-d}
+(@pxref{Directories}). This shows the file's current author. You
+should attempt to contact him to warn him not to continue editing.
+Often the next step is to save the contents of your Emacs buffer under a
+different name, and use @code{diff} to compare the two files.@refill
+
+@node Reverting
+@section Reverting a Buffer
+@findex revert-buffer
+@cindex drastic changes
+
+ If you have made extensive changes to a file and then change your mind
+about them, you can get rid of them by reading in the previous version
+of the file. To do this, use @kbd{M-x revert-buffer}, which operates on
+the current buffer. Since reverting a buffer unintentionally could lose
+a lot of work, you must confirm this command with @kbd{yes}.
+
+ @code{revert-buffer} keeps point at the same distance (measured in
+characters) from the beginning of the file. If the file was edited only
+slightly, you will be at approximately the same piece of text after
+reverting as before. If you have made drastic changes, the same value of
+point in the old file may address a totally different piece of text.
+
+ Reverting marks the buffer as ``not modified'' until another change is
+made.
+
+ Some kinds of buffers whose contents reflect data bases other than files,
+such as Dired buffers, can also be reverted. For them, reverting means
+recalculating their contents from the appropriate data base. Buffers
+created explicitly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
+reports an error when asked to do so.
+
+@vindex revert-without-query
+ When you edit a file that changes automatically and frequently---for
+example, a log of output from a process that continues to run---it may be
+useful for Emacs to revert the file without querying you, whenever you
+visit the file again with @kbd{C-x C-f}.
+
+ To request this behavior, set the variable @code{revert-without-query}
+to a list of regular expressions. When a file name matches one of these
+regular expressions, @code{find-file} and @code{revert-buffer} will
+revert it automatically if it has changed---provided the buffer itself
+is not modified. (If you have edited the text, it would be wrong to
+discard your changes.)
+
+@node Auto Save
+@section Auto-Saving: Protection Against Disasters
+@cindex Auto Save mode
+@cindex mode, Auto Save
+@cindex crashes
+
+ Emacs saves all the visited files from time to time (based on counting
+your keystrokes) without being asked. This is called @dfn{auto-saving}.
+It prevents you from losing more than a limited amount of work if the
+system crashes.
+
+ When Emacs determines that it is time for auto-saving, each buffer is
+considered, and is auto-saved if auto-saving is turned on for it and it
+has been changed since the last time it was auto-saved. The message
+@samp{Auto-saving...} is displayed in the echo area during auto-saving,
+if any files are actually auto-saved. Errors occurring during
+auto-saving are caught so that they do not interfere with the execution
+of commands you have been typing.
+
+@menu
+* Files: Auto Save Files. The file where auto-saved changes are
+ actually made until you save the file.
+* Control: Auto Save Control. Controlling when and how often to auto-save.
+* Recover:: Recovering text from auto-save files.
+@end menu
+
+@node Auto Save Files
+@subsection Auto-Save Files
+
+ Auto-saving does not normally save in the files that you visited, because
+it can be very undesirable to save a program that is in an inconsistent
+state when you have made half of a planned change. Instead, auto-saving
+is done in a different file called the @dfn{auto-save file}, and the
+visited file is changed only when you request saving explicitly (such as
+with @kbd{C-x C-s}).
+
+ Normally, the auto-save file name is made by appending @samp{#} to the
+front and rear of the visited file name. Thus, a buffer visiting file
+@file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that
+are not visiting files are auto-saved only if you request it explicitly;
+when they are auto-saved, the auto-save file name is made by appending
+@samp{#%} to the front and @samp{#} to the rear of buffer name. For
+example, the @samp{*mail*} buffer in which you compose messages to be
+sent is auto-saved in a file named @file{#%*mail*#}. Auto-save file
+names are made this way unless you reprogram parts of Emacs to do
+something different (the functions @code{make-auto-save-file-name} and
+@code{auto-save-file-name-p}). The file name to be used for auto-saving
+in a buffer is calculated when auto-saving is turned on in that buffer.
+
+ When you delete a substantial part of the text in a large buffer, auto
+save turns off temporarily in that buffer. This is because if you
+deleted the text unintentionally, you might find the auto-save file more
+useful if it contains the deleted text. To reenable auto-saving after
+this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x
+auto-save}.
+
+@vindex auto-save-visited-file-name
+ If you want auto-saving to be done in the visited file, set the variable
+@code{auto-save-visited-file-name} to be non-@code{nil}. In this mode,
+there is really no difference between auto-saving and explicit saving.
+
+@vindex delete-auto-save-files
+ A buffer's auto-save file is deleted when you save the buffer in its
+visited file. To inhibit this, set the variable @code{delete-auto-save-files}
+to @code{nil}. Changing the visited file name with @kbd{C-x C-w} or
+@code{set-visited-file-name} renames any auto-save file to go with
+the new visited name.
+
+@node Auto Save Control
+@subsection Controlling Auto-Saving
+
+@vindex auto-save-default
+@findex auto-save-mode
+ Each time you visit a file, auto-saving is turned on for that file's
+buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
+in batch mode; @pxref{Entering Emacs}). The default for this variable is
+@code{t}, so auto-saving is the usual practice for file-visiting buffers.
+Auto-saving can be turned on or off for any existing buffer with the
+command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x
+auto-save-mode} turns auto-saving on with a positive argument, off with a
+zero or negative argument; with no argument, it toggles.
+
+@vindex auto-save-interval
+ Emacs does auto-saving periodically based on counting how many characters
+you have typed since the last time auto-saving was done. The variable
+@code{auto-save-interval} specifies how many characters there are between
+auto-saves. By default, it is 300.
+
+@vindex auto-save-timeout
+ Auto-saving also takes place when you stop typing for a while. The
+variable @code{auto-save-timeout} says how many seconds Emacs should
+wait before it does an auto save (and perhaps also a garbage
+collection). (The actual time period is longer if the current buffer is
+long; this is a heuristic which aims to keep out of your way when you
+are editing long buffers, in which auto-save takes an appreciable amount
+of time.) Auto-saving during idle periods accomplishes two things:
+first, it makes sure all your work is saved if you go away from the
+terminal for a while; second, it may avoid some auto-saving while you
+are actually typing.
+
+ Emacs also does auto-saving whenever it gets a fatal error. This
+includes killing the Emacs job with a shell command such as @samp{kill
+%emacs}, or disconnecting a phone line or network connection.
+
+@findex do-auto-save
+ You can request an auto-save explicitly with the command @kbd{M-x
+do-auto-save}.
+
+@node Recover
+@subsection Recovering Data from Auto-Saves
+
+@findex recover-file
+ You can use the contents of an auto-save file to recover from a loss
+of data with the command @kbd{M-x recover-file @key{RET} @var{file}
+@key{RET}}. This visits @var{file} and then (after your confirmation)
+restores the contents from its auto-save file @file{#@var{file}#}.
+You can then save with @kbd{C-x C-s} to put the recovered text into
+@var{file} itself. For example, to recover file @file{foo.c} from its
+auto-save file @file{#foo.c#}, do:@refill
+
+@example
+M-x recover-file @key{RET} foo.c @key{RET}
+yes @key{RET}
+C-x C-s
+@end example
+
+ Before asking for confirmation, @kbd{M-x recover-file} displays a
+directory listing describing the specified file and the auto-save file,
+so you can compare their sizes and dates. If the auto-save file
+is older, @kbd{M-x recover-file} does not offer to read it.
+
+@findex recover-session
+ If Emacs or the computer crashes, you can recover all the files you
+were editing from their auto save files with the command @kbd{M-x
+recover-session}. This first shows you a list of recorded interrupted
+sessions. Move point to the one you choose, and type @kbd{C-c C-c}.
+
+ Then @code{recover-session} asks about each of the files that were
+being edited during that session, asking whether to recover that file.
+If you answer @kbd{y}, it calls @code{recover-file}, which works in its
+normal fashion. It shows the dates of the original file and its
+auto-save file, and asks once again whether to recover that file.
+
+ When @code{recover-session} is done, the files you've chosen to
+recover are present in Emacs buffers. You should then save them. Only
+this---saving them---updates the files themselves.
+
+@vindex auto-save-list-file-prefix
+ Interrupted sessions are recorded for later recovery in files named
+@file{~/.saves-@var{pid}-@var{hostname}}. The @samp{~/.saves} portion of
+these names comes from the value of @code{auto-save-list-file-prefix}.
+You can arrange to record sessions in a different place by setting that
+variable in your @file{.emacs} file, but you'll have to redefine
+@code{recover-session} as well to make it look in the new place. If you
+set @code{auto-save-list-file-prefix} to @code{nil} in your
+@file{.emacs} file, sessions are not recorded for recovery.
+
+@node File Aliases
+@section File Name Aliases
+
+ Symbolic links and hard links both make it possible for several file
+names to refer to the same file. Hard links are alternate names that
+refer directly to the file; all the names are equally valid, and no one
+of them is preferred. By contrast, a symbolic link is a kind of defined
+alias: when @file{foo} is a symbolic link to @file{bar}, you can use
+either name to refer to the file, but @file{bar} is the real name, while
+@file{foo} is just an alias. More complex cases occur when symbolic
+links point to directories.
+
+ If you visit two names for the same file, normally Emacs makes
+two different buffers, but it warns you about the situation.
+
+@vindex find-file-existing-other-name
+ If you wish to avoid visiting the same file in two buffers under
+different names, set the variable @code{find-file-existing-other-name}
+to a non-@code{nil} value. Then @code{find-file} uses the existing
+buffer visiting the file, no matter which of the file's names you
+specify.
+
+@vindex find-file-visit-truename
+@cindex truenames of files
+@cindex file truenames
+ If the variable @code{find-file-visit-truename} is non-@code{nil},
+then the file name recorded for a buffer is the file's @dfn{truename}
+(made by replacing all symbolic links with their target names), rather
+than the name you specify. Setting @code{find-file-visit-truename} also
+implies the effect of @code{find-file-existing-other-name}.
+
+@node Version Control
+@section Version Control
+@cindex version control
+
+ @dfn{Version control systems} are packages that can record multiple
+versions of a source file, usually storing the unchanged parts of the
+file just once. Version control systems also record history information
+such as the creation time of each version, who created it, and a
+description of what was changed in that version.
+
+ The Emacs version control interface is called VC. Its commands work
+with three version control systems---RCS, CVS and SCCS. The GNU project
+recommends RCS and CVS, which are free software and available from the
+Free Software Foundation.
+
+@menu
+* Introduction to VC:: How version control works in general.
+* VC Mode Line:: How the mode line shows version control status.
+* Basic VC Editing:: How to edit a file under version control.
+* Old Versions:: Examining and comparing old versions.
+* Secondary VC Commands:: The commands used a little less frequently.
+* Branches:: Multiple lines of development.
+* Snapshots:: Sets of file versions treated as a unit.
+* Miscellaneous VC:: Various other commands and features of VC.
+* Customizing VC:: Variables that change VC's behavior.
+@end menu
+
+@node Introduction to VC
+@subsection Introduction to Version Control
+
+ VC allows you to use a version control system from within Emacs,
+integrating the version control operations smoothly with editing. VC
+provides a uniform interface to version control, so that regardless of
+which version control system is in use, you can use it the same way.
+
+ This section provides a general overview of version control, and
+describes the version control systems that VC supports. You can skip
+this section if you are already familiar with the version control system
+you want to use.
+
+@menu
+* Version Systems:: Supported version control back-end systems.
+* VC Concepts:: Words and concepts related to version control.
+@end menu
+
+@node Version Systems
+@subsubsection Supported Version Control Systems
+
+@cindex RCS
+@cindex back end (version control)
+ VC currently works with three different version control systems or
+``back ends'': RCS, CVS, and SCCS.
+
+ RCS is a free version control system that is available from the Free
+Software Foundation. It is perhaps the most mature of the supported
+back ends, and the VC commands are conceptually closest to RCS. Almost
+everything you can do with RCS can be done through VC.
+
+@cindex CVS
+ CVS is built on top of RCS, and extends the features of RCS, allowing
+for more sophisticated release management, and concurrent multi-user
+development. VC supports basic editing operations under CVS, but for
+some less common tasks you still need to call CVS from the command line.
+Note also that before using CVS you must set up a repository, which is a
+subject too complex to treat here.
+
+@cindex SCCS
+ SCCS is a proprietary but widely used version control system. In
+terms of capabilities, it is the weakest of the three that VC
+supports. VC compensates for certain features missing in SCCS
+(snapshots, for example) by implementing them itself, but some other VC
+features, such as multiple branches, are not available with SCCS. You
+should use SCCS only if for some reason you cannot use RCS.
+
+@node VC Concepts
+@subsubsection Concepts of Version Control
+
+@cindex master file
+@cindex registered file
+ When a file is under version control, we also say that it is
+@dfn{registered} in the version control system. Each registered file
+has a corresponding @dfn{master file} which represents the file's
+present state plus its change history---enough to reconstruct the
+current version or any earlier version. Usually the master file also
+records a @dfn{log entry} for each version, describing in words what was
+changed in that version.
+
+@cindex work file
+@cindex checking out files
+ The file that is maintained under version control is sometimes called
+the @dfn{work file} corresponding to its master file. You edit the work
+file and make changes in it, as you would with an ordinary file. (With
+SCCS and RCS, you must @dfn{lock} the file before you start to edit it.)
+After you are done with a set of changes, you @dfn{check the file in},
+which records the changes in the master file, along with a log entry for
+them.
+
+ With CVS, there are usually multiple work files corresponding to a
+single master file---often each user has his own copy. It is also
+possible to use RCS in this way, but this is not the usual way to use
+RCS.
+
+@cindex locking and version control
+ A version control system typically has some mechanism to coordinate
+between users who want to change the same file. One method is
+@dfn{locking} (analogous to the locking that Emacs uses to detect
+simultaneous editing of a file, but distinct from it). The other method
+is to merge your changes with other people's changes when you check them
+in.
+
+ With version control locking, work files are normally read-only so
+that you cannot change them. You ask the version control system to make
+a work file writable for you by locking it; only one user can do
+this at any given time. When you check in your changes, that unlocks
+the file, making the work file read-only again. This allows other users
+to lock the file to make further changes. SCCS always uses locking, and
+RCS normally does.
+
+ The other alternative for RCS is to let each user modify the work file
+at any time. In this mode, locking is not required, but it is
+permitted; check-in is still the way to record a new version.
+
+ CVS normally allows each user to modify his own copy of the work file
+at any time, but requires merging with changes from other users at
+check-in time. However, CVS can also be set up to require locking.
+(@pxref{Backend Options}).
+
+@node VC Mode Line
+@subsection Version Control and the Mode Line
+
+ When you visit a file that is under version control, Emacs indicates
+this on the mode line. For example, @samp{RCS-1.3} says that RCS is
+used for that file, and the current version is 1.3.
+
+ The character between the back-end name and the version number
+indicates the version control status of the file. @samp{-} means that
+the work file is not locked (if locking is in use), or not modified (if
+locking is not in use). @samp{:} indicates that the file is locked, or
+that it is modified. If the file is locked by some other user (for
+instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
+
+@node Basic VC Editing
+@subsection Basic Editing under Version Control
+
+ The principal VC command is an all-purpose command that performs
+either locking or check-in, depending on the situation.
+
+@table @kbd
+@item C-x C-q
+@itemx C-x v v
+Perform the next logical version control operation on this file.
+@end table
+
+@findex vc-next-action
+@findex vc-toggle-read-only
+@kindex C-x v v
+@kindex C-x C-q @r{(Version Control)}
+ Strictly speaking, the command for this job is @code{vc-next-action},
+bound to @kbd{C-x v v}. However, the normal meaning of @kbd{C-x C-q} is
+to make a read-only buffer writable, or vice versa; we have extended it
+to do the same job properly for files managed by version control, by
+performing the appropriate version control operations. When you type
+@kbd{C-x C-q} on a registered file, it acts like @kbd{C-x v v}.
+
+ The precise action of this command depends on the state of the file,
+and whether the version control system uses locking or not. SCCS and
+RCS normally use locking; CVS normally does not use locking.
+
+@menu
+* VC with Locking:: RCS in its default mode, SCCS, and optionally CVS.
+* Without Locking:: Without locking: default mode for CVS.
+* Log Buffer:: Features available in log entry buffers.
+@end menu
+
+@node VC with Locking
+@subsubsection Basic Version Control with Locking
+
+ If locking is used for the file (as with SCCS, and RCS in its default
+mode), @kbd{C-x C-q} can either lock a file or check it in:
+
+@itemize @bullet
+@item
+If the file is not locked, @kbd{C-x C-q} locks it, and
+makes it writable so that you can change it.
+
+@item
+If the file is locked by you, and contains changes, @kbd{C-x C-q} checks
+in the changes. In order to do this, it first reads the log entry
+for the new version. @xref{Log Buffer}.
+
+@item
+If the file is locked by you, but you have not changed it since you
+locked it, @kbd{C-x C-q} releases the lock and makes the file read-only
+again.
+
+@item
+If the file is locked by some other user, @kbd{C-x C-q} asks you whether
+you want to ``steal the lock'' from that user. If you say yes, the file
+becomes locked by you, but a message is sent to the person who had
+formerly locked the file, to inform him of what has happened.
+@end itemize
+
+ These rules also apply when you use CVS in locking mode, except
+that there is no such thing as stealing a lock.
+
+@node Without Locking
+@subsubsection Basic Version Control without Locking
+
+ When there is no locking---the default for CVS---work files are always
+writable; you do not need to do anything before you begin to edit a
+file. The status indicator on the mode line is @samp{-} if the file is
+unmodified; it flips to @samp{:} as soon as you save any changes in the
+work file.
+
+ Here is what @kbd{C-x C-q} does when using CVS:
+
+@itemize @bullet
+@item
+If some other user has checked in changes into the master file,
+Emacs asks you whether you want to merge those changes into your own
+work file (@pxref{Merging}). You must do this before you can check in
+your own changes.
+
+@item
+If there are no new changes in the master file, but you have made
+modifications in your work file, @kbd{C-x C-q} checks in your changes.
+In order to do this, it first reads the log entry for the new version.
+@xref{Log Buffer}.
+
+@item
+If the file is not modified, the @kbd{C-x C-q} does nothing.
+@end itemize
+
+ These rules also apply when you use RCS in the mode that does not
+require locking, except that automatic merging of changes from the
+master file is not implemented. Unfortunately, this means that nothing
+informs you if another user has checked in changes in the same file
+since you began editing it, and when this happens, his changes will be
+effectively removed when you check in your version (though they will
+remain in the master file, so they will not be entirely lost). You must
+therefore verify the current version is unchanged, before you check in your
+changes. We hope to eliminate this risk and provide automatic merging
+with RCS in a future Emacs version.
+
+ In addition, locking is possible with RCS even in this mode, although
+it is not required; @kbd{C-x C-q} with an unmodified file locks the
+file, just as it does with RCS in its normal (locking) mode.
+
+@node Log Buffer
+@subsubsection Features of the Log Entry Buffer
+
+ When you check in changes, @kbd{C-x C-q} first reads a log entry. It
+pops up a buffer called @samp{*VC-Log*} for you to enter the log entry.
+When you are finished, type @kbd{C-c C-c} in the @samp{*VC-Log*} buffer.
+That is when check-in really happens.
+
+ To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that
+buffer. You can switch buffers and do other editing. As long as you
+don't try to check in another file, the entry you were editing remains
+in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any
+time to complete the check-in.
+
+ If you change several source files for the same reason, it is often
+convenient to specify the same log entry for many of the files. To do
+this, use the history of previous log entries. The commands @kbd{M-n},
+@kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the
+minibuffer history commands (except that these versions are used outside
+the minibuffer).
+
+@vindex vc-log-mode-hook
+ Each time you check in a file, the log entry buffer is put into VC Log
+mode, which involves running two hooks: @code{text-mode-hook} and
+@code{vc-log-mode-hook}. @xref{Hooks}.
+
+@node Old Versions
+@subsection Examining And Comparing Old Versions
+
+ One of the convenient features of version control is the ability
+to examine any version of a file, or compare two versions.
+
+@table @kbd
+@item C-x v ~ @var{version} @key{RET}
+Examine version @var{version} of the visited file, in a buffer of its
+own.
+
+@item C-x v =
+Compare the current buffer contents with the latest checked-in version
+of the file.
+
+@item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
+Compare the specified two versions of @var{file}.
+
+@item C-x v g
+Display the result of the CVS annotate command using colors.
+@end table
+
+@findex vc-version-other-window
+@kindex C-x v ~
+ To examine an old version in toto, visit the file and then type
+@kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}).
+This puts the text of version @var{version} in a file named
+@file{@var{filename}.~@var{version}~}, and visits it in its own buffer
+in a separate window. (In RCS, you can also select an old version
+and create a branch from it. @xref{Branches}.)
+
+@findex vc-diff
+@kindex C-x v =
+ But usually it is more convenient to compare two versions of the file,
+with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =}
+compares the current buffer contents (saving them in the file if
+necessary) with the last checked-in version of the file. @kbd{C-u C-x v
+=}, with a numeric argument, reads a file name and two version numbers,
+then compares those versions of the specified file.
+
+ If you supply a directory name instead of the name of a registered
+file, this command compares the two specified versions of all registered
+files in that directory and its subdirectories.
+
+ You can specify a checked-in version by its number; an empty input
+specifies the current contents of the work file (which may be different
+from all the checked-in versions). You can also specify a snapshot name
+(@pxref{Snapshots}) instead of one or both version numbers.
+
+ This command works by running the @code{diff} utility, getting the
+options from the variable @code{diff-switches}. It displays the output
+in a special buffer in another window. Unlike the @kbd{M-x diff}
+command, @kbd{C-x v =} does not try to locate the changes in the old and
+new versions. This is because normally one or both versions do not
+exist as files when you compare them; they exist only in the records of
+the master file. @xref{Comparing Files}, for more information about
+@kbd{M-x diff}.
+
+@findex vc-annotate
+@kindex C-x v g
+ For CVS-controlled files, you can display the result of the CVS
+annotate command, using colors to enhance the visual appearance. Use
+the command @kbd{M-x vc-annotate} to do this. Red means new, blue means
+old, and intermediate colors indicate intermediate ages. A prefix
+argument @var{n} specifies a stretch factor for the time scale; it makes
+each color cover a period @var{n} times as long.
+
+@node Secondary VC Commands
+@subsection The Secondary Commands of VC
+
+ This section explains the secondary commands of VC; those that you might
+use once a day.
+
+@menu
+* Registering:: Putting a file under version control.
+* VC Status:: Viewing the VC status of files.
+* VC Undo:: Cancelling changes before or after check-in.
+* VC Dired Mode:: Listing files managed by version control.
+* VC Dired Commands:: Commands to use in a VC Dired buffer.
+@end menu
+
+@node Registering
+@subsubsection Registering a File for Version Control
+
+@kindex C-x v i
+@findex vc-register
+ You can put any file under version control by simply visiting it, and
+then typing @w{@kbd{C-x v i}} (@code{vc-register}).
+
+@table @kbd
+@item C-x v i
+Register the visited file for version control.
+@end table
+
+@vindex vc-default-back-end
+ To register the file, Emacs must choose which version control system
+to use for it. You can specify your choice explicitly by setting
+@code{vc-default-back-end} to @code{RCS}, @code{CVS} or @code{SCCS}.
+Otherwise, if there is a subdirectory named @file{RCS}, @file{SCCS}, or
+@file{CVS}, Emacs uses the corresponding version control system. In the
+absence of any specification, the default choice is RCS if RCS is
+installed, otherwise SCCS.
+
+ If locking is in use, @kbd{C-x v i} leaves the file unlocked and
+read-only. Type @kbd{C-x C-q} if you wish to start editing it. After
+registering a file with CVS, you must subsequently commit the initial
+version by typing @kbd{C-x C-q}.
+
+@vindex vc-default-init-version
+ The initial version number for a newly registered file is 1.1, by
+default. You can specify a different default by setting the variable
+@code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric
+argument; then it reads the initial version number for this particular
+file using the minibuffer.
+
+@vindex vc-initial-comment
+ If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an
+initial comment to describe the purpose of this source file. Reading
+the initial comment works like reading a log entry (@pxref{Log Buffer}).
+
+@node VC Status
+@subsubsection VC Status Commands
+
+@table @kbd
+@item C-x v l
+Display version control state and change history.
+@end table
+
+@kindex C-x v l
+@findex vc-print-log
+ To view the detailed version control status and history of a file,
+type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of
+changes to the current file, including the text of the log entries. The
+output appears in a separate window.
+
+@node VC Undo
+@subsubsection Undoing Version Control Actions
+
+@table @kbd
+@item C-x v u
+Revert the buffer and the file to the last checked-in version.
+
+@item C-x v c
+Remove the last-entered change from the master for the visited file.
+This undoes your last check-in.
+@end table
+
+@kindex C-x v u
+@findex vc-revert-buffer
+ If you want to discard your current set of changes and revert to the
+last version checked in, use @kbd{C-x v u} (@code{vc-revert-buffer}).
+This leaves the file unlocked; if locking is in use, you must first lock
+the file again before you change it again. @kbd{C-x v u} requires
+confirmation, unless it sees that you haven't made any changes since the
+last checked-in version.
+
+ @kbd{C-x v u} is also the command to unlock a file if you lock it and
+then decide not to change it.
+
+@kindex C-x v c
+@findex vc-cancel-version
+ To cancel a change that you already checked in, use @kbd{C-x v c}
+(@code{vc-cancel-version}). This command discards all record of the
+most recent checked-in version. @kbd{C-x v c} also offers to revert
+your work file and buffer to the previous version (the one that precedes
+the version that is deleted).
+
+ If you answer @kbd{no}, VC keeps your changes in the buffer, and locks
+the file. The no-revert option is useful when you have checked in a
+change and then discover a trivial error in it; you can cancel the
+erroneous check-in, fix the error, and check the file in again.
+
+ When @kbd{C-x v c} does not revert the buffer, it unexpands all
+version control headers in the buffer instead (@pxref{Version Headers}).
+This is because the buffer no longer corresponds to any existing
+version. If you check it in again, the check-in process will expand the
+headers properly for the new version number.
+
+ However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header
+automatically. If you use that header feature, you have to unexpand it
+by hand---by deleting the entry for the version that you just canceled.
+
+ Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of
+work with it. To help you be careful, this command always requires
+confirmation with @kbd{yes}. Note also that this command is disabled
+under CVS, because canceling versions is very dangerous and discouraged
+with CVS.
+
+@node VC Dired Mode
+@subsubsection Dired under VC
+
+@kindex C-x v d
+@findex vc-directory
+ When you are working on a large program, it is often useful to find
+out which files have changed within an entire directory tree, or to view
+the status of all files under version control at once, and to perform
+version control operations on collections of files. You can use the
+command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing
+that includes only files relevant for version control.
+
+@vindex vc-dired-terse-display
+ @kbd{C-x v d} creates a buffer which uses VC Dired Mode. This looks
+much like an ordinary Dired buffer (@pxref{Dired}); however, normally it
+shows only the noteworthy files (those locked or not up-to-date). This
+is called @dfn{terse display}. If you set the variable
+@code{vc-dired-terse-display} to @code{nil}, then VC Dired shows all
+relevant files---those managed under version control, plus all
+subdirectories (@dfn{full display}). The command @kbd{v t} in a VC
+Dired buffer toggles between terse display and full display (@pxref{VC
+Dired Commands}).
+
+@vindex vc-dired-recurse
+ By default, VC Dired produces a recursive listing of noteworthy or
+relevant files at or below the given directory. You can change this by
+setting the variable @code{vc-dired-recurse} to @code{nil}; then VC
+Dired shows only the files in the given directory.
+
+ The line for an individual file shows the version control state in the
+place of the hard link count, owner, group, and size of the file. If
+the file is unmodified, in sync with the master file, the version
+control state shown is blank. Otherwise it consists of text in
+parentheses. Under RCS and SCCS, the name of the user locking the file
+is shown; under CVS, an abbreviated version of the @samp{cvs status}
+output is used. Here is an example using RCS:
+
+@smallexample
+@group
+ /home/jim/project:
+
+ -rw-r--r-- (jim) Apr 2 23:39 file1
+ -r--r--r-- Apr 5 20:21 file2
+@end group
+@end smallexample
+
+@noindent
+The files @samp{file1} and @samp{file2} are under version control,
+@samp{file1} is locked by user jim, and @samp{file2} is unlocked.
+
+ Here is an example using CVS:
+
+@smallexample
+@group
+ /home/joe/develop:
+
+ -rw-r--r-- (modified) Aug 2 1997 file1.c
+ -rw-r--r-- Apr 4 20:09 file2.c
+ -rw-r--r-- (merge) Sep 13 1996 file3.c
+@end group
+@end smallexample
+
+ Here @samp{file1.c} is modified with respect to the repository, and
+@samp{file2.c} is not. @samp{file3.c} is modified, but other changes
+have also been checked in to the repository---you need to merge them
+with the work file before you can check it in.
+
+@vindex vc-directory-exclusion-list
+ When VC Dired displays subdirectories (in the ``full'' display mode),
+it omits some that should never contain any files under version control.
+By default, this includes Version Control subdirectories such as
+@samp{RCS} and @samp{CVS}; you can customize this by setting the
+variable @code{vc-directory-exclusion-list}.
+
+ You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in
+ordinary Dired, that allows you to specify additional switches for the
+@samp{ls} command.
+
+@node VC Dired Commands
+@subsubsection VC Dired Commands
+
+ All the usual Dired commands work normally in VC Dired mode, except
+for @kbd{v}, which is redefined as the version control prefix. You can
+invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by
+typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply
+to the file name on the current line.
+
+ The command @kbd{v v} (@code{vc-next-action}) operates on all the
+marked files, so that you can lock or check in several files at once.
+If it operates on more than one file, it handles each file according to
+its current state; thus, it might lock one file, but check in another
+file. This could be confusing; it is up to you to avoid confusing
+behavior by marking a set of files that are in a similar state.
+
+ If any files call for check-in, @kbd{v v} reads a single log entry,
+then uses it for all the files being checked in. This is convenient for
+registering or checking in several files at once, as part of the same
+change.
+
+@findex vc-dired-toggle-terse-mode
+@findex vc-dired-mark-locked
+ You can toggle between terse display (only locked files, or files not
+up-to-date) and full display at any time by typing @kbd{v t}
+@code{vc-dired-toggle-terse-mode}. There is also a special command
+@kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently
+locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l
+t k} is another way to delete from the buffer all files except those
+currently locked.
+
+@node Branches
+@subsection Multiple Branches of a File
+@cindex branch (version control)
+@cindex trunk (version control)
+
+ One use of version control is to maintain multiple ``current''
+versions of a file. For example, you might have different versions of a
+program in which you are gradually adding various unfinished new
+features. Each such independent line of development is called a
+@dfn{branch}. VC allows you to create branches, switch between
+different branches, and merge changes from one branch to another.
+Please note, however, that branches are only supported for RCS at the
+moment.
+
+ A file's main line of development is usually called the @dfn{trunk}.
+The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At
+any such version, you can start an independent branch. A branch
+starting at version 1.2 would have version number 1.2.1.1, and consecutive
+versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4,
+and so on. If there is a second branch also starting at version 1.2, it
+would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
+
+@cindex head version
+ If you omit the final component of a version number, that is called a
+@dfn{branch number}. It refers to the highest existing version on that
+branch---the @dfn{head version} of that branch. The branches in the
+example above have branch numbers 1.2.1 and 1.2.2.
+
+@menu
+* Switching Branches:: How to get to another existing branch.
+* Creating Branches:: How to start a new branch.
+* Merging:: Transferring changes between branches.
+* Multi-User Branching:: Multiple users working at multiple branches
+ in parallel.
+@end menu
+
+@node Switching Branches
+@subsubsection Switching between Branches
+
+ To switch between branches, type @kbd{C-u C-x C-q} and specify the
+version number you want to select. This version is then visited
+@emph{unlocked} (write-protected), so you can examine it before locking
+it. Switching branches in this way is allowed only when the file is not
+locked.
+
+ You can omit the minor version number, thus giving only the branch
+number; this takes you to the head version on the chosen branch. If you
+only type @key{RET}, Emacs goes to the highest version on the trunk.
+
+ After you have switched to any branch (including the main branch), you
+stay on it for subsequent VC commands, until you explicitly select some
+other branch.
+
+@node Creating Branches
+@subsubsection Creating New Branches
+
+ To create a new branch from a head version (one that is the latest in
+the branch that contains it), first select that version if necessary,
+lock it with @kbd{C-x C-q}, and make whatever changes you want. Then,
+when you check in the changes, use @kbd{C-u C-x C-q}. This lets you
+specify the version number for the new version. You should specify a
+suitable branch number for a branch starting at the current version.
+For example, if the current version is 2.5, the branch number should be
+2.5.1, 2.5.2, and so on, depending on the number of existing branches at
+that point.
+
+ To create a new branch at an older version (one that is no longer the
+head of a branch), first select that version (@pxref{Switching
+Branches}), then lock it with @kbd{C-x C-q}. You'll be asked to
+confirm, when you lock the old version, that you really mean to create a
+new branch---if you say no, you'll be offered a chance to lock the
+latest version instead.
+
+ Then make your changes and type @kbd{C-x C-q} again to check in a new
+version. This automatically creates a new branch starting from the
+selected version. You need not specially request a new branch, because
+that's the only way to add a new version at a point that is not the head
+of a branch.
+
+ After the branch is created, you ``stay'' on it. That means that
+subsequent check-ins create new versions on that branch. To leave the
+branch, you must explicitly select a different version with @kbd{C-u C-x
+C-q}. To transfer changes from one branch to another, use the merge
+command, described in the next section.
+
+@node Merging
+@subsubsection Merging Branches
+
+@cindex merging changes
+ When you have finished the changes on a certain branch, you will
+often want to incorporate them into the file's main line of development
+(the trunk). This is not a trivial operation, because development might
+also have proceeded on the trunk, so that you must @dfn{merge} the
+changes into a file that has already been changed otherwise. VC allows
+you to do this (and other things) with the @code{vc-merge} command.
+
+@table @kbd
+@item C-x v m (vc-merge)
+Merge changes into the work file.
+@end table
+
+@kindex C-x v m
+@findex vc-merge
+ @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
+into the current version of the work file. It first asks you for a
+branch number or a pair of version numbers in the minibuffer. Then it
+finds the changes from that branch, or between the two versions you
+specified, and merges them into the current version of the current file.
+
+ As an example, suppose that you have finished a certain feature on
+branch 1.3.1. In the meantime, development on the trunk has proceeded
+to version 1.5. To merge the changes from the branch to the trunk,
+first go to the head version of the trunk, by typing @kbd{C-u C-x C-q
+RET}. Version 1.5 is now current. If locking is used for the file,
+type @kbd{C-x C-q} to lock version 1.5 so that you can change it. Next,
+type @kbd{C-x v m 1.3.1 RET}. This takes the entire set of changes on
+branch 1.3.1 (relative to version 1.3, where the branch started, up to
+the last version on the branch) and merges it into the current version
+of the work file. You can now check in the changed file, thus creating
+version 1.6 containing the changes from the branch.
+
+ It is possible to do further editing after merging the branch, before
+the next check-in. But it is usually wiser to check in the merged
+version, then lock it and make the further changes. This will keep
+a better record of the history of changes.
+
+@cindex conflicts
+@cindex resolving conflicts
+ When you merge changes into a file that has itself been modified, the
+changes might overlap. We call this situation a @dfn{conflict}, and
+reconciling the conflicting changes is called @dfn{resolving a
+conflict}.
+
+ Whenever conflicts occur during merging, VC detects them, tells you
+about them in the echo area, and asks whether you want help in merging.
+If you say yes, it starts an Ediff session (@pxref{Top,
+Ediff, Ediff, ediff, The Ediff Manual}).
+
+ If you say no, the conflicting changes are both inserted into the
+file, surrounded by @dfn{conflict markers}. The example below shows how
+a conflict region looks; the file is called @samp{name} and the current
+master file version with user B's changes in it is 1.11.
+
+@c @w here is so CVS won't think this is a conflict.
+@smallexample
+@group
+@w{<}<<<<<< name
+ @var{User A's version}
+=======
+ @var{User B's version}
+@w{>}>>>>>> 1.11
+@end group
+@end smallexample
+
+@cindex vc-resolve-conflicts
+ Then you can resolve the conflicts by editing the file manually. Or
+you can type @code{M-x vc-resolve-conflicts} after visiting the file.
+This starts an Ediff session, as described above.
+
+@node Multi-User Branching
+@subsubsection Multi-User Branching
+
+ It is often useful for multiple developers to work simultaneously on
+different branches of a file. CVS allows this by default; for RCS, it
+is possible if you create multiple source directories. Each source
+directory should have a link named @file{RCS} which points to a common
+directory of RCS master files. Then each source directory can have its
+own choice of selected versions, but all share the same common RCS
+records.
+
+ This technique works reliably and automatically, provided that the
+source files contain RCS version headers (@pxref{Version Headers}). The
+headers enable Emacs to be sure, at all times, which version number is
+present in the work file.
+
+ If the files do not have version headers, you must instead tell Emacs
+explicitly in each session which branch you are working on. To do this,
+first find the file, then type @kbd{C-u C-x C-q} and specify the correct
+branch number. This ensures that Emacs knows which branch it is using
+during this particular editing session.
+
+@node Snapshots
+@subsection Snapshots
+@cindex snapshots and version control
+
+ A @dfn{snapshot} is a named set of file versions (one for each
+registered file) that you can treat as a unit. One important kind of
+snapshot is a @dfn{release}, a (theoretically) stable version of the
+system that is ready for distribution to users.
+
+@menu
+* Making Snapshots:: The snapshot facilities.
+* Snapshot Caveats:: Things to be careful of when using snapshots.
+@end menu
+
+@node Making Snapshots
+@subsubsection Making and Using Snapshots
+
+ There are two basic commands for snapshots; one makes a
+snapshot with a given name, the other retrieves a named snapshot.
+
+@table @code
+@kindex C-x v s
+@findex vc-create-snapshot
+@item C-x v s @var{name} @key{RET}
+Define the last saved versions of every registered file in or under the
+current directory as a snapshot named @var{name}
+(@code{vc-create-snapshot}).
+
+@kindex C-x v r
+@findex vc-retrieve-snapshot
+@item C-x v r @var{name} @key{RET}
+For all registered files at or below the current directory level, select
+whatever versions correspond to the snapshot @var{name}
+(@code{vc-retrieve-snapshot}).
+
+This command reports an error if any files are locked at or below the
+current directory, without changing anything; this is to avoid
+overwriting work in progress.
+@end table
+
+ A snapshot uses a very small amount of resources---just enough to record
+the list of file names and which version belongs to the snapshot. Thus,
+you need not hesitate to create snapshots whenever they are useful.
+
+ You can give a snapshot name as an argument to @kbd{C-x v =} or
+@kbd{C-x v ~} (@pxref{Old Versions}). Thus, you can use it to compare a
+snapshot against the current files, or two snapshots against each other,
+or a snapshot against a named version.
+
+@node Snapshot Caveats
+@subsubsection Snapshot Caveats
+
+@cindex named configurations (RCS)
+ VC's snapshot facilities are modeled on RCS's named-configuration
+support. They use RCS's native facilities for this, so under VC
+snapshots made using RCS are visible even when you bypass VC.
+
+@c worded verbosely to avoid overfull hbox.
+ For SCCS, VC implements snapshots itself. The files it uses contain
+name/file/version-number triples. These snapshots are visible only
+through VC.
+
+ A snapshot is a set of checked-in versions. So make sure that all the
+files are checked in and not locked when you make a snapshot.
+
+ File renaming and deletion can create some difficulties with snapshots.
+This is not a VC-specific problem, but a general design issue in version
+control systems that no one has solved very well yet.
+
+ If you rename a registered file, you need to rename its master along
+with it (the command @code{vc-rename-file} does this automatically). If
+you are using SCCS, you must also update the records of the snapshot, to
+mention the file by its new name (@code{vc-rename-file} does this,
+too). An old snapshot that refers to a master file that no longer
+exists under the recorded name is invalid; VC can no longer retrieve
+it. It would be beyond the scope of this manual to explain enough about
+RCS and SCCS to explain how to update the snapshots by hand.
+
+ Using @code{vc-rename-file} makes the snapshot remain valid for
+retrieval, but it does not solve all problems. For example, some of the
+files in the program probably refer to others by name. At the very
+least, the makefile probably mentions the file that you renamed. If you
+retrieve an old snapshot, the renamed file is retrieved under its new
+name, which is not the name that the makefile expects. So the program
+won't really work as retrieved.
+
+@node Miscellaneous VC
+@subsection Miscellaneous Commands and Features of VC
+
+ This section explains the less-frequently-used features of VC.
+
+@menu
+* Change Logs and VC:: Generating a change log file from log entries.
+* Renaming and VC:: A command to rename both the source and master
+ file correctly.
+* Version Headers:: Inserting version control headers into working files.
+@end menu
+
+@node Change Logs and VC
+@subsubsection Change Logs and VC
+
+ If you use RCS or CVS for a program and also maintain a change log
+file for it (@pxref{Change Log}), you can generate change log entries
+automatically from the version control log entries:
+
+@table @kbd
+@item C-x v a
+@kindex C-x v a
+@findex vc-update-change-log
+Visit the current directory's change log file and, for registered files
+in that directory, create new entries for versions checked in since the
+most recent entry in the change log file.
+(@code{vc-update-change-log}).
+
+This command works with RCS or CVS only, not with SCCS.
+
+@item C-u C-x v a
+As above, but only find entries for the current buffer's file.
+
+@item M-1 C-x v a
+As above, but find entries for all the currently visited files that are
+maintained with version control. This works only with RCS, and it puts
+all entries in the log for the default directory, which may not be
+appropriate.
+@end table
+
+ For example, suppose the first line of @file{ChangeLog} is dated
+1999-04-10, and that the only check-in since then was by Nathaniel
+Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log
+messages that start with `#'.}. Then @kbd{C-x v a} visits
+@file{ChangeLog} and inserts text like this:
+
+@iftex
+@medbreak
+@end iftex
+@smallexample
+@group
+1999-05-22 Nathaniel Bowditch <nat@@apn.org>
+
+ * rcs2log: Ignore log messages that start with `#'.
+@end group
+@end smallexample
+@iftex
+@medbreak
+@end iftex
+
+@noindent
+You can then edit the new change log entry further as you wish.
+
+ Unfortunately, timestamps in ChangeLog files are only dates, so some
+of the new change log entry may duplicate what's already in ChangeLog.
+You will have to remove these duplicates by hand.
+
+ Normally, the log entry for file @file{foo} is displayed as @samp{*
+foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted
+if the text of the log entry starts with @w{@samp{(@var{functionname}):
+}}. For example, if the log entry for @file{vc.el} is
+@samp{(vc-do-command): Check call-process status.}, then the text in
+@file{ChangeLog} looks like this:
+
+@iftex
+@medbreak
+@end iftex
+@smallexample
+@group
+1999-05-06 Nathaniel Bowditch <nat@@apn.org>
+
+ * vc.el (vc-do-command): Check call-process status.
+@end group
+@end smallexample
+@iftex
+@medbreak
+@end iftex
+
+ When @kbd{C-x v a} adds several change log entries at once, it groups
+related log entries together if they all are checked in by the same
+author at nearly the same time. If the log entries for several such
+files all have the same text, it coalesces them into a single entry.
+For example, suppose the most recent check-ins have the following log
+entries:
+
+@flushleft
+@bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.}
+@bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.}
+@bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.}
+@end flushleft
+
+@noindent
+They appear like this in @file{ChangeLog}:
+
+@iftex
+@medbreak
+@end iftex
+@smallexample
+@group
+1999-04-01 Nathaniel Bowditch <nat@@apn.org>
+
+ * vc.texinfo: Fix expansion typos.
+
+ * vc.el, vc-hooks.el: Don't call expand-file-name.
+@end group
+@end smallexample
+@iftex
+@medbreak
+@end iftex
+
+ Normally, @kbd{C-x v a} separates log entries by a blank line, but you
+can mark several related log entries to be clumped together (without an
+intervening blank line) by starting the text of each related log entry
+with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label
+itself is not copied to @file{ChangeLog}. For example, suppose the log
+entries are:
+
+@flushleft
+@bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.}
+@bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.}
+@bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.}
+@end flushleft
+
+@noindent
+Then the text in @file{ChangeLog} looks like this:
+
+@iftex
+@medbreak
+@end iftex
+@smallexample
+@group
+1999-04-01 Nathaniel Bowditch <nat@@apn.org>
+
+ * vc.texinfo: Fix expansion typos.
+ * vc.el, vc-hooks.el: Don't call expand-file-name.
+@end group
+@end smallexample
+@iftex
+@medbreak
+@end iftex
+
+ A log entry whose text begins with @samp{#} is not copied to
+@file{ChangeLog}. For example, if you merely fix some misspellings in
+comments, you can log the change with an entry beginning with @samp{#}
+to avoid putting such trivia into @file{ChangeLog}.
+
+@node Renaming and VC
+@subsubsection Renaming VC Work Files and Master Files
+
+@findex vc-rename-file
+ When you rename a registered file, you must also rename its master
+file correspondingly to get proper results. Use @code{vc-rename-file}
+to rename the source file as you specify, and rename its master file
+accordingly. It also updates any snapshots (@pxref{Snapshots}) that
+mention the file, so that they use the new name; despite this, the
+snapshot thus modified may not completely work (@pxref{Snapshot
+Caveats}).
+
+ You cannot use @code{vc-rename-file} on a file that is locked by
+someone else.
+
+@node Version Headers
+@subsubsection Inserting Version Control Headers
+
+ Sometimes it is convenient to put version identification strings
+directly into working files. Certain special strings called
+@dfn{version headers} are replaced in each successive version by the
+number of that version.
+
+ If you are using RCS, and version headers are present in your working
+files, Emacs can use them to determine the current version and the
+locking state of the files. This is more reliable than referring to the
+master files, which is done when there are no version headers. Note
+that in a multi-branch environment, version headers are necessary to
+make VC behave correctly (@pxref{Multi-User Branching}).
+
+ Searching for version headers is controlled by the variable
+@code{vc-consult-headers}. If it is non-@code{nil}, Emacs searches for
+headers to determine the version number you are editing. Setting it to
+@code{nil} disables this feature.
+
+@kindex C-x v h
+@findex vc-insert-headers
+ You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
+insert a suitable header string.
+
+@table @kbd
+@item C-x v h
+Insert headers in a file for use with your version-control system.
+@end table
+
+@vindex vc-header-alist
+ The default header string is @samp{@w{$}Id$} for RCS and
+@samp{@w{%}W%} for SCCS. You can specify other headers to insert by
+setting the variable @code{vc-header-alist}. Its value is a list of
+elements of the form @code{(@var{program} . @var{string})} where
+@var{program} is @code{RCS} or @code{SCCS} and @var{string} is the
+string to use.
+
+ Instead of a single string, you can specify a list of strings; then
+each string in the list is inserted as a separate header on a line of
+its own.
+
+ It is often necessary to use ``superfluous'' backslashes when writing
+the strings that you put in this variable. This is to prevent the
+string in the constant from being interpreted as a header itself if the
+Emacs Lisp file containing it is maintained with version control.
+
+@vindex vc-comment-alist
+ Each header is inserted surrounded by tabs, inside comment delimiters,
+on a new line at point. Normally the ordinary comment
+start and comment end strings of the current mode are used, but for
+certain modes, there are special comment delimiters for this purpose;
+the variable @code{vc-comment-alist} specifies them. Each element of
+this list has the form @code{(@var{mode} @var{starter} @var{ender})}.
+
+@vindex vc-static-header-alist
+ The variable @code{vc-static-header-alist} specifies further strings
+to add based on the name of the buffer. Its value should be a list of
+elements of the form @code{(@var{regexp} . @var{format})}. Whenever
+@var{regexp} matches the buffer name, @var{format} is inserted as part
+of the header. A header line is inserted for each element that matches
+the buffer name, and for each string specified by
+@code{vc-header-alist}. The header line is made by processing the
+string from @code{vc-header-alist} with the format taken from the
+element. The default value for @code{vc-static-header-alist} is as follows:
+
+@example
+@group
+(("\\.c$" .
+ "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
+#endif /* lint */\n"))
+@end group
+@end example
+
+@noindent
+It specifies insertion of text of this form:
+
+@example
+@group
+
+#ifndef lint
+static char vcid[] = "@var{string}";
+#endif /* lint */
+@end group
+@end example
+
+@noindent
+Note that the text above starts with a blank line.
+
+ If you use more than one version header in a file, put them close
+together in the file. The mechanism in @code{revert-buffer} that
+preserves markers may not handle markers positioned between two version
+headers.
+
+@node Customizing VC
+@subsection Customizing VC
+
+ There are many ways of customizing VC. The options you can set fall
+into four categories, described in the following sections.
+
+@menu
+* Backend Options:: Customizing the back-end to your needs.
+* VC Workfile Handling:: Various options concerning working files.
+* VC Status Retrieval:: How VC finds the version control status of a file,
+ and how to customize this.
+* VC Command Execution:: Which commands VC should run, and how.
+@end menu
+
+@node Backend Options
+@subsubsection Options for VC Backends
+
+@cindex backend options (VC)
+@cindex locking under version control
+ You can tell RCS and CVS whether to use locking for a file or not
+(@pxref{VC Concepts}, for a description of locking). VC automatically
+recognizes what you have chosen, and behaves accordingly.
+
+@cindex non-strict locking (RCS)
+@cindex locking, non-strict (RCS)
+ For RCS, the default is to use locking, but there is a mode called
+@dfn{non-strict locking} in which you can check-in changes without
+locking the file first. Use @samp{rcs -U} to switch to non-strict
+locking for a particular file, see the @samp{rcs} manpage for details.
+
+@cindex locking (CVS)
+ Under CVS, the default is not to use locking; anyone can change a work
+file at any time. However, there are ways to restrict this, resulting
+in behavior that resembles locking.
+
+@cindex CVSREAD environment variable (CVS)
+ For one thing, you can set the @code{CVSREAD} environment variable to
+an arbitrary value. If this variable is defined, CVS makes your work
+files read-only by default. In Emacs, you must type @kbd{C-x C-q} to
+make the file writeable, so that editing works in fact similar as if
+locking was used. Note however, that no actual locking is performed, so
+several users can make their files writeable at the same time. When
+setting @code{CVSREAD} for the first time, make sure to check out all
+your modules anew, so that the file protections are set correctly.
+
+@cindex cvs watch feature
+@cindex watching files (CVS)
+ Another way to achieve something similar to locking is to use the
+@dfn{watch} feature of CVS. If a file is being watched, CVS makes it
+read-only by default, and you must also use @kbd{C-x C-q} in Emacs to
+make it writable. VC calls @code{cvs edit} to make the file writeable,
+and CVS takes care to notify other developers of the fact that you
+intend to change the file. See the CVS documentation for details on
+using the watch feature.
+
+@vindex vc-handle-cvs
+ You can turn off use of VC for CVS-managed files by setting the
+variable @code{vc-handle-cvs} to @code{nil}. If you do this, Emacs
+treats these files as if they were not registered, and the VC commands
+are not available for them. You must do all CVS operations manually.
+
+@node VC Workfile Handling
+@subsubsection VC Workfile Handling
+
+@vindex vc-make-backup-files
+ Emacs normally does not save backup files for source files that are
+maintained with version control. If you want to make backup files even
+for files that use version control, set the variable
+@code{vc-make-backup-files} to a non-@code{nil} value.
+
+@vindex vc-keep-workfiles
+ Normally the work file exists all the time, whether it is locked or
+not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking
+in a new version with @kbd{C-x C-q} deletes the work file; but any
+attempt to visit the file with Emacs creates it again. (With CVS, work
+files are always kept.)
+
+@vindex vc-follow-symlinks
+ Editing a version-controlled file through a symbolic link can be
+dangerous. It bypasses the version control system---you can edit the
+file without locking it, and fail to check your changes in. Also,
+your changes might overwrite those of another user. To protect against
+this, VC checks each symbolic link that you visit, to see if it points
+to a file under version control.
+
+ The variable @code{vc-follow-symlinks} controls what to do when a
+symbolic link points to a version-controlled file. If it is @code{nil},
+VC only displays a warning message. If it is @code{t}, VC automatically
+follows the link, and visits the real file instead, telling you about
+this in the echo area. If the value is @code{ask} (the default), VC
+asks you each time whether to follow the link.
+
+@node VC Status Retrieval
+@subsubsection VC Status Retrieval
+@c There is no need to tell users about vc-master-templates.
+
+ When deducing the locked/unlocked state of a file, VC first looks for
+an RCS version header string in the file (@pxref{Version Headers}). If
+there is no header string, or if you are using SCCS, VC normally looks
+at the file permissions of the work file; this is fast. But there might
+be situations when the file permissions cannot be trusted. In this case
+the master file has to be consulted, which is rather expensive. Also
+the master file can only tell you @emph{if} there's any lock on the
+file, but not whether your work file really contains that locked
+version.
+
+@vindex vc-consult-headers
+ You can tell VC not to use version headers to determine lock status by
+setting @code{vc-consult-headers} to @code{nil}. VC then always uses
+the file permissions (if it can trust them), or else checks the master
+file.
+
+@vindex vc-mistrust-permissions
+ You can specify the criterion for whether to trust the file
+permissions by setting the variable @code{vc-mistrust-permissions}. Its
+value can be @code{t} (always mistrust the file permissions and check
+the master file), @code{nil} (always trust the file permissions), or a
+function of one argument which makes the decision. The argument is the
+directory name of the @file{RCS}, @file{CVS} or @file{SCCS}
+subdirectory. A non-@code{nil} value from the function says to mistrust
+the file permissions. If you find that the file permissions of work
+files are changed erroneously, set @code{vc-mistrust-permissions} to
+@code{t}. Then VC always checks the master file to determine the file's
+status.
+
+@node VC Command Execution
+@subsubsection VC Command Execution
+
+@vindex vc-suppress-confirm
+ If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x C-q}
+and @kbd{C-x v i} can save the current buffer without asking, and
+@kbd{C-x v u} also operates without asking for confirmation. (This
+variable does not affect @kbd{C-x v c}; that operation is so drastic
+that it should always ask for confirmation.)
+
+@vindex vc-command-messages
+ VC mode does much of its work by running the shell commands for RCS,
+CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC
+displays messages to indicate which shell commands it runs, and
+additional messages when the commands finish.
+
+@vindex vc-path
+ You can specify additional directories to search for version control
+programs by setting the variable @code{vc-path}. These directories are
+searched before the usual search path. But the proper files are usually
+found automatically.
+
+@node Directories
+@section File Directories
+
+@cindex file directory
+@cindex directory listing
+ The file system groups files into @dfn{directories}. A @dfn{directory
+listing} is a list of all the files in a directory. Emacs provides
+commands to create and delete directories, and to make directory
+listings in brief format (file names only) and verbose format (sizes,
+dates, and authors included). There is also a directory browser called
+Dired; see @ref{Dired}.
+
+@table @kbd
+@item C-x C-d @var{dir-or-pattern} @key{RET}
+Display a brief directory listing (@code{list-directory}).
+@item C-u C-x C-d @var{dir-or-pattern} @key{RET}
+Display a verbose directory listing.
+@item M-x make-directory @key{RET} @var{dirname} @key{RET}
+Create a new directory named @var{dirname}.
+@item M-x delete-directory @key{RET} @var{dirname} @key{RET}
+Delete the directory named @var{dirname}. It must be empty,
+or you get an error.
+@end table
+
+@findex list-directory
+@kindex C-x C-d
+ The command to display a directory listing is @kbd{C-x C-d}
+(@code{list-directory}). It reads using the minibuffer a file name
+which is either a directory to be listed or a wildcard-containing
+pattern for the files to be listed. For example,
+
+@example
+C-x C-d /u2/emacs/etc @key{RET}
+@end example
+
+@noindent
+lists all the files in directory @file{/u2/emacs/etc}. Here is an
+example of specifying a file name pattern:
+
+@example
+C-x C-d /u2/emacs/src/*.c @key{RET}
+@end example
+
+ Normally, @kbd{C-x C-d} prints a brief directory listing containing
+just file names. A numeric argument (regardless of value) tells it to
+make a verbose listing including sizes, dates, and authors (like
+@samp{ls -l}).
+
+@vindex list-directory-brief-switches
+@vindex list-directory-verbose-switches
+ The text of a directory listing is obtained by running @code{ls} in an
+inferior process. Two Emacs variables control the switches passed to
+@code{ls}: @code{list-directory-brief-switches} is a string giving the
+switches to use in brief listings (@code{"-CF"} by default), and
+@code{list-directory-verbose-switches} is a string giving the switches to
+use in a verbose listing (@code{"-l"} by default).
+
+@node Comparing Files
+@section Comparing Files
+@cindex comparing files
+
+@findex diff
+@vindex diff-switches
+ The command @kbd{M-x diff} compares two files, displaying the
+differences in an Emacs buffer named @samp{*Diff*}. It works by running
+the @code{diff} program, using options taken from the variable
+@code{diff-switches}, whose value should be a string.
+
+ The buffer @samp{*Diff*} has Compilation mode as its major mode, so
+you can use @kbd{C-x `} to visit successive changed locations in the two
+source files. You can also move to a particular hunk of changes and
+type @key{RET} or @kbd{C-c C-c}, or click @kbd{Mouse-2} on it, to move
+to the corresponding source location. You can also use the other
+special commands of Compilation mode: @key{SPC} and @key{DEL} for
+scrolling, and @kbd{M-p} and @kbd{M-n} for cursor motion.
+@xref{Compilation}.
+
+@findex diff-backup
+ The command @kbd{M-x diff-backup} compares a specified file with its most
+recent backup. If you specify the name of a backup file,
+@code{diff-backup} compares it with the source file that it is a backup
+of.
+
+@findex compare-windows
+ The command @kbd{M-x compare-windows} compares the text in the current
+window with that in the next window. Comparison starts at point in each
+window, and each starting position is pushed on the mark ring in its
+respective buffer. Then point moves forward in each window, a character
+at a time, until a mismatch between the two windows is reached. Then
+the command is finished. For more information about windows in Emacs,
+@ref{Windows}.
+
+@vindex compare-ignore-case
+ With a numeric argument, @code{compare-windows} ignores changes in
+whitespace. If the variable @code{compare-ignore-case} is
+non-@code{nil}, it ignores differences in case as well.
+
+ See also @ref{Emerge}, for convenient facilities for merging two
+similar files.
+
+@node Misc File Ops
+@section Miscellaneous File Operations
+
+ Emacs has commands for performing many other operations on files.
+All operate on one file; they do not accept wildcard file names.
+
+@findex view-file
+@cindex viewing
+@cindex View mode
+@cindex mode, View
+ @kbd{M-x view-file} allows you to scan or read a file by sequential
+screenfuls. It reads a file name argument using the minibuffer. After
+reading the file into an Emacs buffer, @code{view-file} displays the
+beginning. You can then type @key{SPC} to scroll forward one windowful,
+or @key{DEL} to scroll backward. Various other commands are provided
+for moving around in the file, but none for changing it; type @kbd{?}
+while viewing for a list of them. They are mostly the same as normal
+Emacs cursor motion commands. To exit from viewing, type @kbd{q}.
+The commands for viewing are defined by a special major mode called View
+mode.
+
+ A related command, @kbd{M-x view-buffer}, views a buffer already present
+in Emacs. @xref{Misc Buffer}.
+
+@findex insert-file
+ @kbd{M-x insert-file} inserts a copy of the contents of the specified
+file into the current buffer at point, leaving point unchanged before the
+contents and the mark after them.
+
+@findex write-region
+ @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
+copies the contents of the region into the specified file. @kbd{M-x
+append-to-file} adds the text of the region to the end of the specified
+file. @xref{Accumulating Text}.
+
+@findex delete-file
+@cindex deletion (of files)
+ @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
+command in the shell. If you are deleting many files in one directory, it
+may be more convenient to use Dired (@pxref{Dired}).
+
+@findex rename-file
+ @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
+the minibuffer, then renames file @var{old} as @var{new}. If a file named
+@var{new} already exists, you must confirm with @kbd{yes} or renaming is not
+done; this is because renaming causes the old meaning of the name @var{new}
+to be lost. If @var{old} and @var{new} are on different file systems, the
+file @var{old} is copied and deleted.
+
+@findex add-name-to-file
+ The similar command @kbd{M-x add-name-to-file} is used to add an
+additional name to an existing file without removing its old name.
+The new name must belong on the same file system that the file is on.
+
+@findex copy-file
+@cindex copying files
+ @kbd{M-x copy-file} reads the file @var{old} and writes a new file named
+@var{new} with the same contents. Confirmation is required if a file named
+@var{new} already exists, because copying has the consequence of overwriting
+the old contents of the file @var{new}.
+
+@findex make-symbolic-link
+ @kbd{M-x make-symbolic-link} reads two file names @var{target} and
+@var{linkname}, then creates a symbolic link named @var{linkname} and
+pointing at @var{target}. The effect is that future attempts to open file
+@var{linkname} will refer to whatever file is named @var{target} at the
+time the opening is done, or will get an error if the name @var{target} is
+not in use at that time. This command does not expand the argument
+@var{target}, so that it allows you to specify a relative name
+as the target of the link.
+
+ Confirmation is required when creating the link if @var{linkname} is
+in use. Note that not all systems support symbolic links.
+
+@node Compressed Files
+@section Accessing Compressed Files
+@cindex compression
+@cindex uncompression
+@cindex Auto Compression mode
+@cindex mode, Auto Compression
+@pindex gzip
+
+@findex auto-compression-mode
+ Emacs comes with a library that can automatically uncompress
+compressed files when you visit them, and automatically recompress them
+if you alter them and save them. To enable this feature, type the
+command @kbd{M-x auto-compression-mode}.
+
+ When automatic compression (which implies automatic uncompression as
+well) is enabled, Emacs recognizes compressed files by their file names.
+File names ending in @samp{.gz} indicate a file compressed with
+@code{gzip}. Other endings indicate other compression programs.
+
+ Automatic uncompression and compression apply to all the operations in
+which Emacs uses the contents of a file. This includes visiting it,
+saving it, inserting its contents into a buffer, loading it, and byte
+compiling it.
+
+@node Remote Files
+@section Remote Files
+
+@cindex FTP
+@cindex remote file access
+ You can refer to files on other machines using a special file name syntax:
+
+@example
+@group
+/@var{host}:@var{filename}
+/@var{user}@@@var{host}:@var{filename}
+@end group
+@end example
+
+@noindent
+When you do this, Emacs uses the FTP program to read and write files on
+the specified host. It logs in through FTP using your user name or the
+name @var{user}. It may ask you for a password from time to time; this
+is used for logging in on @var{host}.
+
+@cindex ange-ftp
+@vindex ange-ftp-default-user
+ Normally, if you do not specify a user name in a remote file name,
+that means to use your own user name. But if you set the variable
+@code{ange-ftp-default-user} to a string, that string is used instead.
+(The Emacs package that implements FTP file access is called
+@code{ange-ftp}.)
+
+@vindex file-name-handler-alist
+ You can entirely turn off the FTP file name feature by setting the
+variable @code{file-name-handler-alist} to @code{nil}.
+
+@node Quoted File Names
+@section Quoted File Names
+
+@cindex quoting file names
+ You can @dfn{quote} an absolute file name to prevent special
+characters and syntax in it from having their special effects.
+The way to do this is to add @samp{/:} at the beginning.
+
+ For example, you can quote a local file name which appears remote, to
+prevent it from being treated as a remote file name. Thus, if you have
+a directory named @file{/foo:} and a file named @file{bar} in it, you
+can refer to that file in Emacs as @samp{/:/foo:/bar}.
+
+ @samp{/:} can also prevent @samp{~} from being treated as a special
+character for a user's home directory. For example, @file{/:/tmp/~hack}
+refers to a file whose name is @file{~hack} in directory @file{/tmp}.
+
+ Likewise, quoting with @samp{/:} is one way to enter in the minibuffer
+a file name that contains @samp{$}. However, the @samp{/:} must be at
+the beginning of the buffer in order to quote @samp{$}.
+
+ You can also quote wildcard characters with @samp{/:}, for visiting.
+For example, @file{/:/tmp/foo*bar} visits the file @file{/tmp/foo*bar}.
+However, in most cases you can simply type the wildcard characters for
+themselves. For example, if the only file name in @file{/tmp} that
+starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, then
+specifying @file{/tmp/foo*bar} will visit just @file{/tmp/foo*bar}.
+
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Fixit, Files, Search, Top
+@chapter Commands for Fixing Typos
+@cindex typos, fixing
+@cindex mistakes, correcting
+
+ In this chapter we describe the commands that are especially useful for
+the times when you catch a mistake in your text just after you have made
+it, or change your mind while composing text on the fly.
+
+ The most fundamental command for correcting erroneous editing is the
+undo command, @kbd{C-x u} or @kbd{C-_}. This command undoes a single
+command (usually), a part of a command (in the case of
+@code{query-replace}), or several consecutive self-inserting characters.
+Consecutive repetitions of @kbd{C-_} or @kbd{C-x u} undo earlier and
+earlier changes, back to the limit of the undo information available.
+@xref{Undo}, for for more information.
+
+@menu
+* Kill Errors:: Commands to kill a batch of recently entered text.
+* Transpose:: Exchanging two characters, words, lines, lists...
+* Fixing Case:: Correcting case of last word entered.
+* Spelling:: Apply spelling checker to a word, or a whole file.
+@end menu
+
+@node Kill Errors
+@section Killing Your Mistakes
+
+@table @kbd
+@item @key{DEL}
+Delete last character (@code{delete-backward-char}).
+@item M-@key{DEL}
+Kill last word (@code{backward-kill-word}).
+@item C-x @key{DEL}
+Kill to beginning of sentence (@code{backward-kill-sentence}).
+@end table
+
+ The @key{DEL} character (@code{delete-backward-char}) is the most
+important correction command. It deletes the character before point.
+When @key{DEL} follows a self-inserting character command, you can think
+of it as canceling that command. However, avoid the mistake of thinking
+of @key{DEL} as a general way to cancel a command!
+
+ When your mistake is longer than a couple of characters, it might be
+more convenient to use @kbd{M-@key{DEL}} or @kbd{C-x @key{DEL}}.
+@kbd{M-@key{DEL}} kills back to the start of the last word, and @kbd{C-x
+@key{DEL}} kills back to the start of the last sentence. @kbd{C-x
+@key{DEL}} is particularly useful when you change your mind about the
+phrasing of the text you are writing. @kbd{M-@key{DEL}} and @kbd{C-x
+@key{DEL}} save the killed text for @kbd{C-y} and @kbd{M-y} to
+retrieve. @xref{Yanking}.@refill
+
+ @kbd{M-@key{DEL}} is often useful even when you have typed only a few
+characters wrong, if you know you are confused in your typing and aren't
+sure exactly what you typed. At such a time, you cannot correct with
+@key{DEL} except by looking at the screen to see what you did. Often it
+requires less thought to kill the whole word and start again.
+
+@node Transpose
+@section Transposing Text
+
+@table @kbd
+@item C-t
+Transpose two characters (@code{transpose-chars}).
+@item M-t
+Transpose two words (@code{transpose-words}).
+@item C-M-t
+Transpose two balanced expressions (@code{transpose-sexps}).
+@item C-x C-t
+Transpose two lines (@code{transpose-lines}).
+@end table
+
+@kindex C-t
+@findex transpose-chars
+ The common error of transposing two characters can be fixed, when they
+are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally,
+@kbd{C-t} transposes the two characters on either side of point. When
+given at the end of a line, rather than transposing the last character of
+the line with the newline, which would be useless, @kbd{C-t} transposes the
+last two characters on the line. So, if you catch your transposition error
+right away, you can fix it with just a @kbd{C-t}. If you don't catch it so
+fast, you must move the cursor back to between the two transposed
+characters. If you transposed a space with the last character of the word
+before it, the word motion commands are a good way of getting there.
+Otherwise, a reverse search (@kbd{C-r}) is often the best way.
+@xref{Search}.
+
+
+@kindex C-x C-t
+@findex transpose-lines
+@kindex M-t
+@findex transpose-words
+@kindex C-M-t
+@findex transpose-sexps
+ @kbd{M-t} (@code{transpose-words}) transposes the word before point
+with the word after point. It moves point forward over a word, dragging
+the word preceding or containing point forward as well. The punctuation
+characters between the words do not move. For example, @w{@samp{FOO, BAR}}
+transposes into @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.
+
+ @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for transposing
+two expressions (@pxref{Lists}), and @kbd{C-x C-t} (@code{transpose-lines})
+exchanges lines. They work like @kbd{M-t} except in determining the
+division of the text into syntactic units.
+
+ A numeric argument to a transpose command serves as a repeat count: it
+tells the transpose command to move the character (word, sexp, line)
+before or containing point across several other characters (words,
+sexps, lines). For example, @kbd{C-u 3 C-t} moves the character before
+point forward across three other characters. It would change
+@samp{f@point{}oobar} into @samp{oobf@point{}ar}. This is equivalent to
+repeating @kbd{C-t} three times. @kbd{C-u - 4 M-t} moves the word
+before point backward across four words. @kbd{C-u - C-M-t} would cancel
+the effect of plain @kbd{C-M-t}.@refill
+
+ A numeric argument of zero is assigned a special meaning (because
+otherwise a command with a repeat count of zero would do nothing): to
+transpose the character (word, sexp, line) ending after point with the
+one ending after the mark.
+
+@node Fixing Case
+@section Case Conversion
+
+@table @kbd
+@item M-- M-l
+Convert last word to lower case. Note @kbd{Meta--} is Meta-minus.
+@item M-- M-u
+Convert last word to all upper case.
+@item M-- M-c
+Convert last word to lower case with capital initial.
+@end table
+
+@kindex M-@t{-} M-l
+@kindex M-@t{-} M-u
+@kindex M-@t{-} M-c
+ A very common error is to type words in the wrong case. Because of this,
+the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a
+special feature when used with a negative argument: they do not move the
+cursor. As soon as you see you have mistyped the last word, you can simply
+case-convert it and go on typing. @xref{Case}.@refill
+
+@node Spelling
+@section Checking and Correcting Spelling
+@cindex spelling, checking and correcting
+@cindex checking spelling
+@cindex correcting spelling
+
+ This section describes the commands to check the spelling of a single
+word or of a portion of a buffer. These commands work with the spelling
+checker program Ispell, which is not part of Emacs.
+@ifinfo
+@xref{Top, Ispell, Overview ispell, ispell.info, The Ispell Manual}.
+@end ifinfo
+
+@table @kbd
+@item M-x flyspell-mode
+Enable Flyspell mode, which highlights all misspelled words.
+@item M-$
+Check and correct spelling of the word at point (@code{ispell-word}).
+@item M-@key{TAB}
+Complete the word before point based on the spelling dictionary
+(@code{ispell-complete-word}).
+@item M-x ispell-buffer
+Check and correct spelling of each word in the buffer.
+@item M-x ispell-region
+Check and correct spelling of each word in the region.
+@item M-x ispell-message
+Check and correct spelling of each word in a draft mail message,
+excluding cited material.
+@item M-x ispell-change-dictionary @key{RET} @var{dict} @key{RET}
+Restart the Ispell process, using @var{dict} as the dictionary.
+@item M-x ispell-kill-ispell
+Kill the Ispell subprocess.
+@end table
+
+@cindex Flyspell mode
+@findex flyspell-mode
+ Flyspell mode is a fully-automatic way to check spelling as you edit
+in Emacs. It operates by checking words as you change or insert them.
+When it finds a word that it does not recognize, it highlights that
+word. This does not interfere with your editing, but when you see the
+highlighted word, you can move to it and fix it. Type @kbd{M-x
+flyspell-mode} to enable or disable this mode in the current buffer.
+
+ When Flyspell mode highlights a word as misspelled, you can click on
+it with @kbd{Mouse-2} to display a menu of possible corrections and
+actions. You can also correct the word by editing it manually in any
+way you like.
+
+ The other Emacs spell-checking features check or look up words when
+you give an explicit command to do so. Checking all or part of the
+buffer is useful when you have text that was written outside of this
+Emacs session and might contain any number of misspellings.
+
+@kindex M-$
+@findex ispell-word
+ To check the spelling of the word around or next to point, and
+optionally correct it as well, use the command @kbd{M-$}
+(@code{ispell-word}). If the word is not correct, the command offers
+you various alternatives for what to do about it.
+
+@findex ispell-buffer
+@findex ispell-region
+ To check the entire current buffer, use @kbd{M-x ispell-buffer}. Use
+@kbd{M-x ispell-region} to check just the current region. To check
+spelling in an email message you are writing, use @kbd{M-x
+ispell-message}; that checks the whole buffer, but does not check
+material that is indented or appears to be cited from other messages.
+
+ Each time these commands encounter an incorrect word, they ask you
+what to do. They display a list of alternatives, usually including
+several ``near-misses''---words that are close to the word being
+checked. Then you must type a character. Here are the valid responses:
+
+@table @kbd
+@item @key{SPC}
+Skip this word---continue to consider it incorrect, but don't change it
+here.
+
+@item r @var{new} @key{RET}
+Replace the word (just this time) with @var{new}.
+
+@item R @var{new} @key{RET}
+Replace the word with @var{new}, and do a @code{query-replace} so you
+can replace it elsewhere in the buffer if you wish.
+
+@item @var{digit}
+Replace the word (just this time) with one of the displayed
+near-misses. Each near-miss is listed with a digit; type that digit to
+select it.
+
+@item a
+Accept the incorrect word---treat it as correct, but only in this
+editing session.
+
+@item A
+Accept the incorrect word---treat it as correct, but only in this
+editing session and for this buffer.
+
+@item i
+Insert this word in your private dictionary file so that Ispell will
+consider it correct it from now on, even in future sessions.
+
+@item u
+Insert the lower-case version of this word in your private dictionary
+file.
+
+@item m
+Like @kbd{i}, but you can also specify dictionary completion
+information.
+
+@item l @var{word} @key{RET}
+Look in the dictionary for words that match @var{word}. These words
+become the new list of ``near-misses''; you can select one of them to
+replace with by typing a digit. You can use @samp{*} in @var{word} as a
+wildcard.
+
+@item C-g
+Quit interactive spell checking. You can restart it again afterward
+with @kbd{C-u M-$}.
+
+@item X
+Same as @kbd{C-g}.
+
+@item x
+Quit interactive spell checking and move point back to where it was
+when you started spell checking.
+
+@item q
+Quit interactive spell checking and kill the Ispell subprocess.
+
+@item C-l
+Refresh the screen.
+
+@item C-z
+This key has its normal command meaning (suspend Emacs or iconify this
+frame).
+@end table
+
+@findex ispell-complete-word
+ The command @code{ispell-complete-word}, which is bound to the key
+@kbd{M-@key{TAB}} in Text mode and related modes, shows a list of
+completions based on spelling correction. Insert the beginning of a
+word, and then type @kbd{M-@key{TAB}}; the command displays a completion
+list window. To choose one of the completions listed, click
+@kbd{Mouse-2} on it, or move the cursor there in the completions window
+and type @key{RET}. @xref{Text Mode}.
+
+@ignore
+@findex reload-ispell
+ The first time you use any of the spell checking commands, it starts
+an Ispell subprocess. The first thing the subprocess does is read your
+private dictionary, which defaults to the file @file{~/ispell.words}.
+Words that you ``insert'' with the @kbd{i} command are added to that
+file, but not right away---only at the end of the interactive
+replacement procedure. Use the @kbd{M-x reload-ispell} command to
+reload your private dictionary if you edit the file outside of Ispell.
+@end ignore
+
+@cindex @code{ispell} program
+@findex ispell-kill-ispell
+ Once started, the Ispell subprocess continues to run (waiting for
+something to do), so that subsequent spell checking commands complete
+more quickly. If you want to get rid of the Ispell process, use
+@kbd{M-x ispell-kill-ispell}. This is not usually necessary, since the
+process uses no time except when you do spelling correction.
+
+@vindex ispell-dictionary
+ Ispell uses two dictionaries: the standard dictionary and your private
+dictionary. The variable @code{ispell-dictionary} specifies the file
+name of the standard dictionary to use. A value of @code{nil} says to
+use the default dictionary. The command @kbd{M-x
+ispell-change-dictionary} sets this variable and then restarts the
+Ispell subprocess, so that it will use a different dictionary.
+
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c documentation for forms-mode
+@c Written by Johan Vromans, and edited by Richard Stallman
+
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename ../info/forms
+@settitle Forms Mode User's Manual
+@syncodeindex vr cp
+@syncodeindex fn cp
+@syncodeindex ky cp
+@iftex
+@finalout
+@setchapternewpage odd
+@end iftex
+@c @smallbook
+@comment %**end of header (This is for running Texinfo on a region.)
+
+@dircategory Editors
+@direntry
+* Forms: (forms). Emacs package for editing data bases
+ by filling in forms.
+@end direntry
+
+@ifinfo
+This file documents Forms mode, a form-editing major mode for GNU Emacs.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+@end ifinfo
+
+@iftex
+@titlepage
+@sp 6
+@center @titlefont{Forms Mode User's Manual}
+@sp 4
+@center Forms-Mode version 2
+@sp 1
+@center for GNU Emacs 20.1
+@sp 1
+@center June 1997
+@sp 5
+@center Johan Vromans
+@center @i{jvromans@@squirrel.nl}
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1989, 1997 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+@page
+@end titlepage
+@end iftex
+
+@ifinfo
+@node Top
+@top Forms Mode
+
+Forms mode is an Emacs major mode for working with simple textual data
+bases in a forms-oriented manner. In Forms mode, the information in
+these files is presented in an Emacs window in a user-defined format,
+one record at a time. The user can view records or modify their
+contents.
+
+Forms mode is not a simple major mode, but requires two files to do its
+job: a control file and a data file. The data file holds the
+actual data to be presented. The control file describes
+how to present it.
+
+@menu
+* Forms Example:: An example: editing the password data base.
+* Entering and Exiting Forms Mode::
+ How to visit a file in Forms mode.
+* Forms Commands:: Special commands to use while in Forms mode.
+* Data File Format:: How to format the data file.
+* Control File Format:: How to control forms mode.
+* Format Description:: How to define the forms layout.
+* Modifying Forms Contents:: How to modify.
+* Miscellaneous:: Forms mode messages and other remarks.
+* Error Messages:: List of error messages forms mode can produce.
+* Long Example:: A more complex control file example.
+* Credits:: Thanks everyone.
+* Index:: Index to this manual.
+@end menu
+@end ifinfo
+
+@node Forms Example
+@chapter Forms Example
+
+Let's illustrate Forms mode with an example. Suppose you are looking at
+the @file{/etc/passwd} file, and the screen looks like this:
+
+@example
+====== /etc/passwd ======
+
+User : root Uid: 0 Gid: 1
+
+Name : Super User
+
+Home : /
+
+Shell: /bin/sh
+@end example
+
+As you can see, the familiar fields from the entry for the super user
+are all there, but instead of being colon-separated on one single line,
+they make up a forms.
+
+The contents of the forms consist of the contents of the fields of the
+record (e.g. @samp{root}, @samp{0}, @samp{1}, @samp{Super User})
+interspersed with normal text (e.g @samp{User : }, @samp{Uid: }).
+
+If you modify the contents of the fields, Forms mode will analyze your
+changes and update the file appropriately. You cannot modify the
+interspersed explanatory text (unless you go to some trouble about it),
+because that is marked read-only (@pxref{Text Properties,,, elisp, The
+Emacs Lisp Reference Manual}).
+
+The Forms mode control file specifies the relationship between the
+format of @file{/etc/passwd} and what appears on the screen in Forms
+mode. @xref{Control File Format}.
+
+@node Entering and Exiting Forms Mode
+@chapter Entering and Exiting Forms Mode
+
+@table @kbd
+@findex forms-find-file
+@item M-x forms-find-file @key{RET} @var{control-file} @key{RET}
+Visit a database using Forms mode. Specify the name of the
+@strong{control file}, not the data file!
+
+@findex forms-find-file-other-window
+@item M-x forms-find-file-other-window @key{RET} @var{control-file} @key{RET}
+Similar, but displays the file in another window.
+@end table
+
+The command @code{forms-find-file} evaluates the file
+@var{control-file}, and also visits it in Forms mode. What you see in
+its buffer is not the contents of this file, but rather a single record
+of the corresponding data file that is visited in its own buffer. So
+there are two buffers involved in Forms mode: the @dfn{forms buffer}
+that is initially used to visit the control file and that shows the
+records being browsed, and the @dfn{data buffer} that holds the data
+file being visited. The latter buffer is normally not visible.
+
+Initially, the first record is displayed in the forms buffer.
+The mode line displays the major mode name @samp{Forms}, followed by the
+minor mode @samp{View} if the data base is read-only. The number of the
+current record (@var{n}) and the total number of records in the
+file(@var{t}) are shown in the mode line as @samp{@var{n}/@var{t}}. For
+example:
+
+@example
+--%%-Emacs: passwd-demo (Forms View 1/54)----All-------
+@end example
+
+If the buffer is not read-only, you may change the buffer to modify the
+fields in the record. When you move to a different record, the contents
+of the buffer are parsed using the specifications in
+@code{forms-format-list}, and the data file is updated. If the record
+has fields that aren't included in the display, they are not changed.
+
+@vindex forms-mode-hooks
+Entering Forms mode runs the normal hook @code{forms-mode-hooks} to
+perform user-defined customization.
+
+To save any modified data, you can use @kbd{C-x C-s}
+(@code{forms-save-buffer}). This does not save the forms buffer (which would
+be rather useless), but instead saves the buffer visiting the data file.
+
+To terminate Forms mode, you can use @kbd{C-x C-s} (@code{forms-save-buffer})
+and then kill the forms buffer. However, the data buffer will still
+remain. If this is not desired, you have to kill this buffer too.
+
+@node Forms Commands
+@chapter Forms Commands
+
+The commands of Forms mode belong to the @kbd{C-c} prefix, with one
+exception: @key{TAB}, which moves to the next field. Forms mode uses
+different key maps for normal mode and read-only mode. In read-only
+Forms mode, you can access most of the commands without the @kbd{C-c}
+prefix, but you must type ordinary letters instead of control
+characters; for example, type @kbd{n} instead of @kbd{C-c C-n}.
+
+If your Emacs has been built with X-toolkit support, Forms mode will
+provide its own menu with a number of Forms mode commands.
+
+@table @kbd
+@findex forms-next-record
+@kindex C-c C-n
+@item C-c C-n
+Show the next record (@code{forms-next-record}). With a numeric
+argument @var{n}, show the @var{n}th next record.
+
+@findex forms-prev-record
+@kindex C-c C-p
+@item C-c C-p
+Show the previous record (@code{forms-prev-record}). With a numeric
+argument @var{n}, show the @var{n}th previous record.
+
+@findex forms-jump-record
+@kindex C-c C-l
+@item C-c C-l
+Jump to a record by number (@code{forms-jump-record}). Specify
+the record number with a numeric argument.
+
+@findex forms-first-record
+@kindex C-c <
+@item C-c <
+Jump to the first record (@code{forms-first-record}).
+
+@findex forms-last-record
+@kindex C-c >
+@item C-c >
+Jump to the last record (@code{forms-last-record}). This command also
+recalculates the number of records in the data file.
+
+@findex forms-next-field
+@kindex TAB
+@item @key{TAB}
+@kindex C-c TAB
+@itemx C-c @key{TAB}
+Jump to the next field in the current record (@code{forms-next-field}).
+With a numeric argument @var{n}, jump forward @var{n} fields. If this command
+would move past the last field, it wraps around to the first field.
+
+@findex forms-toggle-read-only
+@kindex C-c C-q
+@item C-c C-q
+Toggles read-only mode (@code{forms-toggle-read-only}). In read-only
+Forms mode, you cannot edit the fields; most Forms mode commands can be
+accessed without the prefix @kbd{C-c} if you use the normal letter
+instead (for example, type @kbd{n} instead of @kbd{C-c C-n}). In edit
+mode, you can edit the fields and thus change the contents of the data
+base; you must begin Forms mode commands with @code{C-c}. Switching
+to edit mode is allowed only if you have write access to the data file.
+
+@findex forms-insert-record
+@kindex C-c C-o
+@item C-c C-o
+Create a new record and insert it before the current record
+(@code{forms-insert-record}). It starts out with empty (or default)
+contents for its fields; you can then edit the fields. With a numeric
+argument, the new record is created @emph{after} the current one.
+See also @code{forms-modified-record-filter} in @ref{Modifying Forms
+Contents}.
+
+@findex forms-delete-record
+@kindex C-c C-k
+@item C-c C-k
+Delete the current record (@code{forms-delete-record}). You are
+prompted for confirmation before the record is deleted unless a numeric
+argument has been provided.
+
+@findex forms-search-forward
+@kindex C-c C-s @var{regexp} @key{RET}
+@item C-c C-s @var{regexp} @key{RET}
+Search forward for @var{regexp} in all records following this one
+(@code{forms-search-forward}). If found, this record is shown.
+If you give an empty argument, the previous regexp is used again.
+
+@findex forms-search-backward
+@kindex C-c C-r @var{regexp} @key{RET}
+@item C-c C-r @var{regexp} @key{RET}
+Search backward for @var{regexp} in all records following this one
+(@code{forms-search-backward}). If found, this record is shown.
+If you give an empty argument, the previous regexp is used again.
+
+@ignore
+@findex forms-exit
+@kindex C-c C-x
+@item C-c C-x
+Terminate Forms mode processing (@code{forms-exit}). The data file is
+saved if it has been modified.
+
+@findex forms-exit-no-save
+@item M-x forms-exit-no-save
+Terminates forms mode processing without saving modified data first.
+@end ignore
+
+@findex forms-prev-field
+@item M-x forms-prev-field
+Similar to @code{forms-next-field} but moves backwards.
+
+@findex forms-save-buffer
+@item M-x forms-save-buffer
+@kindex C-x C-s
+@itemx C-x C-s
+Forms mode replacement for @code{save-buffer}. When executed in the
+forms buffer it will save the contents of the (modified) data buffer
+instead. In Forms mode this function will be bound to @kbd{C-x C-s}.
+
+@findex forms-print
+@item M-x forms-print
+This command can be used to make a formatted print
+of the contents of the data file.
+
+@end table
+
+In addition the command @kbd{M-x revert-buffer} is useful in Forms mode
+just as in other modes.
+
+@ignore
+@vindex forms-forms-scroll
+@findex scroll-up
+@findex scroll-down
+If the variable @code{forms-forms-scrolls} is set to a value other
+than @code{nil} (which it is, by default), the Emacs functions
+@code{scroll-up} and @code{scroll-down} will perform a
+@code{forms-next-record} and @code{forms-prev-record} when in forms
+mode. So you can use your favourite page commands to page through the
+data file.
+
+@vindex forms-forms-jump
+@findex beginning-of-buffer
+@findex end-of-buffer
+Likewise, if the variable @code{forms-forms-jump} is not @code{nil}
+(which it is, by default), Emacs functions @code{beginning-of-buffer}
+and @code{end-of-buffer} will perform @code{forms-first-record} and
+@code{forms-last-record} when in forms mode.
+@end ignore
+
+The following function key definitions are set up in Forms mode
+(whether read-only or not):
+
+@table @kbd
+@kindex next
+@item next
+forms-next-record
+
+@kindex prior
+@item prior
+forms-prev-record
+
+@kindex begin
+@item begin
+forms-first-record
+
+@kindex end
+@item end
+forms-last-record
+
+@kindex S-Tab
+@findex forms-prev-field
+@item S-Tab
+forms-prev-field
+@end table
+
+@node Data File Format
+@chapter Data File Format
+
+@cindex record
+@cindex field
+@vindex forms-field-sep
+Files for use with Forms mode are very simple---each @dfn{record}
+(usually one line) forms the contents of one form. Each record consists
+of a number of @dfn{fields}, which are separated by the value of the
+string @code{forms-field-sep}, which is @code{"\t"} (a Tab) by default.
+
+@vindex forms-read-file-filter
+@vindex forms-write-file-filter
+If the format of the data file is not suitable enough you can define the
+filter functions @code{forms-read-file-filter} and
+@code{forms-write-file-filter}. @code{forms-read-file-filter} is called
+when the data file is read from disk into the data buffer. It operates
+on the data buffer, ignoring read-only protections. When the data file
+is saved to disk @code{forms-write-file-filter} is called to cancel the
+effects of @code{forms-read-file-filter}. After being saved,
+@code{forms-read-file-filter} is called again to prepare the data buffer
+for further processing.
+
+@cindex pseudo-newline
+@vindex forms-multi-line
+Fields may contain text which shows up in the forms in multiple lines.
+These lines are separated in the field using a ``pseudo-newline''
+character which is defined by the value of the string
+@code{forms-multi-line}. Its default value is @code{"\^k"} (a Control-K
+character). If it is
+set to @code{nil}, multiple line fields are prohibited.
+
+If the data file does not exist, it is automatically created.
+
+@node Control File Format
+@chapter Control File Format
+
+@cindex control file
+The Forms mode @dfn{control file} serves two purposes. First, it names
+the data file to use, and defines its format and properties. Second,
+the Emacs buffer it occupies is used by Forms mode to display the forms.
+
+The contents of the control file are evaluated as a Lisp program. It
+should set the following Lisp variables to suitable values:
+
+@table @code
+@vindex forms-file
+@item forms-file
+This variable specifies the name of the data file. Example:
+
+@example
+(setq forms-file "my/data-file")
+@end example
+
+If the control file doesn't set @code{forms-file}, Forms mode
+reports an error.
+
+@vindex forms-format-list
+@item forms-format-list
+This variable describes the way the fields of the record are formatted on
+the screen. For details, see @ref{Format Description}.
+
+@vindex forms-number-of-fields
+@item forms-number-of-fields
+This variable holds the number of fields in each record of the data
+file. Example:
+
+@example
+(setq forms-number-of-fields 10)
+@end example
+@end table
+
+If the control file does not set @code{forms-format-list} a default
+format is used. In this situation, Forms mode will deduce the number of
+fields from the data file providing this file exists and
+@code{forms-number-of-records} has not been set in the control file.
+
+The control file can optionally set the following additional Forms mode
+variables. Most of them have default values that are good for most
+applications.
+
+@table @code
+@vindex forms-field-sep
+@item forms-field-sep
+This variable may be used to designate the string which separates the
+fields in the records of the data file. If not set, it defaults to the
+string @code{"\t"} (a Tab character). Example:
+
+@example
+(setq forms-field-sep "\t")
+@end example
+
+@vindex forms-read-only
+@item forms-read-only
+If the value is non-@code{nil}, the data file is treated read-only. (Forms
+mode also treats the data file as read-only if you don't have access to
+write it.) Example:
+
+@example
+(set forms-read-only t)
+@end example
+
+@vindex forms-multi-line
+@item forms-multi-line
+This variable specifies the @dfn{pseudo newline} separator that allows
+multi-line fields. This separator goes between the ``lines'' within a
+field---thus, the field doesn't really contain multiple lines, but it
+appears that way when displayed in Forms mode. If the value is
+@code{nil}, multi-line text fields are prohibited. The pseudo newline
+must not be a character contained in @code{forms-field-sep}.
+
+The default value is @code{"\^k"}, the character Control-K. Example:
+
+@example
+(setq forms-multi-line "\^k")
+@end example
+
+@ignore
+@vindex forms-forms-scroll
+@item forms-forms-scroll
+@xref{Forms Mode Commands}, for details.
+
+@vindex forms-forms-jump
+@item forms-forms-jump
+@xref{Forms Mode Commands}, for details.
+@end ignore
+
+@findex forms-read-file-filter
+@item forms-read-file-filter
+This variable holds the name of a function to be called after the data
+file has been read in. This can be used to transform the contents of the
+data file into a format more suitable for forms processing.
+If it is @code{nil}, no function is called. For example, to maintain a
+gzipped database:
+
+@example
+(defun gzip-read-file-filter ()
+ (shell-command-on-region (point-min) (point-max)
+ "gzip -d" t t))
+(setq forms-read-file-filter 'gzip-read-file-filter)
+@end example
+
+@findex forms-write-file-filter
+@item forms-write-file-filter
+This variable holds the name of a function to be called before writing
+out the contents of the data file.
+This can be used to undo the effects of @code{forms-read-file-filter}.
+If it is @code{nil}, no function is called. Example:
+
+@example
+(defun gzip-write-file-filter ()
+ (make-variable-buffer-local 'require-final-newline)
+ (setq require-final-newline nil)
+ (shell-command-on-region (point-min) (point-max)
+ "gzip" t t))
+(setq forms-write-file-filter 'gzip-write-file-filter)
+@end example
+
+@findex forms-new-record-filter
+@item forms-new-record-filter
+This variable holds a function to be called whenever a new record is created
+to supply default values for fields. If it is @code{nil}, no function is
+called.
+@xref{Modifying Forms Contents}, for details.
+
+@findex forms-modified-record-filter
+@item forms-modified-record-filter
+This variable holds a function to be called whenever a record is
+modified, just before updating the Forms data file. If it is
+@code{nil}, no function is called.
+@xref{Modifying Forms Contents}, for details.
+
+@findex forms-insert-after
+@item forms-insert-after
+If this variable is not @code{nil}, new records are created @emph{after} the
+current record. Also, upon visiting a file, the initial position will be
+at the last record instead of the first one.
+
+@findex forms-check-number-of-fields
+@item forms-check-number-of-fields
+Normally each record is checked to contain the correct number of fields.
+Under certain circumstances, this can be undesirable.
+If this variable is set to @code{nil}, these checks will be bypassed.
+@end table
+
+@node Format Description
+@chapter The Format Description
+
+@vindex forms-format-list
+ The variable @code{forms-format-list} specifies the format of the data
+in the data file, and how to convert the data for display in Forms mode.
+Its value must be a list of Forms mode @dfn{formatting elements}, each
+of which can be a string, a number, a Lisp list, or a Lisp symbol that
+evaluates to one of those. The formatting elements are processed in the
+order they appear in the list.
+
+@table @var
+@item string
+A string formatting element is inserted in the forms ``as is,'' as text
+that the user cannot alter.
+
+@item number
+A number element selects a field of the record. The contents of this
+field are inserted in the display at this point. Field numbers count
+starting from 1 (one).
+
+@item list
+A formatting element that is a list specifies a function call. This
+function is called every time a record is displayed, and its result,
+which must be a string, is inserted in the display text. The function
+should do nothing but returning a string.
+
+@vindex forms-fields
+The function you call can access the fields of the record as a list in
+the variable
+@code{forms-fields}.
+
+@item symbol
+A symbol used as a formatting element should evaluate to a string, number,
+or list; the value is interpreted as a formatting element, as described
+above.
+@end table
+
+If a record does not contain the number of fields as specified in
+@code{forms-number-of-fields}, a warning message will be printed. Excess
+fields are ignored, missing fields are set to empty.
+
+The control file which displays @file{/etc/passwd} file as demonstrated
+in the beginning of this manual might look as follows:
+
+@example
+;; @r{This demo visits @file{/etc/passwd}.}
+
+(setq forms-file "/etc/passwd")
+(setq forms-number-of-fields 7)
+(setq forms-read-only t) ; @r{to make sure}
+(setq forms-field-sep ":")
+;; @r{Don't allow multi-line fields.}
+(setq forms-multi-line nil)
+
+(setq forms-format-list
+ (list
+ "====== /etc/passwd ======\n\n"
+ "User : " 1
+ " Uid: " 3
+ " Gid: " 4
+ "\n\n"
+ "Name : " 5
+ "\n\n"
+ "Home : " 6
+ "\n\n"
+ "Shell: " 7
+ "\n"))
+@end example
+
+When you construct the value of @code{forms-format-list}, you should
+usually either quote the whole value, like this,
+
+@example
+(setq forms-format-list
+ '(
+ "====== " forms-file " ======\n\n"
+ "User : " 1
+ (make-string 20 ?-)
+ @dots{}
+ ))
+@end example
+
+@noindent
+or quote the elements which are lists, like this:
+
+@example
+(setq forms-format-list
+ (list
+ "====== " forms-file " ======\n\n"
+ "User : " 1
+ '(make-string 20 ?-)
+ @dots{}
+ ))
+@end example
+
+Forms mode validates the contents of @code{forms-format-list} when you
+visit a database. If there are errors, processing is aborted with an
+error message which includes a descriptive text. @xref{Error Messages},
+for a detailed list of error messages.
+
+If no @code{forms-format-list} is specified, Forms mode will supply a
+default format list. This list contains the name of the file being
+visited, and a simple label for each field indicating the field number.
+
+@node Modifying Forms Contents
+@chapter Modifying The Forms Contents
+
+If @code{forms-read-only} is @code{nil}, the user can modify the fields
+and records of the database.
+
+All normal editing commands are available for editing the contents of the
+displayed record. You cannot delete or modify the fixed, explanatory
+text that comes from string formatting elements, but you can modify the
+actual field contents.
+
+@ignore
+@c This is for the Emacs 18 version only.
+If the contents of the forms cannot be recognized properly, this is
+signaled using a descriptive text. @xref{Error Messages}, for more info.
+The cursor will indicate the last part of the forms which was
+successfully parsed. It's important to avoid entering field contents
+that would cause confusion with the field-separating fixed text.
+@end ignore
+
+If the variable @code{forms-modified-record-filter} is non-@code{nil},
+it is called as a function before the new data is written to the data
+file. The function receives one argument, a vector that contains the
+contents of the fields of the record.
+
+The function can refer to fields with @code{aref} and modify them with
+@code{aset}. The first field has number 1 (one); thus, element 0 of the
+vector is not used. The function should return the same vector it was
+passed; the (possibly modified) contents of the vector determine what is
+actually written in the file. Here is an example:
+
+@example
+(defun my-modified-record-filter (record)
+ ;; @r{Modify second field.}
+ (aset record 2 (current-time-string))
+ ;; @r{Return the field vector.}
+ record)
+
+(setq forms-modified-record-filter 'my-modified-record-filter)
+@end example
+
+If the variable @code{forms-new-record-filter} is non-@code{nil}, its
+value is a function to be called to fill in default values for the
+fields of a new record. The function is passed a vector of empty
+strings, one for each field; it should return the same vector, with
+the desired field values stored in it. Fields are numbered starting
+from 1 (one). Example:
+
+@example
+(defun my-new-record-filter (fields)
+ (aset fields 5 (login-name))
+ (aset fields 1 (current-time-string))
+ fields)
+
+(setq forms-new-record-filter 'my-new-record-filter)
+@end example
+
+@node Miscellaneous
+@chapter Miscellaneous
+
+@vindex forms-version
+The global variable @code{forms-version} holds the version information
+of the Forms mode software.
+
+@findex forms-enumerate
+It is very convenient to use symbolic names for the fields in a record.
+The function @code{forms-enumerate} provides an elegant means to define
+a series of variables whose values are consecutive integers. The
+function returns the highest number used, so it can be used to set
+@code{forms-number-of-fields} also. For example:
+
+@example
+(setq forms-number-of-fields
+ (forms-enumerate
+ '(field1 field2 field3 @dots{})))
+@end example
+
+This sets @code{field1} to 1, @code{field2} to 2, and so on.
+
+Care has been taken to keep the Forms mode variables buffer-local, so it
+is possible to visit multiple files in Forms mode simultaneously, even
+if they have different properties.
+
+@findex forms-mode
+If you have visited the control file in normal fashion with
+@code{find-file} or a like command, you can switch to Forms mode with
+the command @code{M-x forms-mode}. If you put @samp{-*- forms -*-} in
+the first line of the control file, then visiting it enables Forms mode
+automatically. But this makes it hard to edit the control file itself,
+so you'd better think twice before using this.
+
+The default format for the data file, using @code{"\t"} to separate
+fields and @code{"\^k"} to separate lines within a field, matches the
+file format of some popular database programs, e.g. FileMaker. So
+@code{forms-mode} can decrease the need to use proprietary software.
+
+@node Error Messages
+@chapter Error Messages
+
+This section describes all error messages which can be generated by
+forms mode. Error messages that result from parsing the control file
+all start with the text @samp{Forms control file error}. Messages
+generated while analyzing the definition of @code{forms-format-list}
+start with @samp{Forms format error}.
+
+@table @code
+@item Forms control file error: `forms-file' has not been set
+The variable @code{forms-file} was not set by the control file.
+
+@item Forms control file error: `forms-number-of-fields' has not been set
+The variable @code{forms-number-of-fields} was not set by the control
+file.
+
+@item Forms control file error: `forms-number-of-fields' must be a number > 0
+The variable @code{forms-number-of-fields} did not contain a positive
+number.
+
+@item Forms control file error: `forms-field-sep' is not a string
+@itemx Forms control file error: `forms-multi-line' must be nil or a one-character string
+The variable @code{forms-multi-line} was set to something other than
+@code{nil} or a single-character string.
+
+@item Forms control file error: `forms-multi-line' is equal to 'forms-field-sep'
+The variable @code{forms-multi-line} may not be equal to
+@code{forms-field-sep} for this would make it impossible to distinguish
+fields and the lines in the fields.
+
+@item Forms control file error: `forms-new-record-filter' is not a function
+@itemx Forms control file error: `forms-modified-record-filter' is not a function
+The variable has been set to something else than a function.
+
+@item Forms control file error: `forms-format-list' is not a list
+The variable @code{forms-format-list} was not set to a Lisp list
+by the control file.
+
+@item Forms format error: field number @var{xx} out of range 1..@var{nn}
+A field number was supplied in @code{forms-format-list} with a value of
+@var{xx}, which was not greater than zero and smaller than or equal to
+the number of fields in the forms, @var{nn}.
+
+@item Forms format error: @var{fun} is not a function
+The first element of a list which is an element of
+@code{forms-format-list} was not a valid Lisp function.
+
+@item Forms format error: invalid element @var{xx}
+A list element was supplied in @code{forms-format-list} which was not a
+string, number or list.
+
+@ignore
+@c This applies to Emacs 18 only.
+@c Error messages generated while a modified form is being analyzed.
+
+@item Parse error: not looking at `...'
+When re-parsing the contents of a forms, the text shown could not
+be found.
+
+@item Parse error: cannot find `...'
+When re-parsing the contents of a forms, the text shown, which
+separates two fields, could not be found.
+
+@item Parse error: cannot parse adjacent fields @var{xx} and @var{yy}
+Fields @var{xx} and @var{yy} were not separated by text, so could not be
+parsed again.
+@end ignore
+
+@item Warning: this record has @var{xx} fields instead of @var{yy}
+The number of fields in this record in the data file did not match
+@code{forms-number-of-fields}. Missing fields will be made empty.
+
+@item Multi-line fields in this record - update refused!
+The current record contains newline characters, hence can not be written
+back to the data file, for it would corrupt it. Probably you inserted a
+newline in a field, while @code{forms-multi-line} was @code{nil}.
+
+@item Field separator occurs in record - update refused!
+The current record contains the field separator string inside one of the
+fields. It can not be written back to the data file, for it would
+corrupt it. Probably you inserted the field separator string in a field.
+
+@item Record number @var{xx} out of range 1..@var{yy}
+A jump was made to non-existing record @var{xx}. @var{yy} denotes the
+number of records in the file.
+
+@item Stuck at record @var{xx}
+An internal error prevented a specific record from being retrieved.
+
+@item No write access to @code{"}@var{file}@code{"}
+An attempt was made to enable edit mode on a file that has been write
+protected.
+
+@item Search failed: @var{regexp}
+The @var{regexp} could not be found in the data file. Forward searching
+is done from the current location until the end of the file, then
+retrying from the beginning of the file until the current location.
+Backward searching is done from the current location until the beginning
+of the file, then retrying from the end of the file until the current
+location.
+
+@item Wrapped
+A search completed successfully after wrapping around.
+
+@item Warning: number of records changed to @var{nn}
+Forms mode's idea of the number of records has been adjusted to the
+number of records actually present in the data file.
+
+@item Problem saving buffers?
+An error occurred while saving the data file buffer. Most likely, Emacs
+did ask to confirm deleting the buffer because it had been modified, and
+you said `no'.
+@end table
+
+@node Long Example
+@chapter Long Example
+
+The following example exploits most of the features of Forms mode.
+This example is included in the distribution as file @file{forms-d2.el}.
+
+@example
+;; demo2 -- demo forms-mode -*- emacs-lisp -*-
+
+;; @r{This sample forms exploit most of the features of forms mode.}
+
+;; @r{Set the name of the data file.}
+(setq forms-file "forms-d2.dat")
+
+;; @r{Use @code{forms-enumerate} to set field names and number thereof.}
+(setq forms-number-of-fields
+ (forms-enumerate
+ '(arch-newsgroup ; 1
+ arch-volume ; 2
+ arch-issue ; and ...
+ arch-article ; ... so
+ arch-shortname ; ... ... on
+ arch-parts
+ arch-from
+ arch-longname
+ arch-keywords
+ arch-date
+ arch-remarks)))
+
+;; @r{The following functions are used by this form for layout purposes.}
+;;
+(defun arch-tocol (target &optional fill)
+ "Produces a string to skip to column TARGET.
+Prepends newline if needed.
+The optional FILL should be a character, used to fill to the column."
+ (if (null fill)
+ (setq fill ? ))
+ (if (< target (current-column))
+ (concat "\n" (make-string target fill))
+ (make-string (- target (current-column)) fill)))
+;;
+(defun arch-rj (target field &optional fill)
+ "Produces a string to skip to column TARGET\
+ minus the width of field FIELD.
+Prepends newline if needed.
+The optional FILL should be a character,
+used to fill to the column."
+ (arch-tocol (- target (length (nth field forms-fields))) fill))
+
+;; @r{Record filters.}
+;;
+(defun new-record-filter (the-record)
+ "Form a new record with some defaults."
+ (aset the-record arch-from (user-full-name))
+ (aset the-record arch-date (current-time-string))
+ the-record) ; return it
+(setq forms-new-record-filter 'new-record-filter)
+
+;; @r{The format list.}
+(setq forms-format-list
+ (list
+ "====== Public Domain Software Archive ======\n\n"
+ arch-shortname
+ " - " arch-longname
+ "\n\n"
+ "Article: " arch-newsgroup
+ "/" arch-article
+ " "
+ '(arch-tocol 40)
+ "Issue: " arch-issue
+ " "
+ '(arch-rj 73 10)
+ "Date: " arch-date
+ "\n\n"
+ "Submitted by: " arch-from
+ "\n"
+ '(arch-tocol 79 ?-)
+ "\n"
+ "Keywords: " arch-keywords
+ "\n\n"
+ "Parts: " arch-parts
+ "\n\n====== Remarks ======\n\n"
+ arch-remarks
+ ))
+
+;; @r{That's all, folks!}
+@end example
+
+@node Credits
+@chapter Credits
+
+Bug fixes and other useful suggestions were supplied by
+Harald Hanche-Olsen (@code{hanche@@imf.unit.no}),
+@code{cwitty@@portia.stanford.edu},
+Jonathan I. Kamens,
+Per Cederqvist (@code{ceder@@signum.se}),
+Michael Lipka (@code{lipka@@lip.hanse.de}),
+Andy Piper (@code{ajp@@eng.cam.ac.uk}),
+Frederic Pierresteguy (@code{F.Pierresteguy@@frcl.bull.fr}),
+Ignatios Souvatzis
+and Richard Stallman (@code{rms@@gnu.org}).
+
+This documentation was slightly inspired by the documentation of ``rolo
+mode'' by Paul Davis at Schlumberger Cambridge Research
+(@code{davis%scrsu1%sdr.slb.com@@relay.cs.net}).
+
+None of this would have been possible without GNU Emacs of the Free
+Software Foundation. Thanks, Richard!
+
+@node Index
+@unnumbered Index
+@printindex cp
+
+@contents
+@bye
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Frames, International, Windows, Top
+@chapter Frames and X Windows
+@cindex frames
+
+ When using the X Window System, you can create multiple windows at the
+X level in a single Emacs session. Each X window that belongs to Emacs
+displays a @dfn{frame} which can contain one or several Emacs windows.
+A frame initially contains a single general-purpose Emacs window which
+you can subdivide vertically or horizontally into smaller windows. A
+frame normally contains its own echo area and minibuffer, but you can
+make frames that don't have these---they use the echo area and
+minibuffer of another frame.
+
+ Editing you do in one frame also affects the other frames. For
+instance, if you put text in the kill ring in one frame, you can yank it
+in another frame. If you exit Emacs through @kbd{C-x C-c} in one frame,
+it terminates all the frames. To delete just one frame, use @kbd{C-x 5
+0}.
+
+ To avoid confusion, we reserve the word ``window'' for the
+subdivisions that Emacs implements, and never use it to refer to a
+frame.
+
+ Emacs compiled for MS-DOS emulates some aspects of the window system
+so that you can use many of the features described in this chapter.
+@xref{MS-DOS Input}, for more information.
+
+@menu
+* Mouse Commands:: Moving, cutting, and pasting, with the mouse.
+* Secondary Selection:: Cutting without altering point and mark.
+* Mouse References:: Using the mouse to select an item from a list.
+* Menu Mouse Clicks:: Mouse clicks that bring up menus.
+* Mode Line Mouse:: Mouse clicks on the mode line.
+* Speedbar:: How to make and use a speedbar frame.
+* Creating Frames:: Creating additional Emacs frames with various contents.
+* Multiple Displays:: How one Emacs job can talk to several displays.
+* Special Buffer Frames:: You can make certain buffers have their own frames.
+* Frame Parameters:: Changing the colors and other modes of frames.
+* Scroll Bars:: How to enable and disable scroll bars; how to use them.
+* Menu Bars:: Enabling and disabling the menu bar.
+* Faces:: How to change the display style using faces.
+* Font Lock:: Minor mode for syntactic highlighting using faces.
+* Support Modes:: Font Lock support modes make Font Lock faster.
+* Highlight Changes:: Using colors to show where you changed the buffer.
+* Misc X:: Iconifying and deleting frames. Region highlighting.
+* Non-Window Terminals:: Multiple frames on terminals that show only one.
+@end menu
+
+@node Mouse Commands
+@section Mouse Commands for Editing
+@cindex mouse buttons (what they do)
+
+ The mouse commands for selecting and copying a region are mostly
+compatible with the @code{xterm} program. You can use the same mouse
+commands for copying between Emacs and other X client programs.
+
+@kindex DELETE
+ If you select a region with any of these mouse commands, and then
+immediately afterward type the @key{DELETE} function key, it deletes the
+region that you selected. The @key{BACKSPACE} function key and the
+ASCII character @key{DEL} do not do this; if you type any other key
+in between the mouse command and @key{DELETE}, it does not do this.
+
+@findex mouse-set-region
+@findex mouse-set-point
+@findex mouse-yank-at-click
+@findex mouse-save-then-click
+@kindex Mouse-1
+@kindex Mouse-2
+@kindex Mouse-3
+@table @kbd
+@item Mouse-1
+Move point to where you click (@code{mouse-set-point}).
+This is normally the left button.
+
+@item Drag-Mouse-1
+Set the region to the text you select by dragging, and copy it to the
+kill ring (@code{mouse-set-region}). You can specify both ends of the
+region with this single command.
+
+@vindex mouse-scroll-min-lines
+If you move the mouse off the top or bottom of the window while
+dragging, the window scrolls at a steady rate until you move the mouse
+back into the window. This way, you can select regions that don't fit
+entirely on the screen. The number of lines scrolled per step depends
+on how far away from the window edge the mouse has gone; the variable
+@code{mouse-scroll-min-lines} specifies a minimum step size.
+
+@item Mouse-2
+Yank the last killed text, where you click (@code{mouse-yank-at-click}).
+This is normally the middle button.
+
+@item Mouse-3
+This command, @code{mouse-save-then-kill}, has several functions
+depending on where you click and the status of the region.
+
+The most basic case is when you click @kbd{Mouse-1} in one place and
+then @kbd{Mouse-3} in another. This selects the text between those two
+positions as the region. It also copies the new region to the kill
+ring, so that you can copy it to someplace else.
+
+If you click @kbd{Mouse-1} in the text, scroll with the scroll bar, and
+then click @kbd{Mouse-3}, it remembers where point was before scrolling
+(where you put it with @kbd{Mouse-1}), and uses that position as the
+other end of the region. This is so that you can select a region that
+doesn't fit entirely on the screen.
+
+More generally, if you do not have a highlighted region, @kbd{Mouse-3}
+selects the text between point and the click position as the region. It
+does this by setting the mark where point was, and moving point to where
+you click.
+
+If you have a highlighted region, or if the region was set just before
+by dragging button 1, @kbd{Mouse-3} adjusts the nearer end of the region
+by moving it to where you click. The adjusted region's text also
+replaces the old region's text in the kill ring.
+
+If you originally specified the region using a double or triple
+@kbd{Mouse-1}, so that the region is defined to consist of entire words
+or lines, then adjusting the region with @kbd{Mouse-3} also proceeds by
+entire words or lines.
+
+If you use @kbd{Mouse-3} a second time consecutively, at the same place,
+that kills the region already selected.
+
+@item Double-Mouse-1
+This key sets the region around the word which you click on. If you
+click on a character with ``symbol'' syntax (such as underscore, in C
+mode), it sets the region around the symbol surrounding that character.
+
+If you click on a character with open-parenthesis or close-parenthesis
+syntax, it sets the region around the parenthetical grouping (sexp)
+which that character starts or ends. If you click on a character with
+string-delimiter syntax (such as a singlequote or doublequote in C), it
+sets the region around the string constant (using heuristics to figure
+out whether that character is the beginning or the end of it).
+
+@item Double-Drag-Mouse-1
+This key selects a region made up of the words you drag across.
+
+@item Triple-Mouse-1
+This key sets the region around the line you click on.
+
+@item Triple-Drag-Mouse-1
+This key selects a region made up of the lines you drag across.
+@end table
+
+ The simplest way to kill text with the mouse is to press @kbd{Mouse-1}
+at one end, then press @kbd{Mouse-3} twice at the other end.
+@xref{Killing}. To copy the text into the kill ring without deleting it
+from the buffer, press @kbd{Mouse-3} just once---or just drag across the
+text with @kbd{Mouse-1}. Then you can copy it elsewhere by yanking it.
+
+@vindex mouse-yank-at-point
+ To yank the killed or copied text somewhere else, move the mouse there
+and press @kbd{Mouse-2}. @xref{Yanking}. However, if
+@code{mouse-yank-at-point} is non-@code{nil}, @kbd{Mouse-2} yanks at
+point. Then it does not matter where you click, or even which of the
+frame's windows you click on. The default value is @code{nil}. This
+variable also affects yanking the secondary selection.
+
+@cindex cutting and X
+@cindex pasting and X
+@cindex X cutting and pasting
+ To copy text to another X window, kill it or save it in the kill ring.
+Under X, this also sets the @dfn{primary selection}. Then use the
+``paste'' or ``yank'' command of the program operating the other window
+to insert the text from the selection.
+
+ To copy text from another X window, use the ``cut'' or ``copy'' command
+of the program operating the other window, to select the text you want.
+Then yank it in Emacs with @kbd{C-y} or @kbd{Mouse-2}.
+
+ These cutting and pasting commands also work on MS-Windows.
+
+@cindex primary selection
+@cindex cut buffer
+@cindex selection, primary
+@vindex x-cut-buffer-max
+ When Emacs puts text into the kill ring, or rotates text to the front
+of the kill ring, it sets the @dfn{primary selection} in the X server.
+This is how other X clients can access the text. Emacs also stores the
+text in the cut buffer, but only if the text is short enough
+(@code{x-cut-buffer-max} specifies the maximum number of characters);
+putting long strings in the cut buffer can be slow.
+
+ The commands to yank the first entry in the kill ring actually check
+first for a primary selection in another program; after that, they check
+for text in the cut buffer. If neither of those sources provides text
+to yank, the kill ring contents are used.
+
+@node Secondary Selection
+@section Secondary Selection
+@cindex secondary selection
+
+ The @dfn{secondary selection} is another way of selecting text using
+X. It does not use point or the mark, so you can use it to kill text
+without setting point or the mark.
+
+@table @kbd
+@findex mouse-set-secondary
+@kindex M-Drag-Mouse-1
+@item M-Drag-Mouse-1
+Set the secondary selection, with one end at the place where you press
+down the button, and the other end at the place where you release it
+(@code{mouse-set-secondary}). The highlighting appears and changes as
+you drag.
+
+If you move the mouse off the top or bottom of the window while
+dragging, the window scrolls at a steady rate until you move the mouse
+back into the window. This way, you can mark regions that don't fit
+entirely on the screen.
+
+@findex mouse-start-secondary
+@kindex M-Mouse-1
+@item M-Mouse-1
+Set one endpoint for the @dfn{secondary selection}
+(@code{mouse-start-secondary}).
+
+@findex mouse-secondary-save-then-kill
+@kindex M-Mouse-3
+@item M-Mouse-3
+Make a secondary selection, using the place specified with @kbd{M-Mouse-1}
+as the other end (@code{mouse-secondary-save-then-kill}). A second click
+at the same place kills the secondary selection just made.
+
+@findex mouse-yank-secondary
+@kindex M-Mouse-2
+@item M-Mouse-2
+Insert the secondary selection where you click
+(@code{mouse-yank-secondary}). This places point at the end of the
+yanked text.
+@end table
+
+Double or triple clicking of @kbd{M-Mouse-1} operates on words and
+lines, much like @kbd{Mouse-1}.
+
+If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-Mouse-2}
+yanks at point. Then it does not matter precisely where you click; all
+that matters is which window you click on. @xref{Mouse Commands}.
+
+@node Mouse References
+@section Following References with the Mouse
+@kindex Mouse-2 @r{(selection)}
+
+ Some Emacs buffers display lists of various sorts. These include
+lists of files, of buffers, of possible completions, of matches for
+a pattern, and so on.
+
+ Since yanking text into these buffers is not very useful, most of them
+define @kbd{Mouse-2} specially, as a command to use or view the item you
+click on.
+
+ For example, if you click @kbd{Mouse-2} on a file name in a Dired
+buffer, you visit that file. If you click @kbd{Mouse-2} on an error
+message in the @samp{*Compilation*} buffer, you go to the source code
+for that error message. If you click @kbd{Mouse-2} on a completion in
+the @samp{*Completions*} buffer, you choose that completion.
+
+ You can usually tell when @kbd{Mouse-2} has this special sort of
+meaning because the sensitive text highlights when you move the mouse
+over it.
+
+@node Menu Mouse Clicks
+@section Mouse Clicks for Menus
+
+ Mouse clicks modified with the @key{CTRL} and @key{SHIFT} keys
+bring up menus.
+
+@kindex C-Mouse-3
+@table @kbd
+@item C-Mouse-1
+This menu is for selecting a buffer.
+
+@item C-Mouse-2
+This menu is for specifying faces and other text properties
+for editing formatted text. @xref{Formatted Text}.
+
+@item C-Mouse-3
+This menu is mode-specific. For most modes, this menu has the same
+items as all the mode-specific menu-bar menus put together. Some modes
+may specify a different menu for this button.@footnote{Some systems use
+@kbd{Mouse-3} for a mode-specific menu. We took a survey of users, and
+found they preferred to keep @kbd{Mouse-3} for selecting and killing
+regions. Hence the decision to use @kbd{C-Mouse-3} for this menu.}
+
+@item S-mouse-1
+This menu is for specifying the frame's principal font.
+@end table
+
+@node Mode Line Mouse
+@section Mode Line Mouse Commands
+
+ You can use mouse clicks on window mode lines to select and manipulate
+windows.
+
+@table @kbd
+@item Mouse-1
+@kbd{Mouse-1} on a mode line selects the window above. By dragging
+@kbd{Mouse-1} on the mode line, you can move it, thus changing the
+height of the windows above and below.
+
+@item Mouse-2
+@kbd{Mouse-2} on a mode line expands that window to fill its frame.
+
+@item Mouse-3
+@kbd{Mouse-3} on a mode line deletes the window above.
+
+@item C-Mouse-2
+@kbd{C-Mouse-2} on a mode line splits the window above
+horizontally, above the place in the mode line where you click.
+@end table
+
+ @kbd{C-Mouse-2} on a scroll bar splits the corresponding window
+vertically. @xref{Split Window}.
+
+@node Creating Frames
+@section Creating Frames
+@cindex creating frames
+
+@kindex C-x 5
+ The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}, with parallel
+subcommands. The difference is that @kbd{C-x 5} commands create a new
+frame rather than just a new window in the selected frame (@pxref{Pop
+Up Window}). If an existing visible or iconified frame already displays
+the requested material, these commands use the existing frame, after
+raising or deiconifying as necessary.
+
+ The various @kbd{C-x 5} commands differ in how they find or create the
+buffer to select:
+
+@table @kbd
+@item C-x 5 2
+@kindex C-x 5 2
+@findex make-frame-command
+Create a new frame (@code{make-frame-command}).
+@item C-x 5 b @var{bufname} @key{RET}
+Select buffer @var{bufname} in another frame. This runs
+@code{switch-to-buffer-other-frame}.
+@item C-x 5 f @var{filename} @key{RET}
+Visit file @var{filename} and select its buffer in another frame. This
+runs @code{find-file-other-frame}. @xref{Visiting}.
+@item C-x 5 d @var{directory} @key{RET}
+Select a Dired buffer for directory @var{directory} in another frame.
+This runs @code{dired-other-frame}. @xref{Dired}.
+@item C-x 5 m
+Start composing a mail message in another frame. This runs
+@code{mail-other-frame}. It is the other-frame variant of @kbd{C-x m}.
+@xref{Sending Mail}.
+@item C-x 5 .
+Find a tag in the current tag table in another frame. This runs
+@code{find-tag-other-frame}, the multiple-frame variant of @kbd{M-.}.
+@xref{Tags}.
+@item C-x 5 r @var{filename} @key{RET}
+@kindex C-x 5 r
+@findex find-file-read-only-other-frame
+Visit file @var{filename} read-only, and select its buffer in another
+frame. This runs @code{find-file-read-only-other-frame}.
+@xref{Visiting}.
+@end table
+
+@cindex default-frame-alist
+@cindex initial-frame-alist
+ You can control the appearance of new frames you create by setting the
+frame parameters in @code{default-frame-alist}. You can use the
+variable @code{initial-frame-alist} to specify parameters that affect
+only the initial frame. @xref{Initial Parameters,,, elisp, The Emacs
+Lisp Reference Manual}, for more information.
+
+@cindex font (default)
+ The easiest way to specify the principal font for all your Emacs
+frames is with an X resource (@pxref{Font X}), but you can also do it by
+modifying @code{default-frame-alist} to specify the @code{font}
+parameter, as shown here:
+
+@example
+(add-to-list 'default-frame-alist '(font . "10x20"))
+@end example
+
+@node Speedbar
+@section Making and Using a Speedbar Frame
+@cindex speedbar
+
+ An Emacs frame can have a @dfn{speedbar}, which is a vertical window
+that serves as a scrollable menu of files you could visit and tags
+within those files. To create a speedbar, type @kbd{M-x speedbar}; this
+creates a speedbar window for the selected frame. From then on, you can
+click on a file name in the speedbar to visit that file in the
+corresponding Emacs frame, or click on a tag name to jump to that tag in
+the Emacs frame.
+
+ Initially the speedbar lists the immediate contents of the current
+directory, one file per line. Each line also has a box, @samp{[+]} or
+@samp{<+>}, that you can click on with @kbd{Mouse-2} to ``open up'' the
+contents of that item. If the line names a directory, opening it adds
+the contents of that directory to the speedbar display, underneath the
+directory's own line. If the line lists an ordinary file, opening it up
+adds a list of the tags in that file to the speedbar display. When a
+file is opened up, the @samp{[+]} changes to @samp{[-]}; you can click
+on that box to ``close up'' that file (hide its contents).
+
+ Some major modes, including Rmail mode, Info, and GUD, have
+specialized ways of putting useful items into the speedbar for you to
+select. For example, in Rmail mode, the speedbar shows a list of Rmail
+files, and lets you move the current message to another Rmail file by
+clicking on its @samp{<M>} box.
+
+ A speedbar belongs to one Emacs frame, and always operates on that
+frame. If you use multiple frames, you can make a speedbar for some or
+all of the frames; type @kbd{M-x speedbar} in any given frame to make a
+speedbar for it.
+
+@node Multiple Displays
+@section Multiple Displays
+@cindex multiple displays
+
+ A single Emacs can talk to more than one X Windows display.
+Initially, Emacs uses just one display---the one specified with the
+@code{DISPLAY} environment variable or with the @samp{--display} option
+(@pxref{Initial Options}). To connect to another display, use the
+command @code{make-frame-on-display}:
+
+@findex make-frame-on-display
+@table @kbd
+@item M-x make-frame-on-display @key{RET} @var{display} @key{RET}
+Create a new frame on display @var{display}.
+@end table
+
+ A single X server can handle more than one screen. When you open
+frames on two screens belonging to one server, Emacs knows they share a
+single keyboard, and it treats all the commands arriving from these
+screens as a single stream of input.
+
+ When you open frames on different X servers, Emacs makes a separate
+input stream for each server. This way, two users can type
+simultaneously on the two displays, and Emacs will not garble their
+input. Each server also has its own selected frame. The commands you
+enter with a particular X server apply to that server's selected frame.
+
+ Despite these features, people using the same Emacs job from different
+displays can still interfere with each other if they are not careful.
+For example, if any one types @kbd{C-x C-c}, that exits the Emacs job
+for all of them!
+
+@node Special Buffer Frames
+@section Special Buffer Frames
+
+@vindex special-display-buffer-names
+ You can make certain chosen buffers, for which Emacs normally creates
+a second window when you have just one window, appear in special frames
+of their own. To do this, set the variable
+@code{special-display-buffer-names} to a list of buffer names; any
+buffer whose name is in that list automatically gets a special frame,
+when an Emacs command wants to display it ``in another window.''
+
+ For example, if you set the variable this way,
+
+@example
+(setq special-display-buffer-names
+ '("*Completions*" "*grep*" "*tex-shell*"))
+@end example
+
+@noindent
+then completion lists, @code{grep} output and the @TeX{} mode shell
+buffer get individual frames of their own. These frames, and the
+windows in them, are never automatically split or reused for any other
+buffers. They continue to show the buffers they were created for,
+unless you alter them by hand. Killing the special buffer deletes its
+frame automatically.
+
+@vindex special-display-regexps
+ More generally, you can set @code{special-display-regexps} to a list
+of regular expressions; then a buffer gets its own frame if its name
+matches any of those regular expressions. (Once again, this applies only
+to buffers that normally get displayed for you in a separate window.)
+
+@vindex special-display-frame-alist
+ The variable @code{special-display-frame-alist} specifies the frame
+parameters for these frames. It has a default value, so you don't need
+to set it.
+
+ For those who know Lisp, an element of
+@code{special-display-buffer-names} or @code{special-display-regexps}
+can also be a list. Then the first element is the buffer name or
+regular expression; the rest of the list specifies how to create the
+frame. It can be an association list specifying frame parameter values;
+these values take precedence over parameter values specified in
+@code{special-display-frame-alist}. Alternatively, it can have this
+form:
+
+@example
+(@var{function} @var{args}...)
+@end example
+
+@noindent
+where @var{function} is a symbol. Then the frame is constructed by
+calling @var{function}; its first argument is the buffer, and its
+remaining arguments are @var{args}.
+
+ An analogous feature lets you specify buffers which should be
+displayed in the selected window. @xref{Force Same Window}. The
+same-window feature takes precedence over the special-frame feature;
+therefore, if you add a buffer name to
+@code{special-display-buffer-names} and it has no effect, check to see
+whether that feature is also in use for the same buffer name.
+
+@node Frame Parameters
+@section Setting Frame Parameters
+@cindex colors
+@cindex Auto-Raise mode
+@cindex Auto-Lower mode
+
+ This section describes commands for altering the display style and
+window management behavior of the selected frame.
+
+@findex set-foreground-color
+@findex set-background-color
+@findex set-cursor-color
+@findex set-mouse-color
+@findex set-border-color
+@findex auto-raise-mode
+@findex auto-lower-mode
+@table @kbd
+@item M-x set-foreground-color @key{RET} @var{color} @key{RET}
+Specify color @var{color} for the foreground of the selected frame.
+(This also changes the foreground color of the default face.)
+
+@item M-x set-background-color @key{RET} @var{color} @key{RET}
+Specify color @var{color} for the background of the selected frame.
+(This also changes the background color of the default face.)
+
+@item M-x set-cursor-color @key{RET} @var{color} @key{RET}
+Specify color @var{color} for the cursor of the selected frame.
+
+@item M-x set-mouse-color @key{RET} @var{color} @key{RET}
+Specify color @var{color} for the mouse cursor when it is over the
+selected frame.
+
+@item M-x set-border-color @key{RET} @var{color} @key{RET}
+Specify color @var{color} for the border of the selected frame.
+
+@item M-x list-colors-display
+Display the defined color names and show what the colors look like.
+This command is somewhat slow.
+
+@item M-x auto-raise-mode
+Toggle whether or not the selected frame should auto-raise. Auto-raise
+means that every time you move the mouse onto the frame, it raises the
+frame.
+
+Note that this auto-raise feature is implemented by Emacs itself. Some
+window managers also implement auto-raise. If you enable auto-raise for
+Emacs frames in your X window manager, it should work, but it is beyond
+Emacs's control and therefore @code{auto-raise-mode} has no effect on
+it.
+
+@item M-x auto-lower-mode
+Toggle whether or not the selected frame should auto-lower.
+Auto-lower means that every time you move the mouse off the frame,
+the frame moves to the bottom of the stack of X windows.
+
+The command @code{auto-lower-mode} has no effect on auto-lower
+implemented by the X window manager. To control that, you must use
+the appropriate window manager features.
+
+@findex set-frame-font
+@item M-x set-frame-font @key{RET} @var{font} @key{RET}
+@cindex font (principal)
+Specify font @var{font} as the principal font for the selected frame.
+The principal font controls several face attributes of the
+@code{default} face (@pxref{Faces}). For example, if the principal font
+has a height of 12 pt, all text will be drawn in 12 pt fonts, unless you
+use another face that specifies a different height. @xref{Font X}, for
+ways to list the available fonts on your system.
+
+@kindex S-Mouse-1
+You can also set a frame's principal font through a pop-up menu.
+Press @kbd{S-Mouse-1} to activate this menu.
+@end table
+
+ In Emacs versions that use an X toolkit, the color-setting and
+font-setting functions don't affect menus and the menu bar, since they
+are displayed by their own widget classes. To change the appearance of
+the menus and menu bar, you must use X resources (@pxref{Resources X}).
+@xref{Colors X}, regarding colors. @xref{Font X}, regarding choice of
+font.
+
+ For information on frame parameters and customization, see @ref{Frame
+Parameters,,, elisp, The Emacs Lisp Reference Manual}.
+
+@node Scroll Bars
+@section Scroll Bars
+@cindex Scroll Bar mode
+@cindex mode, Scroll Bar
+
+ When using X, Emacs normally makes a @dfn{scroll bar} at the left of
+each Emacs window. The scroll bar runs the height of the window, and
+shows a moving rectangular inner box which represents the portion of the
+buffer currently displayed. The entire height of the scroll bar
+represents the entire length of the buffer.
+
+ You can use @kbd{Mouse-2} (normally, the middle button) in the scroll
+bar to move or drag the inner box up and down. If you move it to the
+top of the scroll bar, you see the top of the buffer. If you move it to
+the bottom of the scroll bar, you see the bottom of the buffer.
+
+ The left and right buttons in the scroll bar scroll by controlled
+increments. @kbd{Mouse-1} (normally, the left button) moves the line at
+the level where you click up to the top of the window. @kbd{Mouse-3}
+(normally, the right button) moves the line at the top of the window
+down to the level where you click. By clicking repeatedly in the same
+place, you can scroll by the same distance over and over.
+
+ Aside from scrolling, you can also click @kbd{C-Mouse-2} in the scroll
+bar to split a window vertically. The split occurs on the line where
+you click.
+
+@findex scroll-bar-mode
+ You can enable or disable Scroll Bar mode with the command @kbd{M-x
+scroll-bar-mode}. With no argument, it toggles the use of scroll bars.
+With an argument, it turns use of scroll bars on if and only if the
+argument is positive. This command applies to all frames, including
+frames yet to be created. You can use the X resource
+@samp{verticalScrollBars} to control the initial setting of Scroll Bar
+mode. @xref{Resources X}.
+
+@findex toggle-scroll-bar
+ To enable or disable scroll bars for just the selected frame, use the
+@kbd{M-x toggle-scroll-bar} command.
+
+@node Menu Bars
+@section Menu Bars
+@cindex Menu Bar mode
+@cindex mode, Menu Bar
+
+ You can turn display of menu bars on or off with @kbd{M-x
+menu-bar-mode}. With no argument, this command toggles Menu Bar mode, a
+minor mode. With an argument, the command turns Menu Bar mode on if the
+argument is positive, off if the argument is not positive. You can use
+the X resource @samp{menuBarLines} to control the initial setting of
+Menu Bar mode. @xref{Resources X}. Expert users often turn off the
+menu bar, especially on text-only terminals, where this makes one
+additional line available for text.
+
+ @xref{Menu Bar}, for information on how to invoke commands with the
+menu bar.
+
+@node Faces
+@section Using Multiple Typefaces
+@cindex faces
+
+ When using Emacs with X, you can set up multiple styles of displaying
+characters. The aspects of style that you can control are the type
+font, the foreground color, the background color, and whether to
+underline. Emacs on MS-DOS supports faces partially by letting you
+control the foreground and background colors of each face
+(@pxref{MS-DOS}).
+
+ The way you control display style is by defining named @dfn{faces}.
+Each face can specify a type font, a foreground color, a background
+color, and an underline flag; but it does not have to specify all of
+them. Then by specifying the face or faces to use for a given part
+of the text in the buffer, you control how that text appears.
+
+ The style of display used for a given character in the text is
+determined by combining several faces. Any aspect of the display style
+that isn't specified by overlays or text properties comes from the frame
+itself.
+
+ Enriched mode, the mode for editing formatted text, includes several
+commands and menus for specifying faces. @xref{Format Faces}, for how
+to specify the font for text in the buffer. @xref{Format Colors}, for
+how to specify the foreground and background color.
+
+ To alter the appearance of a face, use the customization buffer.
+@xref{Face Customization}. You can also use X resources to specify
+attributes of particular faces (@pxref{Resources X}).
+
+@findex list-faces-display
+ To see what faces are currently defined, and what they look like, type
+@kbd{M-x list-faces-display}. It's possible for a given face to look
+different in different frames; this command shows the appearance in the
+frame in which you type it. Here's a list of the standardly defined
+faces:
+
+@table @code
+@item default
+This face is used for ordinary text that doesn't specify any other face.
+@item modeline
+This face is used for mode lines. By default, it's set up as the
+inverse of the default face. @xref{Display Vars}.
+@item highlight
+This face is used for highlighting portions of text, in various modes.
+@item region
+This face is used for displaying a selected region (when Transient Mark
+mode is enabled---see below).
+@item secondary-selection
+This face is used for displaying a secondary selection (@pxref{Secondary
+Selection}).
+@item bold
+This face uses a bold variant of the default font, if it has one.
+@item italic
+This face uses an italic variant of the default font, if it has one.
+@item bold-italic
+This face uses a bold italic variant of the default font, if it has one.
+@item underline
+This face underlines text.
+@end table
+
+@cindex @code{region} face
+ When Transient Mark mode is enabled, the text of the region is
+highlighted when the mark is active. This uses the face named
+@code{region}; you can control the style of highlighting by changing the
+style of this face (@pxref{Face Customization}). @xref{Transient Mark},
+for more information about Transient Mark mode and activation and
+deactivation of the mark.
+
+ One easy way to use faces is to turn on Font Lock mode. This minor
+mode, which is always local to a particular buffer, arranges to
+choose faces according to the syntax of the text you are editing. It
+can recognize comments and strings in most languages; in several
+languages, it can also recognize and properly highlight various other
+important constructs. @xref{Font Lock}, for more information about
+Font Lock mode and syntactic highlighting.
+
+ You can print out the buffer with the highlighting that appears
+on your screen using the command @code{ps-print-buffer-with-faces}.
+@xref{Postscript}.
+
+@node Font Lock
+@section Font Lock mode
+@cindex Font Lock mode
+@cindex mode, Font Lock
+@cindex syntax highlighting
+
+ Font Lock mode is a minor mode, always local to a particular
+buffer, which highlights (or ``fontifies'') using various faces
+according to the syntax of the text you are editing. It can
+recognize comments and strings in most languages; in several
+languages, it can also recognize and properly highlight various other
+important constructs---for example, names of functions being defined
+or reserved keywords.
+
+@findex font-lock-mode
+@findex turn-on-font-lock
+ The command @kbd{M-x font-lock-mode} turns Font Lock mode on or off
+according to the argument, and toggles the mode when it has no argument.
+The function @code{turn-on-font-lock} unconditionally enables Font Lock
+mode. This is useful in mode-hook functions. For example, to enable
+Font Lock mode whenever you edit a C file, you can do this:
+
+@example
+(add-hook 'c-mode-hook 'turn-on-font-lock)
+@end example
+
+@findex global-font-lock-mode
+ To turn on Font Lock mode automatically in all modes which support it,
+use the function @code{global-font-lock-mode}, like this:
+
+@example
+(global-font-lock-mode 1)
+@end example
+
+@kindex M-g M-g
+@findex font-lock-fontify-block
+ In Font Lock mode, when you edit the text, the highlighting updates
+automatically in the line that you changed. Most changes don't affect
+the highlighting of subsequent lines, but occasionally they do. To
+rehighlight a range of lines, use the command @kbd{M-g M-g}
+(@code{font-lock-fontify-block}).
+
+@vindex font-lock-mark-block-function
+ In certain major modes, @kbd{M-g M-g} refontifies the entire current
+function. (The variable @code{font-lock-mark-block-function} controls
+how to find the current function.) In other major modes, @kbd{M-g M-g}
+refontifies 16 lines above and below point.
+
+ With a prefix argument @var{n}, @kbd{M-g M-g} refontifies @var{n}
+lines above and below point, regardless of the mode.
+
+ To get the full benefit of Font Lock mode, you need to choose a
+default font which has bold, italic, and bold-italic variants; or else
+you need to have a color or gray-scale screen.
+
+@vindex font-lock-maximum-decoration
+ The variable @code{font-lock-maximum-decoration} specifies the
+preferred level of fontification, for modes that provide multiple
+levels. Level 1 is the least amount of fontification; some modes
+support levels as high as 3. The normal default is ``as high as
+possible.'' You can specify an integer, which applies to all modes, or
+you can specify different numbers for particular major modes; for
+example, to use level 1 for C/C++ modes, and the default level
+otherwise, use this:
+
+@example
+(setq font-lock-maximum-decoration
+ '((c-mode . 1) (c++-mode . 1)))
+@end example
+
+@vindex font-lock-maximum-size
+ Fontification can be too slow for large buffers, so you can suppress
+it. The variable @code{font-lock-maximum-size} specifies a buffer size,
+beyond which buffer fontification is suppressed.
+
+@c @w is used below to prevent a bad page-break.
+@vindex font-lock-beginning-of-syntax-function
+ Comment and string fontification (or ``syntactic'' fontification)
+relies on analysis of the syntactic structure of the buffer text. For
+the purposes of speed, some modes including C mode and Lisp mode rely on
+a special convention: an open-parenthesis in the leftmost column always
+defines the @w{beginning} of a defun, and is thus always outside any string
+or comment. (@xref{Defuns}.) If you don't follow this convention,
+then Font Lock mode can misfontify the text after an open-parenthesis in
+the leftmost column that is inside a string or comment.
+
+ The variable @code{font-lock-beginning-of-syntax-function} (always
+buffer-local) specifies how Font Lock mode can find a position
+guaranteed to be outside any comment or string. In modes which use the
+leftmost column parenthesis convention, the default value of the variable
+is @code{beginning-of-defun}---that tells Font Lock mode to use the
+convention. If you set this variable to @code{nil}, Font Lock no longer
+relies on the convention. This avoids incorrect results, but the price
+is that, in some cases, fontification for a changed text must rescan
+buffer text from the beginning of the buffer.
+
+@findex font-lock-add-keywords
+ Font Lock highlighting patterns already exist for many modes, but you
+may want to fontify additional patterns. You can use the function
+@code{font-lock-add-keywords}, to add your own highlighting patterns for
+a particular mode. For example, to highlight @samp{FIXME:} words in C
+comments, use this:
+
+@example
+(font-lock-add-keywords
+ 'c-mode
+ '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t)))
+@end example
+
+@node Support Modes
+@section Font Lock Support Modes
+
+ Font Lock support modes make Font Lock mode faster for large buffers.
+There are two support modes: Fast Lock mode and Lazy Lock mode. They
+use two different methods of speeding up Font Lock mode.
+
+@menu
+* Fast Lock Mode:: Saving font information in files.
+* Lazy Lock Mode:: Fontifying only text that is actually displayed.
+* Fast or Lazy:: Which support mode is best for you?
+@end menu
+
+@node Fast Lock Mode
+@subsection Fast Lock Mode
+
+@cindex Fast Lock mode
+@cindex mode, Fast Lock
+ To make Font Lock mode faster for buffers visiting large files, you
+can use Fast Lock mode. Fast Lock mode saves the font information for
+each file in a separate cache file; each time you visit the file, it
+rereads the font information from the cache file instead of refontifying
+the text from scratch.
+
+@findex fast-lock-mode
+ The command @kbd{M-x fast-lock-mode} turns Fast Lock mode on or off,
+according to the argument (with no argument, it toggles). You can also
+arrange to enable Fast Lock mode whenever you use Font Lock mode, like
+this:
+
+@example
+(setq font-lock-support-mode 'fast-lock-mode)
+@end example
+
+@vindex fast-lock-minimum-size
+ It is not worth writing a cache file for small buffers. Therefore,
+the variable @code{fast-lock-minimum-size} specifies a minimum file size
+for caching font information.
+
+@vindex fast-lock-cache-directories
+ The variable @code{fast-lock-cache-directories} specifies where to put
+the cache files. Its value is a list of directories to try; @code{"."}
+means the same directory as the file being edited. The default value is
+@w{@code{("." "~/.emacs-flc")}}, which means to use the same directory if
+possible, and otherwise the directory @file{~/.emacs-flc}.
+
+@vindex fast-lock-save-others
+ The variable @code{fast-lock-save-others} specifies whether Fast Lock
+mode should save cache files for files that you do not own. A
+non-@code{nil} value means yes (and that is the default).
+
+@node Lazy Lock Mode
+@subsection Lazy Lock Mode
+@cindex Lazy Lock mode
+@cindex mode, Lazy Lock
+
+ To make Font Lock mode faster for large buffers, you can use Lazy Lock
+mode to reduce the amount of text that is fontified. In Lazy Lock mode,
+buffer fontification is demand-driven; it happens to portions of the
+buffer that are about to be displayed. And fontification of your
+changes is deferred; it happens only when Emacs has been idle for a
+certain short period of time.
+
+@findex lazy-lock-mode
+ The command @kbd{M-x lazy-lock-mode} turns Lazy Lock mode on or off,
+according to the argument (with no argument, it toggles). You can also
+arrange to enable Lazy Lock mode whenever you use Font Lock mode, like
+this:
+
+@example
+(setq font-lock-support-mode 'lazy-lock-mode)
+@end example
+
+@vindex lazy-lock-minimum-size
+ It is not worth avoiding buffer fontification for small buffers.
+Therefore, the variable @code{lazy-lock-minimum-size} specifies a
+minimum buffer size for demand-driven buffer fontification. Buffers
+smaller than that are fontified all at once, as in plain Font Lock mode.
+
+@vindex lazy-lock-defer-time
+ When you alter the buffer, Lazy Lock mode defers fontification of the
+text you changed. The variable @code{lazy-lock-defer-time} specifies
+how many seconds Emacs must be idle before it starts fontifying your
+changes. If the value is 0, then changes are fontified immediately, as
+in plain Font Lock mode.
+
+@vindex lazy-lock-defer-on-scrolling
+ Lazy Lock mode normally fontifies newly visible portions of the buffer
+before they are first displayed. However, if the value of
+@code{lazy-lock-defer-on-scrolling} is non-@code{nil}, newly visible
+text is fontified only when Emacs is idle for
+@code{lazy-lock-defer-time} seconds.
+
+@vindex lazy-lock-defer-contextually
+ In some modes, including C mode and Emacs Lisp mode, changes in one
+line's contents can alter the context for subsequent lines, and thus
+change how they ought to be fontified. Ordinarily, you must type
+@kbd{M-g M-g} to refontify the subsequent lines. However, if you set
+the variable @code{lazy-lock-defer-contextually} to non-@code{nil}, Lazy
+Lock mode does this automatically, after @code{lazy-lock-defer-time}
+seconds.
+
+@cindex stealth fontification
+ When Emacs is idle for a long time, Lazy Lock fontifies additional
+portions of the buffer, not yet displayed, in case you will display them
+later. This is called @dfn{stealth fontification}.
+
+@vindex lazy-lock-stealth-time
+@vindex lazy-lock-stealth-lines
+@vindex lazy-lock-stealth-verbose
+ The variable @code{lazy-lock-stealth-time} specifies how many seconds
+Emacs has to be idle before stealth fontification starts. A value of
+@code{nil} means no stealth fontification. The variables
+@code{lazy-lock-stealth-lines} and @code{lazy-lock-stealth-verbose}
+specify the granularity and verbosity of stealth fontification.
+
+@node Fast or Lazy
+@subsection Fast Lock or Lazy Lock?
+
+ Here is a simple guide to help you choose one of the Font Lock support
+modes.
+
+@itemize @bullet
+@item
+Fast Lock mode intervenes only during file visiting and buffer
+killing (and related events); therefore buffer editing and window
+scrolling are no faster or slower than in plain Font Lock mode.
+
+@item
+Fast Lock mode is slower at reading a cache file than Lazy Lock
+mode is at fontifying a window; therefore Fast Lock mode is slower at
+visiting a file than Lazy Lock mode.
+
+@item
+Lazy Lock mode intervenes during window scrolling to fontify text that
+scrolls onto the screen; therefore, scrolling is slower than in plain
+Font Lock mode.
+
+@item
+Lazy Lock mode doesn't fontify during buffer editing (it defers
+fontification of changes); therefore, editing is faster than in plain
+Font Lock mode.
+
+@item
+Fast Lock mode can be fooled by a file that is kept under version
+control software; therefore buffer fontification may occur even when
+a cache file exists for the file.
+
+@item
+Fast Lock mode only works with a buffer visiting a file; Lazy Lock
+mode works with any buffer.
+
+@item
+Fast Lock mode generates cache files; Lazy Lock mode does not.
+@end itemize
+
+@vindex font-lock-support-mode
+ The variable @code{font-lock-support-mode} specifies which of these
+support modes to use; for example, to specify that Fast Lock mode is
+used for C/C++ modes, and Lazy Lock mode otherwise, set the variable
+like this:
+
+@example
+(setq font-lock-support-mode
+ '((c-mode . fast-lock-mode) (c++-mode . fast-lock-mode)
+ (t . lazy-lock-mode)))
+@end example
+
+@node Highlight Changes
+@section Highlight Changes Mode
+
+@findex highlight-changes-mode
+ Use @kbd{M-x highlight-changes-mode} to enable a minor mode
+that uses faces (colors, typically) to indicate which parts of
+the buffer were changed most recently.
+
+@node Misc X
+@section Miscellaneous X Window Features
+
+ The following commands let you create, delete and operate on frames:
+
+@table @kbd
+@item C-z
+@kindex C-z @r{(X windows)}
+@findex iconify-or-deiconify-frame
+Iconify the selected Emacs frame (@code{iconify-or-deiconify-frame}).
+The normal meaning of @kbd{C-z}, to suspend Emacs, is not useful under a
+window system, so it has a different binding in that case.
+
+If you type this command on an Emacs frame's icon, it deiconifies the frame.
+
+@item C-x 5 0
+@kindex C-x 5 0
+@findex delete-frame
+Delete the selected frame (@code{delete-frame}). This is not allowed if
+there is only one frame.
+
+@item C-x 5 o
+@kindex C-x 5 o
+@findex other-frame
+Select another frame, raise it, and warp the mouse to it so that it
+stays selected. If you repeat this command, it cycles through all the
+frames on your terminal.
+@end table
+
+@node Non-Window Terminals
+@section Non-Window Terminals
+@cindex non-window terminals
+@cindex single-frame terminals
+
+ If your terminal does not have a window system that Emacs supports,
+then it can display only one Emacs frame at a time. However, you can
+still create multiple Emacs frames, and switch between them. Switching
+frames on these terminals is much like switching between different
+window configurations.
+
+ Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x
+5 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete
+the current frame.
+
+ Each frame has a number to distinguish it. If your terminal can
+display only one frame at a time, the selected frame's number @var{n}
+appears near the beginning of the mode line, in the form
+@samp{F@var{n}}.
+
+@findex set-frame-name
+@findex select-frame-by-name
+ @samp{F@var{n}} is actually the frame's name. You can also specify a
+different name if you wish, and you can select a frame by its name. Use
+the command @kbd{M-x set-frame-name @key{RET} @var{name} @key{RET}} to
+specify a new name for the selected frame, and use @kbd{M-x
+select-frame-by-name @key{RET} @var{name} @key{RET}} to select a frame
+according to its name. The name you specify appears in the mode line
+when the frame is selected.
+
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Glossary, Key Index, Intro, Top
+@unnumbered Glossary
+
+@table @asis
+@item Abbrev
+An abbrev is a text string which expands into a different text string
+when present in the buffer. For example, you might define a few letters
+as an abbrev for a long phrase that you want to insert frequently.
+@xref{Abbrevs}.
+
+@item Aborting
+Aborting means getting out of a recursive edit (q.v.@:). The
+commands @kbd{C-]} and @kbd{M-x top-level} are used for this.
+@xref{Quitting}.
+
+@item Alt
+Alt is the name of a modifier bit which a keyboard input character may
+have. To make a character Alt, type it while holding down the @key{ALT}
+key. Such characters are given names that start with @kbd{Alt-}
+(usually written @kbd{A-} for short). (Note that many terminals have a
+key labeled @key{ALT} which is really a @key{META} key.) @xref{User
+Input, Alt}.
+
+@item ASCII character
+An ASCII character is either an ASCII control character or an ASCII
+printing character. @xref{User Input}.
+
+@item ASCII control character
+An ASCII control character is the Control version of an upper-case
+letter, or the Control version of one of the characters @samp{@@[\]^_?}.
+
+@item ASCII printing character
+ASCII printing characters include letters, digits, space, and these
+punctuation characters: @samp{!@@#$%^& *()_-+=|\~` @{@}[]:;"' <>,.?/}.
+
+@item Auto Fill Mode
+Auto Fill mode is a minor mode in which text that you insert is
+automatically broken into lines of fixed width. @xref{Filling}.
+
+@item Auto Saving
+Auto saving is the practice of saving the contents of an Emacs buffer in
+a specially-named file, so that the information will not be lost if the
+buffer is lost due to a system error or user error. @xref{Auto Save}.
+
+@item Backup File
+A backup file records the contents that a file had before the current
+editing session. Emacs makes backup files automatically to help you
+track down or cancel changes you later regret making. @xref{Backup}.
+
+@item Balance Parentheses
+Emacs can balance parentheses manually or automatically. Manual
+balancing is done by the commands to move over balanced expressions
+(@pxref{Lists}). Automatic balancing is done by blinking or
+highlighting the parenthesis that matches one just inserted
+(@pxref{Matching,,Matching Parens}).
+
+@item Bind
+To bind a key sequence means to give it a binding (q.v.@:).
+@xref{Rebinding}.
+
+@item Binding
+A key sequence gets its meaning in Emacs by having a binding, which is a
+command (q.v.@:), a Lisp function that is run when the user types that
+sequence. @xref{Commands,Binding}. Customization often involves
+rebinding a character to a different command function. The bindings of
+all key sequences are recorded in the keymaps (q.v.@:). @xref{Keymaps}.
+
+@item Blank Lines
+Blank lines are lines that contain only whitespace. Emacs has several
+commands for operating on the blank lines in the buffer.
+
+@item Buffer
+The buffer is the basic editing unit; one buffer corresponds to one text
+being edited. You can have several buffers, but at any time you are
+editing only one, the `selected' buffer, though several can be visible
+when you are using multiple windows (q.v.). Most buffers are visiting
+(q.v.@:) some file. @xref{Buffers}.
+
+@item Buffer Selection History
+Emacs keeps a buffer selection history which records how recently each
+Emacs buffer has been selected. This is used for choosing a buffer to
+select. @xref{Buffers}.
+
+@item Button Down Event
+A button down event is the kind of input event generated right away when
+you press a mouse button. @xref{Mouse Buttons}.
+
+@item @kbd{C-}
+@kbd{C-} in the name of a character is an abbreviation for Control.
+@xref{User Input,C-}.
+
+@item @kbd{C-M-}
+@kbd{C-M-} in the name of a character is an abbreviation for
+Control-Meta. @xref{User Input,C-M-}.
+
+@item Case Conversion
+Case conversion means changing text from upper case to lower case or
+vice versa. @xref{Case}, for the commands for case conversion.
+
+@item Character
+Characters form the contents of an Emacs buffer; see @ref{Text
+Characters}. Also, key sequences (q.v.@:) are usually made up of
+characters (though they may include other input events as well).
+@xref{User Input}.
+
+@item Character Set
+Emacs supports a number of character sets, each of which represents a
+particular alphabet or script. @xref{International}.
+
+@item Click Event
+A click event is the kind of input event generated when you press a
+mouse button and release it without moving the mouse. @xref{Mouse Buttons}.
+
+@item Coding System
+A coding system is an encoding for representing text characters in a
+file or in a stream of information. Emacs has the ability to convert
+text to or from a variety of coding systems when reading or writing it.
+@xref{Coding Systems}.
+
+@item Command
+A command is a Lisp function specially defined to be able to serve as a
+key binding in Emacs. When you type a key sequence (q.v.@:), its
+binding (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find
+the command to run. @xref{Commands}.
+
+@item Command Name
+A command name is the name of a Lisp symbol which is a command
+(@pxref{Commands}). You can invoke any command by its name using
+@kbd{M-x} (@pxref{M-x}).
+
+@item Comment
+A comment is text in a program which is intended only for humans reading
+the program, and which is marked specially so that it will be ignored
+when the program is loaded or compiled. Emacs offers special commands
+for creating, aligning and killing comments. @xref{Comments}.
+
+@item Compilation
+Compilation is the process of creating an executable program from source
+code. Emacs has commands for compiling files of Emacs Lisp code
+(@pxref{Byte Compilation,, Byte Compilation, elisp, the Emacs Lisp
+Reference Manual}) and programs in C and other languages
+(@pxref{Compilation}).
+
+@item Complete Key
+A complete key is a key sequence which fully specifies one action to be
+performed by Emacs. For example, @kbd{X} and @kbd{C-f} and @kbd{C-x m}
+are complete keys. Complete keys derive their meanings from being bound
+(q.v.@:) to commands (q.v.@:). Thus, @kbd{X} is conventionally bound to
+a command to insert @samp{X} in the buffer; @kbd{C-x m} is
+conventionally bound to a command to begin composing a mail message.
+@xref{Keys}.
+
+@item Completion
+Completion is what Emacs does when it automatically fills out an
+abbreviation for a name into the entire name. Completion is done for
+minibuffer (q.v.@:) arguments when the set of possible valid inputs
+is known; for example, on command names, buffer names, and
+file names. Completion occurs when @key{TAB}, @key{SPC} or @key{RET}
+is typed. @xref{Completion}.@refill
+
+@item Continuation Line
+When a line of text is longer than the width of the window, it
+takes up more than one screen line when displayed. We say that the
+text line is continued, and all screen lines used for it after the
+first are called continuation lines. @xref{Basic,Continuation,Basic
+Editing}.
+
+@item Control Character
+A control character is a character that you type by holding down the
+@key{CTRL} key. Some control characters also have their own keys, so
+that you can type them without using @key{CTRL}. For example,
+@key{RET}, @key{TAB}, @key{ESC} and @key{DEL} are all control
+characters. @xref{User Input}.
+
+@item Copyleft
+A copyleft is a notice giving the public legal permission to
+redistribute a program or other work of art. Copylefts are used by
+left-wing programmers to promote freedom and cooperation, just as
+copyrights are used by right-wing programmers to gain power over other
+people.
+
+The particular form of copyleft used by the GNU project is called the
+GNU General Public License. @xref{Copying}.
+
+@item Current Buffer
+The current buffer in Emacs is the Emacs buffer on which most editing
+commands operate. You can select any Emacs buffer as the current one.
+@xref{Buffers}.
+
+@item Current Line
+The line point is on (@pxref{Point}).
+
+@item Current Paragraph
+The paragraph that point is in. If point is between paragraphs, the
+current paragraph is the one that follows point. @xref{Paragraphs}.
+
+@item Current Defun
+The defun (q.v.@:) that point is in. If point is between defuns, the
+current defun is the one that follows point. @xref{Defuns}.
+
+@item Cursor
+The cursor is the rectangle on the screen which indicates the position
+called point (q.v.@:) at which insertion and deletion takes place.
+The cursor is on or under the character that follows point. Often
+people speak of `the cursor' when, strictly speaking, they mean
+`point'. @xref{Basic,Cursor,Basic Editing}.
+
+@item Customization
+Customization is making minor changes in the way Emacs works. It is
+often done by setting variables (@pxref{Variables}) or by rebinding
+key sequences (@pxref{Keymaps}).
+
+@item Default Argument
+The default for an argument is the value that will be assumed if you
+do not specify one. When the minibuffer is used to read an argument,
+the default argument is used if you just type @key{RET}.
+@xref{Minibuffer}.
+
+@item Default Directory
+When you specify a file name that does not start with @samp{/} or @samp{~},
+it is interpreted relative to the current buffer's default directory.
+@xref{Minibuffer File,Default Directory}.
+
+@item Defun
+A defun is a list at the top level of parenthesis or bracket structure
+in a program. It is so named because most such lists in Lisp programs
+are calls to the Lisp function @code{defun}. @xref{Defuns}.
+
+@item @key{DEL}
+@key{DEL} is a character that runs the command to delete one character of
+text. @xref{Basic,DEL,Basic Editing}.
+
+@item Deletion
+Deletion means erasing text without copying it into the kill ring
+(q.v.@:). The alternative is killing (q.v.@:). @xref{Killing,Deletion}.
+
+@item Deletion of Files
+Deleting a file means erasing it from the file system.
+@xref{Misc File Ops}.
+
+@item Deletion of Messages
+Deleting a message means flagging it to be eliminated from your mail
+file. Until you expunge (q.v.@:) the Rmail file, you can still undelete
+the messages you have deleted. @xref{Rmail Deletion}.
+
+@item Deletion of Windows
+Deleting a window means eliminating it from the screen. Other windows
+expand to use up the space. The deleted window can never come back,
+but no actual text is thereby lost. @xref{Windows}.
+
+@item Directory
+File directories are named collections in the file system, within which
+you can place individual files or subdirectories. @xref{Directories}.
+
+@item Dired
+Dired is the Emacs facility that displays the contents of a file
+directory and allows you to ``edit the directory,'' performing
+operations on the files in the directory. @xref{Dired}.
+
+@item Disabled Command
+A disabled command is one that you may not run without special
+confirmation. The usual reason for disabling a command is that it is
+confusing for beginning users. @xref{Disabling}.
+
+@item Down Event
+Short for `button down event'.
+
+@item Drag Event
+A drag event is the kind of input event generated when you press a mouse
+button, move the mouse, and then release the button. @xref{Mouse
+Buttons}.
+
+@item Dribble File
+A file into which Emacs writes all the characters that the user types
+on the keyboard. Dribble files are used to make a record for
+debugging Emacs bugs. Emacs does not make a dribble file unless you
+tell it to. @xref{Bugs}.
+
+@item Echo Area
+The echo area is the bottom line of the screen, used for echoing the
+arguments to commands, for asking questions, and printing brief messages
+(including error messages). The messages are stored in the buffer
+@samp{*Messages*} so you can review them later. @xref{Echo Area}.
+
+@item Echoing
+Echoing is acknowledging the receipt of commands by displaying them (in
+the echo area). Emacs never echoes single-character key sequences;
+longer key sequences echo only if you pause while typing them.
+
+@item Electric
+We say that a character is electric if it is normally self-inserting
+(q.v.), but the current major mode (q.v.) redefines it to do something
+else as well. For example, some programming language major modes define
+particular delimiter characters to reindent the line or insert one or
+more newlines in addition to self-insertion.
+
+@item Error
+An error occurs when an Emacs command cannot execute in the current
+circumstances. When an error occurs, execution of the command stops
+(unless the command has been programmed to do otherwise) and Emacs
+reports the error by printing an error message (q.v.@:). Type-ahead
+is discarded. Then Emacs is ready to read another editing command.
+
+@item Error Message
+An error message is a single line of output displayed by Emacs when the
+user asks for something impossible to do (such as, killing text
+forward when point is at the end of the buffer). They appear in the
+echo area, accompanied by a beep.
+
+@item @key{ESC}
+@key{ESC} is a character used as a prefix for typing Meta characters on
+keyboards lacking a @key{META} key. Unlike the @key{META} key (which,
+like the @key{SHIFT} key, is held down while another character is
+typed), you press the @key{ESC} key as you would press a letter key, and
+it applies to the next character you type.
+
+@item Expunging
+Expunging an Rmail file or Dired buffer is an operation that truly
+discards the messages or files you have previously flagged for deletion.
+
+@item File Locking
+Emacs used file locking to notice when two different users
+start to edit one file at the same time. @xref{Interlocking}.
+
+@item File Name
+A file name is a name that refers to a file. File names may be relative
+or absolute; the meaning of a relative file name depends on the current
+directory, but an absolute file name refers to the same file regardless
+of which directory is current. On GNU and Unix systems, an absolute
+file name starts with a slash (the root directory) or with @samp{~/} or
+@samp{~@var{user}/} (a home directory).
+
+Some people use the term ``pathname'' for file names, but we do not;
+we use the word ``path'' only in the term ``search path'' (q.v.).
+
+@item File-Name Component
+A file-name component names a file directly within a particular
+directory. On GNU and Unix systems, a file name is a sequence of
+file-name components, separated by slashes. For example, @file{foo/bar}
+is a file name containing two components, @samp{foo} and @samp{bar}; it
+refers to the file named @samp{bar} in the directory named @samp{foo} in
+the current directory.
+
+@item Fill Prefix
+The fill prefix is a string that should be expected at the beginning
+of each line when filling is done. It is not regarded as part of the
+text to be filled. @xref{Filling}.
+
+@item Filling
+Filling text means shifting text between consecutive lines so that all
+the lines are approximately the same length. @xref{Filling}.
+
+@item Formatted Text
+Formatted text is text that displays with formatting information while
+you edit. Formatting information includes fonts, colors, and specified
+margins. @xref{Formatted Text}.
+
+@item Frame
+A frame is a rectangular cluster of Emacs windows. Emacs starts out
+with one frame, but you can create more. You can subdivide each frame
+into Emacs windows (q.v.). When you are using X windows, all the frames
+can be visible at the same time. @xref{Frames}.
+
+@item Function Key
+A function key is a key on the keyboard that sends input but does not
+correspond to any character. @xref{Function Keys}.
+
+@item Global
+Global means `independent of the current environment; in effect
+throughout Emacs'. It is the opposite of local (q.v.@:). Particular
+examples of the use of `global' appear below.
+
+@item Global Abbrev
+A global definition of an abbrev (q.v.@:) is effective in all major
+modes that do not have local (q.v.@:) definitions for the same abbrev.
+@xref{Abbrevs}.
+
+@item Global Keymap
+The global keymap (q.v.@:) contains key bindings that are in effect
+except when overridden by local key bindings in a major mode's local
+keymap (q.v.@:). @xref{Keymaps}.
+
+@item Global Mark Ring
+The global mark ring records the series of buffers you have recently set
+a mark in. In many cases you can use this to backtrack through buffers
+you have been editing in, or in which you have found tags. @xref{Global
+Mark Ring}.
+
+@item Global Substitution
+Global substitution means replacing each occurrence of one string by
+another string through a large amount of text. @xref{Replace}.
+
+@item Global Variable
+The global value of a variable (q.v.@:) takes effect in all buffers
+that do not have their own local (q.v.@:) values for the variable.
+@xref{Variables}.
+
+@item Graphic Character
+Graphic characters are those assigned pictorial images rather than
+just names. All the non-Meta (q.v.@:) characters except for the
+Control (q.v.@:) characters are graphic characters. These include
+letters, digits, punctuation, and spaces; they do not include
+@key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts
+that character (in ordinary editing modes). @xref{Basic,,Basic Editing}.
+
+@item Highlighting
+Highlighting text means displaying it with a different foreground and/or
+background color to make it stand out from the rest of the text in the
+buffer.
+
+@item Hardcopy
+Hardcopy means printed output. Emacs has commands for making printed
+listings of text in Emacs buffers. @xref{Hardcopy}.
+
+@item @key{HELP}
+@key{HELP} is the Emacs name for @kbd{C-h} or @key{F1}. You can type
+@key{HELP} at any time to ask what options you have, or to ask what any
+command does. @xref{Help}.
+
+@item Hyper
+Hyper is the name of a modifier bit which a keyboard input character may
+have. To make a character Hyper, type it while holding down the
+@key{HYPER} key. Such characters are given names that start with
+@kbd{Hyper-} (usually written @kbd{H-} for short). @xref{User Input,
+Hyper}.
+
+@item Inbox
+An inbox is a file in which mail is delivered by the operating system.
+Rmail transfers mail from inboxes to Rmail files (q.v.@:) in which the
+mail is then stored permanently or until explicitly deleted.
+@xref{Rmail Inbox}.
+
+@item Indentation
+Indentation means blank space at the beginning of a line. Most
+programming languages have conventions for using indentation to
+illuminate the structure of the program, and Emacs has special
+commands to adjust indentation.
+@xref{Indentation}.
+
+@item Indirect Buffer
+An indirect buffer is a buffer that shares the text of another buffer,
+called its base buffer. @xref{Indirect Buffers}.
+
+@item Input Event
+An input event represents, within Emacs, one action taken by the user on
+the terminal. Input events include typing characters, typing function
+keys, pressing or releasing mouse buttons, and switching between Emacs
+frames. @xref{User Input}.
+
+@item Input Method
+An input method is a system for entering non-ASCII text characters by
+typing sequences of ASCII characters (q.v.@:). @xref{Input Methods}.
+
+@item Insertion
+Insertion means copying text into the buffer, either from the keyboard
+or from some other place in Emacs.
+
+@item Interlocking
+Interlocking is a feature for warning when you start to alter a file
+that someone else is already editing. @xref{Interlocking,,Simultaneous
+Editing}.
+
+@item Justification
+Justification means adding extra spaces to lines of text to make them
+come exactly to a specified width. @xref{Filling,Justification}.
+
+@item Keyboard Macro
+Keyboard macros are a way of defining new Emacs commands from
+sequences of existing ones, with no need to write a Lisp program.
+@xref{Keyboard Macros}.
+
+@item Key Sequence
+A key sequence (key, for short) is a sequence of input events (q.v.@:)
+that are meaningful as a single unit. If the key sequence is enough to
+specify one action, it is a complete key (q.v.@:); if it is not enough,
+it is a prefix key (q.v.@:). @xref{Keys}.
+
+@item Keymap
+The keymap is the data structure that records the bindings (q.v.@:) of
+key sequences to the commands that they run. For example, the global
+keymap binds the character @kbd{C-n} to the command function
+@code{next-line}. @xref{Keymaps}.
+
+@item Keyboard Translation Table
+The keyboard translation table is an array that translates the character
+codes that come from the terminal into the character codes that make up
+key sequences. @xref{Keyboard Translations}.
+
+@item Kill Ring
+The kill ring is where all text you have killed recently is saved.
+You can reinsert any of the killed text still in the ring; this is
+called yanking (q.v.@:). @xref{Yanking}.
+
+@item Killing
+Killing means erasing text and saving it on the kill ring so it can be
+yanked (q.v.@:) later. Some other systems call this ``cutting.''
+Most Emacs commands to erase text do killing, as opposed to deletion
+(q.v.@:). @xref{Killing}.
+
+@item Killing Jobs
+Killing a job (such as, an invocation of Emacs) means making it cease
+to exist. Any data within it, if not saved in a file, is lost.
+@xref{Exiting}.
+
+@item Language Environment
+Your choice of language environment specifies defaults for the input
+method (q.v.@:) and coding system (q.v.@:). @xref{Language
+Environments}. These defaults are relevant if you edit non-ASCII text
+(@pxref{International}).
+
+@item List
+A list is, approximately, a text string beginning with an open
+parenthesis and ending with the matching close parenthesis. In C mode
+and other non-Lisp modes, groupings surrounded by other kinds of matched
+delimiters appropriate to the language, such as braces, are also
+considered lists. Emacs has special commands for many operations on
+lists. @xref{Lists}.
+
+@item Local
+Local means `in effect only in a particular context'; the relevant
+kind of context is a particular function execution, a particular
+buffer, or a particular major mode. It is the opposite of `global'
+(q.v.@:). Specific uses of `local' in Emacs terminology appear below.
+
+@item Local Abbrev
+A local abbrev definition is effective only if a particular major mode
+is selected. In that major mode, it overrides any global definition
+for the same abbrev. @xref{Abbrevs}.
+
+@item Local Keymap
+A local keymap is used in a particular major mode; the key bindings
+(q.v.@:) in the current local keymap override global bindings of the
+same key sequences. @xref{Keymaps}.
+
+@item Local Variable
+A local value of a variable (q.v.@:) applies to only one buffer.
+@xref{Locals}.
+
+@item @kbd{M-}
+@kbd{M-} in the name of a character is an abbreviation for @key{META},
+one of the modifier keys that can accompany any character.
+@xref{User Input}.
+
+@item @kbd{M-C-}
+@kbd{M-C-} in the name of a character is an abbreviation for
+Control-Meta; it means the same thing as @kbd{C-M-}. If your
+terminal lacks a real @key{META} key, you type a Control-Meta character by
+typing @key{ESC} and then typing the corresponding Control character.
+@xref{User Input,C-M-}.
+
+@item @kbd{M-x}
+@kbd{M-x} is the key sequence which is used to call an Emacs command by
+name. This is how you run commands that are not bound to key sequences.
+@xref{M-x}.
+
+@item Mail
+Mail means messages sent from one user to another through the computer
+system, to be read at the recipient's convenience. Emacs has commands for
+composing and sending mail, and for reading and editing the mail you have
+received. @xref{Sending Mail}. @xref{Rmail}, for how to read mail.
+
+@item Mail Composition Method
+A mail composition method is a program runnable within Emacs for editing
+and sending a mail message. Emacs lets you select from several
+alternative mail composition methods. @xref{Mail Methods}.
+
+@item Major Mode
+The Emacs major modes are a mutually exclusive set of options, each of
+which configures Emacs for editing a certain sort of text. Ideally,
+each programming language has its own major mode. @xref{Major Modes}.
+
+@item Mark
+The mark points to a position in the text. It specifies one end of the
+region (q.v.@:), point being the other end. Many commands operate on
+all the text from point to the mark. Each buffer has its own mark.
+@xref{Mark}.
+
+@item Mark Ring
+The mark ring is used to hold several recent previous locations of the
+mark, just in case you want to move back to them. Each buffer has its
+own mark ring; in addition, there is a single global mark ring (q.v.).
+@xref{Mark Ring}.
+
+@item Menu Bar
+The menu bar is the line at the top of an Emacs frame. It contains
+words you can click on with the mouse to bring up menus. The menu bar
+feature is supported only with X. @xref{Menu Bars}.
+
+@item Message
+See `mail'.
+
+@item Meta
+Meta is the name of a modifier bit which a command character may have.
+It is present in a character if the character is typed with the
+@key{META} key held down. Such characters are given names that start
+with @kbd{Meta-} (usually written @kbd{M-} for short). For example,
+@kbd{M-<} is typed by holding down @key{META} and at the same time
+typing @kbd{<} (which itself is done, on most terminals, by holding
+down @key{SHIFT} and typing @kbd{,}). @xref{User Input,Meta}.
+
+@item Meta Character
+A Meta character is one whose character code includes the Meta bit.
+
+@item Minibuffer
+The minibuffer is the window that appears when necessary inside the
+echo area (q.v.@:), used for reading arguments to commands.
+@xref{Minibuffer}.
+
+@item Minibuffer History
+The minibuffer history records the text you have specified in the past
+for minibuffer arguments, so you can conveniently use the same text
+again. @xref{Minibuffer History}.
+
+@item Minor Mode
+A minor mode is an optional feature of Emacs which can be switched on
+or off independently of all other features. Each minor mode has a
+command to turn it on or off. @xref{Minor Modes}.
+
+@item Minor Mode Keymap
+A keymap that belongs to a minor mode and is active when that mode is
+enabled. Minor mode keymaps take precedence over the buffer's local
+keymap, just as the local keymap takes precedence over the global
+keymap. @xref{Keymaps}.
+
+@item Mode Line
+The mode line is the line at the bottom of each window (q.v.@:), giving
+status information on the buffer displayed in that window. @xref{Mode
+Line}.
+
+@item Modified Buffer
+A buffer (q.v.@:) is modified if its text has been changed since the
+last time the buffer was saved (or since when it was created, if it
+has never been saved). @xref{Saving}.
+
+@item Moving Text
+Moving text means erasing it from one place and inserting it in
+another. The usual way to move text by killing (q.v.@:) and then
+yanking (q.v.@:). @xref{Killing}.
+
+@item MULE
+MULE refers to the Emacs features for editing non-ASCII text
+using multibyte characters (q.v.@:). @xref{International}.
+
+@item Multibyte Character
+A multibyte character is a character that takes up several buffer
+positions. Emacs uses multibyte characters to represent non-ASCII text,
+since the number of non-ASCII characters is much more than 256.
+@xref{International Intro}.
+
+@item Named Mark
+A named mark is a register (q.v.@:) in its role of recording a
+location in text so that you can move point to that location.
+@xref{Registers}.
+
+@item Narrowing
+Narrowing means creating a restriction (q.v.@:) that limits editing in
+the current buffer to only a part of the text in the buffer. Text
+outside that part is inaccessible to the user until the boundaries are
+widened again, but it is still there, and saving the file saves it
+all. @xref{Narrowing}.
+
+@item Newline
+Control-J characters in the buffer terminate lines of text and are
+therefore also called newlines. @xref{Text Characters,Newline}.
+
+@item Numeric Argument
+A numeric argument is a number, specified before a command, to change
+the effect of the command. Often the numeric argument serves as a
+repeat count. @xref{Arguments}.
+
+@item Overwrite Mode
+Overwrite mode is a minor mode. When it is enabled, ordinary text
+characters replace the existing text after point rather than pushing
+it to the right. @xref{Minor Modes}.
+
+@item Page
+A page is a unit of text, delimited by formfeed characters (ASCII
+control-L, code 014) coming at the beginning of a line. Some Emacs
+commands are provided for moving over and operating on pages.
+@xref{Pages}.
+
+@item Paragraph
+Paragraphs are the medium-size unit of English text. There are
+special Emacs commands for moving over and operating on paragraphs.
+@xref{Paragraphs}.
+
+@item Parsing
+We say that certain Emacs commands parse words or expressions in the
+text being edited. Really, all they know how to do is find the other
+end of a word or expression. @xref{Syntax}.
+
+@item Point
+Point is the place in the buffer at which insertion and deletion
+occur. Point is considered to be between two characters, not at one
+character. The terminal's cursor (q.v.@:) indicates the location of
+point. @xref{Basic,Point}.
+
+@item Prefix Argument
+See `numeric argument'.
+
+@item Prefix Key
+A prefix key is a key sequence (q.v.@:) whose sole function is to
+introduce a set of longer key sequences. @kbd{C-x} is an example of
+prefix key; any two-character sequence starting with @kbd{C-x} is
+therefore a legitimate key sequence. @xref{Keys}.
+
+@item Primary Rmail File
+Your primary Rmail file is the file named @samp{RMAIL} in your home
+directory. That's where Rmail stores your incoming mail, unless you
+specify a different file name. @xref{Rmail}.
+
+@item Primary Selection
+The primary selection is one particular X selection (q.v.@:); it is the
+selection that most X applications use for transferring text to and from
+other applications.
+
+The Emacs kill commands set the primary selection and the yank command
+uses the primary selection when appropriate. @xref{Killing}.
+
+@item Prompt
+A prompt is text printed to ask the user for input. Displaying a prompt
+is called prompting. Emacs prompts always appear in the echo area
+(q.v.@:). One kind of prompting happens when the minibuffer is used to
+read an argument (@pxref{Minibuffer}); the echoing which happens when
+you pause in the middle of typing a multi-character key sequence is also
+a kind of prompting (@pxref{Echo Area}).
+
+@item Quitting
+Quitting means canceling a partially typed command or a running
+command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS). @xref{Quitting}.
+
+@item Quoting
+Quoting means depriving a character of its usual special significance.
+The most common kind of quoting in Emacs is with @kbd{C-q}. What
+constitutes special significance depends on the context and on
+convention. For example, an ``ordinary'' character as an Emacs command
+inserts itself; so in this context, a special character is any character
+that does not normally insert itself (such as @key{DEL}, for example),
+and quoting it makes it insert itself as if it were not special. Not
+all contexts allow quoting. @xref{Basic,Quoting,Basic Editing}.
+
+@item Quoting File Names
+Quoting a file name turns off the special significance of constructs
+such as @samp{$}, @samp{~} and @samp{:}. @xref{Quoted File Names}.
+
+@item Read-Only Buffer
+A read-only buffer is one whose text you are not allowed to change.
+Normally Emacs makes buffers read-only when they contain text which
+has a special significance to Emacs; for example, Dired buffers.
+Visiting a file that is write-protected also makes a read-only buffer.
+@xref{Buffers}.
+
+@item Rectangle
+A rectangle consists of the text in a given range of columns on a given
+range of lines. Normally you specify a rectangle by putting point at
+one corner and putting the mark at the opposite corner.
+@xref{Rectangles}.
+
+@item Recursive Editing Level
+A recursive editing level is a state in which part of the execution of
+a command involves asking the user to edit some text. This text may
+or may not be the same as the text to which the command was applied.
+The mode line indicates recursive editing levels with square brackets
+(@samp{[} and @samp{]}). @xref{Recursive Edit}.
+
+@item Redisplay
+Redisplay is the process of correcting the image on the screen to
+correspond to changes that have been made in the text being edited.
+@xref{Screen,Redisplay}.
+
+@item Regexp
+See `regular expression'.
+
+@item Region
+The region is the text between point (q.v.@:) and the mark (q.v.@:).
+Many commands operate on the text of the region. @xref{Mark,Region}.
+
+@item Registers
+Registers are named slots in which text or buffer positions or
+rectangles can be saved for later use. @xref{Registers}.
+
+@item Regular Expression
+A regular expression is a pattern that can match various text strings;
+for example, @samp{l[0-9]+} matches @samp{l} followed by one or more
+digits. @xref{Regexps}.
+
+@item Repeat Count
+See `numeric argument'.
+
+@item Replacement
+See `global substitution'.
+
+@item Restriction
+A buffer's restriction is the amount of text, at the beginning or the
+end of the buffer, that is temporarily inaccessible. Giving a buffer a
+nonzero amount of restriction is called narrowing (q.v.@:).
+@xref{Narrowing}.
+
+@item @key{RET}
+@key{RET} is a character that in Emacs runs the command to insert a
+newline into the text. It is also used to terminate most arguments
+read in the minibuffer (q.v.@:). @xref{User Input,Return}.
+
+@item Rmail File
+An Rmail file is a file containing text in a special format used by
+Rmail for storing mail. @xref{Rmail}.
+
+@item Saving
+Saving a buffer means copying its text into the file that was visited
+(q.v.@:) in that buffer. This is the way text in files actually gets
+changed by your Emacs editing. @xref{Saving}.
+
+@item Scroll Bar
+A scroll bar is a tall thin hollow box that appears at the side of a
+window. You can use mouse commands in the scroll bar to scroll the
+window. The scroll bar feature is supported only with X. @xref{Scroll
+Bars}.
+
+@item Scrolling
+Scrolling means shifting the text in the Emacs window so as to see a
+different part of the buffer. @xref{Display,Scrolling}.
+
+@item Searching
+Searching means moving point to the next occurrence of a specified
+string or the next match for a specified regular expression.
+@xref{Search}.
+
+@item Search Path
+A search path is a list of directory names, to be used for searching for
+files for certain purposes. For example, the variable @code{load-path}
+holds a search path for finding Lisp library files. @xref{Lisp Libraries}.
+
+@item Secondary Selection
+The secondary selection is one particular X selection; some X
+applications can use it for transferring text to and from other
+applications. Emacs has special mouse commands for transferring text
+using the secondary selection. @xref{Secondary Selection}.
+
+@item Selecting
+Selecting a buffer means making it the current (q.v.@:) buffer.
+@xref{Buffers,Selecting}.
+
+@item Selection
+The X window system allows an application program to specify named
+selections whose values are text. A program can also read the
+selections that other programs have set up. This is the principal way
+of transferring text between window applications. Emacs has commands to
+work with the primary (q.v.@:) selection and the secondary (q.v.@:)
+selection.
+
+@item Self-Documentation
+Self-documentation is the feature of Emacs which can tell you what any
+command does, or give you a list of all commands related to a topic
+you specify. You ask for self-documentation with the help character,
+@kbd{C-h}. @xref{Help}.
+
+@item Self-Inserting Character
+A character is self-inserting if typing that character inserts that
+character in the buffer. Ordinary printing and whitespace characters
+are self-inserting in Emacs, except in certain special major modes.
+
+@item Sentences
+Emacs has commands for moving by or killing by sentences.
+@xref{Sentences}.
+
+@item Sexp
+A sexp (short for `s-expression') is the basic syntactic unit of Lisp
+in its textual form: either a list, or Lisp atom. Many Emacs commands
+operate on sexps. The term `sexp' is generalized to languages other
+than Lisp, to mean a syntactically recognizable expression.
+@xref{Lists,Sexps}.
+
+@item Simultaneous Editing
+Simultaneous editing means two users modifying the same file at once.
+Simultaneous editing if not detected can cause one user to lose his
+work. Emacs detects all cases of simultaneous editing and warns one of
+the users to investigate. @xref{Interlocking,,Simultaneous Editing}.
+
+@item String
+A string is a kind of Lisp data object which contains a sequence of
+characters. Many Emacs variables are intended to have strings as
+values. The Lisp syntax for a string consists of the characters in the
+string with a @samp{"} before and another @samp{"} after. A @samp{"}
+that is part of the string must be written as @samp{\"} and a @samp{\}
+that is part of the string must be written as @samp{\\}. All other
+characters, including newline, can be included just by writing them
+inside the string; however, backslash sequences as in C, such as
+@samp{\n} for newline or @samp{\241} using an octal character code, are
+allowed as well.
+
+@item String Substitution
+See `global substitution'.
+
+@item Syntax Table
+The syntax table tells Emacs which characters are part of a word,
+which characters balance each other like parentheses, etc.
+@xref{Syntax}.
+
+@item Super
+Super is the name of a modifier bit which a keyboard input character may
+have. To make a character Super, type it while holding down the
+@key{SUPER} key. Such characters are given names that start with
+@kbd{Super-} (usually written @kbd{s-} for short). @xref{User Input,
+Super}.
+
+@item Tags Table
+A tags table is a file that serves as an index to the function
+definitions in one or more other files. @xref{Tags}.
+
+@item Termscript File
+A termscript file contains a record of all characters sent by Emacs to
+the terminal. It is used for tracking down bugs in Emacs redisplay.
+Emacs does not make a termscript file unless you tell it to.
+@xref{Bugs}.
+
+@item Text
+Two meanings (@pxref{Text}):
+
+@itemize @bullet
+@item
+Data consisting of a sequence of characters, as opposed to binary
+numbers, images, graphics commands, executable programs, and the like.
+The contents of an Emacs buffer are always text in this sense.
+@item
+Data consisting of written human language, as opposed to programs,
+or following the stylistic conventions of human language.
+@end itemize
+
+@item Top Level
+Top level is the normal state of Emacs, in which you are editing the
+text of the file you have visited. You are at top level whenever you
+are not in a recursive editing level (q.v.@:) or the minibuffer
+(q.v.@:), and not in the middle of a command. You can get back to top
+level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}.
+
+@item Transposition
+Transposing two units of text means putting each one into the place
+formerly occupied by the other. There are Emacs commands to transpose
+two adjacent characters, words, sexps (q.v.@:) or lines
+(@pxref{Transpose}).
+
+@item Truncation
+Truncating text lines in the display means leaving out any text on a
+line that does not fit within the right margin of the window
+displaying it. See also `continuation line'.
+@xref{Basic,Truncation,Basic Editing}.
+
+@item Undoing
+Undoing means making your previous editing go in reverse, bringing
+back the text that existed earlier in the editing session.
+@xref{Undo}.
+
+@item User Option
+A user option is a variable (q.v.@:) that exists so that you can customize
+Emacs by setting it to a new value. @xref{Variables}.
+
+@item Variable
+A variable is an object in Lisp that can store an arbitrary value.
+Emacs uses some variables for internal purposes, and has others (known
+as `user options' (q.v.@:)) just so that you can set their values to
+control the behavior of Emacs. The variables used in Emacs that you
+are likely to be interested in are listed in the Variables Index in
+this manual. @xref{Variables}, for information on variables.
+
+@item Version Control
+Version control systems keep track of multiple versions of a source file.
+They provide a more powerful alternative to keeping backup files (q.v.@:).
+@xref{Version Control}.
+
+@item Visiting
+Visiting a file means loading its contents into a buffer (q.v.@:)
+where they can be edited. @xref{Visiting}.
+
+@item Whitespace
+Whitespace is any run of consecutive formatting characters (space,
+tab, newline, and backspace).
+
+@item Widening
+Widening is removing any restriction (q.v.@:) on the current buffer;
+it is the opposite of narrowing (q.v.@:). @xref{Narrowing}.
+
+@item Window
+Emacs divides a frame (q.v.@:) into one or more windows, each of which
+can display the contents of one buffer (q.v.@:) at any time.
+@xref{Screen}, for basic information on how Emacs uses the screen.
+@xref{Windows}, for commands to control the use of windows.
+
+@item Word Abbrev
+Synonymous with `abbrev'.
+
+@item Word Search
+Word search is searching for a sequence of words, considering the
+punctuation between them as insignificant. @xref{Word Search}.
+
+@item WYSIWYG
+WYSIWYG stands for `What you see is what you get.' Emacs generally
+provides WYSIWYG editing for files of characters; in Enriched mode
+(@pxref{Formatted Text}), it provides WYSIWYG editing for files that
+include text formatting information.
+
+@item Yanking
+Yanking means reinserting text previously killed. It can be used to
+undo a mistaken kill, or for copying or moving text. Some other
+systems call this ``pasting.'' @xref{Yanking}.
+@end table
+
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1995 Free Software Foundation, Inc.
+@ifclear justgnu
+@node Manifesto,, MS-DOS, Top
+@unnumbered The GNU Manifesto
+@end ifclear
+@ifset justgnu
+Copyright (C) 1985, 1993 Free Software Foundation, Inc.
+
+Permission is granted to anyone to make or distribute verbatim copies
+of this document, in any medium, provided that the
+copyright notice and permission notice are preserved,
+and that the distributor grants the recipient permission
+for further redistribution as permitted by this notice.
+
+Modified versions may not be made.
+
+@node Top
+@top The GNU Manifesto
+@end ifset
+
+@quotation
+The GNU Manifesto which appears below was written by Richard Stallman at
+the beginning of the GNU project, to ask for participation and support.
+For the first few years, it was updated in minor ways to account for
+developments, but now it seems best to leave it unchanged as most people
+have seen it.
+
+Since that time, we have learned about certain common misunderstandings
+that different wording could help avoid. Footnotes added in 1993 help
+clarify these points.
+
+For up-to-date information about the available GNU software, please see
+the latest issue of the GNU's Bulletin. The list is much too long to
+include here.
+@end quotation
+
+@unnumberedsec What's GNU? Gnu's Not Unix!
+
+GNU, which stands for Gnu's Not Unix, is the name for the complete
+Unix-compatible software system which I am writing so that I can give it
+away free to everyone who can use it.@footnote{The wording here was
+careless. The intention was that nobody would have to pay for
+@emph{permission} to use the GNU system. But the words don't make this
+clear, and people often interpret them as saying that copies of GNU
+should always be distributed at little or no charge. That was never the
+intent; later on, the manifesto mentions the possibility of companies
+providing the service of distribution for a profit. Subsequently I have
+learned to distinguish carefully between ``free'' in the sense of
+freedom and ``free'' in the sense of price. Free software is software
+that users have the freedom to distribute and change. Some users may
+obtain copies at no charge, while others pay to obtain copies---and if
+the funds help support improving the software, so much the better. The
+important thing is that everyone who has a copy has the freedom to
+cooperate with others in using it.} Several other volunteers are helping
+me. Contributions of time, money, programs and equipment are greatly
+needed.
+
+So far we have an Emacs text editor with Lisp for writing editor commands,
+a source level debugger, a yacc-compatible parser generator, a linker, and
+around 35 utilities. A shell (command interpreter) is nearly completed. A
+new portable optimizing C compiler has compiled itself and may be released
+this year. An initial kernel exists but many more features are needed to
+emulate Unix. When the kernel and compiler are finished, it will be
+possible to distribute a GNU system suitable for program development. We
+will use @TeX{} as our text formatter, but an nroff is being worked on. We
+will use the free, portable X window system as well. After this we will
+add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of
+other things, plus on-line documentation. We hope to supply, eventually,
+everything useful that normally comes with a Unix system, and more.
+
+GNU will be able to run Unix programs, but will not be identical to Unix.
+We will make all improvements that are convenient, based on our experience
+with other operating systems. In particular, we plan to have longer
+file names, file version numbers, a crashproof file system, file name
+completion perhaps, terminal-independent display support, and perhaps
+eventually a Lisp-based window system through which several Lisp programs
+and ordinary Unix programs can share a screen. Both C and Lisp will be
+available as system programming languages. We will try to support UUCP,
+MIT Chaosnet, and Internet protocols for communication.
+
+GNU is aimed initially at machines in the 68000/16000 class with virtual
+memory, because they are the easiest machines to make it run on. The extra
+effort to make it run on smaller machines will be left to someone who wants
+to use it on them.
+
+To avoid horrible confusion, please pronounce the `G' in the word `GNU'
+when it is the name of this project.
+
+@unnumberedsec Why I Must Write GNU
+
+I consider that the golden rule requires that if I like a program I must
+share it with other people who like it. Software sellers want to divide
+the users and conquer them, making each user agree not to share with
+others. I refuse to break solidarity with other users in this way. I
+cannot in good conscience sign a nondisclosure agreement or a software
+license agreement. For years I worked within the Artificial Intelligence
+Lab to resist such tendencies and other inhospitalities, but eventually
+they had gone too far: I could not remain in an institution where such
+things are done for me against my will.
+
+So that I can continue to use computers without dishonor, I have decided to
+put together a sufficient body of free software so that I will be able to
+get along without any software that is not free. I have resigned from the
+AI lab to deny MIT any legal excuse to prevent me from giving GNU away.
+
+@unnumberedsec Why GNU Will Be Compatible with Unix
+
+Unix is not my ideal system, but it is not too bad. The essential features
+of Unix seem to be good ones, and I think I can fill in what Unix lacks
+without spoiling them. And a system compatible with Unix would be
+convenient for many other people to adopt.
+
+@unnumberedsec How GNU Will Be Available
+
+GNU is not in the public domain. Everyone will be permitted to modify and
+redistribute GNU, but no distributor will be allowed to restrict its
+further redistribution. That is to say, proprietary modifications will not
+be allowed. I want to make sure that all versions of GNU remain free.
+
+@unnumberedsec Why Many Other Programmers Want to Help
+
+I have found many other programmers who are excited about GNU and want to
+help.
+
+Many programmers are unhappy about the commercialization of system
+software. It may enable them to make more money, but it requires them to
+feel in conflict with other programmers in general rather than feel as
+comrades. The fundamental act of friendship among programmers is the
+sharing of programs; marketing arrangements now typically used essentially
+forbid programmers to treat others as friends. The purchaser of software
+must choose between friendship and obeying the law. Naturally, many decide
+that friendship is more important. But those who believe in law often do
+not feel at ease with either choice. They become cynical and think that
+programming is just a way of making money.
+
+By working on and using GNU rather than proprietary programs, we can be
+hospitable to everyone and obey the law. In addition, GNU serves as an
+example to inspire and a banner to rally others to join us in sharing.
+This can give us a feeling of harmony which is impossible if we use
+software that is not free. For about half the programmers I talk to, this
+is an important happiness that money cannot replace.
+
+@unnumberedsec How You Can Contribute
+
+I am asking computer manufacturers for donations of machines and money.
+I'm asking individuals for donations of programs and work.
+
+One consequence you can expect if you donate machines is that GNU will run
+on them at an early date. The machines should be complete, ready to use
+systems, approved for use in a residential area, and not in need of
+sophisticated cooling or power.
+
+I have found very many programmers eager to contribute part-time work for
+GNU. For most projects, such part-time distributed work would be very hard
+to coordinate; the independently-written parts would not work together.
+But for the particular task of replacing Unix, this problem is absent. A
+complete Unix system contains hundreds of utility programs, each of which
+is documented separately. Most interface specifications are fixed by Unix
+compatibility. If each contributor can write a compatible replacement for
+a single Unix utility, and make it work properly in place of the original
+on a Unix system, then these utilities will work right when put together.
+Even allowing for Murphy to create a few unexpected problems, assembling
+these components will be a feasible task. (The kernel will require closer
+communication and will be worked on by a small, tight group.)
+
+If I get donations of money, I may be able to hire a few people full or
+part time. The salary won't be high by programmers' standards, but I'm
+looking for people for whom building community spirit is as important as
+making money. I view this as a way of enabling dedicated people to devote
+their full energies to working on GNU by sparing them the need to make a
+living in another way.
+
+@unnumberedsec Why All Computer Users Will Benefit
+
+Once GNU is written, everyone will be able to obtain good system
+software free, just like air.@footnote{This is another place I failed to
+distinguish carefully between the two different meanings of ``free''.
+The statement as it stands is not false---you can get copies of GNU
+software at no charge, from your friends or over the net. But it does
+suggest the wrong idea.}
+
+This means much more than just saving everyone the price of a Unix license.
+It means that much wasteful duplication of system programming effort will
+be avoided. This effort can go instead into advancing the state of the
+art.
+
+Complete system sources will be available to everyone. As a result, a user
+who needs changes in the system will always be free to make them himself,
+or hire any available programmer or company to make them for him. Users
+will no longer be at the mercy of one programmer or company which owns the
+sources and is in sole position to make changes.
+
+Schools will be able to provide a much more educational environment by
+encouraging all students to study and improve the system code. Harvard's
+computer lab used to have the policy that no program could be installed on
+the system if its sources were not on public display, and upheld it by
+actually refusing to install certain programs. I was very much inspired by
+this.
+
+Finally, the overhead of considering who owns the system software and what
+one is or is not entitled to do with it will be lifted.
+
+Arrangements to make people pay for using a program, including licensing of
+copies, always incur a tremendous cost to society through the cumbersome
+mechanisms necessary to figure out how much (that is, which programs) a
+person must pay for. And only a police state can force everyone to obey
+them. Consider a space station where air must be manufactured at great
+cost: charging each breather per liter of air may be fair, but wearing the
+metered gas mask all day and all night is intolerable even if everyone can
+afford to pay the air bill. And the TV cameras everywhere to see if you
+ever take the mask off are outrageous. It's better to support the air
+plant with a head tax and chuck the masks.
+
+Copying all or parts of a program is as natural to a programmer as
+breathing, and as productive. It ought to be as free.
+
+@unnumberedsec Some Easily Rebutted Objections to GNU's Goals
+
+@quotation
+``Nobody will use it if it is free, because that means they can't rely
+on any support.''
+
+``You have to charge for the program to pay for providing the
+support.''
+@end quotation
+
+If people would rather pay for GNU plus service than get GNU free without
+service, a company to provide just service to people who have obtained GNU
+free ought to be profitable.@footnote{Several such companies now exist.}
+
+We must distinguish between support in the form of real programming work
+and mere handholding. The former is something one cannot rely on from a
+software vendor. If your problem is not shared by enough people, the
+vendor will tell you to get lost.
+
+If your business needs to be able to rely on support, the only way is to
+have all the necessary sources and tools. Then you can hire any available
+person to fix your problem; you are not at the mercy of any individual.
+With Unix, the price of sources puts this out of consideration for most
+businesses. With GNU this will be easy. It is still possible for there to
+be no available competent person, but this problem cannot be blamed on
+distribution arrangements. GNU does not eliminate all the world's problems,
+only some of them.
+
+Meanwhile, the users who know nothing about computers need handholding:
+doing things for them which they could easily do themselves but don't know
+how.
+
+Such services could be provided by companies that sell just hand-holding
+and repair service. If it is true that users would rather spend money and
+get a product with service, they will also be willing to buy the service
+having got the product free. The service companies will compete in quality
+and price; users will not be tied to any particular one. Meanwhile, those
+of us who don't need the service should be able to use the program without
+paying for the service.
+
+@quotation
+``You cannot reach many people without advertising,
+and you must charge for the program to support that.''
+
+``It's no use advertising a program people can get free.''
+@end quotation
+
+There are various forms of free or very cheap publicity that can be used to
+inform numbers of computer users about something like GNU. But it may be
+true that one can reach more microcomputer users with advertising. If this
+is really so, a business which advertises the service of copying and
+mailing GNU for a fee ought to be successful enough to pay for its
+advertising and more. This way, only the users who benefit from the
+advertising pay for it.
+
+On the other hand, if many people get GNU from their friends, and such
+companies don't succeed, this will show that advertising was not really
+necessary to spread GNU. Why is it that free market advocates don't
+want to let the free market decide this?@footnote{The Free Software
+Foundation raises most of its funds from a distribution service,
+although it is a charity rather than a company. If @emph{no one}
+chooses to obtain copies by ordering from the FSF, it will be unable
+to do its work. But this does not mean that proprietary restrictions
+are justified to force every user to pay. If a small fraction of all
+the users order copies from the FSF, that is sufficient to keep the FSF
+afloat. So we ask users to choose to support us in this way. Have you
+done your part?}
+
+@quotation
+``My company needs a proprietary operating system
+to get a competitive edge.''
+@end quotation
+
+GNU will remove operating system software from the realm of competition.
+You will not be able to get an edge in this area, but neither will your
+competitors be able to get an edge over you. You and they will compete in
+other areas, while benefiting mutually in this one. If your business is
+selling an operating system, you will not like GNU, but that's tough on
+you. If your business is something else, GNU can save you from being
+pushed into the expensive business of selling operating systems.
+
+I would like to see GNU development supported by gifts from many
+manufacturers and users, reducing the cost to each.@footnote{A group of
+computer companies recently pooled funds to support maintenance of the
+GNU C Compiler.}
+
+@quotation
+``Don't programmers deserve a reward for their creativity?''
+@end quotation
+
+If anything deserves a reward, it is social contribution. Creativity can
+be a social contribution, but only in so far as society is free to use the
+results. If programmers deserve to be rewarded for creating innovative
+programs, by the same token they deserve to be punished if they restrict
+the use of these programs.
+
+@quotation
+``Shouldn't a programmer be able to ask for a reward for his creativity?''
+@end quotation
+
+There is nothing wrong with wanting pay for work, or seeking to maximize
+one's income, as long as one does not use means that are destructive. But
+the means customary in the field of software today are based on
+destruction.
+
+Extracting money from users of a program by restricting their use of it is
+destructive because the restrictions reduce the amount and the ways that
+the program can be used. This reduces the amount of wealth that humanity
+derives from the program. When there is a deliberate choice to restrict,
+the harmful consequences are deliberate destruction.
+
+The reason a good citizen does not use such destructive means to become
+wealthier is that, if everyone did so, we would all become poorer from the
+mutual destructiveness. This is Kantian ethics; or, the Golden Rule.
+Since I do not like the consequences that result if everyone hoards
+information, I am required to consider it wrong for one to do so.
+Specifically, the desire to be rewarded for one's creativity does not
+justify depriving the world in general of all or part of that creativity.
+
+@quotation
+``Won't programmers starve?''
+@end quotation
+
+I could answer that nobody is forced to be a programmer. Most of us cannot
+manage to get any money for standing on the street and making faces. But
+we are not, as a result, condemned to spend our lives standing on the
+street making faces, and starving. We do something else.
+
+But that is the wrong answer because it accepts the questioner's implicit
+assumption: that without ownership of software, programmers cannot possibly
+be paid a cent. Supposedly it is all or nothing.
+
+The real reason programmers will not starve is that it will still be
+possible for them to get paid for programming; just not paid as much as
+now.
+
+Restricting copying is not the only basis for business in software. It is
+the most common basis because it brings in the most money. If it were
+prohibited, or rejected by the customer, software business would move to
+other bases of organization which are now used less often. There are
+always numerous ways to organize any kind of business.
+
+Probably programming will not be as lucrative on the new basis as it is
+now. But that is not an argument against the change. It is not considered
+an injustice that sales clerks make the salaries that they now do. If
+programmers made the same, that would not be an injustice either. (In
+practice they would still make considerably more than that.)
+
+@quotation
+``Don't people have a right to control how their creativity is used?''
+@end quotation
+
+``Control over the use of one's ideas'' really constitutes control over
+other people's lives; and it is usually used to make their lives more
+difficult.
+
+People who have studied the issue of intellectual property rights carefully
+(such as lawyers) say that there is no intrinsic right to intellectual
+property. The kinds of supposed intellectual property rights that the
+government recognizes were created by specific acts of legislation for
+specific purposes.
+
+For example, the patent system was established to encourage inventors to
+disclose the details of their inventions. Its purpose was to help society
+rather than to help inventors. At the time, the life span of 17 years for
+a patent was short compared with the rate of advance of the state of the
+art. Since patents are an issue only among manufacturers, for whom the
+cost and effort of a license agreement are small compared with setting up
+production, the patents often do not do much harm. They do not obstruct
+most individuals who use patented products.
+
+The idea of copyright did not exist in ancient times, when authors
+frequently copied other authors at length in works of non-fiction. This
+practice was useful, and is the only way many authors' works have survived
+even in part. The copyright system was created expressly for the purpose
+of encouraging authorship. In the domain for which it was
+invented---books, which could be copied economically only on a printing
+press---it did little harm, and did not obstruct most of the individuals
+who read the books.
+
+All intellectual property rights are just licenses granted by society
+because it was thought, rightly or wrongly, that society as a whole would
+benefit by granting them. But in any particular situation, we have to ask:
+are we really better off granting such license? What kind of act are we
+licensing a person to do?
+
+The case of programs today is very different from that of books a hundred
+years ago. The fact that the easiest way to copy a program is from one
+neighbor to another, the fact that a program has both source code and
+object code which are distinct, and the fact that a program is used rather
+than read and enjoyed, combine to create a situation in which a person who
+enforces a copyright is harming society as a whole both materially and
+spiritually; in which a person should not do so regardless of whether the
+law enables him to.
+
+@quotation
+``Competition makes things get done better.''
+@end quotation
+
+The paradigm of competition is a race: by rewarding the winner, we
+encourage everyone to run faster. When capitalism really works this way,
+it does a good job; but its defenders are wrong in assuming it always works
+this way. If the runners forget why the reward is offered and become
+intent on winning, no matter how, they may find other strategies---such as,
+attacking other runners. If the runners get into a fist fight, they will
+all finish late.
+
+Proprietary and secret software is the moral equivalent of runners in a
+fist fight. Sad to say, the only referee we've got does not seem to
+object to fights; he just regulates them (``For every ten yards you run,
+you can fire one shot''). He really ought to break them up, and penalize
+runners for even trying to fight.
+
+@quotation
+``Won't everyone stop programming without a monetary incentive?''
+@end quotation
+
+Actually, many people will program with absolutely no monetary incentive.
+Programming has an irresistible fascination for some people, usually the
+people who are best at it. There is no shortage of professional musicians
+who keep at it even though they have no hope of making a living that way.
+
+But really this question, though commonly asked, is not appropriate to the
+situation. Pay for programmers will not disappear, only become less. So
+the right question is, will anyone program with a reduced monetary
+incentive? My experience shows that they will.
+
+For more than ten years, many of the world's best programmers worked at the
+Artificial Intelligence Lab for far less money than they could have had
+anywhere else. They got many kinds of non-monetary rewards: fame and
+appreciation, for example. And creativity is also fun, a reward in itself.
+
+Then most of them left when offered a chance to do the same interesting
+work for a lot of money.
+
+What the facts show is that people will program for reasons other than
+riches; but if given a chance to make a lot of money as well, they will
+come to expect and demand it. Low-paying organizations do poorly in
+competition with high-paying ones, but they do not have to do badly if the
+high-paying ones are banned.
+
+@quotation
+``We need the programmers desperately. If they demand that we
+stop helping our neighbors, we have to obey.''
+@end quotation
+
+You're never so desperate that you have to obey this sort of demand.
+Remember: millions for defense, but not a cent for tribute!
+
+@quotation
+``Programmers need to make a living somehow.''
+@end quotation
+
+In the short run, this is true. However, there are plenty of ways that
+programmers could make a living without selling the right to use a program.
+This way is customary now because it brings programmers and businessmen the
+most money, not because it is the only way to make a living. It is easy to
+find other ways if you want to find them. Here are a number of examples.
+
+A manufacturer introducing a new computer will pay for the porting of
+operating systems onto the new hardware.
+
+The sale of teaching, hand-holding and maintenance services could also
+employ programmers.
+
+People with new ideas could distribute programs as freeware, asking for
+donations from satisfied users, or selling hand-holding services. I have
+met people who are already working this way successfully.
+
+Users with related needs can form users' groups, and pay dues. A group
+would contract with programming companies to write programs that the
+group's members would like to use.
+
+All sorts of development can be funded with a Software Tax:
+
+@quotation
+Suppose everyone who buys a computer has to pay x percent of
+the price as a software tax. The government gives this to
+an agency like the NSF to spend on software development.
+
+But if the computer buyer makes a donation to software development
+himself, he can take a credit against the tax. He can donate to
+the project of his own choosing---often, chosen because he hopes to
+use the results when it is done. He can take a credit for any amount
+of donation up to the total tax he had to pay.
+
+The total tax rate could be decided by a vote of the payers of
+the tax, weighted according to the amount they will be taxed on.
+
+The consequences:
+
+@itemize @bullet
+@item
+The computer-using community supports software development.
+@item
+This community decides what level of support is needed.
+@item
+Users who care which projects their share is spent on
+can choose this for themselves.
+@end itemize
+@end quotation
+
+In the long run, making programs free is a step toward the post-scarcity
+world, where nobody will have to work very hard just to make a living.
+People will be free to devote themselves to activities that are fun, such
+as programming, after spending the necessary ten hours a week on required
+tasks such as legislation, family counseling, robot repair and asteroid
+prospecting. There will be no need to be able to make a living from
+programming.
+
+We have already greatly reduced the amount of work that the whole society
+must do for its actual productivity, but only a little of this has
+translated itself into leisure for workers because much nonproductive
+activity is required to accompany productive activity. The main causes of
+this are bureaucracy and isometric struggles against competition. Free
+software will greatly reduce these drains in the area of software
+production. We must do this, in order for technical gains in productivity
+to translate into less work for us.
--- /dev/null
+\input texinfo
+@c -*-texinfo-*-
+@c Copyright (C) 1995 Free Software Foundation, Inc.
+@setfilename gnus-faq.info
+
+@node Frequently Asked Questions
+@section Frequently Asked Questions
+
+This is the Gnus Frequently Asked Questions list.
+If you have a Web browser, the official hypertext version is at
+@file{http://www.miranova.com/~steve/gnus-faq.html>}, and has
+probably been updated since you got this manual.
+
+@menu
+* Installation FAQ:: Installation of Gnus.
+* Customization FAQ:: Customizing Gnus.
+* Reading News FAQ:: News Reading Questions.
+* Reading Mail FAQ:: Mail Reading Questions.
+@end menu
+
+
+@node Installation FAQ
+@subsection Installation
+
+@itemize @bullet
+@item
+Q1.1 What is the latest version of Gnus?
+
+The latest (and greatest) version is 5.0.10. You might also run
+across something called @emph{September Gnus}. September Gnus
+is the alpha version of the next major release of Gnus. It is currently
+not stable enough to run unless you are prepared to debug lisp.
+
+@item
+Q1.2 Where do I get Gnus?
+
+Any of the following locations:
+
+@itemize @minus
+@item
+@file{ftp://ftp.ifi.uio.no/pub/emacs/gnus/gnus.tar.gz}
+
+@item
+@file{ftp://ftp.pilgrim.umass.edu/pub/misc/ding/}
+
+@item
+@file{gopher://gopher.pilgrim.umass.edu/11/pub/misc/ding/}
+
+@item
+@file{ftp://aphrodite.nectar.cs.cmu.edu/pub/ding-gnus/}
+
+@item
+@file{ftp://ftp.solace.mh.se:/pub/gnu/elisp/}
+
+@end itemize
+
+@item
+Q1.3 Which version of Emacs do I need?
+
+At least GNU Emacs 19.28, or XEmacs 19.12 is recommended. GNU Emacs
+19.25 has been reported to work under certain circumstances, but it
+doesn't @emph{officially} work on it. 19.27 has also been reported to
+work. Gnus has been reported to work under OS/2 as well as Unix.
+
+
+@item
+Q1.4 Where is timezone.el?
+
+Upgrade to XEmacs 19.13. In earlier versions of XEmacs this file was
+placed with Gnus 4.1.3, but that has been corrected.
+
+
+@item
+Q1.5 When I run Gnus on XEmacs 19.13 I get weird error messages.
+
+You're running an old version of Gnus. Upgrade to at least version
+5.0.4.
+
+
+@item
+Q1.6 How do I unsubscribe from the Mailing List?
+
+Send an e-mail message to @file{ding-request@@ifi.uio.no} with the magic word
+@emph{unsubscribe} somewhere in it, and you will be removed.
+
+If you are reading the digest version of the list, send an e-mail message
+to @*
+@file{ding-rn-digests-d-request@@moe.shore.net}
+with @emph{unsubscribe} as the subject and you will be removed.
+
+
+@item
+Q1.7 How do I run Gnus on both Emacs and XEmacs?
+
+The basic answer is to byte-compile under XEmacs, and then you can
+run under either Emacsen. There is, however, a potential version
+problem with easymenu.el with Gnu Emacs prior to 19.29.
+
+Per Abrahamsen <abraham@@dina.kvl.dk> writes :@*
+The internal easymenu.el interface changed between 19.28 and 19.29 in
+order to make it possible to create byte compiled files that can be
+shared between Gnu Emacs and XEmacs. The change is upward
+compatible, but not downward compatible.
+This gives the following compatibility table:
+
+@example
+Compiled with: | Can be used with:
+----------------+--------------------------------------
+19.28 | 19.28 19.29
+19.29 | 19.29 XEmacs
+XEmacs | 19.29 XEmacs
+@end example
+
+If you have Gnu Emacs 19.28 or earlier, or XEmacs 19.12 or earlier, get
+a recent version of auc-menu.el from
+@file{ftp://ftp.iesd.auc.dk/pub/emacs-lisp/auc-menu.el}, and install it
+under the name easymenu.el somewhere early in your load path.
+
+
+@item
+Q1.8 What resources are available?
+
+There is the newsgroup Gnu.emacs.gnus. Discussion of Gnus 5.x is now
+taking place there. There is also a mailing list, send mail to
+@file{ding-request@@ifi.uio.no} with the magic word @emph{subscribe}
+somewhere in it.
+
+@emph{NOTE:} the traffic on this list is heavy so you may not want to be
+on it (unless you use Gnus as your mailer reader, that is). The mailing
+list is mainly for developers and testers.
+
+Gnus has a home World Wide Web page at@*
+@file{http://www.ifi.uio.no/~larsi/ding.html}.
+
+Gnus has a write up in the X Windows Applications FAQ at@*
+@file{http://www.ee.ryerson.ca:8080/~elf/xapps/Q-III.html}.
+
+The Gnus manual is also available on the World Wide Web. The canonical
+source is in Norway at@*
+@file{http://www.ifi.uio.no/~larsi/ding-manual/gnus_toc.html}.
+
+There are three mirrors in the United States:
+@enumerate
+@item
+@file{http://www.miranova.com/gnus-man/}
+
+@item
+@file{http://www.pilgrim.umass.edu/pub/misc/ding/manual/gnus_toc.html}
+
+@item
+@file{http://www.rtd.com/~woo/gnus/}
+
+@end enumerate
+
+PostScript copies of the Gnus Reference card are available from@*
+@file{ftp://ftp.cs.ualberta.ca/pub/oolog/gnus/}. They are mirrored at@*
+@file{ftp://ftp.pilgrim.umass.edu/pub/misc/ding/refcard/} in the
+United States. And@*
+@file{ftp://marvin.fkphy.uni-duesseldorf.de/pub/gnus/}
+in Germany.
+
+An online version of the Gnus FAQ is available at@*
+@file{http://www.miranova.com/~steve/gnus-faq.html}. Off-line formats
+are also available:@*
+ASCII: @file{ftp://ftp.miranova.com/pub/gnus/gnus-faq}@*
+PostScript: @file{ftp://ftp.miranova.com/pub/gnus/gnus-faq.ps}.
+
+
+@item
+Q1.9 Gnus hangs on connecting to NNTP server
+
+I am running XEmacs on SunOS and Gnus prints a message about Connecting
+to NNTP server and then just hangs.
+
+Ben Wing <wing@@netcom.com> writes :@*
+I wonder if you're hitting the infamous @emph{libresolv} problem.
+The basic problem is that under SunOS you can compile either
+with DNS or NIS name lookup libraries but not both. Try
+substituting the IP address and see if that works; if so, you
+need to download the sources and recompile.
+
+
+@item
+Q1.10 Mailcrypt 3.4 doesn't work
+
+This problem is verified to still exist in Gnus 5.0.9 and MailCrypt 3.4.
+The answer comes from Peter Arius
+<arius@@immd2.informatik.uni-erlangen.de>.
+
+I found out that mailcrypt uses
+@code{gnus-eval-in-buffer-window}, which is a macro.
+It seems as if you have
+compiled mailcrypt with plain old GNUS in load path, and the XEmacs byte
+compiler has inserted that macro definition into
+@file{mc-toplev.elc}.
+The solution is to recompile @file{mc-toplev.el} with Gnus 5 in
+load-path, and it works fine.
+
+Steve Baur <steve@@miranova.com> adds :@*
+The problem also manifests itself if neither GNUS 4 nor Gnus 5 is in the
+load-path.
+
+
+@item
+Q1.11 What other packages work with Gnus?
+
+@itemize @minus
+@item
+Mailcrypt.
+
+Mailcrypt is an Emacs interface to PGP. It works, it installs
+without hassle, and integrates very easily. Mailcrypt can be
+obtained from@*
+@file{ftp://cag.lcs.mit.edu/pub/patl/mailcrypt-3.4.tar.gz}.
+
+@item
+Tiny Mime.
+
+Tiny Mime is an Emacs MUA interface to MIME. Installation is
+a two-step process unlike most other packages, so you should
+be prepared to move the byte-compiled code somewhere. There
+are currently two versions of this package available. It can
+be obtained from@*
+@file{ftp://ftp.jaist.ac.jp/pub/GNU/elisp/}.
+Be sure to apply the supplied patch. It works with Gnus through
+version 5.0.9. In order for all dependencies to work correctly
+the load sequence is as follows:
+@lisp
+ (load "tm-setup")
+ (load "gnus")
+ (load "mime-compose")
+@end lisp
+
+@emph{NOTE:} Loading the package disables citation highlighting by
+default. To get the old behavior back, use the @kbd{M-t} command.
+
+@end itemize
+
+@end itemize
+
+
+@node Customization FAQ
+@subsection Customization
+
+@itemize @bullet
+@item
+Q2.1 Custom Edit does not work under XEmacs
+
+The custom package has not been ported to XEmacs.
+
+
+@item
+Q2.2 How do I quote messages?
+
+I see lots of messages with quoted material in them. I am wondering
+how to have Gnus do it for me.
+
+This is Gnus, so there are a number of ways of doing this. You can use
+the built-in commands to do this. There are the @kbd{F} and @kbd{R}
+keys from the summary buffer which automatically include the article
+being responded to. These commands are also selectable as @i{Followup
+and Yank} and @i{Reply and Yank} in the Post menu.
+
+@kbd{C-c C-y} grabs the previous message and prefixes each line with
+@code{ail-indentation-spaces} spaces or @code{mail-yank-prefix} if that is
+non-nil, unless you have set your own @code{mail-citation-hook}, which will
+be called to to do the job.
+
+You might also consider the Supercite package, which allows for pretty
+arbitrarily complex quoting styles. Some people love it, some people
+hate it.
+
+
+@item
+Q2.3 How can I keep my nnvirtual:* groups sorted?
+
+How can I most efficiently arrange matters so as to keep my nnvirtual:*
+(etc) groups at the top of my group selection buffer, whilst keeping
+everything sorted in alphabetical order.
+
+If you don't subscribe often to new groups then the easiest way is to
+first sort the groups and then manually kill and yank the virtuals
+wherever you want them.
+
+
+@item
+Q2.4 Any good suggestions on stuff for an all.SCORE file?
+
+Here is a collection of suggestions from the Gnus mailing list.
+
+@enumerate
+@item
+From ``Dave Disser'' <disser@@sdd.hp.com>@*
+I like blasting anything without lowercase letters. Weeds out most of
+the make $$ fast, as well as the lame titles like ``IBM'' and ``HP-UX''
+with no further description.
+@lisp
+ (("Subject"
+ ("^\\(Re: \\)?[^a-z]*$" -200 nil R)))
+@end lisp
+
+@item
+From ``Peter Arius'' <arius@@immd2.informatik.uni-erlangen.de>@*
+The most vital entries in my (still young) all.SCORE:
+@lisp
+(("xref"
+ ("alt.fan.oj-simpson" -1000 nil s))
+ ("subject"
+ ("\\<\\(make\\|fast\\|big\\)\\s-*\\(money\\|cash\\|bucks?\\)\\>" -1000 nil r)
+ ("$$$$" -1000 nil s)))
+@end lisp
+
+@item
+From ``Per Abrahamsen'' <abraham@@dina.kvl.dk>@*
+@lisp
+(("subject"
+ ;; CAPS OF THE WORLD, UNITE
+ ("^..[^a-z]+$" -1 nil R)
+ ;; $$$ Make Money $$$ (Try work)
+ ("$" -1 nil s)
+ ;; I'm important! And I have exclamation marks to prove it!
+ ("!" -1 nil s)))
+@end lisp
+
+@item
+From ``heddy boubaker'' <boubaker@@cenatls.cena.dgac.fr>@*
+I would like to contribute with mine.
+@lisp
+(
+ (read-only t)
+ ("subject"
+ ;; ALL CAPS SUBJECTS
+ ("^\\([Rr][Ee]: +\\)?[^a-z]+$" -1 nil R)
+ ;; $$$ Make Money $$$
+ ("$$" -10 nil s)
+ ;; Empty subjects are worthless!
+ ("^ *\\([(<]none[>)]\\|(no subject\\( given\\)?)\\)? *$" -10 nil r)
+ ;; Sometimes interesting announces occur!
+ ("ANN?OU?NC\\(E\\|ING\\)" +10 nil r)
+ ;; Some people think they're on mailing lists
+ ("\\(un\\)?sub?scribe" -100 nil r)
+ ;; Stop Micro$oft NOW!!
+ ("\\(m\\(icro\\)?[s$]\\(oft\\|lot\\)?-?\\)?wind?\\(ows\\|aube\\|oze\\)?[- ]*\\('?95\\|NT\\|3[.]1\\|32\\)" -1001 nil r)
+ ;; I've nothing to buy
+ ("\\(for\\|4\\)[- ]*sale" -100 nil r)
+ ;; SELF-DISCIPLINED people
+ ("\\[[^a-z0-9 \t\n][^a-z0-9 \t\n]\\]" +100 nil r)
+ )
+ ("from"
+ ;; To keep track of posters from my site
+ (".dgac.fr" +1000 nil s))
+ ("followup"
+ ;; Keep track of answers to my posts
+ ("boubaker" +1000 nil s))
+ ("lines"
+ ;; Some people have really nothing to say!!
+ (1 -10 nil <=))
+ (mark -100)
+ (expunge -1000)
+ )
+@end lisp
+
+@item
+From ``Christopher Jones'' <cjones@@au.oracle.com>@*
+The sample @file{all.SCORE} files from Per and boubaker could be
+augmented with:
+@lisp
+ (("subject"
+ ;; No junk mail please!
+ ("please ignore" -500 nil s)
+ ("test" -500 nil e))
+ )
+@end lisp
+
+@item
+From ``Brian Edmonds'' <edmonds@@cs.ubc.ca>@*
+Augment any of the above with a fast method of scoring down
+excessively cross posted articles.
+@lisp
+ ("xref"
+ ;; the more cross posting, the exponentially worse the article
+ ("^xref: \\S-+ \\S-+ \\S-+ \\S-+" -1 nil r)
+ ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -2 nil r)
+ ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -4 nil r)
+ ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -8 nil r)
+ ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -16 nil r)
+ ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -32 nil r)
+ ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -64 nil r)
+ ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -128 nil r)
+ ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -256 nil r)
+ ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -512 nil r))
+@end lisp
+
+@end enumerate
+
+
+@item
+Q2.5 What do I use to yank-through when replying?
+
+You should probably reply and followup with @kbd{R} and @kbd{F}, instead
+of @kbd{r} and @kbd{f}, which solves your problem. But you could try
+something like:
+
+@example
+(defconst mail-yank-ignored-headers
+ "^.*:"
+ "Delete these headers from old message when it's inserted in a reply.")
+@end example
+
+
+@item
+Q2.6 I don't like the default WWW browser
+
+Now when choosing an URL Gnus starts up a W3 buffer, I would like it
+to always use Netscape (I don't browse in text-mode ;-).
+
+@enumerate
+@item
+Activate `Customize...' from the `Help' menu.
+
+@item
+Scroll down to the `WWW Browser' field.
+
+@item
+Click `mouse-2' on `WWW Browser'.
+
+@item
+Select `Netscape' from the pop up menu.
+
+@item
+Press `C-c C-c'
+
+@end enumerate
+
+If you are using XEmacs then to specify Netscape do
+@lisp
+ (setq gnus-button-url 'gnus-netscape-open-url)
+@end lisp
+
+
+@item
+Q2.7 What, if any, relation is between ``ask-server'' and ``(setq
+gnus-read-active-file 'some)''?
+
+In order for Gnus to show you the complete list of newsgroups, it will
+either have to either store the list locally, or ask the server to
+transmit the list. You enable the first with
+
+@lisp
+ (setq gnus-save-killed-list t)
+@end lisp
+
+and the second with
+
+@lisp
+ (setq gnus-read-active-file t)
+@end lisp
+
+If both are disabled, Gnus will not know what newsgroups exists. There
+is no option to get the list by casting a spell.
+
+
+@item
+Q2.8 Moving between groups is slow.
+
+Per Abrahamsen <abraham@@dina.kvl.dk> writes:@*
+
+Do you call @code{define-key} or something like that in one of the
+summary mode hooks? This would force Emacs to recalculate the keyboard
+shortcuts. Removing the call should speed up @kbd{M-x gnus-summary-mode
+RET} by a couple of orders of magnitude. You can use
+
+@lisp
+(define-key gnus-summary-mode-map KEY COMMAND)
+@end lisp
+
+in your @file{.gnus} instead.
+
+@end itemize
+
+
+@node Reading News FAQ
+@subsection Reading News
+
+@itemize @bullet
+@item
+Q3.1 How do I convert my kill files to score files?
+
+A kill-to-score translator was written by Ethan Bradford
+<ethanb@@ptolemy.astro.washington.edu>. It is available from@*
+@file{http://baugi.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}.
+
+
+@item
+Q3.2 My news server has a lot of groups, and killing groups is painfully
+slow.
+
+Don't do that then. The best way to get rid of groups that should be
+dead is to edit your newsrc directly. This problem will be addressed
+in the near future.
+
+
+@item
+Q3.3 How do I use an NNTP server with authentication?
+
+Put the following into your .gnus:
+@lisp
+ (add-hook 'nntp-server-opened-hook 'nntp-send-authinfo)
+@end lisp
+
+
+@item
+Q3.4 Not reading the first article.
+
+How do I avoid reading the first article when a group is selected?
+
+@enumerate
+@item
+Use @kbd{RET} to select the group instead of @kbd{SPC}.
+
+@item
+@code{(setq gnus-auto-select first nil)}
+
+@item
+Luis Fernandes <elf@@mailhost.ee.ryerson.ca>writes:@*
+This is what I use...customize as necessary...
+
+@lisp
+;;; Don't auto-select first article if reading sources, or archives or
+;;; jobs postings, etc. and just display the summary buffer
+(add-hook 'gnus-select-group-hook
+ (function
+ (lambda ()
+ (cond ((string-match "sources" gnus-newsgroup-name)
+ (setq gnus-auto-select-first nil))
+ ((string-match "jobs" gnus-newsgroup-name)
+ (setq gnus-auto-select-first nil))
+ ((string-match "comp\\.archives" gnus-newsgroup-name)
+ (setq gnus-auto-select-first nil))
+ ((string-match "reviews" gnus-newsgroup-name)
+ (setq gnus-auto-select-first nil))
+ ((string-match "announce" gnus-newsgroup-name)
+ (setq gnus-auto-select-first nil))
+ ((string-match "binaries" gnus-newsgroup-name)
+ (setq gnus-auto-select-first nil))
+ (t
+ (setq gnus-auto-select-first t))))))
+@end lisp
+
+@item
+Per Abrahamsen <abraham@@dina.kvl.dk> writes:@*
+Another possibility is to create an @file{all.binaries.all.SCORE} file
+like this:
+
+@lisp
+((local
+ (gnus-auto-select-first nil)))
+@end lisp
+
+and insert
+@lisp
+ (setq gnus-auto-select-first t)
+@end lisp
+
+in your @file{.gnus}.
+
+@end enumerate
+
+@item
+Q3.5 Why aren't BBDB known posters marked in the summary buffer?
+
+Brian Edmonds <edmonds@@cs.ubc.ca> writes:@*
+Due to changes in Gnus 5.0, @file{bbdb-gnus.el} no longer marks known
+posters in the summary buffer. An updated version, @file{gnus-bbdb.el}
+is available at the locations listed below. This package also supports
+autofiling of incoming mail to folders specified in the BBDB. Extensive
+instructions are included as comments in the file.
+
+Send mail to @file{majordomo@@edmonds.home.cs.ubc.ca} with the following
+line in the body of the message: @emph{get misc gnus-bbdb.el}.
+
+Or get it from the World Wide Web:@*
+@file{http://www.cs.ubc.ca/spider/edmonds/gnus-bbdb.el}.
+
+@end itemize
+
+
+@node Reading Mail FAQ
+@subsection Reading Mail
+
+@itemize @bullet
+@item
+Q4.1 What does the message ``Buffer has changed on disk'' mean in a mail
+group?
+
+Your filter program should not deliver mail directly to your folders,
+instead it should put the mail into spool files. Gnus will then move
+the mail safely from the spool files into the folders. This will
+eliminate the problem. Look it up in the manual, in the section
+entitled ``Mail & Procmail''.
+
+
+@item
+Q4.2 How do you make articles un-expirable?
+
+I am using nnml to read news and have used
+@code{gnus-auto-expirable-newsgroups} to automagically expire articles
+in some groups (Gnus being one of them). Sometimes there are
+interesting articles in these groups that I want to keep. Is there any
+way of explicitly marking an article as un-expirable - that is mark it
+as read but not expirable?
+
+Use @kbd{u}, @kbd{!}, @kbd{d} or @kbd{M-u} in the summary buffer. You
+just remove the @kbd{E} mark by setting some other mark. It's not
+necessary to tick the articles.
+
+
+@item
+Q4.3 How do I delete bogus nnml: groups?
+
+My problem is that I have various mail (nnml) groups generated while
+experimenting with Gnus. How do I remove them now? Setting the level to
+9 does not help. Also @code{gnus-group-check-bogus-groups} does not
+recognize them.
+
+Removing mail groups is tricky at the moment. (It's on the to-do list,
+though.) You basically have to kill the groups in Gnus, shut down Gnus,
+edit the active file to exclude these groups, and probably remove the
+nnml directories that contained these groups as well. Then start Gnus
+back up again.
+
+
+@item
+Q4.4 What happened to my new mail groups?
+
+I got new mail, but I have
+never seen the groups they should have been placed in.
+
+They are probably there, but as zombies. Press @kbd{A z} to list
+zombie groups, and then subscribe to the groups you want with @kbd{u}.
+This is all documented quite nicely in the user's manual.
+
+
+@item
+Q4.5 Not scoring mail groups
+
+How do you @emph{totally} turn off scoring in mail groups?
+
+Use an nnbabyl:all.SCORE (or nnmh, or nnml, or whatever) file containing:
+
+@example
+((adapt ignore)
+ (local (gnus-use-scoring nil))
+ (exclude-files "all.SCORE"))
+@end example
+
+@end itemize
+
+
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+
+@setfilename ../info/gnus
+@settitle Gnus Manual
+@synindex fn cp
+@synindex vr cp
+@synindex pg cp
+@direntry
+* Gnus: (gnus). The newsreader Gnus.
+@end direntry
+@iftex
+@finalout
+@end iftex
+@setchapternewpage odd
+
+@iftex
+@end iftex
+
+
+@ifinfo
+
+This file documents Gnus, the GNU Emacs newsreader.
+
+Copyright (C) 1995,96 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ifinfo
+
+@tex
+
+@titlepage
+@title Gnus 5.7 Manual
+
+@author by Lars Magne Ingebrigtsen
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1995,96,97 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+
+@end titlepage
+@page
+
+@end tex
+
+
+@node Top
+@top The Gnus Newsreader
+
+@ifinfo
+
+You can read news (and mail) from within Emacs by using Gnus. The news
+can be gotten by any nefarious means you can think of---@sc{nntp}, local
+spool or your mbox file. All at the same time, if you want to push your
+luck.
+
+This manual corresponds to Gnus 5.7.
+
+@end ifinfo
+
+@iftex
+
+Gnus is the advanced, self-documenting, customizable, extensible
+unreal-time newsreader for GNU Emacs.
+
+Oops. That sounds oddly familiar, so let's start over again to avoid
+being accused of plagiarism:
+
+Gnus is a message-reading laboratory. It will let you look at just
+about anything as if it were a newsgroup. You can read mail with it,
+you can browse directories with it, you can @code{ftp} with it---you can
+even read news with it!
+
+Gnus tries to empower people who read news the same way Emacs empowers
+people who edit text. Gnus sets no limits to what the user should be
+allowed to do. Users are encouraged to extend Gnus to make it behave
+like they want it to behave. A program should not control people;
+people should be empowered to do what they want by using (or abusing)
+the program.
+
+@end iftex
+
+
+@menu
+* Starting Up:: Finding news can be a pain.
+* The Group Buffer:: Selecting, subscribing and killing groups.
+* The Summary Buffer:: Reading, saving and posting articles.
+* The Article Buffer:: Displaying and handling articles.
+* Composing Messages:: Information on sending mail and news.
+* Select Methods:: Gnus reads all messages from various select methods.
+* Scoring:: Assigning values to articles.
+* Various:: General purpose settings.
+* The End:: Farewell and goodbye.
+* Appendices:: Terminology, Emacs intro, FAQ, History, Internals.
+* Index:: Variable, function and concept index.
+* Key Index:: Key Index.
+@end menu
+
+@node Starting Up
+@chapter Starting Gnus
+@cindex starting up
+
+@kindex M-x gnus
+@findex gnus
+If your system administrator has set things up properly, starting Gnus
+and reading news is extremely easy---you just type @kbd{M-x gnus} in
+your Emacs.
+
+@findex gnus-other-frame
+@kindex M-x gnus-other-frame
+If you want to start Gnus in a different frame, you can use the command
+@kbd{M-x gnus-other-frame} instead.
+
+If things do not go smoothly at startup, you have to twiddle some
+variables in your @file{~/.gnus} file. This file is similar to
+@file{~/.emacs}, but is read when gnus starts.
+
+If you puzzle at any terms used in this manual, please refer to the
+terminology section (@pxref{Terminology}).
+
+@menu
+* Finding the News:: Choosing a method for getting news.
+* The First Time:: What does Gnus do the first time you start it?
+* The Server is Down:: How can I read my mail then?
+* Slave Gnusae:: You can have more than one Gnus active at a time.
+* Fetching a Group:: Starting Gnus just to read a group.
+* New Groups:: What is Gnus supposed to do with new groups?
+* Startup Files:: Those pesky startup files---@file{.newsrc}.
+* Auto Save:: Recovering from a crash.
+* The Active File:: Reading the active file over a slow line Takes Time.
+* Changing Servers:: You may want to move from one server to another.
+* Startup Variables:: Other variables you might change.
+@end menu
+
+
+@node Finding the News
+@section Finding the News
+@cindex finding news
+
+@vindex gnus-select-method
+@c @head
+The @code{gnus-select-method} variable says where Gnus should look for
+news. This variable should be a list where the first element says
+@dfn{how} and the second element says @dfn{where}. This method is your
+native method. All groups not fetched with this method are
+foreign groups.
+
+For instance, if the @samp{news.somewhere.edu} @sc{nntp} server is where
+you want to get your daily dosage of news from, you'd say:
+
+@lisp
+(setq gnus-select-method '(nntp "news.somewhere.edu"))
+@end lisp
+
+If you want to read directly from the local spool, say:
+
+@lisp
+(setq gnus-select-method '(nnspool ""))
+@end lisp
+
+If you can use a local spool, you probably should, as it will almost
+certainly be much faster.
+
+@vindex gnus-nntpserver-file
+@cindex NNTPSERVER
+@cindex @sc{nntp} server
+If this variable is not set, Gnus will take a look at the
+@code{NNTPSERVER} environment variable. If that variable isn't set,
+Gnus will see whether @code{gnus-nntpserver-file}
+(@file{/etc/nntpserver} by default) has any opinions on the matter. If
+that fails as well, Gnus will try to use the machine running Emacs as an @sc{nntp} server. That's a long shot, though.
+
+@vindex gnus-nntp-server
+If @code{gnus-nntp-server} is set, this variable will override
+@code{gnus-select-method}. You should therefore set
+@code{gnus-nntp-server} to @code{nil}, which is what it is by default.
+
+@vindex gnus-secondary-servers
+You can also make Gnus prompt you interactively for the name of an
+@sc{nntp} server. If you give a non-numerical prefix to @code{gnus}
+(i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers
+in the @code{gnus-secondary-servers} list (if any). You can also just
+type in the name of any server you feel like visiting.
+
+@findex gnus-group-browse-foreign-server
+@kindex B (Group)
+However, if you use one @sc{nntp} server regularly and are just
+interested in a couple of groups from a different server, you would be
+better served by using the @kbd{B} command in the group buffer. It will
+let you have a look at what groups are available, and you can subscribe
+to any of the groups you want to. This also makes @file{.newsrc}
+maintenance much tidier. @xref{Foreign Groups}.
+
+@vindex gnus-secondary-select-methods
+@c @head
+A slightly different approach to foreign groups is to set the
+@code{gnus-secondary-select-methods} variable. The select methods
+listed in this variable are in many ways just as native as the
+@code{gnus-select-method} server. They will also be queried for active
+files during startup (if that's required), and new newsgroups that
+appear on these servers will be subscribed (or not) just as native
+groups are.
+
+For instance, if you use the @code{nnmbox} backend to read your mail, you
+would typically set this variable to
+
+@lisp
+(setq gnus-secondary-select-methods '((nnmbox "")))
+@end lisp
+
+
+@node The First Time
+@section The First Time
+@cindex first time usage
+
+If no startup files exist, Gnus will try to determine what groups should
+be subscribed by default.
+
+@vindex gnus-default-subscribed-newsgroups
+If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus
+will subscribe you to just those groups in that list, leaving the rest
+killed. Your system administrator should have set this variable to
+something useful.
+
+Since she hasn't, Gnus will just subscribe you to a few arbitrarily
+picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is defined
+here as @dfn{whatever Lars thinks you should read}.)
+
+You'll also be subscribed to the Gnus documentation group, which should
+help you with most common problems.
+
+If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just
+use the normal functions for handling new groups, and not do anything
+special.
+
+
+@node The Server is Down
+@section The Server is Down
+@cindex server errors
+
+If the default server is down, Gnus will understandably have some
+problems starting. However, if you have some mail groups in addition to
+the news groups, you may want to start Gnus anyway.
+
+Gnus, being the trusting sort of program, will ask whether to proceed
+without a native select method if that server can't be contacted. This
+will happen whether the server doesn't actually exist (i.e., you have
+given the wrong address) or the server has just momentarily taken ill
+for some reason or other. If you decide to continue and have no foreign
+groups, you'll find it difficult to actually do anything in the group
+buffer. But, hey, that's your problem. Blllrph!
+
+@findex gnus-no-server
+@kindex M-x gnus-no-server
+@c @head
+If you know that the server is definitely down, or you just want to read
+your mail without bothering with the server at all, you can use the
+@code{gnus-no-server} command to start Gnus. That might come in handy
+if you're in a hurry as well. This command will not attempt to contact
+your primary server---instead, it will just activate all groups on level
+1 and 2. (You should preferably keep no native groups on those two
+levels.)
+
+
+@node Slave Gnusae
+@section Slave Gnusae
+@cindex slave
+
+You might want to run more than one Emacs with more than one Gnus at the
+same time. If you are using different @file{.newsrc} files (e.g., if you
+are using the two different Gnusae to read from two different servers),
+that is no problem whatsoever. You just do it.
+
+The problem appears when you want to run two Gnusae that use the same
+@code{.newsrc} file.
+
+To work around that problem some, we here at the Think-Tank at the Gnus
+Towers have come up with a new concept: @dfn{Masters} and
+@dfn{slaves}. (We have applied for a patent on this concept, and have
+taken out a copyright on those words. If you wish to use those words in
+conjunction with each other, you have to send $1 per usage instance to
+me. Usage of the patent (@dfn{Master/Slave Relationships In Computer
+Applications}) will be much more expensive, of course.)
+
+Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or
+however you do it). Each subsequent slave Gnusae should be started with
+@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc}
+files, but instead save @dfn{slave files} that contain information only
+on what groups have been read in the slave session. When a master Gnus
+starts, it will read (and delete) these slave files, incorporating all
+information from them. (The slave files will be read in the sequence
+they were created, so the latest changes will have precedence.)
+
+Information from the slave files has, of course, precedence over the
+information in the normal (i.e., master) @code{.newsrc} file.
+
+
+@node Fetching a Group
+@section Fetching a Group
+@cindex fetching a group
+
+@findex gnus-fetch-group
+It is sometimes convenient to be able to just say ``I want to read this
+group and I don't care whether Gnus has been started or not''. This is
+perhaps more useful for people who write code than for users, but the
+command @code{gnus-fetch-group} provides this functionality in any case.
+It takes the group name as a parameter.
+
+
+@node New Groups
+@section New Groups
+@cindex new groups
+@cindex subscription
+
+@vindex gnus-check-new-newsgroups
+If you are satisfied that you really never want to see any new groups,
+you can set @code{gnus-check-new-newsgroups} to @code{nil}. This will
+also save you some time at startup. Even if this variable is
+@code{nil}, you can always subscribe to the new groups just by pressing
+@kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable
+is @code{ask-server} by default. If you set this variable to
+@code{always}, then Gnus will query the backends for new groups even
+when you do the @kbd{g} command (@pxref{Scanning New Messages}).
+
+@menu
+* Checking New Groups:: Determining what groups are new.
+* Subscription Methods:: What Gnus should do with new groups.
+* Filtering New Groups:: Making Gnus ignore certain new groups.
+@end menu
+
+
+@node Checking New Groups
+@subsection Checking New Groups
+
+Gnus normally determines whether a group is new or not by comparing the
+list of groups from the active file(s) with the lists of subscribed and
+dead groups. This isn't a particularly fast method. If
+@code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the
+server for new groups since the last time. This is both faster and
+cheaper. This also means that you can get rid of the list of killed
+groups altogether, so you may set @code{gnus-save-killed-list} to
+@code{nil}, which will save time both at startup, at exit, and all over.
+Saves disk space, too. Why isn't this the default, then?
+Unfortunately, not all servers support this command.
+
+I bet I know what you're thinking now: How do I find out whether my
+server supports @code{ask-server}? No? Good, because I don't have a
+fail-safe answer. I would suggest just setting this variable to
+@code{ask-server} and see whether any new groups appear within the next
+few days. If any do, then it works. If none do, then it doesn't
+work. I could write a function to make Gnus guess whether the server
+supports @code{ask-server}, but it would just be a guess. So I won't.
+You could @code{telnet} to the server and say @code{HELP} and see
+whether it lists @samp{NEWGROUPS} among the commands it understands. If
+it does, then it might work. (But there are servers that lists
+@samp{NEWGROUPS} without supporting the function properly.)
+
+This variable can also be a list of select methods. If so, Gnus will
+issue an @code{ask-server} command to each of the select methods, and
+subscribe them (or not) using the normal methods. This might be handy
+if you are monitoring a few servers for new groups. A side effect is
+that startup will take much longer, so you can meditate while waiting.
+Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss.
+
+
+@node Subscription Methods
+@subsection Subscription Methods
+
+@vindex gnus-subscribe-newsgroup-method
+What Gnus does when it encounters a new group is determined by the
+@code{gnus-subscribe-newsgroup-method} variable.
+
+This variable should contain a function. This function will be called
+with the name of the new group as the only parameter.
+
+Some handy pre-fab functions are:
+
+@table @code
+
+@item gnus-subscribe-zombies
+@vindex gnus-subscribe-zombies
+Make all new groups zombies. This is the default. You can browse the
+zombies later (with @kbd{A z}) and either kill them all off properly
+(with @kbd{S z}), or subscribe to them (with @kbd{u}).
+
+@item gnus-subscribe-randomly
+@vindex gnus-subscribe-randomly
+Subscribe all new groups in arbitrary order. This really means that all
+new groups will be added at ``the top'' of the group buffer.
+
+@item gnus-subscribe-alphabetically
+@vindex gnus-subscribe-alphabetically
+Subscribe all new groups in alphabetical order.
+
+@item gnus-subscribe-hierarchically
+@vindex gnus-subscribe-hierarchically
+Subscribe all new groups hierarchically. The difference between this
+function and @code{gnus-subscribe-alphabetically} is slight.
+@code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly
+alphabetical fashion, while this function will enter groups into it's
+hierarchy. So if you want to have the @samp{rec} hierarchy before the
+@samp{comp} hierarchy, this function will not mess that configuration
+up. Or something like that.
+
+@item gnus-subscribe-interactively
+@vindex gnus-subscribe-interactively
+Subscribe new groups interactively. This means that Gnus will ask
+you about @strong{all} new groups. The groups you choose to subscribe
+to will be subscribed hierarchically.
+
+@item gnus-subscribe-killed
+@vindex gnus-subscribe-killed
+Kill all new groups.
+
+@end table
+
+@vindex gnus-subscribe-hierarchical-interactive
+A closely related variable is
+@code{gnus-subscribe-hierarchical-interactive}. (That's quite a
+mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a
+hierarchical fashion whether to subscribe to new groups or not. Gnus
+will ask you for each sub-hierarchy whether you want to descend the
+hierarchy or not.
+
+One common mistake is to set the variable a few paragraphs above
+(@code{gnus-subscribe-newsgroup-method}) to
+@code{gnus-subscribe-hierarchical-interactive}. This is an error. This
+will not work. This is ga-ga. So don't do it.
+
+
+@node Filtering New Groups
+@subsection Filtering New Groups
+
+A nice and portable way to control which new newsgroups should be
+subscribed (or ignored) is to put an @dfn{options} line at the start of
+the @file{.newsrc} file. Here's an example:
+
+@example
+options -n !alt.all !rec.all sci.all
+@end example
+
+@vindex gnus-subscribe-options-newsgroup-method
+This line obviously belongs to a serious-minded intellectual scientific
+person (or she may just be plain old boring), because it says that all
+groups that have names beginning with @samp{alt} and @samp{rec} should
+be ignored, and all groups with names beginning with @samp{sci} should
+be subscribed. Gnus will not use the normal subscription method for
+subscribing these groups.
+@code{gnus-subscribe-options-newsgroup-method} is used instead. This
+variable defaults to @code{gnus-subscribe-alphabetically}.
+
+@vindex gnus-options-not-subscribe
+@vindex gnus-options-subscribe
+If you don't want to mess with your @file{.newsrc} file, you can just
+set the two variables @code{gnus-options-subscribe} and
+@code{gnus-options-not-subscribe}. These two variables do exactly the
+same as the @file{.newsrc} @samp{options -n} trick. Both are regexps,
+and if the new group matches the former, it will be unconditionally
+subscribed, and if it matches the latter, it will be ignored.
+
+@vindex gnus-auto-subscribed-groups
+Yet another variable that meddles here is
+@code{gnus-auto-subscribed-groups}. It works exactly like
+@code{gnus-options-subscribe}, and is therefore really superfluous, but I
+thought it would be nice to have two of these. This variable is more
+meant for setting some ground rules, while the other variable is used
+more for user fiddling. By default this variable makes all new groups
+that come from mail backends (@code{nnml}, @code{nnbabyl},
+@code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you
+don't like that, just set this variable to @code{nil}.
+
+New groups that match this regexp are subscribed using
+@code{gnus-subscribe-options-newsgroup-method}.
+
+
+@node Changing Servers
+@section Changing Servers
+@cindex changing servers
+
+Sometimes it is necessary to move from one @sc{nntp} server to another.
+This happens very rarely, but perhaps you change jobs, or one server is
+very flaky and you want to use another.
+
+Changing the server is pretty easy, right? You just change
+@code{gnus-select-method} to point to the new server?
+
+@emph{Wrong!}
+
+Article numbers are not (in any way) kept synchronized between different
+@sc{nntp} servers, and the only way Gnus keeps track of what articles
+you have read is by keeping track of article numbers. So when you
+change @code{gnus-select-method}, your @file{.newsrc} file becomes
+worthless.
+
+Gnus provides a few functions to attempt to translate a @file{.newsrc}
+file from one server to another. They all have one thing in
+common---they take a looong time to run. You don't want to use these
+functions more than absolutely necessary.
+
+@kindex M-x gnus-change-server
+@findex gnus-change-server
+If you have access to both servers, Gnus can request the headers for all
+the articles you have read and compare @code{Message-ID}s and map the
+article numbers of the read articles and article marks. The @kbd{M-x
+gnus-change-server} command will do this for all your native groups. It
+will prompt for the method you want to move to.
+
+@kindex M-x gnus-group-move-group-to-server
+@findex gnus-group-move-group-to-server
+You can also move individual groups with the @kbd{M-x
+gnus-group-move-group-to-server} command. This is useful if you want to
+move a (foreign) group from one server to another.
+
+@kindex M-x gnus-group-clear-data-on-native-groups
+@findex gnus-group-clear-data-on-native-groups
+If you don't have access to both the old and new server, all your marks
+and read ranges have become worthless. You can use the @kbd{M-x
+gnus-group-clear-data-on-native-groups} command to clear out all data
+that you have on your native groups. Use with caution.
+
+
+@node Startup Files
+@section Startup Files
+@cindex startup files
+@cindex .newsrc
+@cindex .newsrc.el
+@cindex .newsrc.eld
+
+Now, you all know about the @file{.newsrc} file. All subscription
+information is traditionally stored in this file.
+
+Things got a bit more complicated with @sc{gnus}. In addition to
+keeping the @file{.newsrc} file updated, it also used a file called
+@file{.newsrc.el} for storing all the information that didn't fit into
+the @file{.newsrc} file. (Actually, it also duplicated everything in
+the @file{.newsrc} file.) @sc{gnus} would read whichever one of these
+files was the most recently saved, which enabled people to swap between
+@sc{gnus} and other newsreaders.
+
+That was kinda silly, so Gnus went one better: In addition to the
+@file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called
+@file{.newsrc.eld}. It will read whichever of these files that are most
+recent, but it will never write a @file{.newsrc.el} file. You should
+never delete the @file{.newsrc.eld} file---it contains much information
+not stored in the @file{.newsrc} file.
+
+@vindex gnus-save-newsrc-file
+You can turn off writing the @file{.newsrc} file by setting
+@code{gnus-save-newsrc-file} to @code{nil}, which means you can delete
+the file and save some space, as well as exiting from Gnus faster.
+However, this will make it impossible to use other newsreaders than
+Gnus. But hey, who would want to, right?
+
+@vindex gnus-save-killed-list
+If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus
+will not save the list of killed groups to the startup file. This will
+save both time (when starting and quitting) and space (on disk). It
+will also mean that Gnus has no record of what groups are new or old,
+so the automatic new groups subscription methods become meaningless.
+You should always set @code{gnus-check-new-newsgroups} to @code{nil} or
+@code{ask-server} if you set this variable to @code{nil} (@pxref{New
+Groups}). This variable can also be a regular expression. If that's
+the case, remove all groups that do not match this regexp before
+saving. This can be useful in certain obscure situations that involve
+several servers where not all servers support @code{ask-server}.
+
+@vindex gnus-startup-file
+The @code{gnus-startup-file} variable says where the startup files are.
+The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
+file being whatever that one is, with a @samp{.eld} appended.
+
+@vindex gnus-save-newsrc-hook
+@vindex gnus-save-quick-newsrc-hook
+@vindex gnus-save-standard-newsrc-hook
+@code{gnus-save-newsrc-hook} is called before saving any of the newsrc
+files, while @code{gnus-save-quick-newsrc-hook} is called just before
+saving the @file{.newsrc.eld} file, and
+@code{gnus-save-standard-newsrc-hook} is called just before saving the
+@file{.newsrc} file. The latter two are commonly used to turn version
+control on or off. Version control is on by default when saving the
+startup files. If you want to turn backup creation off, say something like:
+
+@lisp
+(defun turn-off-backup ()
+ (set (make-local-variable 'backup-inhibited) t))
+
+(add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup)
+(add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup)
+@end lisp
+
+@vindex gnus-init-file
+When Gnus starts, it will read the @code{gnus-site-init-file}
+(@file{.../site-lisp/gnus} by default) and @code{gnus-init-file}
+(@file{~/.gnus} by default) files. These are normal Emacs Lisp files
+and can be used to avoid cluttering your @file{~/.emacs} and
+@file{site-init} files with Gnus stuff. Gnus will also check for files
+with the same names as these, but with @file{.elc} and @file{.el}
+suffixes. In other words, if you have set @code{gnus-init-file} to
+@file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el},
+and finally @file{~/.gnus} (in this order).
+
+
+
+@node Auto Save
+@section Auto Save
+@cindex dribble file
+@cindex auto-save
+
+Whenever you do something that changes the Gnus data (reading articles,
+catching up, killing/subscribing groups), the change is added to a
+special @dfn{dribble buffer}. This buffer is auto-saved the normal
+Emacs way. If your Emacs should crash before you have saved the
+@file{.newsrc} files, all changes you have made can be recovered from
+this file.
+
+If Gnus detects this file at startup, it will ask the user whether to
+read it. The auto save file is deleted whenever the real startup file is
+saved.
+
+@vindex gnus-use-dribble-file
+If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and
+maintain a dribble buffer. The default is @code{t}.
+
+@vindex gnus-dribble-directory
+Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If
+this variable is @code{nil}, which it is by default, Gnus will dribble
+into the directory where the @file{.newsrc} file is located. (This is
+normally the user's home directory.) The dribble file will get the same
+file permissions as the @code{.newsrc} file.
+
+@vindex gnus-always-read-dribble-file
+If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will
+read the dribble file on startup without querying the user.
+
+
+@node The Active File
+@section The Active File
+@cindex active file
+@cindex ignored groups
+
+When Gnus starts, or indeed whenever it tries to determine whether new
+articles have arrived, it reads the active file. This is a very large
+file that lists all the active groups and articles on the server.
+
+@vindex gnus-ignored-newsgroups
+Before examining the active file, Gnus deletes all lines that match the
+regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject
+any groups with bogus names, but you can use this variable to make Gnus
+ignore hierarchies you aren't ever interested in. However, this is not
+recommended. In fact, it's highly discouraged. Instead, @pxref{New
+Groups} for an overview of other variables that can be used instead.
+
+@c This variable is
+@c @code{nil} by default, and will slow down active file handling somewhat
+@c if you set it to anything else.
+
+@vindex gnus-read-active-file
+@c @head
+The active file can be rather Huge, so if you have a slow network, you
+can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from
+reading the active file. This variable is @code{some} by default.
+
+Gnus will try to make do by getting information just on the groups that
+you actually subscribe to.
+
+Note that if you subscribe to lots and lots of groups, setting this
+variable to @code{nil} will probably make Gnus slower, not faster. At
+present, having this variable @code{nil} will slow Gnus down
+considerably, unless you read news over a 2400 baud modem.
+
+This variable can also have the value @code{some}. Gnus will then
+attempt to read active info only on the subscribed groups. On some
+servers this is quite fast (on sparkling, brand new INN servers that
+support the @code{LIST ACTIVE group} command), on others this isn't fast
+at all. In any case, @code{some} should be faster than @code{nil}, and
+is certainly faster than @code{t} over slow lines.
+
+If this variable is @code{nil}, Gnus will ask for group info in total
+lock-step, which isn't very fast. If it is @code{some} and you use an
+@sc{nntp} server, Gnus will pump out commands as fast as it can, and
+read all the replies in one swoop. This will normally result in better
+performance, but if the server does not support the aforementioned
+@code{LIST ACTIVE group} command, this isn't very nice to the server.
+
+In any case, if you use @code{some} or @code{nil}, you should definitely
+kill all groups that you aren't interested in to speed things up.
+
+Note that this variable also affects active file retrieval from
+secondary select methods.
+
+
+@node Startup Variables
+@section Startup Variables
+
+@table @code
+
+@item gnus-load-hook
+@vindex gnus-load-hook
+A hook run while Gnus is being loaded. Note that this hook will
+normally be run just once in each Emacs session, no matter how many
+times you start Gnus.
+
+@item gnus-before-startup-hook
+@vindex gnus-before-startup-hook
+A hook run after starting up Gnus successfully.
+
+@item gnus-startup-hook
+@vindex gnus-startup-hook
+A hook run as the very last thing after starting up Gnus
+
+@item gnus-started-hook
+@vindex gnus-started-hook
+A hook that is run as the very last thing after starting up Gnus
+successfully.
+
+@item gnus-started-hook
+@vindex gnus-started-hook
+A hook that is run after reading the @file{.newsrc} file(s), but before
+generating the group buffer.
+
+@item gnus-check-bogus-newsgroups
+@vindex gnus-check-bogus-newsgroups
+If non-@code{nil}, Gnus will check for and delete all bogus groups at
+startup. A @dfn{bogus group} is a group that you have in your
+@file{.newsrc} file, but doesn't exist on the news server. Checking for
+bogus groups can take quite a while, so to save time and resources it's
+best to leave this option off, and do the checking for bogus groups once
+in a while from the group buffer instead (@pxref{Group Maintenance}).
+
+@item gnus-inhibit-startup-message
+@vindex gnus-inhibit-startup-message
+If non-@code{nil}, the startup message won't be displayed. That way,
+your boss might not notice as easily that you are reading news instead
+of doing your job. Note that this variable is used before
+@file{.gnus.el} is loaded, so it should be set in @code{.emacs} instead.
+
+@item gnus-no-groups-message
+@vindex gnus-no-groups-message
+Message displayed by Gnus when no groups are available.
+
+@item gnus-play-startup-jingle
+@vindex gnus-play-startup-jingle
+If non-@code{nil}, play the Gnus jingle at startup.
+
+@item gnus-startup-jingle
+@vindex gnus-startup-jingle
+Jingle to be played if the above variable is non-@code{nil}. The
+default is @samp{Tuxedomoon.Jingle4.au}.
+
+@end table
+
+
+@node The Group Buffer
+@chapter The Group Buffer
+@cindex group buffer
+
+The @dfn{group buffer} lists all (or parts) of the available groups. It
+is the first buffer shown when Gnus starts, and will never be killed as
+long as Gnus is active.
+
+
+@menu
+* Group Buffer Format:: Information listed and how you can change it.
+* Group Maneuvering:: Commands for moving in the group buffer.
+* Selecting a Group:: Actually reading news.
+* Group Data:: Changing the info for a group.
+* Subscription Commands:: Unsubscribing, killing, subscribing.
+* Group Levels:: Levels? What are those, then?
+* Group Score:: A mechanism for finding out what groups you like.
+* Marking Groups:: You can mark groups for later processing.
+* Foreign Groups:: Creating and editing groups.
+* Group Parameters:: Each group may have different parameters set.
+* Listing Groups:: Gnus can list various subsets of the groups.
+* Sorting Groups:: Re-arrange the group order.
+* Group Maintenance:: Maintaining a tidy @file{.newsrc} file.
+* Browse Foreign Server:: You can browse a server. See what it has to offer.
+* Exiting Gnus:: Stop reading news and get some work done.
+* Group Topics:: A folding group mode divided into topics.
+* Misc Group Stuff:: Other stuff that you can to do.
+@end menu
+
+
+@node Group Buffer Format
+@section Group Buffer Format
+
+@menu
+* Group Line Specification:: Deciding how the group buffer is to look.
+* Group Modeline Specification:: The group buffer modeline.
+* Group Highlighting:: Having nice colors in the group buffer.
+@end menu
+
+
+@node Group Line Specification
+@subsection Group Line Specification
+@cindex group buffer format
+
+The default format of the group buffer is nice and dull, but you can
+make it as exciting and ugly as you feel like.
+
+Here's a couple of example group lines:
+
+@example
+ 25: news.announce.newusers
+ * 0: alt.fan.andrea-dworkin
+@end example
+
+Quite simple, huh?
+
+You can see that there are 25 unread articles in
+@samp{news.announce.newusers}. There are no unread articles, but some
+ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little
+asterisk at the beginning of the line?).
+
+@vindex gnus-group-line-format
+You can change that format to whatever you want by fiddling with the
+@code{gnus-group-line-format} variable. This variable works along the
+lines of a @code{format} specification, which is pretty much the same as
+a @code{printf} specifications, for those of you who use (feh!) C.
+@xref{Formatting Variables}.
+
+@samp{%M%S%5y: %(%g%)\n} is the value that produced those lines above.
+
+There should always be a colon on the line; the cursor always moves to
+the colon after performing an operation. Nothing else is required---not
+even the group name. All displayed text is just window dressing, and is
+never examined by Gnus. Gnus stores all real information it needs using
+text properties.
+
+(Note that if you make a really strange, wonderful, spreadsheet-like
+layout, everybody will believe you are hard at work with the accounting
+instead of wasting time reading news.)
+
+Here's a list of all available format characters:
+
+@table @samp
+
+@item M
+An asterisk if the group only has marked articles.
+
+@item S
+Whether the group is subscribed.
+
+@item L
+Level of subscribedness.
+
+@item N
+Number of unread articles.
+
+@item I
+Number of dormant articles.
+
+@item T
+Number of ticked articles.
+
+@item R
+Number of read articles.
+
+@item t
+Estimated total number of articles. (This is really @var{max-number}
+minus @var{min-number} plus 1.)
+
+@item y
+Number of unread, unticked, non-dormant articles.
+
+@item i
+Number of ticked and dormant articles.
+
+@item g
+Full group name.
+
+@item G
+Group name.
+
+@item D
+Newsgroup description.
+
+@item o
+@samp{m} if moderated.
+
+@item O
+@samp{(m)} if moderated.
+
+@item s
+Select method.
+
+@item n
+Select from where.
+
+@item z
+A string that looks like @samp{<%s:%n>} if a foreign select method is
+used.
+
+@item P
+Indentation based on the level of the topic (@pxref{Group Topics}).
+
+@item c
+@vindex gnus-group-uncollapsed-levels
+Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels}
+variable says how many levels to leave at the end of the group name.
+The default is 1---this will mean that group names like
+@samp{gnu.emacs.gnus} will be shortened to @samp{g.emacs.gnus}.
+
+@item m
+@vindex gnus-new-mail-mark
+@cindex %
+@samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to
+the group lately.
+
+@item d
+A string that says when you last read the group (@pxref{Group
+Timestamp}).
+
+@item u
+User defined specifier. The next character in the format string should
+be a letter. Gnus will call the function
+@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
+following @samp{%u}. The function will be passed a single dummy
+parameter as argument. The function should return a string, which will
+be inserted into the buffer just like information from any other
+specifier.
+@end table
+
+@cindex *
+All the ``number-of'' specs will be filled with an asterisk (@samp{*})
+if no info is available---for instance, if it is a non-activated foreign
+group, or a bogus native group.
+
+
+@node Group Modeline Specification
+@subsection Group Modeline Specification
+@cindex group modeline
+
+@vindex gnus-group-mode-line-format
+The mode line can be changed by setting
+@code{gnus-group-mode-line-format} (@pxref{Mode Line Formatting}). It
+doesn't understand that many format specifiers:
+
+@table @samp
+@item S
+The native news server.
+@item M
+The native select method.
+@end table
+
+
+@node Group Highlighting
+@subsection Group Highlighting
+@cindex highlighting
+@cindex group highlighting
+
+@vindex gnus-group-highlight
+Highlighting in the group buffer is controlled by the
+@code{gnus-group-highlight} variable. This is an alist with elements
+that look like @var{(form . face)}. If @var{form} evaluates to
+something non-@code{nil}, the @var{face} will be used on the line.
+
+Here's an example value for this variable that might look nice if the
+background is dark:
+
+@lisp
+(face-spec-set 'my-group-face-1
+ '((t (:foreground "Red" :bold t))))
+(face-spec-set 'my-group-face-2
+ '((t (:foreground "SeaGreen" :bold t))))
+(face-spec-set 'my-group-face-3
+ '((t (:foreground "SpringGreen" :bold t))))
+(face-spec-set 'my-group-face-4
+ '((t (:foreground "SteelBlue" :bold t))))
+(face-spec-set 'my-group-face-5
+ '((t (:foreground "SkyBlue" :bold t))))
+
+(setq gnus-group-highlight
+ '(((> unread 200) . my-group-face-1)
+ ((and (< level 3) (zerop unread)) . my-group-face-2)
+ ((< level 3) . my-group-face-3)
+ ((zerop unread) . my-group-face-4)
+ (t . my-group-face-5)))
+@end lisp
+
+Also @pxref{Faces and Fonts}.
+
+Variables that are dynamically bound when the forms are evaluated
+include:
+
+@table @code
+@item group
+The group name.
+@item unread
+The number of unread articles in the group.
+@item method
+The select method.
+@item mailp
+Whether the group is a mail group.
+@item level
+The level of the group.
+@item score
+The score of the group.
+@item ticked
+The number of ticked articles in the group.
+@item total
+The total number of articles in the group. Or rather, MAX-NUMBER minus
+MIN-NUMBER plus one.
+@item topic
+When using the topic minor mode, this variable is bound to the current
+topic being inserted.
+@end table
+
+When the forms are @code{eval}ed, point is at the beginning of the line
+of the group in question, so you can use many of the normal Gnus
+functions for snarfing info on the group.
+
+@vindex gnus-group-update-hook
+@findex gnus-group-highlight-line
+@code{gnus-group-update-hook} is called when a group line is changed.
+It will not be called when @code{gnus-visual} is @code{nil}. This hook
+calls @code{gnus-group-highlight-line} by default.
+
+
+@node Group Maneuvering
+@section Group Maneuvering
+@cindex group movement
+
+All movement commands understand the numeric prefix and will behave as
+expected, hopefully.
+
+@table @kbd
+
+@item n
+@kindex n (Group)
+@findex gnus-group-next-unread-group
+Go to the next group that has unread articles
+(@code{gnus-group-next-unread-group}).
+
+@item p
+@itemx DEL
+@kindex DEL (Group)
+@kindex p (Group)
+@findex gnus-group-prev-unread-group
+Go to the previous group that has unread articles
+(@code{gnus-group-prev-unread-group}).
+
+@item N
+@kindex N (Group)
+@findex gnus-group-next-group
+Go to the next group (@code{gnus-group-next-group}).
+
+@item P
+@kindex P (Group)
+@findex gnus-group-prev-group
+Go to the previous group (@code{gnus-group-prev-group}).
+
+@item M-n
+@kindex M-n (Group)
+@findex gnus-group-next-unread-group-same-level
+Go to the next unread group on the same (or lower) level
+(@code{gnus-group-next-unread-group-same-level}).
+
+@item M-p
+@kindex M-p (Group)
+@findex gnus-group-prev-unread-group-same-level
+Go to the previous unread group on the same (or lower) level
+(@code{gnus-group-prev-unread-group-same-level}).
+@end table
+
+Three commands for jumping to groups:
+
+@table @kbd
+
+@item j
+@kindex j (Group)
+@findex gnus-group-jump-to-group
+Jump to a group (and make it visible if it isn't already)
+(@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just
+like living groups.
+
+@item ,
+@kindex , (Group)
+@findex gnus-group-best-unread-group
+Jump to the unread group with the lowest level
+(@code{gnus-group-best-unread-group}).
+
+@item .
+@kindex . (Group)
+@findex gnus-group-first-unread-group
+Jump to the first group with unread articles
+(@code{gnus-group-first-unread-group}).
+@end table
+
+@vindex gnus-group-goto-unread
+If @code{gnus-group-goto-unread} is @code{nil}, all the movement
+commands will move to the next group, not the next unread group. Even
+the commands that say they move to the next unread group. The default
+is @code{t}.
+
+
+@node Selecting a Group
+@section Selecting a Group
+@cindex group selection
+
+@table @kbd
+
+@item SPACE
+@kindex SPACE (Group)
+@findex gnus-group-read-group
+Select the current group, switch to the summary buffer and display the
+first unread article (@code{gnus-group-read-group}). If there are no
+unread articles in the group, or if you give a non-numerical prefix to
+this command, Gnus will offer to fetch all the old articles in this
+group from the server. If you give a numerical prefix @var{N}, @var{N}
+determines the number of articles Gnus will fetch. If @var{N} is
+positive, Gnus fetches the @var{N} newest articles, if @var{N} is
+negative, Gnus fetches the @var{abs(N)} oldest articles.
+
+@item RET
+@kindex RET (Group)
+@findex gnus-group-select-group
+Select the current group and switch to the summary buffer
+(@code{gnus-group-select-group}). Takes the same arguments as
+@code{gnus-group-read-group}---the only difference is that this command
+does not display the first unread article automatically upon group
+entry.
+
+@item M-RET
+@kindex M-RET (Group)
+@findex gnus-group-quick-select-group
+This does the same as the command above, but tries to do it with the
+minimum amount of fuzz (@code{gnus-group-quick-select-group}). No
+scoring/killing will be performed, there will be no highlights and no
+expunging. This might be useful if you're in a real hurry and have to
+enter some humongous group. If you give a 0 prefix to this command
+(i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer,
+which is useful if you want to toggle threading before generating the
+summary buffer (@pxref{Summary Generation Commands}).
+
+@item M-SPACE
+@kindex M-SPACE (Group)
+@findex gnus-group-visible-select-group
+This is yet one more command that does the same as the @kbd{RET}
+command, but this one does it without expunging and hiding dormants
+(@code{gnus-group-visible-select-group}).
+
+@item M-C-RET
+@kindex M-C-RET (Group)
+@findex gnus-group-select-group-ephemerally
+Finally, this command selects the current group ephemerally without
+doing any processing of its contents
+(@code{gnus-group-select-group-ephemerally}). Even threading has been
+turned off. Everything you do in the group after selecting it in this
+manner will have no permanent effects.
+
+@end table
+
+@vindex gnus-large-newsgroup
+The @code{gnus-large-newsgroup} variable says what Gnus should consider
+to be a big group. This is 200 by default. If the group has more
+(unread and/or ticked) articles than this, Gnus will query the user
+before entering the group. The user can then specify how many articles
+should be fetched from the server. If the user specifies a negative
+number (@code{-n}), the @code{n} oldest articles will be fetched. If it
+is positive, the @code{n} articles that have arrived most recently will
+be fetched.
+
+@vindex gnus-select-group-hook
+@vindex gnus-auto-select-first
+@code{gnus-auto-select-first} control whether any articles are selected
+automatically when entering a group with the @kbd{SPACE} command.
+
+@table @code
+
+@item nil
+Don't select any articles when entering the group. Just display the
+full summary buffer.
+
+@item t
+Select the first unread article when entering the group.
+
+@item best
+Select the highest scored article in the group when entering the
+group.
+@end table
+
+If you want to prevent automatic selection in some group (say, in a
+binary group with Huge articles) you can set this variable to @code{nil}
+in @code{gnus-select-group-hook}, which is called when a group is
+selected.
+
+
+@node Subscription Commands
+@section Subscription Commands
+@cindex subscription
+
+@table @kbd
+
+@item S t
+@itemx u
+@kindex S t (Group)
+@kindex u (Group)
+@findex gnus-group-unsubscribe-current-group
+@c @icon{gnus-group-unsubscribe}
+Toggle subscription to the current group
+(@code{gnus-group-unsubscribe-current-group}).
+
+@item S s
+@itemx U
+@kindex S s (Group)
+@kindex U (Group)
+@findex gnus-group-unsubscribe-group
+Prompt for a group to subscribe, and then subscribe it. If it was
+subscribed already, unsubscribe it instead
+(@code{gnus-group-unsubscribe-group}).
+
+@item S k
+@itemx C-k
+@kindex S k (Group)
+@kindex C-k (Group)
+@findex gnus-group-kill-group
+@c @icon{gnus-group-kill-group}
+Kill the current group (@code{gnus-group-kill-group}).
+
+@item S y
+@itemx C-y
+@kindex S y (Group)
+@kindex C-y (Group)
+@findex gnus-group-yank-group
+Yank the last killed group (@code{gnus-group-yank-group}).
+
+@item C-x C-t
+@kindex C-x C-t (Group)
+@findex gnus-group-transpose-groups
+Transpose two groups (@code{gnus-group-transpose-groups}). This isn't
+really a subscription command, but you can use it instead of a
+kill-and-yank sequence sometimes.
+
+@item S w
+@itemx C-w
+@kindex S w (Group)
+@kindex C-w (Group)
+@findex gnus-group-kill-region
+Kill all groups in the region (@code{gnus-group-kill-region}).
+
+@item S z
+@kindex S z (Group)
+@findex gnus-group-kill-all-zombies
+Kill all zombie groups (@code{gnus-group-kill-all-zombies}).
+
+@item S C-k
+@kindex S C-k (Group)
+@findex gnus-group-kill-level
+Kill all groups on a certain level (@code{gnus-group-kill-level}).
+These groups can't be yanked back after killing, so this command should
+be used with some caution. The only time where this command comes in
+really handy is when you have a @file{.newsrc} with lots of unsubscribed
+groups that you want to get rid off. @kbd{S C-k} on level 7 will
+kill off all unsubscribed groups that do not have message numbers in the
+@file{.newsrc} file.
+
+@end table
+
+Also @pxref{Group Levels}.
+
+
+@node Group Data
+@section Group Data
+
+@table @kbd
+
+@item c
+@kindex c (Group)
+@findex gnus-group-catchup-current
+@vindex gnus-group-catchup-group-hook
+@c @icon{gnus-group-catchup-current}
+Mark all unticked articles in this group as read
+(@code{gnus-group-catchup-current}).
+@code{gnus-group-catchup-group-hook} is called when catching up a group from
+the group buffer.
+
+@item C
+@kindex C (Group)
+@findex gnus-group-catchup-current-all
+Mark all articles in this group, even the ticked ones, as read
+(@code{gnus-group-catchup-current-all}).
+
+@item M-c
+@kindex M-c (Group)
+@findex gnus-group-clear-data
+Clear the data from the current group---nix out marks and the list of
+read articles (@code{gnus-group-clear-data}).
+
+@item M-x gnus-group-clear-data-on-native-groups
+@kindex M-x gnus-group-clear-data-on-native-groups
+@findex gnus-group-clear-data-on-native-groups
+If you have switched from one @sc{nntp} server to another, all your marks
+and read ranges have become worthless. You can use this command to
+clear out all data that you have on your native groups. Use with
+caution.
+
+@end table
+
+
+@node Group Levels
+@section Group Levels
+@cindex group level
+@cindex level
+
+All groups have a level of @dfn{subscribedness}. For instance, if a
+group is on level 2, it is more subscribed than a group on level 5. You
+can ask Gnus to just list groups on a given level or lower
+(@pxref{Listing Groups}), or to just check for new articles in groups on
+a given level or lower (@pxref{Scanning New Messages}).
+
+Remember: The higher the level of the group, the less important it is.
+
+@table @kbd
+
+@item S l
+@kindex S l (Group)
+@findex gnus-group-set-current-level
+Set the level of the current group. If a numeric prefix is given, the
+next @var{n} groups will have their levels set. The user will be
+prompted for a level.
+@end table
+
+@vindex gnus-level-killed
+@vindex gnus-level-zombie
+@vindex gnus-level-unsubscribed
+@vindex gnus-level-subscribed
+Gnus considers groups from levels 1 to
+@code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed,
+@code{gnus-level-subscribed} (exclusive) and
+@code{gnus-level-unsubscribed} (inclusive) (default 7) to be
+unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
+(default 8) and @code{gnus-level-killed} to be killed (completely dead)
+(default 9). Gnus treats subscribed and unsubscribed groups exactly the
+same, but zombie and killed groups have no information on what articles
+you have read, etc, stored. This distinction between dead and living
+groups isn't done because it is nice or clever, it is done purely for
+reasons of efficiency.
+
+It is recommended that you keep all your mail groups (if any) on quite
+low levels (e.g. 1 or 2).
+
+If you want to play with the level variables, you should show some care.
+Set them once, and don't touch them ever again. Better yet, don't touch
+them at all unless you know exactly what you're doing.
+
+@vindex gnus-level-default-unsubscribed
+@vindex gnus-level-default-subscribed
+Two closely related variables are @code{gnus-level-default-subscribed}
+(default 3) and @code{gnus-level-default-unsubscribed} (default 6),
+which are the levels that new groups will be put on if they are
+(un)subscribed. These two variables should, of course, be inside the
+relevant valid ranges.
+
+@vindex gnus-keep-same-level
+If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands
+will only move to groups of the same level (or lower). In
+particular, going from the last article in one group to the next group
+will go to the next group of the same level (or lower). This might be
+handy if you want to read the most important groups before you read the
+rest.
+
+@vindex gnus-group-default-list-level
+All groups with a level less than or equal to
+@code{gnus-group-default-list-level} will be listed in the group buffer
+by default.
+
+@vindex gnus-group-list-inactive-groups
+If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active
+groups will be listed along with the unread groups. This variable is
+@code{t} by default. If it is @code{nil}, inactive groups won't be
+listed.
+
+@vindex gnus-group-use-permanent-levels
+If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you
+give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will
+use this level as the ``work'' level.
+
+@vindex gnus-activate-level
+Gnus will normally just activate (i. e., query the server about) groups
+on level @code{gnus-activate-level} or less. If you don't want to
+activate unsubscribed groups, for instance, you might set this variable
+to 5. The default is 6.
+
+
+@node Group Score
+@section Group Score
+@cindex group score
+@cindex group rank
+@cindex rank
+
+You would normally keep important groups on high levels, but that scheme
+is somewhat restrictive. Don't you wish you could have Gnus sort the
+group buffer according to how often you read groups, perhaps? Within
+reason?
+
+This is what @dfn{group score} is for. You can assign a score to each
+group. You can then sort the group buffer based on this score.
+Alternatively, you can sort on score and then level. (Taken together,
+the level and the score is called the @dfn{rank} of the group. A group
+that is on level 4 and has a score of 1 has a higher rank than a group
+on level 5 that has a score of 300. (The level is the most significant
+part and the score is the least significant part.))
+
+@findex gnus-summary-bubble-group
+If you want groups you read often to get higher scores than groups you
+read seldom you can add the @code{gnus-summary-bubble-group} function to
+the @code{gnus-summary-exit-hook} hook. This will result (after
+sorting) in a bubbling sort of action. If you want to see that in
+action after each summary exit, you can add
+@code{gnus-group-sort-groups-by-rank} or
+@code{gnus-group-sort-groups-by-score} to the same hook, but that will
+slow things down somewhat.
+
+
+@node Marking Groups
+@section Marking Groups
+@cindex marking groups
+
+If you want to perform some command on several groups, and they appear
+subsequently in the group buffer, you would normally just give a
+numerical prefix to the command. Most group commands will then do your
+bidding on those groups.
+
+However, if the groups are not in sequential order, you can still
+perform a command on several groups. You simply mark the groups first
+with the process mark and then execute the command.
+
+@table @kbd
+
+@item #
+@kindex # (Group)
+@itemx M m
+@kindex M m (Group)
+@findex gnus-group-mark-group
+Set the mark on the current group (@code{gnus-group-mark-group}).
+
+@item M-#
+@kindex M-# (Group)
+@itemx M u
+@kindex M u (Group)
+@findex gnus-group-unmark-group
+Remove the mark from the current group
+(@code{gnus-group-unmark-group}).
+
+@item M U
+@kindex M U (Group)
+@findex gnus-group-unmark-all-groups
+Remove the mark from all groups (@code{gnus-group-unmark-all-groups}).
+
+@item M w
+@kindex M w (Group)
+@findex gnus-group-mark-region
+Mark all groups between point and mark (@code{gnus-group-mark-region}).
+
+@item M b
+@kindex M b (Group)
+@findex gnus-group-mark-buffer
+Mark all groups in the buffer (@code{gnus-group-mark-buffer}).
+
+@item M r
+@kindex M r (Group)
+@findex gnus-group-mark-regexp
+Mark all groups that match some regular expression
+(@code{gnus-group-mark-regexp}).
+@end table
+
+Also @pxref{Process/Prefix}.
+
+@findex gnus-group-universal-argument
+If you want to execute some command on all groups that have been marked
+with the process mark, you can use the @kbd{M-&}
+(@code{gnus-group-universal-argument}) command. It will prompt you for
+the command to be executed.
+
+
+@node Foreign Groups
+@section Foreign Groups
+@cindex foreign groups
+
+Below are some group mode commands for making and editing general foreign
+groups, as well as commands to ease the creation of a few
+special-purpose groups. All these commands insert the newly created
+groups under point---@code{gnus-subscribe-newsgroup-method} is not
+consulted.
+
+@table @kbd
+
+@item G m
+@kindex G m (Group)
+@findex gnus-group-make-group
+@cindex making groups
+Make a new group (@code{gnus-group-make-group}). Gnus will prompt you
+for a name, a method and possibly an @dfn{address}. For an easier way
+to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}.
+
+@item G r
+@kindex G r (Group)
+@findex gnus-group-rename-group
+@cindex renaming groups
+Rename the current group to something else
+(@code{gnus-group-rename-group}). This is valid only on some
+groups---mail groups mostly. This command might very well be quite slow
+on some backends.
+
+@item G c
+@kindex G c (Group)
+@cindex customizing
+@findex gnus-group-customize
+Customize the group parameters (@code{gnus-group-customize}).
+
+@item G e
+@kindex G e (Group)
+@findex gnus-group-edit-group-method
+@cindex renaming groups
+Enter a buffer where you can edit the select method of the current
+group (@code{gnus-group-edit-group-method}).
+
+@item G p
+@kindex G p (Group)
+@findex gnus-group-edit-group-parameters
+Enter a buffer where you can edit the group parameters
+(@code{gnus-group-edit-group-parameters}).
+
+@item G E
+@kindex G E (Group)
+@findex gnus-group-edit-group
+Enter a buffer where you can edit the group info
+(@code{gnus-group-edit-group}).
+
+@item G d
+@kindex G d (Group)
+@findex gnus-group-make-directory-group
+@cindex nndir
+Make a directory group (@pxref{Directory Groups}). You will be prompted
+for a directory name (@code{gnus-group-make-directory-group}).
+
+@item G h
+@kindex G h (Group)
+@cindex help group
+@findex gnus-group-make-help-group
+Make the Gnus help group (@code{gnus-group-make-help-group}).
+
+@item G a
+@kindex G a (Group)
+@cindex (ding) archive
+@cindex archive group
+@findex gnus-group-make-archive-group
+@vindex gnus-group-archive-directory
+@vindex gnus-group-recent-archive-directory
+Make a Gnus archive group (@code{gnus-group-make-archive-group}). By
+default a group pointing to the most recent articles will be created
+(@code{gnus-group-recent-archive-directory}), but given a prefix, a full
+group will be created from @code{gnus-group-archive-directory}.
+
+@item G k
+@kindex G k (Group)
+@findex gnus-group-make-kiboze-group
+@cindex nnkiboze
+Make a kiboze group. You will be prompted for a name, for a regexp to
+match groups to be ``included'' in the kiboze group, and a series of
+strings to match on headers (@code{gnus-group-make-kiboze-group}).
+@xref{Kibozed Groups}.
+
+@item G D
+@kindex G D (Group)
+@findex gnus-group-enter-directory
+@cindex nneething
+Read an arbitrary directory as if it were a newsgroup with the
+@code{nneething} backend (@code{gnus-group-enter-directory}).
+@xref{Anything Groups}.
+
+@item G f
+@kindex G f (Group)
+@findex gnus-group-make-doc-group
+@cindex ClariNet Briefs
+@cindex nndoc
+Make a group based on some file or other
+(@code{gnus-group-make-doc-group}). If you give a prefix to this
+command, you will be prompted for a file name and a file type.
+Currently supported types are @code{babyl}, @code{mbox}, @code{digest},
+@code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs},
+@code{rfc934}, @code{rfc822-forward}, and @code{forward}. If you run
+this command without a prefix, Gnus will guess at the file type.
+@xref{Document Groups}.
+
+@item G u
+@kindex G u (Group)
+@vindex gnus-useful-groups
+@findex gnus-group-make-useful-group
+Create one of the groups mentioned in @code{gnus-useful-groups}
+(@code{gnus-group-make-useful-group}).
+
+@item G w
+@kindex G w (Group)
+@findex gnus-group-make-web-group
+@cindex DejaNews
+@cindex Alta Vista
+@cindex InReference
+@cindex nnweb
+Make an ephemeral group based on a web search
+(@code{gnus-group-make-web-group}). If you give a prefix to this
+command, make a solid group instead. You will be prompted for the
+search engine type and the search string. Valid search engine types
+include @code{dejanews}, @code{altavista} and @code{reference}.
+@xref{Web Searches}.
+
+If you use the @code{dejanews} search engine, you can limit the search
+to a particular group by using a match string like
+@samp{~g alt.sysadmin.recovery shaving}.
+
+@item G DEL
+@kindex G DEL (Group)
+@findex gnus-group-delete-group
+This function will delete the current group
+(@code{gnus-group-delete-group}). If given a prefix, this function will
+actually delete all the articles in the group, and forcibly remove the
+group itself from the face of the Earth. Use a prefix only if you are
+absolutely sure of what you are doing. This command can't be used on
+read-only groups (like @code{nntp} group), though.
+
+@item G V
+@kindex G V (Group)
+@findex gnus-group-make-empty-virtual
+Make a new, fresh, empty @code{nnvirtual} group
+(@code{gnus-group-make-empty-virtual}). @xref{Virtual Groups}.
+
+@item G v
+@kindex G v (Group)
+@findex gnus-group-add-to-virtual
+Add the current group to an @code{nnvirtual} group
+(@code{gnus-group-add-to-virtual}). Uses the process/prefix convention.
+@end table
+
+@xref{Select Methods}, for more information on the various select
+methods.
+
+@vindex gnus-activate-foreign-newsgroups
+If @code{gnus-activate-foreign-newsgroups} is a positive number,
+Gnus will check all foreign groups with this level or lower at startup.
+This might take quite a while, especially if you subscribe to lots of
+groups from different @sc{nntp} servers. Also @pxref{Group Levels};
+@code{gnus-activate-level} also affects activation of foreign
+newsgroups.
+
+
+@node Group Parameters
+@section Group Parameters
+@cindex group parameters
+
+The group parameters store information local to a particular group.
+Here's an example group parameter list:
+
+@example
+((to-address . "ding@@gnus.org")
+ (auto-expire . t))
+@end example
+
+We see that each element consists of a "dotted pair"---the thing before
+the dot is the key, while the thing after the dot is the value. All the
+parameters have this form @emph{except} local variable specs, which are
+not dotted pairs, but proper lists.
+
+The following group parameters can be used:
+
+@table @code
+@item to-address
+@cindex to-address
+Address used by when doing followups and new posts.
+
+@example
+(to-address . "some@@where.com")
+@end example
+
+This is primarily useful in mail groups that represent closed mailing
+lists---mailing lists where it's expected that everybody that writes to
+the mailing list is subscribed to it. Since using this parameter
+ensures that the mail only goes to the mailing list itself, it means
+that members won't receive two copies of your followups.
+
+Using @code{to-address} will actually work whether the group is foreign
+or not. Let's say there's a group on the server that is called
+@samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten
+the articles from a mail-to-news gateway. Posting directly to this
+group is therefore impossible---you have to send mail to the mailing
+list address instead.
+
+@item to-list
+@cindex to-list
+Address used when doing a @kbd{a} in that group.
+
+@example
+(to-list . "some@@where.com")
+@end example
+
+It is totally ignored
+when doing a followup---except that if it is present in a news group,
+you'll get mail group semantics when doing @kbd{f}.
+
+If you do an @kbd{a} command in a mail group and you have neither a
+@code{to-list} group parameter nor a @code{to-address} group parameter,
+then a @code{to-list} group parameter will be added automatically upon
+sending the message if @code{gnus-add-to-list} is set to @code{t}.
+@vindex gnus-add-to-list
+
+If you do an @kbd{a} command in a mail group and you don't have a
+@code{to-list} group parameter, one will be added automatically upon
+sending the message.
+
+@item visible
+@cindex visible
+If the group parameter list has the element @code{(visible . t)},
+that group will always be visible in the Group buffer, regardless
+of whether it has any unread articles.
+
+@item broken-reply-to
+@cindex broken-reply-to
+Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
+headers in this group are to be ignored. This can be useful if you're
+reading a mailing list group where the listserv has inserted
+@code{Reply-To} headers that point back to the listserv itself. This is
+broken behavior. So there!
+
+@item to-group
+@cindex to-group
+Elements like @code{(to-group . "some.group.name")} means that all
+posts in that group will be sent to @code{some.group.name}.
+
+@item newsgroup
+@cindex newsgroup
+If you have @code{(newsgroup . t)} in the group parameter list, Gnus
+will treat all responses as if they were responses to news articles.
+This can be useful if you have a mail group that's really a mirror of a
+news group.
+
+@item gcc-self
+@cindex gcc-self
+If @code{(gcc-self . t)} is present in the group parameter list, newly
+composed messages will be @code{Gcc}'d to the current group. If
+@code{(gcc-self . none)} is present, no @code{Gcc:} header will be
+generated, if @code{(gcc-self . "string")} is present, this string will
+be inserted literally as a @code{gcc} header. This parameter takes
+precedence over any default @code{Gcc} rules as described later
+(@pxref{Archived Messages}).
+
+@item auto-expire
+@cindex auto-expire
+If the group parameter has an element that looks like @code{(auto-expire
+. t)}, all articles read will be marked as expirable. For an
+alternative approach, @pxref{Expiring Mail}.
+
+@item total-expire
+@cindex total-expire
+If the group parameter has an element that looks like
+@code{(total-expire . t)}, all read articles will be put through the
+expiry process, even if they are not marked as expirable. Use with
+caution. Unread, ticked and dormant articles are not eligible for
+expiry.
+
+@item expiry-wait
+@cindex expiry-wait
+@vindex nnmail-expiry-wait-function
+If the group parameter has an element that looks like @code{(expiry-wait
+. 10)}, this value will override any @code{nnmail-expiry-wait} and
+@code{nnmail-expiry-wait-function} when expiring expirable messages.
+The value can either be a number of days (not necessarily an integer) or
+the symbols @code{never} or @code{immediate}.
+
+@item score-file
+@cindex score file group parameter
+Elements that look like @code{(score-file . "file")} will make
+@file{file} into the current score file for the group in question. All
+interactive score entries will be put into this file.
+
+@item adapt-file
+@cindex adapt file group parameter
+Elements that look like @code{(adapt-file . "file")} will make
+@file{file} into the current adaptive file for the group in question.
+All adaptive score entries will be put into this file.
+
+@item admin-address
+When unsubscribing from a mailing list you should never send the
+unsubscription notice to the mailing list itself. Instead, you'd send
+messages to the administrative address. This parameter allows you to
+put the admin address somewhere convenient.
+
+@item display
+Elements that look like @code{(display . MODE)} say which articles to
+display on entering the group. Valid values are:
+
+@table @code
+@item all
+Display all articles, both read and unread.
+
+@item default
+Display the default visible articles, which normally includes unread and
+ticked articles.
+@end table
+
+@item comment
+Elements that look like @code{(comment . "This is a comment")}
+are arbitrary comments on the group. They are currently ignored by
+Gnus, but provide a place for you to store information on particular
+groups.
+
+@item @var{(variable form)}
+You can use the group parameters to set variables local to the group you
+are entering. If you want to turn threading off in @samp{news.answers},
+you could put @code{(gnus-show-threads nil)} in the group parameters of
+that group. @code{gnus-show-threads} will be made into a local variable
+in the summary buffer you enter, and the form @code{nil} will be
+@code{eval}ed there.
+
+This can also be used as a group-specific hook function, if you'd like.
+If you want to hear a beep when you enter a group, you could put
+something like @code{(dummy-variable (ding))} in the parameters of that
+group. @code{dummy-variable} will be set to the result of the
+@code{(ding)} form, but who cares?
+
+@end table
+
+Use the @kbd{G p} command to edit group parameters of a group. You
+might also be interested in reading about topic parameters (@pxref{Topic
+Parameters}).
+
+
+@node Listing Groups
+@section Listing Groups
+@cindex group listing
+
+These commands all list various slices of the groups available.
+
+@table @kbd
+
+@item l
+@itemx A s
+@kindex A s (Group)
+@kindex l (Group)
+@findex gnus-group-list-groups
+List all groups that have unread articles
+(@code{gnus-group-list-groups}). If the numeric prefix is used, this
+command will list only groups of level ARG and lower. By default, it
+only lists groups of level five (i. e.,
+@code{gnus-group-default-list-level}) or lower (i.e., just subscribed
+groups).
+
+@item L
+@itemx A u
+@kindex A u (Group)
+@kindex L (Group)
+@findex gnus-group-list-all-groups
+List all groups, whether they have unread articles or not
+(@code{gnus-group-list-all-groups}). If the numeric prefix is used,
+this command will list only groups of level ARG and lower. By default,
+it lists groups of level seven or lower (i.e., just subscribed and
+unsubscribed groups).
+
+@item A l
+@kindex A l (Group)
+@findex gnus-group-list-level
+List all unread groups on a specific level
+(@code{gnus-group-list-level}). If given a prefix, also list the groups
+with no unread articles.
+
+@item A k
+@kindex A k (Group)
+@findex gnus-group-list-killed
+List all killed groups (@code{gnus-group-list-killed}). If given a
+prefix argument, really list all groups that are available, but aren't
+currently (un)subscribed. This could entail reading the active file
+from the server.
+
+@item A z
+@kindex A z (Group)
+@findex gnus-group-list-zombies
+List all zombie groups (@code{gnus-group-list-zombies}).
+
+@item A m
+@kindex A m (Group)
+@findex gnus-group-list-matching
+List all unread, subscribed groups with names that match a regexp
+(@code{gnus-group-list-matching}).
+
+@item A M
+@kindex A M (Group)
+@findex gnus-group-list-all-matching
+List groups that match a regexp (@code{gnus-group-list-all-matching}).
+
+@item A A
+@kindex A A (Group)
+@findex gnus-group-list-active
+List absolutely all groups in the active file(s) of the
+server(s) you are connected to (@code{gnus-group-list-active}). This
+might very well take quite a while. It might actually be a better idea
+to do a @kbd{A M} to list all matching, and just give @samp{.} as the
+thing to match on. Also note that this command may list groups that
+don't exist (yet)---these will be listed as if they were killed groups.
+Take the output with some grains of salt.
+
+@item A a
+@kindex A a (Group)
+@findex gnus-group-apropos
+List all groups that have names that match a regexp
+(@code{gnus-group-apropos}).
+
+@item A d
+@kindex A d (Group)
+@findex gnus-group-description-apropos
+List all groups that have names or descriptions that match a regexp
+(@code{gnus-group-description-apropos}).
+
+@end table
+
+@vindex gnus-permanently-visible-groups
+@cindex visible group parameter
+Groups that match the @code{gnus-permanently-visible-groups} regexp will
+always be shown, whether they have unread articles or not. You can also
+add the @code{visible} element to the group parameters in question to
+get the same effect.
+
+@vindex gnus-list-groups-with-ticked-articles
+Groups that have just ticked articles in it are normally listed in the
+group buffer. If @code{gnus-list-groups-with-ticked-articles} is
+@code{nil}, these groups will be treated just like totally empty
+groups. It is @code{t} by default.
+
+
+@node Sorting Groups
+@section Sorting Groups
+@cindex sorting groups
+
+@kindex C-c C-s (Group)
+@findex gnus-group-sort-groups
+@vindex gnus-group-sort-function
+The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the
+group buffer according to the function(s) given by the
+@code{gnus-group-sort-function} variable. Available sorting functions
+include:
+
+@table @code
+
+@item gnus-group-sort-by-alphabet
+@findex gnus-group-sort-by-alphabet
+Sort the group names alphabetically. This is the default.
+
+@item gnus-group-sort-by-real-name
+@findex gnus-group-sort-by-real-name
+Sort the group alphabetically on the real (unprefixed) group names.
+
+@item gnus-group-sort-by-level
+@findex gnus-group-sort-by-level
+Sort by group level.
+
+@item gnus-group-sort-by-score
+@findex gnus-group-sort-by-score
+Sort by group score. @xref{Group Score}.
+
+@item gnus-group-sort-by-rank
+@findex gnus-group-sort-by-rank
+Sort by group score and then the group level. The level and the score
+are, when taken together, the group's @dfn{rank}. @xref{Group Score}.
+
+@item gnus-group-sort-by-unread
+@findex gnus-group-sort-by-unread
+Sort by number of unread articles.
+
+@item gnus-group-sort-by-method
+@findex gnus-group-sort-by-method
+Sort alphabetically on the select method.
+
+
+@end table
+
+@code{gnus-group-sort-function} can also be a list of sorting
+functions. In that case, the most significant sort key function must be
+the last one.
+
+
+There are also a number of commands for sorting directly according to
+some sorting criteria:
+
+@table @kbd
+@item G S a
+@kindex G S a (Group)
+@findex gnus-group-sort-groups-by-alphabet
+Sort the group buffer alphabetically by group name
+(@code{gnus-group-sort-groups-by-alphabet}).
+
+@item G S u
+@kindex G S u (Group)
+@findex gnus-group-sort-groups-by-unread
+Sort the group buffer by the number of unread articles
+(@code{gnus-group-sort-groups-by-unread}).
+
+@item G S l
+@kindex G S l (Group)
+@findex gnus-group-sort-groups-by-level
+Sort the group buffer by group level
+(@code{gnus-group-sort-groups-by-level}).
+
+@item G S v
+@kindex G S v (Group)
+@findex gnus-group-sort-groups-by-score
+Sort the group buffer by group score
+(@code{gnus-group-sort-groups-by-score}). @xref{Group Score}.
+
+@item G S r
+@kindex G S r (Group)
+@findex gnus-group-sort-groups-by-rank
+Sort the group buffer by group rank
+(@code{gnus-group-sort-groups-by-rank}). @xref{Group Score}.
+
+@item G S m
+@kindex G S m (Group)
+@findex gnus-group-sort-groups-by-method
+Sort the group buffer alphabetically by backend name
+(@code{gnus-group-sort-groups-by-method}).
+
+@end table
+
+When given a prefix, all these commands will sort in reverse order.
+
+You can also sort a subset of the groups:
+
+@table @kbd
+@item G P a
+@kindex G P a (Group)
+@findex gnus-group-sort-selected-groups-by-alphabet
+Sort the process/prefixed groups in the group buffer alphabetically by
+group name (@code{gnus-group-sort-selected-groups-by-alphabet}).
+
+@item G P u
+@kindex G P u (Group)
+@findex gnus-group-sort-selected-groups-by-unread
+Sort the process/prefixed groups in the group buffer by the number of
+unread articles (@code{gnus-group-sort-selected-groups-by-unread}).
+
+@item G P l
+@kindex G P l (Group)
+@findex gnus-group-sort-selected-groups-by-level
+Sort the process/prefixed groups in the group buffer by group level
+(@code{gnus-group-sort-selected-groups-by-level}).
+
+@item G P v
+@kindex G P v (Group)
+@findex gnus-group-sort-selected-groups-by-score
+Sort the process/prefixed groups in the group buffer by group score
+(@code{gnus-group-sort-selected-groups-by-score}). @xref{Group Score}.
+
+@item G P r
+@kindex G P r (Group)
+@findex gnus-group-sort-selected-groups-by-rank
+Sort the process/prefixed groups in the group buffer by group rank
+(@code{gnus-group-sort-selected-groups-by-rank}). @xref{Group Score}.
+
+@item G P m
+@kindex G P m (Group)
+@findex gnus-group-sort-selected-groups-by-method
+Sort the process/prefixed groups in the group buffer alphabetically by
+backend name (@code{gnus-group-sort-selected-groups-by-method}).
+
+@end table
+
+
+
+@node Group Maintenance
+@section Group Maintenance
+@cindex bogus groups
+
+@table @kbd
+@item b
+@kindex b (Group)
+@findex gnus-group-check-bogus-groups
+Find bogus groups and delete them
+(@code{gnus-group-check-bogus-groups}).
+
+@item F
+@kindex F (Group)
+@findex gnus-group-find-new-groups
+Find new groups and process them (@code{gnus-group-find-new-groups}).
+With 1 @kbd{C-u}, use the @code{ask-server} method to query the server
+for new groups. With 2 @kbd{C-u}'s, use most complete method possible
+to query the server for new groups, and subscribe the new groups as
+zombies.
+
+@item C-c C-x
+@kindex C-c C-x (Group)
+@findex gnus-group-expire-articles
+Run all expirable articles in the current group through the expiry
+process (if any) (@code{gnus-group-expire-articles}).
+
+@item C-c M-C-x
+@kindex C-c M-C-x (Group)
+@findex gnus-group-expire-all-groups
+Run all articles in all groups through the expiry process
+(@code{gnus-group-expire-all-groups}).
+
+@end table
+
+
+@node Browse Foreign Server
+@section Browse Foreign Server
+@cindex foreign servers
+@cindex browsing servers
+
+@table @kbd
+@item B
+@kindex B (Group)
+@findex gnus-group-browse-foreign-server
+You will be queried for a select method and a server name. Gnus will
+then attempt to contact this server and let you browse the groups there
+(@code{gnus-group-browse-foreign-server}).
+@end table
+
+@findex gnus-browse-mode
+A new buffer with a list of available groups will appear. This buffer
+will use the @code{gnus-browse-mode}. This buffer looks a bit (well,
+a lot) like a normal group buffer.
+
+Here's a list of keystrokes available in the browse mode:
+
+@table @kbd
+@item n
+@kindex n (Browse)
+@findex gnus-group-next-group
+Go to the next group (@code{gnus-group-next-group}).
+
+@item p
+@kindex p (Browse)
+@findex gnus-group-prev-group
+Go to the previous group (@code{gnus-group-prev-group}).
+
+@item SPACE
+@kindex SPACE (Browse)
+@findex gnus-browse-read-group
+Enter the current group and display the first article
+(@code{gnus-browse-read-group}).
+
+@item RET
+@kindex RET (Browse)
+@findex gnus-browse-select-group
+Enter the current group (@code{gnus-browse-select-group}).
+
+@item u
+@kindex u (Browse)
+@findex gnus-browse-unsubscribe-current-group
+Unsubscribe to the current group, or, as will be the case here,
+subscribe to it (@code{gnus-browse-unsubscribe-current-group}).
+
+@item l
+@itemx q
+@kindex q (Browse)
+@kindex l (Browse)
+@findex gnus-browse-exit
+Exit browse mode (@code{gnus-browse-exit}).
+
+@item ?
+@kindex ? (Browse)
+@findex gnus-browse-describe-briefly
+Describe browse mode briefly (well, there's not much to describe, is
+there) (@code{gnus-browse-describe-briefly}).
+@end table
+
+
+@node Exiting Gnus
+@section Exiting Gnus
+@cindex exiting Gnus
+
+Yes, Gnus is ex(c)iting.
+
+@table @kbd
+@item z
+@kindex z (Group)
+@findex gnus-group-suspend
+Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus,
+but it kills all buffers except the Group buffer. I'm not sure why this
+is a gain, but then who am I to judge?
+
+@item q
+@kindex q (Group)
+@findex gnus-group-exit
+@c @icon{gnus-group-exit}
+Quit Gnus (@code{gnus-group-exit}).
+
+@item Q
+@kindex Q (Group)
+@findex gnus-group-quit
+Quit Gnus without saving the @file{.newsrc} files (@code{gnus-group-quit}).
+The dribble file will be saved, though (@pxref{Auto Save}).
+@end table
+
+@vindex gnus-exit-gnus-hook
+@vindex gnus-suspend-gnus-hook
+@code{gnus-suspend-gnus-hook} is called when you suspend Gnus and
+@code{gnus-exit-gnus-hook} is called when you quit Gnus, while
+@code{gnus-after-exiting-gnus-hook} is called as the final item when
+exiting Gnus.
+
+@findex gnus-unload
+@cindex unloading
+If you wish to completely unload Gnus and all its adherents, you can use
+the @code{gnus-unload} command. This command is also very handy when
+trying to customize meta-variables.
+
+Note:
+
+@quotation
+Miss Lisa Cannifax, while sitting in English class, felt her feet go
+numbly heavy and herself fall into a hazy trance as the boy sitting
+behind her drew repeated lines with his pencil across the back of her
+plastic chair.
+@end quotation
+
+
+@node Group Topics
+@section Group Topics
+@cindex topics
+
+If you read lots and lots of groups, it might be convenient to group
+them hierarchically according to topics. You put your Emacs groups over
+here, your sex groups over there, and the rest (what, two groups or so?)
+you put in some misc section that you never bother with anyway. You can
+even group the Emacs sex groups as a sub-topic to either the Emacs
+groups or the sex groups---or both! Go wild!
+
+Here's an example:
+
+@example
+Gnus
+ Emacs -- I wuw it!
+ 3: comp.emacs
+ 2: alt.religion.emacs
+ Naughty Emacs
+ 452: alt.sex.emacs
+ 0: comp.talk.emacs.recovery
+ Misc
+ 8: comp.binaries.fractals
+ 13: comp.sources.unix
+@end example
+
+@findex gnus-topic-mode
+@kindex t (Group)
+To get this @emph{fab} functionality you simply turn on (ooh!) the
+@code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This
+is a toggling command.)
+
+Go ahead, just try it. I'll still be here when you get back. La de
+dum... Nice tune, that... la la la... What, you're back? Yes, and now
+press @kbd{l}. There. All your groups are now listed under
+@samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
+bothered?
+
+If you want this permanently enabled, you should add that minor mode to
+the hook for the group mode:
+
+@lisp
+(add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
+@end lisp
+
+@menu
+* Topic Variables:: How to customize the topics the Lisp Way.
+* Topic Commands:: Interactive E-Z commands.
+* Topic Sorting:: Sorting each topic individually.
+* Topic Topology:: A map of the world.
+* Topic Parameters:: Parameters that apply to all groups in a topic.
+@end menu
+
+
+@node Topic Variables
+@subsection Topic Variables
+@cindex topic variables
+
+Now, if you select a topic, it will fold/unfold that topic, which is
+really neat, I think.
+
+@vindex gnus-topic-line-format
+The topic lines themselves are created according to the
+@code{gnus-topic-line-format} variable (@pxref{Formatting Variables}).
+Valid elements are:
+
+@table @samp
+@item i
+Indentation.
+@item n
+Topic name.
+@item v
+Visibility.
+@item l
+Level.
+@item g
+Number of groups in the topic.
+@item a
+Number of unread articles in the topic.
+@item A
+Number of unread articles in the topic and all its subtopics.
+@end table
+
+@vindex gnus-topic-indent-level
+Each sub-topic (and the groups in the sub-topics) will be indented with
+@code{gnus-topic-indent-level} times the topic level number of spaces.
+The default is 2.
+
+@vindex gnus-topic-mode-hook
+@code{gnus-topic-mode-hook} is called in topic minor mode buffers.
+
+@vindex gnus-topic-display-empty-topics
+The @code{gnus-topic-display-empty-topics} says whether to display even
+topics that have no unread articles in them. The default is @code{t}.
+
+
+@node Topic Commands
+@subsection Topic Commands
+@cindex topic commands
+
+When the topic minor mode is turned on, a new @kbd{T} submap will be
+available. In addition, a few of the standard keys change their
+definitions slightly.
+
+@table @kbd
+
+@item T n
+@kindex T n (Topic)
+@findex gnus-topic-create-topic
+Prompt for a new topic name and create it
+(@code{gnus-topic-create-topic}).
+
+@item T m
+@kindex T m (Topic)
+@findex gnus-topic-move-group
+Move the current group to some other topic
+(@code{gnus-topic-move-group}). This command uses the process/prefix
+convention (@pxref{Process/Prefix}).
+
+@item T c
+@kindex T c (Topic)
+@findex gnus-topic-copy-group
+Copy the current group to some other topic
+(@code{gnus-topic-copy-group}). This command uses the process/prefix
+convention (@pxref{Process/Prefix}).
+
+@item T D
+@kindex T D (Topic)
+@findex gnus-topic-remove-group
+Remove a group from the current topic (@code{gnus-topic-remove-group}).
+This command is mainly useful if you have the same group in several
+topics and wish to remove it from one of the topics. You may also
+remove a group from all topics, but in that case, Gnus will add it to
+the root topic the next time you start Gnus. In fact, all new groups
+(which, naturally, don't belong to any topic) will show up in the root
+topic.
+
+This command uses the process/prefix convention
+(@pxref{Process/Prefix}).
+
+@item T M
+@kindex T M (Topic)
+@findex gnus-topic-move-matching
+Move all groups that match some regular expression to a topic
+(@code{gnus-topic-move-matching}).
+
+@item T C
+@kindex T C (Topic)
+@findex gnus-topic-copy-matching
+Copy all groups that match some regular expression to a topic
+(@code{gnus-topic-copy-matching}).
+
+@item T H
+@kindex T H (Topic)
+@findex gnus-topic-toggle-display-empty-topics
+Toggle hiding empty topics
+(@code{gnus-topic-toggle-display-empty-topics}).
+
+@item T #
+@kindex T # (Topic)
+@findex gnus-topic-mark-topic
+Mark all groups in the current topic with the process mark
+(@code{gnus-topic-mark-topic}).
+
+@item T M-#
+@kindex T M-# (Topic)
+@findex gnus-topic-unmark-topic
+Remove the process mark from all groups in the current topic
+(@code{gnus-topic-unmark-topic}).
+
+@item RET
+@kindex RET (Topic)
+@findex gnus-topic-select-group
+@itemx SPACE
+Either select a group or fold a topic (@code{gnus-topic-select-group}).
+When you perform this command on a group, you'll enter the group, as
+usual. When done on a topic line, the topic will be folded (if it was
+visible) or unfolded (if it was folded already). So it's basically a
+toggling command on topics. In addition, if you give a numerical
+prefix, group on that level (and lower) will be displayed.
+
+@item T TAB
+@itemx TAB
+@kindex T TAB (Topic)
+@kindex TAB (Topic)
+@findex gnus-topic-indent
+``Indent'' the current topic so that it becomes a sub-topic of the
+previous topic (@code{gnus-topic-indent}). If given a prefix,
+``un-indent'' the topic instead.
+
+@item M-TAB
+@kindex M-TAB (Topic)
+@findex gnus-topic-unindent
+``Un-indent'' the current topic so that it becomes a sub-topic of the
+parent of its current parent (@code{gnus-topic-unindent}).
+
+@item C-k
+@kindex C-k (Topic)
+@findex gnus-topic-kill-group
+Kill a group or topic (@code{gnus-topic-kill-group}). All groups in the
+topic will be removed along with the topic.
+
+@item C-y
+@kindex C-y (Topic)
+@findex gnus-topic-yank-group
+Yank the previously killed group or topic
+(@code{gnus-topic-yank-group}). Note that all topics will be yanked
+before all groups.
+
+@item T r
+@kindex T r (Topic)
+@findex gnus-topic-rename
+Rename a topic (@code{gnus-topic-rename}).
+
+@item T DEL
+@kindex T DEL (Topic)
+@findex gnus-topic-delete
+Delete an empty topic (@code{gnus-topic-delete}).
+
+@item A T
+@kindex A T (Topic)
+@findex gnus-topic-list-active
+List all groups that Gnus knows about in a topics-ified way
+(@code{gnus-topic-list-active}).
+
+@item G p
+@kindex G p (Topic)
+@findex gnus-topic-edit-parameters
+@cindex group parameters
+@cindex topic parameters
+@cindex parameters
+Edit the topic parameters (@code{gnus-topic-edit-parameters}).
+@xref{Topic Parameters}.
+
+@end table
+
+
+@node Topic Sorting
+@subsection Topic Sorting
+@cindex topic sorting
+
+You can sort the groups in each topic individually with the following
+commands:
+
+
+@table @kbd
+@item T S a
+@kindex T S a (Topic)
+@findex gnus-topic-sort-groups-by-alphabet
+Sort the current topic alphabetically by group name
+(@code{gnus-topic-sort-groups-by-alphabet}).
+
+@item T S u
+@kindex T S u (Topic)
+@findex gnus-topic-sort-groups-by-unread
+Sort the current topic by the number of unread articles
+(@code{gnus-topic-sort-groups-by-unread}).
+
+@item T S l
+@kindex T S l (Topic)
+@findex gnus-topic-sort-groups-by-level
+Sort the current topic by group level
+(@code{gnus-topic-sort-groups-by-level}).
+
+@item T S v
+@kindex T S v (Topic)
+@findex gnus-topic-sort-groups-by-score
+Sort the current topic by group score
+(@code{gnus-topic-sort-groups-by-score}). @xref{Group Score}.
+
+@item T S r
+@kindex T S r (Topic)
+@findex gnus-topic-sort-groups-by-rank
+Sort the current topic by group rank
+(@code{gnus-topic-sort-groups-by-rank}). @xref{Group Score}.
+
+@item T S m
+@kindex T S m (Topic)
+@findex gnus-topic-sort-groups-by-method
+Sort the current topic alphabetically by backend name
+(@code{gnus-topic-sort-groups-by-method}).
+
+@end table
+
+@xref{Sorting Groups}, for more information about group sorting.
+
+
+@node Topic Topology
+@subsection Topic Topology
+@cindex topic topology
+@cindex topology
+
+So, let's have a look at an example group buffer:
+
+@example
+Gnus
+ Emacs -- I wuw it!
+ 3: comp.emacs
+ 2: alt.religion.emacs
+ Naughty Emacs
+ 452: alt.sex.emacs
+ 0: comp.talk.emacs.recovery
+ Misc
+ 8: comp.binaries.fractals
+ 13: comp.sources.unix
+@end example
+
+So, here we have one top-level topic (@samp{Gnus}), two topics under
+that, and one sub-topic under one of the sub-topics. (There is always
+just one (1) top-level topic). This topology can be expressed as
+follows:
+
+@lisp
+(("Gnus" visible)
+ (("Emacs -- I wuw it!" visible)
+ (("Naughty Emacs" visible)))
+ (("Misc" visible)))
+@end lisp
+
+@vindex gnus-topic-topology
+This is in fact how the variable @code{gnus-topic-topology} would look
+for the display above. That variable is saved in the @file{.newsrc.eld}
+file, and shouldn't be messed with manually---unless you really want
+to. Since this variable is read from the @file{.newsrc.eld} file,
+setting it in any other startup files will have no effect.
+
+This topology shows what topics are sub-topics of what topics (right),
+and which topics are visible. Two settings are currently
+allowed---@code{visible} and @code{invisible}.
+
+
+@node Topic Parameters
+@subsection Topic Parameters
+@cindex topic parameters
+
+All groups in a topic will inherit group parameters from the parent (and
+ancestor) topic parameters. All valid group parameters are valid topic
+parameters (@pxref{Group Parameters}).
+
+Group parameters (of course) override topic parameters, and topic
+parameters in sub-topics override topic parameters in super-topics. You
+know. Normal inheritance rules. (@dfn{Rules} is here a noun, not a
+verb, although you may feel free to disagree with me here.)
+
+@example
+Gnus
+ Emacs
+ 3: comp.emacs
+ 2: alt.religion.emacs
+ 452: alt.sex.emacs
+ Relief
+ 452: alt.sex.emacs
+ 0: comp.talk.emacs.recovery
+ Misc
+ 8: comp.binaries.fractals
+ 13: comp.sources.unix
+ 452: alt.sex.emacs
+@end example
+
+The @samp{Emacs} topic has the topic parameter @code{(score-file
+. "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter
+@code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the
+topic parameter @code{(score-file . "emacs.SCORE")}. In addition,
+@* @samp{alt.religion.emacs} has the group parameter @code{(score-file
+. "religion.SCORE")}.
+
+Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you
+will get the @file{relief.SCORE} home score file. If you enter the same
+group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home
+score file. If you enter the group @samp{alt.religion.emacs}, you'll
+get the @file{religion.SCORE} home score file.
+
+This seems rather simple and self-evident, doesn't it? Well, yes. But
+there are some problems, especially with the @code{total-expiry}
+parameter. Say you have a mail group in two topics; one with
+@code{total-expiry} and one without. What happens when you do @kbd{M-x
+gnus-expire-all-expirable-groups}? Gnus has no way of telling which one
+of these topics you mean to expire articles from, so anything may
+happen. In fact, I hereby declare that it is @dfn{undefined} what
+happens. You just have to be careful if you do stuff like that.
+
+
+@node Misc Group Stuff
+@section Misc Group Stuff
+
+@menu
+* Scanning New Messages:: Asking Gnus to see whether new messages have arrived.
+* Group Information:: Information and help on groups and Gnus.
+* Group Timestamp:: Making Gnus keep track of when you last read a group.
+* File Commands:: Reading and writing the Gnus files.
+@end menu
+
+@table @kbd
+
+@item ^
+@kindex ^ (Group)
+@findex gnus-group-enter-server-mode
+Enter the server buffer (@code{gnus-group-enter-server-mode}).
+@xref{The Server Buffer}.
+
+@item a
+@kindex a (Group)
+@findex gnus-group-post-news
+Post an article to a group (@code{gnus-group-post-news}). If given a
+prefix, the current group name will be used as the default.
+
+@item m
+@kindex m (Group)
+@findex gnus-group-mail
+Mail a message somewhere (@code{gnus-group-mail}).
+
+@end table
+
+Variables for the group buffer:
+
+@table @code
+
+@item gnus-group-mode-hook
+@vindex gnus-group-mode-hook
+is called after the group buffer has been
+created.
+
+@item gnus-group-prepare-hook
+@vindex gnus-group-prepare-hook
+is called after the group buffer is
+generated. It may be used to modify the buffer in some strange,
+unnatural way.
+
+@item gnus-group-prepared-hook
+@vindex gnus-group-prepare-hook
+is called as the very last thing after the group buffer has been
+generated. It may be used to move point around, for instance.
+
+@item gnus-permanently-visible-groups
+@vindex gnus-permanently-visible-groups
+Groups matching this regexp will always be listed in the group buffer,
+whether they are empty or not.
+
+@end table
+
+
+@node Scanning New Messages
+@subsection Scanning New Messages
+@cindex new messages
+@cindex scanning new news
+
+@table @kbd
+
+@item g
+@kindex g (Group)
+@findex gnus-group-get-new-news
+@c @icon{gnus-group-get-new-news}
+Check the server(s) for new articles. If the numerical prefix is used,
+this command will check only groups of level @var{arg} and lower
+(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this
+command will force a total re-reading of the active file(s) from the
+backend(s).
+
+@item M-g
+@kindex M-g (Group)
+@findex gnus-group-get-new-news-this-group
+@vindex gnus-goto-next-group-when-activating
+@c @icon{gnus-group-get-new-news-this-group}
+Check whether new articles have arrived in the current group
+(@code{gnus-group-get-new-news-this-group}).
+@code{gnus-goto-next-group-when-activating} says whether this command is
+to move point to the next group or not. It is @code{t} by default.
+
+@findex gnus-activate-all-groups
+@cindex activating groups
+@item C-c M-g
+@kindex C-c M-g (Group)
+Activate absolutely all groups (@code{gnus-activate-all-groups}).
+
+@item R
+@kindex R (Group)
+@cindex restarting
+@findex gnus-group-restart
+Restart Gnus (@code{gnus-group-restart}). This saves the @file{.newsrc}
+file(s), closes the connection to all servers, clears up all run-time
+Gnus variables, and then starts Gnus all over again.
+
+@end table
+
+@vindex gnus-get-new-news-hook
+@code{gnus-get-new-news-hook} is run just before checking for new news.
+
+@vindex gnus-after-getting-new-news-hook
+@code{gnus-after-getting-new-news-hook} is run after checking for new
+news.
+
+
+@node Group Information
+@subsection Group Information
+@cindex group information
+@cindex information on groups
+
+@table @kbd
+
+
+@item H f
+@kindex H f (Group)
+@findex gnus-group-fetch-faq
+@vindex gnus-group-faq-directory
+@cindex FAQ
+@cindex ange-ftp
+Try to fetch the FAQ for the current group
+(@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from
+@code{gnus-group-faq-directory}, which is usually a directory on a
+remote machine. This variable can also be a list of directories. In
+that case, giving a prefix to this command will allow you to choose
+between the various sites. @code{ange-ftp} (or @code{efs}) will be used
+for fetching the file.
+
+If fetching from the first site is unsuccessful, Gnus will attempt to go
+through @code{gnus-group-faq-directory} and try to open them one by one.
+
+@item H d
+@itemx C-c C-d
+@c @icon{gnus-group-describe-group}
+@kindex H d (Group)
+@kindex C-c C-d (Group)
+@cindex describing groups
+@cindex group description
+@findex gnus-group-describe-group
+Describe the current group (@code{gnus-group-describe-group}). If given
+a prefix, force Gnus to re-read the description from the server.
+
+@item M-d
+@kindex M-d (Group)
+@findex gnus-group-describe-all-groups
+Describe all groups (@code{gnus-group-describe-all-groups}). If given a
+prefix, force Gnus to re-read the description file from the server.
+
+@item H v
+@itemx V
+@kindex V (Group)
+@kindex H v (Group)
+@cindex version
+@findex gnus-version
+Display current Gnus version numbers (@code{gnus-version}).
+
+@item ?
+@kindex ? (Group)
+@findex gnus-group-describe-briefly
+Give a very short help message (@code{gnus-group-describe-briefly}).
+
+@item C-c C-i
+@kindex C-c C-i (Group)
+@cindex info
+@cindex manual
+@findex gnus-info-find-node
+Go to the Gnus info node (@code{gnus-info-find-node}).
+@end table
+
+
+@node Group Timestamp
+@subsection Group Timestamp
+@cindex timestamps
+@cindex group timestamps
+
+It can be convenient to let Gnus keep track of when you last read a
+group. To set the ball rolling, you should add
+@code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}:
+
+@lisp
+(add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp)
+@end lisp
+
+After doing this, each time you enter a group, it'll be recorded.
+
+This information can be displayed in various ways---the easiest is to
+use the @samp{%d} spec in the group line format:
+
+@lisp
+(setq gnus-group-line-format
+ "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n")
+@end lisp
+
+This will result in lines looking like:
+
+@example
+* 0: mail.ding 19961002T012943
+ 0: custom 19961002T012713
+@end example
+
+As you can see, the date is displayed in compact ISO 8601 format. This
+may be a bit too much, so to just display the date, you could say
+something like:
+
+@lisp
+(setq gnus-group-line-format
+ "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n")
+@end lisp
+
+
+@node File Commands
+@subsection File Commands
+@cindex file commands
+
+@table @kbd
+
+@item r
+@kindex r (Group)
+@findex gnus-group-read-init-file
+@vindex gnus-init-file
+@cindex reading init file
+Re-read the init file (@code{gnus-init-file}, which defaults to
+@file{~/.gnus}) (@code{gnus-group-read-init-file}).
+
+@item s
+@kindex s (Group)
+@findex gnus-group-save-newsrc
+@cindex saving .newsrc
+Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted)
+(@code{gnus-group-save-newsrc}). If given a prefix, force saving the
+file(s) whether Gnus thinks it is necessary or not.
+
+@c @item Z
+@c @kindex Z (Group)
+@c @findex gnus-group-clear-dribble
+@c Clear the dribble buffer (@code{gnus-group-clear-dribble}).
+
+@end table
+
+
+@node The Summary Buffer
+@chapter The Summary Buffer
+@cindex summary buffer
+
+A line for each article is displayed in the summary buffer. You can
+move around, read articles, post articles and reply to articles.
+
+The most common way to a summary buffer is to select a group from the
+group buffer (@pxref{Selecting a Group}).
+
+You can have as many summary buffers open as you wish.
+
+@menu
+* Summary Buffer Format:: Deciding how the summary buffer is to look.
+* Summary Maneuvering:: Moving around the summary buffer.
+* Choosing Articles:: Reading articles.
+* Paging the Article:: Scrolling the current article.
+* Reply Followup and Post:: Posting articles.
+* Canceling and Superseding:: ``Whoops, I shouldn't have called him that.''
+* Marking Articles:: Marking articles as read, expirable, etc.
+* Limiting:: You can limit the summary buffer.
+* Threading:: How threads are made.
+* Sorting:: How articles and threads are sorted.
+* Asynchronous Fetching:: Gnus might be able to pre-fetch articles.
+* Article Caching:: You may store articles in a cache.
+* Persistent Articles:: Making articles expiry-resistant.
+* Article Backlog:: Having already read articles hang around.
+* Saving Articles:: Ways of customizing article saving.
+* Decoding Articles:: Gnus can treat series of (uu)encoded articles.
+* Article Treatment:: The article buffer can be mangled at will.
+* Article Commands:: Doing various things with the article buffer.
+* Summary Sorting:: Sorting the summary buffer in various ways.
+* Finding the Parent:: No child support? Get the parent.
+* Alternative Approaches:: Reading using non-default summaries.
+* Tree Display:: A more visual display of threads.
+* Mail Group Commands:: Some commands can only be used in mail groups.
+* Various Summary Stuff:: What didn't fit anywhere else.
+* Exiting the Summary Buffer:: Returning to the Group buffer.
+* Crosspost Handling:: How crossposted articles are dealt with.
+* Duplicate Suppression:: An alternative when crosspost handling fails.
+@end menu
+
+
+@node Summary Buffer Format
+@section Summary Buffer Format
+@cindex summary buffer format
+
+@menu
+* Summary Buffer Lines:: You can specify how summary lines should look.
+* Summary Buffer Mode Line:: You can say how the mode line should look.
+* Summary Highlighting:: Making the summary buffer all pretty and nice.
+@end menu
+
+@findex mail-extract-address-components
+@findex gnus-extract-address-components
+@vindex gnus-extract-address-components
+Gnus will use the value of the @code{gnus-extract-address-components}
+variable as a function for getting the name and address parts of a
+@code{From} header. Two pre-defined functions exist:
+@code{gnus-extract-address-components}, which is the default, quite
+fast, and too simplistic solution; and
+@code{mail-extract-address-components}, which works very nicely, but is
+slower. The default function will return the wrong answer in 5% of the
+cases. If this is unacceptable to you, use the other function instead.
+
+@vindex gnus-summary-same-subject
+@code{gnus-summary-same-subject} is a string indicating that the current
+article has the same subject as the previous. This string will be used
+with those specs that require it. The default is @code{""}.
+
+
+@node Summary Buffer Lines
+@subsection Summary Buffer Lines
+
+@vindex gnus-summary-line-format
+You can change the format of the lines in the summary buffer by changing
+the @code{gnus-summary-line-format} variable. It works along the same
+lines as a normal @code{format} string, with some extensions
+(@pxref{Formatting Variables}).
+
+The default string is @samp{%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n}.
+
+The following format specification characters are understood:
+
+@table @samp
+@item N
+Article number.
+@item S
+Subject string.
+@item s
+Subject if the article is the root of the thread or the previous article
+had a different subject, @code{gnus-summary-same-subject} otherwise.
+(@code{gnus-summary-same-subject} defaults to @code{""}.)
+@item F
+Full @code{From} header.
+@item n
+The name (from the @code{From} header).
+@item a
+The name (from the @code{From} header). This differs from the @code{n}
+spec in that it uses the function designated by the
+@code{gnus-extract-address-components} variable, which is slower, but
+may be more thorough.
+@item A
+The address (from the @code{From} header). This works the same way as
+the @code{a} spec.
+@item L
+Number of lines in the article.
+@item c
+Number of characters in the article.
+@item I
+Indentation based on thread level (@pxref{Customizing Threading}).
+@item T
+Nothing if the article is a root and lots of spaces if it isn't (it
+pushes everything after it off the screen).
+@item [
+Opening bracket, which is normally @samp{[}, but can also be @samp{<}
+for adopted articles (@pxref{Customizing Threading}).
+@item ]
+Closing bracket, which is normally @samp{]}, but can also be @samp{>}
+for adopted articles.
+@item >
+One space for each thread level.
+@item <
+Twenty minus thread level spaces.
+@item U
+Unread.
+
+@item R
+This misleadingly named specifier is the @dfn{secondary mark}. This
+mark will say whether the article has been replied to, has been cached,
+or has been saved.
+
+@item i
+Score as a number (@pxref{Scoring}).
+@item z
+@vindex gnus-summary-zcore-fuzz
+Zcore, @samp{+} if above the default level and @samp{-} if below the
+default level. If the difference between
+@code{gnus-summary-default-score} and the score is less than
+@code{gnus-summary-zcore-fuzz}, this spec will not be used.
+@item V
+Total thread score.
+@item x
+@code{Xref}.
+@item D
+@code{Date}.
+@item d
+The @code{Date} in @code{DD-MMM} format.
+@item o
+The @code{Date} in @var{YYYYMMDD}@code{T}@var{HHMMSS} format.
+@item M
+@code{Message-ID}.
+@item r
+@code{References}.
+@item t
+Number of articles in the current sub-thread. Using this spec will slow
+down summary buffer generation somewhat.
+@item e
+An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the
+article has any children.
+@item P
+The line number.
+@item O
+Download mark.
+@item u
+User defined specifier. The next character in the format string should
+be a letter. Gnus will call the function
+@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter
+following @samp{%u}. The function will be passed the current header as
+argument. The function should return a string, which will be inserted
+into the summary just like information from any other summary specifier.
+@end table
+
+The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs
+have to be handled with care. For reasons of efficiency, Gnus will
+compute what column these characters will end up in, and ``hard-code''
+that. This means that it is invalid to have these specs after a
+variable-length spec. Well, you might not be arrested, but your summary
+buffer will look strange, which is bad enough.
+
+The smart choice is to have these specs as far to the left as possible.
+(Isn't that the case with everything, though? But I digress.)
+
+This restriction may disappear in later versions of Gnus.
+
+
+@node Summary Buffer Mode Line
+@subsection Summary Buffer Mode Line
+
+@vindex gnus-summary-mode-line-format
+You can also change the format of the summary mode bar (@pxref{Mode Line
+Formatting}). Set @code{gnus-summary-mode-line-format} to whatever you
+like. The default is @samp{Gnus: %%b [%A] %Z}.
+
+Here are the elements you can play with:
+
+@table @samp
+@item G
+Group name.
+@item p
+Unprefixed group name.
+@item A
+Current article number.
+@item z
+Current article score.
+@item V
+Gnus version.
+@item U
+Number of unread articles in this group.
+@item e
+Number of unread articles in this group that aren't displayed in the
+summary buffer.
+@item Z
+A string with the number of unread and unselected articles represented
+either as @samp{<%U(+%e) more>} if there are both unread and unselected
+articles, and just as @samp{<%U more>} if there are just unread articles
+and no unselected ones.
+@item g
+Shortish group name. For instance, @samp{rec.arts.anime} will be
+shortened to @samp{r.a.anime}.
+@item S
+Subject of the current article.
+@item u
+User-defined spec (@pxref{User-Defined Specs}).
+@item s
+Name of the current score file (@pxref{Scoring}).
+@item d
+Number of dormant articles (@pxref{Unread Articles}).
+@item t
+Number of ticked articles (@pxref{Unread Articles}).
+@item r
+Number of articles that have been marked as read in this session.
+@item E
+Number of articles expunged by the score files.
+@end table
+
+
+@node Summary Highlighting
+@subsection Summary Highlighting
+
+@table @code
+
+@item gnus-visual-mark-article-hook
+@vindex gnus-visual-mark-article-hook
+This hook is run after selecting an article. It is meant to be used for
+highlighting the article in some way. It is not run if
+@code{gnus-visual} is @code{nil}.
+
+@item gnus-summary-update-hook
+@vindex gnus-summary-update-hook
+This hook is called when a summary line is changed. It is not run if
+@code{gnus-visual} is @code{nil}.
+
+@item gnus-summary-selected-face
+@vindex gnus-summary-selected-face
+This is the face (or @dfn{font} as some people call it) used to
+highlight the current article in the summary buffer.
+
+@item gnus-summary-highlight
+@vindex gnus-summary-highlight
+Summary lines are highlighted according to this variable, which is a
+list where the elements are of the format @var{(FORM . FACE)}. If you
+would, for instance, like ticked articles to be italic and high-scored
+articles to be bold, you could set this variable to something like
+@lisp
+(((eq mark gnus-ticked-mark) . italic)
+ ((> score default) . bold))
+@end lisp
+As you may have guessed, if @var{FORM} returns a non-@code{nil} value,
+@var{FACE} will be applied to the line.
+@end table
+
+
+@node Summary Maneuvering
+@section Summary Maneuvering
+@cindex summary movement
+
+All the straight movement commands understand the numeric prefix and
+behave pretty much as you'd expect.
+
+None of these commands select articles.
+
+@table @kbd
+@item G M-n
+@itemx M-n
+@kindex M-n (Summary)
+@kindex G M-n (Summary)
+@findex gnus-summary-next-unread-subject
+Go to the next summary line of an unread article
+(@code{gnus-summary-next-unread-subject}).
+
+@item G M-p
+@itemx M-p
+@kindex M-p (Summary)
+@kindex G M-p (Summary)
+@findex gnus-summary-prev-unread-subject
+Go to the previous summary line of an unread article
+(@code{gnus-summary-prev-unread-subject}).
+
+@item G j
+@itemx j
+@kindex j (Summary)
+@kindex G j (Summary)
+@findex gnus-summary-goto-article
+Ask for an article number or @code{Message-ID}, and then go to that
+article (@code{gnus-summary-goto-article}).
+
+@item G g
+@kindex G g (Summary)
+@findex gnus-summary-goto-subject
+Ask for an article number and then go to the summary line of that article
+without displaying the article (@code{gnus-summary-goto-subject}).
+@end table
+
+If Gnus asks you to press a key to confirm going to the next group, you
+can use the @kbd{C-n} and @kbd{C-p} keys to move around the group
+buffer, searching for the next group to read without actually returning
+to the group buffer.
+
+Variables related to summary movement:
+
+@table @code
+
+@vindex gnus-auto-select-next
+@item gnus-auto-select-next
+If you issue one of the movement commands (like @kbd{n}) and there are
+no more unread articles after the current one, Gnus will offer to go to
+the next group. If this variable is @code{t} and the next group is
+empty, Gnus will exit summary mode and return to the group buffer. If
+this variable is neither @code{t} nor @code{nil}, Gnus will select the
+next group, no matter whether it has any unread articles or not. As a
+special case, if this variable is @code{quietly}, Gnus will select the
+next group without asking for confirmation. If this variable is
+@code{almost-quietly}, the same will happen only if you are located on
+the last article in the group. Finally, if this variable is
+@code{slightly-quietly}, the @kbd{Z n} command will go to the next group
+without confirmation. Also @pxref{Group Levels}.
+
+@item gnus-auto-select-same
+@vindex gnus-auto-select-same
+If non-@code{nil}, all the movement commands will try to go to the next
+article with the same subject as the current. (@dfn{Same} here might
+mean @dfn{roughly equal}. See @code{gnus-summary-gather-subject-limit}
+for details (@pxref{Customizing Threading}).) If there are no more
+articles with the same subject, go to the first unread article.
+
+This variable is not particularly useful if you use a threaded display.
+
+@item gnus-summary-check-current
+@vindex gnus-summary-check-current
+If non-@code{nil}, all the ``unread'' movement commands will not proceed
+to the next (or previous) article if the current article is unread.
+Instead, they will choose the current article.
+
+@item gnus-auto-center-summary
+@vindex gnus-auto-center-summary
+If non-@code{nil}, Gnus will keep the point in the summary buffer
+centered at all times. This makes things quite tidy, but if you have a
+slow network connection, or simply do not like this un-Emacsism, you can
+set this variable to @code{nil} to get the normal Emacs scrolling
+action. This will also inhibit horizontal re-centering of the summary
+buffer, which might make it more inconvenient to read extremely long
+threads.
+
+@end table
+
+
+@node Choosing Articles
+@section Choosing Articles
+@cindex selecting articles
+
+@menu
+* Choosing Commands:: Commands for choosing articles.
+* Choosing Variables:: Variables that influence these commands.
+@end menu
+
+
+@node Choosing Commands
+@subsection Choosing Commands
+
+None of the following movement commands understand the numeric prefix,
+and they all select and display an article.
+
+@table @kbd
+@item SPACE
+@kindex SPACE (Summary)
+@findex gnus-summary-next-page
+Select the current article, or, if that one's read already, the next
+unread article (@code{gnus-summary-next-page}).
+
+@item G n
+@itemx n
+@kindex n (Summary)
+@kindex G n (Summary)
+@findex gnus-summary-next-unread-article
+@c @icon{gnus-summary-next-unread}
+Go to next unread article (@code{gnus-summary-next-unread-article}).
+
+@item G p
+@itemx p
+@kindex p (Summary)
+@findex gnus-summary-prev-unread-article
+@c @icon{gnus-summary-prev-unread}
+Go to previous unread article (@code{gnus-summary-prev-unread-article}).
+
+@item G N
+@itemx N
+@kindex N (Summary)
+@kindex G N (Summary)
+@findex gnus-summary-next-article
+Go to the next article (@code{gnus-summary-next-article}).
+
+@item G P
+@itemx P
+@kindex P (Summary)
+@kindex G P (Summary)
+@findex gnus-summary-prev-article
+Go to the previous article (@code{gnus-summary-prev-article}).
+
+@item G C-n
+@kindex G C-n (Summary)
+@findex gnus-summary-next-same-subject
+Go to the next article with the same subject
+(@code{gnus-summary-next-same-subject}).
+
+@item G C-p
+@kindex G C-p (Summary)
+@findex gnus-summary-prev-same-subject
+Go to the previous article with the same subject
+(@code{gnus-summary-prev-same-subject}).
+
+@item G f
+@itemx .
+@kindex G f (Summary)
+@kindex . (Summary)
+@findex gnus-summary-first-unread-article
+Go to the first unread article
+(@code{gnus-summary-first-unread-article}).
+
+@item G b
+@itemx ,
+@kindex G b (Summary)
+@kindex , (Summary)
+@findex gnus-summary-best-unread-article
+Go to the article with the highest score
+(@code{gnus-summary-best-unread-article}).
+
+@item G l
+@itemx l
+@kindex l (Summary)
+@kindex G l (Summary)
+@findex gnus-summary-goto-last-article
+Go to the previous article read (@code{gnus-summary-goto-last-article}).
+
+@item G o
+@kindex G o (Summary)
+@findex gnus-summary-pop-article
+@cindex history
+@cindex article history
+Pop an article off the summary history and go to this article
+(@code{gnus-summary-pop-article}). This command differs from the
+command above in that you can pop as many previous articles off the
+history as you like, while @kbd{l} toggles the two last read articles.
+For a somewhat related issue (if you use these commands a lot),
+@pxref{Article Backlog}.
+@end table
+
+
+@node Choosing Variables
+@subsection Choosing Variables
+
+Some variables relevant for moving and selecting articles:
+
+@table @code
+@item gnus-auto-extend-newsgroup
+@vindex gnus-auto-extend-newsgroup
+All the movement commands will try to go to the previous (or next)
+article, even if that article isn't displayed in the Summary buffer if
+this variable is non-@code{nil}. Gnus will then fetch the article from
+the server and display it in the article buffer.
+
+@item gnus-select-article-hook
+@vindex gnus-select-article-hook
+This hook is called whenever an article is selected. By default it
+exposes any threads hidden under the selected article.
+
+@item gnus-mark-article-hook
+@vindex gnus-mark-article-hook
+@findex gnus-summary-mark-unread-as-read
+@findex gnus-summary-mark-read-and-unread-as-read
+@findex gnus-unread-mark
+This hook is called whenever an article is selected. It is intended to
+be used for marking articles as read. The default value is
+@code{gnus-summary-mark-read-and-unread-as-read}, and will change the
+mark of almost any article you read to @code{gnus-unread-mark}. The
+only articles not affected by this function are ticked, dormant, and
+expirable articles. If you'd instead like to just have unread articles
+marked as read, you can use @code{gnus-summary-mark-unread-as-read}
+instead. It will leave marks like @code{gnus-low-score-mark},
+@code{gnus-del-mark} (and so on) alone.
+
+@end table
+
+
+@node Paging the Article
+@section Scrolling the Article
+@cindex article scrolling
+
+@table @kbd
+
+@item SPACE
+@kindex SPACE (Summary)
+@findex gnus-summary-next-page
+Pressing @kbd{SPACE} will scroll the current article forward one page,
+or, if you have come to the end of the current article, will choose the
+next article (@code{gnus-summary-next-page}).
+
+@item DEL
+@kindex DEL (Summary)
+@findex gnus-summary-prev-page
+Scroll the current article back one page (@code{gnus-summary-prev-page}).
+
+@item RET
+@kindex RET (Summary)
+@findex gnus-summary-scroll-up
+Scroll the current article one line forward
+(@code{gnus-summary-scroll-up}).
+
+@item M-RET
+@kindex M-RET (Summary)
+@findex gnus-summary-scroll-down
+Scroll the current article one line backward
+(@code{gnus-summary-scroll-down}).
+
+@item A g
+@itemx g
+@kindex A g (Summary)
+@kindex g (Summary)
+@findex gnus-summary-show-article
+(Re)fetch the current article (@code{gnus-summary-show-article}). If
+given a prefix, fetch the current article, but don't run any of the
+article treatment functions. This will give you a ``raw'' article, just
+the way it came from the server.
+
+@item A <
+@itemx <
+@kindex < (Summary)
+@kindex A < (Summary)
+@findex gnus-summary-beginning-of-article
+Scroll to the beginning of the article
+(@code{gnus-summary-beginning-of-article}).
+
+@item A >
+@itemx >
+@kindex > (Summary)
+@kindex A > (Summary)
+@findex gnus-summary-end-of-article
+Scroll to the end of the article (@code{gnus-summary-end-of-article}).
+
+@item A s
+@itemx s
+@kindex A s (Summary)
+@kindex s (Summary)
+@findex gnus-summary-isearch-article
+Perform an isearch in the article buffer
+(@code{gnus-summary-isearch-article}).
+
+@item h
+@kindex h (Summary)
+@findex gnus-summary-select-article-buffer
+Select the article buffer (@code{gnus-summary-select-article-buffer}).
+
+@end table
+
+
+@node Reply Followup and Post
+@section Reply, Followup and Post
+
+@menu
+* Summary Mail Commands:: Sending mail.
+* Summary Post Commands:: Sending news.
+@end menu
+
+
+@node Summary Mail Commands
+@subsection Summary Mail Commands
+@cindex mail
+@cindex composing mail
+
+Commands for composing a mail message:
+
+@table @kbd
+
+@item S r
+@itemx r
+@kindex S r (Summary)
+@kindex r (Summary)
+@findex gnus-summary-reply
+@c @icon{gnus-summary-mail-reply}
+@c @icon{gnus-summary-reply}
+Mail a reply to the author of the current article
+(@code{gnus-summary-reply}).
+
+@item S R
+@itemx R
+@kindex R (Summary)
+@kindex S R (Summary)
+@findex gnus-summary-reply-with-original
+@c @icon{gnus-summary-reply-with-original}
+Mail a reply to the author of the current article and include the
+original message (@code{gnus-summary-reply-with-original}). This
+command uses the process/prefix convention.
+
+@item S w
+@kindex S w (Summary)
+@findex gnus-summary-wide-reply
+Mail a wide reply to the author of the current article
+(@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that
+goes out to all people listed in the @code{To}, @code{From} (or
+@code{Reply-to}) and @code{Cc} headers.
+
+@item S W
+@kindex S W (Summary)
+@findex gnus-summary-wide-reply-with-original
+Mail a wide reply to the current article and include the original
+message (@code{gnus-summary-reply-with-original}). This command uses
+the process/prefix convention.
+
+@item S o m
+@kindex S o m (Summary)
+@findex gnus-summary-mail-forward
+@c @icon{gnus-summary-mail-forward}
+Forward the current article to some other person
+(@code{gnus-summary-mail-forward}). If given a prefix, include the full
+headers of the forwarded article.
+
+@item S m
+@itemx m
+@kindex m (Summary)
+@kindex S m (Summary)
+@findex gnus-summary-mail-other-window
+@c @icon{gnus-summary-mail-originate}
+Send a mail to some other person
+(@code{gnus-summary-mail-other-window}).
+
+@item S D b
+@kindex S D b (Summary)
+@findex gnus-summary-resend-bounced-mail
+@cindex bouncing mail
+If you have sent a mail, but the mail was bounced back to you for some
+reason (wrong address, transient failure), you can use this command to
+resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You
+will be popped into a mail buffer where you can edit the headers before
+sending the mail off again. If you give a prefix to this command, and
+the bounced mail is a reply to some other mail, Gnus will try to fetch
+that mail and display it for easy perusal of its headers. This might
+very well fail, though.
+
+@item S D r
+@kindex S D r (Summary)
+@findex gnus-summary-resend-message
+Not to be confused with the previous command,
+@code{gnus-summary-resend-message} will prompt you for an address to
+send the current message off to, and then send it to that place. The
+headers of the message won't be altered---but lots of headers that say
+@code{Resent-To}, @code{Resent-From} and so on will be added. This
+means that you actually send a mail to someone that has a @code{To}
+header that (probably) points to yourself. This will confuse people.
+So, natcherly you'll only do that if you're really eVIl.
+
+This command is mainly used if you have several accounts and want to
+ship a mail to a different account of yours. (If you're both
+@code{root} and @code{postmaster} and get a mail for @code{postmaster}
+to the @code{root} account, you may want to resend it to
+@code{postmaster}. Ordnung muß sein!
+
+This command understands the process/prefix convention
+(@pxref{Process/Prefix}).
+
+@item S O m
+@kindex S O m (Summary)
+@findex gnus-uu-digest-mail-forward
+Digest the current series (@pxref{Decoding Articles}) and forward the
+result using mail (@code{gnus-uu-digest-mail-forward}). This command
+uses the process/prefix convention (@pxref{Process/Prefix}).
+
+@item S M-c
+@kindex S M-c (Summary)
+@findex gnus-summary-mail-crosspost-complaint
+@cindex crossposting
+@cindex excessive crossposting
+Send a complaint about excessive crossposting to the author of the
+current article (@code{gnus-summary-mail-crosspost-complaint}).
+
+@findex gnus-crosspost-complaint
+This command is provided as a way to fight back against the current
+crossposting pandemic that's sweeping Usenet. It will compose a reply
+using the @code{gnus-crosspost-complaint} variable as a preamble. This
+command understands the process/prefix convention
+(@pxref{Process/Prefix}) and will prompt you before sending each mail.
+
+@end table
+
+Also @pxref{(message)Header Commands} for more information.
+
+
+@node Summary Post Commands
+@subsection Summary Post Commands
+@cindex post
+@cindex composing news
+
+Commands for posting a news article:
+
+@table @kbd
+@item S p
+@itemx a
+@kindex a (Summary)
+@kindex S p (Summary)
+@findex gnus-summary-post-news
+@c @icon{gnus-summary-post-news}
+Post an article to the current group
+(@code{gnus-summary-post-news}).
+
+@item S f
+@itemx f
+@kindex f (Summary)
+@kindex S f (Summary)
+@findex gnus-summary-followup
+@c @icon{gnus-summary-followup}
+Post a followup to the current article (@code{gnus-summary-followup}).
+
+@item S F
+@itemx F
+@kindex S F (Summary)
+@kindex F (Summary)
+@c @icon{gnus-summary-followup-with-original}
+@findex gnus-summary-followup-with-original
+Post a followup to the current article and include the original message
+(@code{gnus-summary-followup-with-original}). This command uses the
+process/prefix convention.
+
+@item S n
+@kindex S n (Summary)
+@findex gnus-summary-followup-to-mail
+Post a followup to the current article via news, even if you got the
+message through mail (@code{gnus-summary-followup-to-mail}).
+
+@item S N
+@kindex S N (Summary)
+@findex gnus-summary-followup-to-mail-with-original
+Post a followup to the current article via news, even if you got the
+message through mail and include the original message
+(@code{gnus-summary-followup-to-mail-with-original}). This command uses
+the process/prefix convention.
+
+@item S o p
+@kindex S o p (Summary)
+@findex gnus-summary-post-forward
+Forward the current article to a newsgroup
+(@code{gnus-summary-post-forward}). If given a prefix, include the full
+headers of the forwarded article.
+
+@item S O p
+@kindex S O p (Summary)
+@findex gnus-uu-digest-post-forward
+@cindex digests
+@cindex making digests
+Digest the current series and forward the result to a newsgroup
+(@code{gnus-uu-digest-mail-forward}). This command uses the
+process/prefix convention.
+
+@item S u
+@kindex S u (Summary)
+@findex gnus-uu-post-news
+@c @icon{gnus-uu-post-news}
+Uuencode a file, split it into parts, and post it as a series
+(@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}).
+@end table
+
+Also @pxref{(message)Header Commands} for more information.
+
+
+@node Canceling and Superseding
+@section Canceling Articles
+@cindex canceling articles
+@cindex superseding articles
+
+Have you ever written something, and then decided that you really,
+really, really wish you hadn't posted that?
+
+Well, you can't cancel mail, but you can cancel posts.
+
+@findex gnus-summary-cancel-article
+@kindex C (Summary)
+@c @icon{gnus-summary-cancel-article}
+Find the article you wish to cancel (you can only cancel your own
+articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S
+c} (@code{gnus-summary-cancel-article}). Your article will be
+canceled---machines all over the world will be deleting your article.
+This command uses the process/prefix convention (@pxref{Process/Prefix}).
+
+Be aware, however, that not all sites honor cancels, so your article may
+live on here and there, while most sites will delete the article in
+question.
+
+Gnus will use the ``current'' select method when canceling. If you
+want to use the standard posting method, use the @samp{a} symbolic
+prefix (@pxref{Symbolic Prefixes}).
+
+If you discover that you have made some mistakes and want to do some
+corrections, you can post a @dfn{superseding} article that will replace
+your original article.
+
+@findex gnus-summary-supersede-article
+@kindex S (Summary)
+Go to the original article and press @kbd{S s}
+(@code{gnus-summary-supersede-article}). You will be put in a buffer
+where you can edit the article all you want before sending it off the
+usual way.
+
+The same goes for superseding as for canceling, only more so: Some
+sites do not honor superseding. On those sites, it will appear that you
+have posted almost the same article twice.
+
+If you have just posted the article, and change your mind right away,
+there is a trick you can use to cancel/supersede the article without
+waiting for the article to appear on your site first. You simply return
+to the post buffer (which is called @code{*sent ...*}). There you will
+find the article you just posted, with all the headers intact. Change
+the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes}
+header by substituting one of those words for the word
+@code{Message-ID}. Then just press @kbd{C-c C-c} to send the article as
+you would do normally. The previous article will be
+canceled/superseded.
+
+Just remember, kids: There is no 'c' in 'supersede'.
+
+
+@node Marking Articles
+@section Marking Articles
+@cindex article marking
+@cindex article ticking
+@cindex marks
+
+There are several marks you can set on an article.
+
+You have marks that decide the @dfn{readedness} (whoo, neato-keano
+neologism ohoy!) of the article. Alphabetic marks generally mean
+@dfn{read}, while non-alphabetic characters generally mean @dfn{unread}.
+
+In addition, you also have marks that do not affect readedness.
+
+@menu
+* Unread Articles:: Marks for unread articles.
+* Read Articles:: Marks for read articles.
+* Other Marks:: Marks that do not affect readedness.
+@end menu
+
+@ifinfo
+There's a plethora of commands for manipulating these marks:
+@end ifinfo
+
+@menu
+* Setting Marks:: How to set and remove marks.
+* Setting Process Marks:: How to mark articles for later processing.
+@end menu
+
+
+@node Unread Articles
+@subsection Unread Articles
+
+The following marks mark articles as (kinda) unread, in one form or
+other.
+
+@table @samp
+@item !
+@vindex gnus-ticked-mark
+Marked as ticked (@code{gnus-ticked-mark}).
+
+@dfn{Ticked articles} are articles that will remain visible always. If
+you see an article that you find interesting, or you want to put off
+reading it, or replying to it, until sometime later, you'd typically
+tick it. However, articles can be expired, so if you want to keep an
+article forever, you'll have to make it persistent (@pxref{Persistent
+Articles}).
+
+@item ?
+@vindex gnus-dormant-mark
+Marked as dormant (@code{gnus-dormant-mark}).
+
+@dfn{Dormant articles} will only appear in the summary buffer if there
+are followups to it. If you want to see them even if they don't have
+followups, you can use the @kbd{/ D} command (@pxref{Limiting}).
+
+@item SPACE
+@vindex gnus-unread-mark
+Marked as unread (@code{gnus-unread-mark}).
+
+@dfn{Unread articles} are articles that haven't been read at all yet.
+@end table
+
+
+@node Read Articles
+@subsection Read Articles
+@cindex expirable mark
+
+All the following marks mark articles as read.
+
+@table @samp
+
+@item r
+@vindex gnus-del-mark
+These are articles that the user has marked as read with the @kbd{d}
+command manually, more or less (@code{gnus-del-mark}).
+
+@item R
+@vindex gnus-read-mark
+Articles that have actually been read (@code{gnus-read-mark}).
+
+@item O
+@vindex gnus-ancient-mark
+Articles that were marked as read in previous sessions and are now
+@dfn{old} (@code{gnus-ancient-mark}).
+
+@item K
+@vindex gnus-killed-mark
+Marked as killed (@code{gnus-killed-mark}).
+
+@item X
+@vindex gnus-kill-file-mark
+Marked as killed by kill files (@code{gnus-kill-file-mark}).
+
+@item Y
+@vindex gnus-low-score-mark
+Marked as read by having too low a score (@code{gnus-low-score-mark}).
+
+@item C
+@vindex gnus-catchup-mark
+Marked as read by a catchup (@code{gnus-catchup-mark}).
+
+@item G
+@vindex gnus-canceled-mark
+Canceled article (@code{gnus-canceled-mark})
+
+@item F
+@vindex gnus-souped-mark
+@sc{SOUP}ed article (@code{gnus-souped-mark}). @xref{SOUP}.
+
+@item Q
+@vindex gnus-sparse-mark
+Sparsely reffed article (@code{gnus-sparse-mark}). @xref{Customizing
+Threading}.
+
+@item M
+@vindex gnus-duplicate-mark
+Article marked as read by duplicate suppression
+(@code{gnus-duplicated-mark}). @xref{Duplicate Suppression}.
+
+@end table
+
+All these marks just mean that the article is marked as read, really.
+They are interpreted differently when doing adaptive scoring, though.
+
+One more special mark, though:
+
+@table @samp
+@item E
+@vindex gnus-expirable-mark
+Marked as expirable (@code{gnus-expirable-mark}).
+
+Marking articles as @dfn{expirable} (or have them marked as such
+automatically) doesn't make much sense in normal groups---a user doesn't
+control expiring of news articles, but in mail groups, for instance,
+articles marked as @dfn{expirable} can be deleted by Gnus at
+any time.
+@end table
+
+
+@node Other Marks
+@subsection Other Marks
+@cindex process mark
+@cindex bookmarks
+
+There are some marks that have nothing to do with whether the article is
+read or not.
+
+@itemize @bullet
+
+@item
+You can set a bookmark in the current article. Say you are reading a
+long thesis on cats' urinary tracts, and have to go home for dinner
+before you've finished reading the thesis. You can then set a bookmark
+in the article, and Gnus will jump to this bookmark the next time it
+encounters the article. @xref{Setting Marks}.
+
+@item
+@vindex gnus-replied-mark
+All articles that you have replied to or made a followup to (i.e., have
+answered) will be marked with an @samp{A} in the second column
+(@code{gnus-replied-mark}).
+
+@item
+@vindex gnus-cached-mark
+Articles stored in the article cache will be marked with an @samp{*} in
+the second column (@code{gnus-cached-mark}). @xref{Article Caching}.
+
+@item
+@vindex gnus-saved-mark
+Articles ``saved'' (in some manner or other; not necessarily
+religiously) are marked with an @samp{S} in the second column
+(@code{gnus-saved-mark}).
+
+@item
+@vindex gnus-not-empty-thread-mark
+@vindex gnus-empty-thread-mark
+If the @samp{%e} spec is used, the presence of threads or not will be
+marked with @code{gnus-not-empty-thread-mark} and
+@code{gnus-empty-thread-mark} in the third column, respectively.
+
+@item
+@vindex gnus-process-mark
+Finally we have the @dfn{process mark} (@code{gnus-process-mark}). A
+variety of commands react to the presence of the process mark. For
+instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view
+all articles that have been marked with the process mark. Articles
+marked with the process mark have a @samp{#} in the second column.
+
+@end itemize
+
+You might have noticed that most of these ``non-readedness'' marks
+appear in the second column by default. So if you have a cached, saved,
+replied article that you have process-marked, what will that look like?
+
+Nothing much. The precedence rules go as follows: process -> cache ->
+replied -> saved. So if the article is in the cache and is replied,
+you'll only see the cache mark and not the replied mark.
+
+
+@node Setting Marks
+@subsection Setting Marks
+@cindex setting marks
+
+All the marking commands understand the numeric prefix.
+
+@table @kbd
+@item M c
+@itemx M-u
+@kindex M c (Summary)
+@kindex M-u (Summary)
+@findex gnus-summary-clear-mark-forward
+@cindex mark as unread
+Clear all readedness-marks from the current article
+(@code{gnus-summary-clear-mark-forward}). In other words, mark the
+article as unread.
+
+@item M t
+@itemx !
+@kindex ! (Summary)
+@kindex M t (Summary)
+@findex gnus-summary-tick-article-forward
+Tick the current article (@code{gnus-summary-tick-article-forward}).
+@xref{Article Caching}.
+
+@item M ?
+@itemx ?
+@kindex ? (Summary)
+@kindex M ? (Summary)
+@findex gnus-summary-mark-as-dormant
+Mark the current article as dormant
+(@code{gnus-summary-mark-as-dormant}). @xref{Article Caching}.
+
+@item M d
+@itemx d
+@kindex M d (Summary)
+@kindex d (Summary)
+@findex gnus-summary-mark-as-read-forward
+Mark the current article as read
+(@code{gnus-summary-mark-as-read-forward}).
+
+@item D
+@kindex D (Summary)
+@findex gnus-summary-mark-as-read-backward
+Mark the current article as read and move point to the previous line
+(@code{gnus-summary-mark-as-read-backward}).
+
+@item M k
+@itemx k
+@kindex k (Summary)
+@kindex M k (Summary)
+@findex gnus-summary-kill-same-subject-and-select
+Mark all articles that have the same subject as the current one as read,
+and then select the next unread article
+(@code{gnus-summary-kill-same-subject-and-select}).
+
+@item M K
+@itemx C-k
+@kindex M K (Summary)
+@kindex C-k (Summary)
+@findex gnus-summary-kill-same-subject
+Mark all articles that have the same subject as the current one as read
+(@code{gnus-summary-kill-same-subject}).
+
+@item M C
+@kindex M C (Summary)
+@findex gnus-summary-catchup
+@c @icon{gnus-summary-catchup}
+Mark all unread articles as read (@code{gnus-summary-catchup}).
+
+@item M C-c
+@kindex M C-c (Summary)
+@findex gnus-summary-catchup-all
+Mark all articles in the group as read---even the ticked and dormant
+articles (@code{gnus-summary-catchup-all}).
+
+@item M H
+@kindex M H (Summary)
+@findex gnus-summary-catchup-to-here
+Catchup the current group to point
+(@code{gnus-summary-catchup-to-here}).
+
+@item C-w
+@kindex C-w (Summary)
+@findex gnus-summary-mark-region-as-read
+Mark all articles between point and mark as read
+(@code{gnus-summary-mark-region-as-read}).
+
+@item M V k
+@kindex M V k (Summary)
+@findex gnus-summary-kill-below
+Kill all articles with scores below the default score (or below the
+numeric prefix) (@code{gnus-summary-kill-below}).
+
+@item M e
+@itemx E
+@kindex M e (Summary)
+@kindex E (Summary)
+@findex gnus-summary-mark-as-expirable
+Mark the current article as expirable
+(@code{gnus-summary-mark-as-expirable}).
+
+@item M b
+@kindex M b (Summary)
+@findex gnus-summary-set-bookmark
+Set a bookmark in the current article
+(@code{gnus-summary-set-bookmark}).
+
+@item M B
+@kindex M B (Summary)
+@findex gnus-summary-remove-bookmark
+Remove the bookmark from the current article
+(@code{gnus-summary-remove-bookmark}).
+
+@item M V c
+@kindex M V c (Summary)
+@findex gnus-summary-clear-above
+Clear all marks from articles with scores over the default score (or
+over the numeric prefix) (@code{gnus-summary-clear-above}).
+
+@item M V u
+@kindex M V u (Summary)
+@findex gnus-summary-tick-above
+Tick all articles with scores over the default score (or over the
+numeric prefix) (@code{gnus-summary-tick-above}).
+
+@item M V m
+@kindex M V m (Summary)
+@findex gnus-summary-mark-above
+Prompt for a mark, and mark all articles with scores over the default
+score (or over the numeric prefix) with this mark
+(@code{gnus-summary-clear-above}).
+@end table
+
+@vindex gnus-summary-goto-unread
+The @code{gnus-summary-goto-unread} variable controls what action should
+be taken after setting a mark. If non-@code{nil}, point will move to
+the next/previous unread article. If @code{nil}, point will just move
+one line up or down. As a special case, if this variable is
+@code{never}, all the marking commands as well as other commands (like
+@kbd{SPACE}) will move to the next article, whether it is unread or not.
+The default is @code{t}.
+
+
+@node Setting Process Marks
+@subsection Setting Process Marks
+@cindex setting process marks
+
+@table @kbd
+
+@item M P p
+@itemx #
+@kindex # (Summary)
+@kindex M P p (Summary)
+@findex gnus-summary-mark-as-processable
+Mark the current article with the process mark
+(@code{gnus-summary-mark-as-processable}).
+@findex gnus-summary-unmark-as-processable
+
+@item M P u
+@itemx M-#
+@kindex M P u (Summary)
+@kindex M-# (Summary)
+Remove the process mark, if any, from the current article
+(@code{gnus-summary-unmark-as-processable}).
+
+@item M P U
+@kindex M P U (Summary)
+@findex gnus-summary-unmark-all-processable
+Remove the process mark from all articles
+(@code{gnus-summary-unmark-all-processable}).
+
+@item M P i
+@kindex M P i (Summary)
+@findex gnus-uu-invert-processable
+Invert the list of process marked articles
+(@code{gnus-uu-invert-processable}).
+
+@item M P R
+@kindex M P R (Summary)
+@findex gnus-uu-mark-by-regexp
+Mark articles that have a @code{Subject} header that matches a regular
+expression (@code{gnus-uu-mark-by-regexp}).
+
+@item M P r
+@kindex M P r (Summary)
+@findex gnus-uu-mark-region
+Mark articles in region (@code{gnus-uu-mark-region}).
+
+@item M P t
+@kindex M P t (Summary)
+@findex gnus-uu-mark-thread
+Mark all articles in the current (sub)thread
+(@code{gnus-uu-mark-thread}).
+
+@item M P T
+@kindex M P T (Summary)
+@findex gnus-uu-unmark-thread
+Unmark all articles in the current (sub)thread
+(@code{gnus-uu-unmark-thread}).
+
+@item M P v
+@kindex M P v (Summary)
+@findex gnus-uu-mark-over
+Mark all articles that have a score above the prefix argument
+(@code{gnus-uu-mark-over}).
+
+@item M P s
+@kindex M P s (Summary)
+@findex gnus-uu-mark-series
+Mark all articles in the current series (@code{gnus-uu-mark-series}).
+
+@item M P S
+@kindex M P S (Summary)
+@findex gnus-uu-mark-sparse
+Mark all series that have already had some articles marked
+(@code{gnus-uu-mark-sparse}).
+
+@item M P a
+@kindex M P a (Summary)
+@findex gnus-uu-mark-all
+Mark all articles in series order (@code{gnus-uu-mark-series}).
+
+@item M P b
+@kindex M P b (Summary)
+@findex gnus-uu-mark-buffer
+Mark all articles in the buffer in the order they appear
+(@code{gnus-uu-mark-buffer}).
+
+@item M P k
+@kindex M P k (Summary)
+@findex gnus-summary-kill-process-mark
+Push the current process mark set onto the stack and unmark all articles
+(@code{gnus-summary-kill-process-mark}).
+
+@item M P y
+@kindex M P y (Summary)
+@findex gnus-summary-yank-process-mark
+Pop the previous process mark set from the stack and restore it
+(@code{gnus-summary-yank-process-mark}).
+
+@item M P w
+@kindex M P w (Summary)
+@findex gnus-summary-save-process-mark
+Push the current process mark set onto the stack
+(@code{gnus-summary-save-process-mark}).
+
+@end table
+
+
+@node Limiting
+@section Limiting
+@cindex limiting
+
+It can be convenient to limit the summary buffer to just show some
+subset of the articles currently in the group. The effect most limit
+commands have is to remove a few (or many) articles from the summary
+buffer.
+
+All limiting commands work on subsets of the articles already fetched
+from the servers. None of these commands query the server for
+additional articles.
+
+@table @kbd
+
+@item / /
+@itemx / s
+@kindex / / (Summary)
+@findex gnus-summary-limit-to-subject
+Limit the summary buffer to articles that match some subject
+(@code{gnus-summary-limit-to-subject}).
+
+@item / a
+@kindex / a (Summary)
+@findex gnus-summary-limit-to-author
+Limit the summary buffer to articles that match some author
+(@code{gnus-summary-limit-to-author}).
+
+@item / u
+@itemx x
+@kindex / u (Summary)
+@kindex x (Summary)
+@findex gnus-summary-limit-to-unread
+Limit the summary buffer to articles not marked as read
+(@code{gnus-summary-limit-to-unread}). If given a prefix, limit the
+buffer to articles strictly unread. This means that ticked and
+dormant articles will also be excluded.
+
+@item / m
+@kindex / m (Summary)
+@findex gnus-summary-limit-to-marks
+Ask for a mark and then limit to all articles that have been marked
+with that mark (@code{gnus-summary-limit-to-marks}).
+
+@item / t
+@kindex / t (Summary)
+@findex gnus-summary-limit-to-age
+Ask for a number and then limit the summary buffer to articles older than (or equal to) that number of days
+(@code{gnus-summary-limit-to-marks}). If given a prefix, limit to
+articles younger than that number of days.
+
+@item / n
+@kindex / n (Summary)
+@findex gnus-summary-limit-to-articles
+Limit the summary buffer to the current article
+(@code{gnus-summary-limit-to-articles}). Uses the process/prefix
+convention (@pxref{Process/Prefix}).
+
+@item / w
+@kindex / w (Summary)
+@findex gnus-summary-pop-limit
+Pop the previous limit off the stack and restore it
+(@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off
+the stack.
+
+@item / v
+@kindex / v (Summary)
+@findex gnus-summary-limit-to-score
+Limit the summary buffer to articles that have a score at or above some
+score (@code{gnus-summary-limit-to-score}).
+
+@item / E
+@itemx M S
+@kindex M S (Summary)
+@kindex / E (Summary)
+@findex gnus-summary-limit-include-expunged
+Include all expunged articles in the limit
+(@code{gnus-summary-limit-include-expunged}).
+
+@item / D
+@kindex / D (Summary)
+@findex gnus-summary-limit-include-dormant
+Include all dormant articles in the limit
+(@code{gnus-summary-limit-include-dormant}).
+
+@item / *
+@kindex / * (Summary)
+@findex gnus-summary-limit-include-cached
+Include all cached articles in the limit
+(@code{gnus-summary-limit-include-cached}).
+
+@item / d
+@kindex / d (Summary)
+@findex gnus-summary-limit-exclude-dormant
+Exclude all dormant articles from the limit
+(@code{gnus-summary-limit-exclude-dormant}).
+
+@item / T
+@kindex / T (Summary)
+@findex gnus-summary-limit-include-thread
+Include all the articles in the current thread in the limit.
+
+@item / c
+@kindex / c (Summary)
+@findex gnus-summary-limit-exclude-childless-dormant
+Exclude all dormant articles that have no children from the limit
+(@code{gnus-summary-limit-exclude-childless-dormant}).
+
+@item / C
+@kindex / C (Summary)
+@findex gnus-summary-limit-mark-excluded-as-read
+Mark all excluded unread articles as read
+(@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix,
+also mark excluded ticked and dormant articles as read.
+
+@end table
+
+
+@node Threading
+@section Threading
+@cindex threading
+@cindex article threading
+
+Gnus threads articles by default. @dfn{To thread} is to put responses
+to articles directly after the articles they respond to---in a
+hierarchical fashion.
+
+Threading is done by looking at the @code{References} headers of the
+articles. In a perfect world, this would be enough to build pretty
+trees, but unfortunately, the @code{References} header is often broken
+or simply missing. Weird news propagation excarcerbates the problem,
+so one has to employ other heuristics to get pleasing results. A
+plethora of approaches exists, as detailed in horrible detail in
+@pxref{Customizing Threading}.
+
+First, a quick overview of the concepts:
+
+@table @dfn
+@item root
+The top-most article in a thread; the first article in the thread.
+
+@item thread
+A tree-like article structure.
+
+@item sub-thread
+A small(er) section of this tree-like structure.
+
+@item loose threads
+Threads often lose their roots due to article expiry, or due to the root
+already having been read in a previous session, and not displayed in the
+summary buffer. We then typically have many sub-threads that really
+belong to one thread, but are without connecting roots. These are
+called loose threads.
+
+@item thread gathering
+An attempt to gather loose threads into bigger threads.
+
+@item sparse threads
+A thread where the missing articles have been ``guessed'' at, and are
+displayed as empty lines in the summary buffer.
+
+@end table
+
+
+@menu
+* Customizing Threading:: Variables you can change to affect the threading.
+* Thread Commands:: Thread based commands in the summary buffer.
+@end menu
+
+
+@node Customizing Threading
+@subsection Customizing Threading
+@cindex customizing threading
+
+@menu
+* Loose Threads:: How Gnus gathers loose threads into bigger threads.
+* Filling In Threads:: Making the threads displayed look fuller.
+* More Threading:: Even more variables for fiddling with threads.
+* Low-Level Threading:: You thought it was over... but you were wrong!
+@end menu
+
+
+@node Loose Threads
+@subsubsection Loose Threads
+@cindex <
+@cindex >
+@cindex loose threads
+
+@table @code
+@item gnus-summary-make-false-root
+@vindex gnus-summary-make-false-root
+If non-@code{nil}, Gnus will gather all loose subtrees into one big tree
+and create a dummy root at the top. (Wait a minute. Root at the top?
+Yup.) Loose subtrees occur when the real root has expired, or you've
+read or killed the root in a previous session.
+
+When there is no real root of a thread, Gnus will have to fudge
+something. This variable says what fudging method Gnus should use.
+There are four possible values:
+
+@cindex adopting articles
+
+@table @code
+
+@item adopt
+Gnus will make the first of the orphaned articles the parent. This
+parent will adopt all the other articles. The adopted articles will be
+marked as such by pointy brackets (@samp{<>}) instead of the standard
+square brackets (@samp{[]}). This is the default method.
+
+@item dummy
+@vindex gnus-summary-dummy-line-format
+Gnus will create a dummy summary line that will pretend to be the
+parent. This dummy line does not correspond to any real article, so
+selecting it will just select the first real article after the dummy
+article. @code{gnus-summary-dummy-line-format} is used to specify the
+format of the dummy roots. It accepts only one format spec: @samp{S},
+which is the subject of the article. @xref{Formatting Variables}.
+
+@item empty
+Gnus won't actually make any article the parent, but simply leave the
+subject field of all orphans except the first empty. (Actually, it will
+use @code{gnus-summary-same-subject} as the subject (@pxref{Summary
+Buffer Format}).)
+
+@item none
+Don't make any article parent at all. Just gather the threads and
+display them after one another.
+
+@item nil
+Don't gather loose threads.
+@end table
+
+@item gnus-summary-gather-subject-limit
+@vindex gnus-summary-gather-subject-limit
+Loose threads are gathered by comparing subjects of articles. If this
+variable is @code{nil}, Gnus requires an exact match between the
+subjects of the loose threads before gathering them into one big
+super-thread. This might be too strict a requirement, what with the
+presence of stupid newsreaders that chop off long subject lines. If
+you think so, set this variable to, say, 20 to require that only the
+first 20 characters of the subjects have to match. If you set this
+variable to a really low number, you'll find that Gnus will gather
+everything in sight into one thread, which isn't very helpful.
+
+@cindex fuzzy article gathering
+If you set this variable to the special value @code{fuzzy}, Gnus will
+use a fuzzy string comparison algorithm on the subjects (@pxref{Fuzzy
+Matching}).
+
+@item gnus-simplify-subject-fuzzy-regexp
+@vindex gnus-simplify-subject-fuzzy-regexp
+This can either be a regular expression or list of regular expressions
+that match strings that will be removed from subjects if fuzzy subject
+simplification is used.
+
+@item gnus-simplify-ignored-prefixes
+@vindex gnus-simplify-ignored-prefixes
+If you set @code{gnus-summary-gather-subject-limit} to something as low
+as 10, you might consider setting this variable to something sensible:
+
+@c Written by Michael Ernst <mernst@cs.rice.edu>
+@lisp
+(setq gnus-simplify-ignored-prefixes
+ (concat
+ "\\`\\[?\\("
+ (mapconcat
+ 'identity
+ '("looking"
+ "wanted" "followup" "summary\\( of\\)?"
+ "help" "query" "problem" "question"
+ "answer" "reference" "announce"
+ "How can I" "How to" "Comparison of"
+ ;; ...
+ )
+ "\\|")
+ "\\)\\s *\\("
+ (mapconcat 'identity
+ '("for" "for reference" "with" "about")
+ "\\|")
+ "\\)?\\]?:?[ \t]*"))
+@end lisp
+
+All words that match this regexp will be removed before comparing two
+subjects.
+
+@item gnus-simplify-subject-functions
+@vindex gnus-simplify-subject-functions
+If non-@code{nil}, this variable overrides
+@code{gnus-summary-gather-subject-limit}. This variable should be a
+list of functions to apply to the @code{Subject} string iteratively to
+arrive at the simplified version of the string.
+
+Useful functions to put in this list include:
+
+@table @code
+@item gnus-simplify-subject-re
+@findex gnus-simplify-subject-re
+Strip the leading @samp{Re:}.
+
+@item gnus-simplify-subject-fuzzy
+@findex gnus-simplify-subject-fuzzy
+Simplify fuzzily.
+
+@item gnus-simplify-whitespace
+@findex gnus-simplify-whitespace
+Remove excessive whitespace.
+@end table
+
+You may also write your own functions, of course.
+
+
+@item gnus-summary-gather-exclude-subject
+@vindex gnus-summary-gather-exclude-subject
+Since loose thread gathering is done on subjects only, that might lead
+to many false hits, especially with certain common subjects like
+@samp{} and @samp{(none)}. To make the situation slightly better,
+you can use the regexp @code{gnus-summary-gather-exclude-subject} to say
+what subjects should be excluded from the gathering process.@*
+The default is @samp{^ *$\\|^(none)$}.
+
+@item gnus-summary-thread-gathering-function
+@vindex gnus-summary-thread-gathering-function
+Gnus gathers threads by looking at @code{Subject} headers. This means
+that totally unrelated articles may end up in the same ``thread'', which
+is confusing. An alternate approach is to look at all the
+@code{Message-ID}s in all the @code{References} headers to find matches.
+This will ensure that no gathered threads ever include unrelated
+articles, but it also means that people who have posted with broken
+newsreaders won't be gathered properly. The choice is yours---plague or
+cholera:
+
+@table @code
+@item gnus-gather-threads-by-subject
+@findex gnus-gather-threads-by-subject
+This function is the default gathering function and looks at
+@code{Subject}s exclusively.
+
+@item gnus-gather-threads-by-references
+@findex gnus-gather-threads-by-references
+This function looks at @code{References} headers exclusively.
+@end table
+
+If you want to test gathering by @code{References}, you could say
+something like:
+
+@lisp
+(setq gnus-summary-thread-gathering-function
+ 'gnus-gather-threads-by-references)
+@end lisp
+
+@end table
+
+
+@node Filling In Threads
+@subsubsection Filling In Threads
+
+@table @code
+@item gnus-fetch-old-headers
+@vindex gnus-fetch-old-headers
+If non-@code{nil}, Gnus will attempt to build old threads by fetching
+more old headers---headers to articles marked as read. If you
+would like to display as few summary lines as possible, but still
+connect as many loose threads as possible, you should set this variable
+to @code{some} or a number. If you set it to a number, no more than
+that number of extra old headers will be fetched. In either case,
+fetching old headers only works if the backend you are using carries
+overview files---this would normally be @code{nntp}, @code{nnspool} and
+@code{nnml}. Also remember that if the root of the thread has been
+expired by the server, there's not much Gnus can do about that.
+
+This variable can also be set to @code{invisible}. This won't have any
+visible effects, but is useful if you use the @kbd{A T} command a lot
+(@pxref{Finding the Parent}).
+
+@item gnus-build-sparse-threads
+@vindex gnus-build-sparse-threads
+Fetching old headers can be slow. A low-rent similar effect can be
+gotten by setting this variable to @code{some}. Gnus will then look at
+the complete @code{References} headers of all articles and try to string
+together articles that belong in the same thread. This will leave
+@dfn{gaps} in the threading display where Gnus guesses that an article
+is missing from the thread. (These gaps appear like normal summary
+lines. If you select a gap, Gnus will try to fetch the article in
+question.) If this variable is @code{t}, Gnus will display all these
+``gaps'' without regard for whether they are useful for completing the
+thread or not. Finally, if this variable is @code{more}, Gnus won't cut
+off sparse leaf nodes that don't lead anywhere. This variable is
+@code{nil} by default.
+
+@end table
+
+
+@node More Threading
+@subsubsection More Threading
+
+@table @code
+@item gnus-show-threads
+@vindex gnus-show-threads
+If this variable is @code{nil}, no threading will be done, and all of
+the rest of the variables here will have no effect. Turning threading
+off will speed group selection up a bit, but it is sure to make reading
+slower and more awkward.
+
+@item gnus-thread-hide-subtree
+@vindex gnus-thread-hide-subtree
+If non-@code{nil}, all threads will be hidden when the summary buffer is
+generated.
+
+@item gnus-thread-expunge-below
+@vindex gnus-thread-expunge-below
+All threads that have a total score (as defined by
+@code{gnus-thread-score-function}) less than this number will be
+expunged. This variable is @code{nil} by default, which means that no
+threads are expunged.
+
+@item gnus-thread-hide-killed
+@vindex gnus-thread-hide-killed
+if you kill a thread and this variable is non-@code{nil}, the subtree
+will be hidden.
+
+@item gnus-thread-ignore-subject
+@vindex gnus-thread-ignore-subject
+Sometimes somebody changes the subject in the middle of a thread. If
+this variable is non-@code{nil}, the subject change is ignored. If it
+is @code{nil}, which is the default, a change in the subject will result
+in a new thread.
+
+@item gnus-thread-indent-level
+@vindex gnus-thread-indent-level
+This is a number that says how much each sub-thread should be indented.
+The default is 4.
+
+@end table
+
+
+@node Low-Level Threading
+@subsubsection Low-Level Threading
+
+@table @code
+
+@item gnus-parse-headers-hook
+@vindex gnus-parse-headers-hook
+Hook run before parsing any headers. The default value is
+@code{(gnus-decode-rfc1522)}, which means that QPized headers will be
+slightly decoded in a hackish way. This is likely to change in the
+future when Gnus becomes @sc{MIME}ified.
+
+@item gnus-alter-header-function
+@vindex gnus-alter-header-function
+If non-@code{nil}, this function will be called to allow alteration of
+article header structures. The function is called with one parameter,
+the article header vector, which it may alter in any way. For instance,
+if you have a mail-to-news gateway which alters the @code{Message-ID}s
+in systematic ways (by adding prefixes and such), you can use this
+variable to un-scramble the @code{Message-ID}s so that they are more
+meaningful. Here's one example:
+
+@lisp
+(setq gnus-alter-header-function 'my-alter-message-id)
+
+(defun my-alter-message-id (header)
+ (let ((id (mail-header-id header)))
+ (when (string-match
+ "\\(<[^<>@@]*\\)\\.?cygnus\\..*@@\\([^<>@@]*>\\)" id)
+ (mail-header-set-id
+ (concat (match-string 1 id) "@@" (match-string 2 id))
+ header))))
+@end lisp
+
+@end table
+
+
+@node Thread Commands
+@subsection Thread Commands
+@cindex thread commands
+
+@table @kbd
+
+@item T k
+@itemx M-C-k
+@kindex T k (Summary)
+@kindex M-C-k (Summary)
+@findex gnus-summary-kill-thread
+Mark all articles in the current (sub-)thread as read
+(@code{gnus-summary-kill-thread}). If the prefix argument is positive,
+remove all marks instead. If the prefix argument is negative, tick
+articles instead.
+
+@item T l
+@itemx M-C-l
+@kindex T l (Summary)
+@kindex M-C-l (Summary)
+@findex gnus-summary-lower-thread
+Lower the score of the current (sub-)thread
+(@code{gnus-summary-lower-thread}).
+
+@item T i
+@kindex T i (Summary)
+@findex gnus-summary-raise-thread
+Increase the score of the current (sub-)thread
+(@code{gnus-summary-raise-thread}).
+
+@item T #
+@kindex T # (Summary)
+@findex gnus-uu-mark-thread
+Set the process mark on the current (sub-)thread
+(@code{gnus-uu-mark-thread}).
+
+@item T M-#
+@kindex T M-# (Summary)
+@findex gnus-uu-unmark-thread
+Remove the process mark from the current (sub-)thread
+(@code{gnus-uu-unmark-thread}).
+
+@item T T
+@kindex T T (Summary)
+@findex gnus-summary-toggle-threads
+Toggle threading (@code{gnus-summary-toggle-threads}).
+
+@item T s
+@kindex T s (Summary)
+@findex gnus-summary-show-thread
+Expose the (sub-)thread hidden under the current article, if any
+(@code{gnus-summary-show-thread}).
+
+@item T h
+@kindex T h (Summary)
+@findex gnus-summary-hide-thread
+Hide the current (sub-)thread (@code{gnus-summary-hide-thread}).
+
+@item T S
+@kindex T S (Summary)
+@findex gnus-summary-show-all-threads
+Expose all hidden threads (@code{gnus-summary-show-all-threads}).
+
+@item T H
+@kindex T H (Summary)
+@findex gnus-summary-hide-all-threads
+Hide all threads (@code{gnus-summary-hide-all-threads}).
+
+@item T t
+@kindex T t (Summary)
+@findex gnus-summary-rethread-current
+Re-thread the current article's thread
+(@code{gnus-summary-rethread-current}). This works even when the
+summary buffer is otherwise unthreaded.
+
+@item T ^
+@kindex T ^ (Summary)
+@findex gnus-summary-reparent-thread
+Make the current article the child of the marked (or previous) article
+(@code{gnus-summary-reparent-thread}).
+
+@end table
+
+The following commands are thread movement commands. They all
+understand the numeric prefix.
+
+@table @kbd
+
+@item T n
+@kindex T n (Summary)
+@findex gnus-summary-next-thread
+Go to the next thread (@code{gnus-summary-next-thread}).
+
+@item T p
+@kindex T p (Summary)
+@findex gnus-summary-prev-thread
+Go to the previous thread (@code{gnus-summary-prev-thread}).
+
+@item T d
+@kindex T d (Summary)
+@findex gnus-summary-down-thread
+Descend the thread (@code{gnus-summary-down-thread}).
+
+@item T u
+@kindex T u (Summary)
+@findex gnus-summary-up-thread
+Ascend the thread (@code{gnus-summary-up-thread}).
+
+@item T o
+@kindex T o (Summary)
+@findex gnus-summary-top-thread
+Go to the top of the thread (@code{gnus-summary-top-thread}).
+@end table
+
+@vindex gnus-thread-operation-ignore-subject
+If you ignore subject while threading, you'll naturally end up with
+threads that have several different subjects in them. If you then issue
+a command like `T k' (@code{gnus-summary-kill-thread}) you might not
+wish to kill the entire thread, but just those parts of the thread that
+have the same subject as the current article. If you like this idea,
+you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it
+is non-@code{nil} (which it is by default), subjects will be ignored
+when doing thread commands. If this variable is @code{nil}, articles in
+the same thread with different subjects will not be included in the
+operation in question. If this variable is @code{fuzzy}, only articles
+that have subjects fuzzily equal will be included (@pxref{Fuzzy
+Matching}).
+
+
+@node Sorting
+@section Sorting
+
+@findex gnus-thread-sort-by-total-score
+@findex gnus-thread-sort-by-date
+@findex gnus-thread-sort-by-score
+@findex gnus-thread-sort-by-subject
+@findex gnus-thread-sort-by-author
+@findex gnus-thread-sort-by-number
+@vindex gnus-thread-sort-functions
+If you are using a threaded summary display, you can sort the threads by
+setting @code{gnus-thread-sort-functions}, which is a list of functions.
+By default, sorting is done on article numbers. Ready-made sorting
+predicate functions include @code{gnus-thread-sort-by-number},
+@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
+@code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
+@code{gnus-thread-sort-by-total-score}.
+
+Each function takes two threads and returns non-@code{nil} if the first
+thread should be sorted before the other. Note that sorting really is
+normally done by looking only at the roots of each thread. If you use
+more than one function, the primary sort key should be the last function
+in the list. You should probably always include
+@code{gnus-thread-sort-by-number} in the list of sorting
+functions---preferably first. This will ensure that threads that are
+equal with respect to the other sort criteria will be displayed in
+ascending article order.
+
+If you would like to sort by score, then by subject, and finally by
+number, you could do something like:
+
+@lisp
+(setq gnus-thread-sort-functions
+ '(gnus-thread-sort-by-number
+ gnus-thread-sort-by-subject
+ gnus-thread-sort-by-total-score))
+@end lisp
+
+The threads that have highest score will be displayed first in the
+summary buffer. When threads have the same score, they will be sorted
+alphabetically. The threads that have the same score and the same
+subject will be sorted by number, which is (normally) the sequence in
+which the articles arrived.
+
+If you want to sort by score and then reverse arrival order, you could
+say something like:
+
+@lisp
+(setq gnus-thread-sort-functions
+ '((lambda (t1 t2)
+ (not (gnus-thread-sort-by-number t1 t2)))
+ gnus-thread-sort-by-score))
+@end lisp
+
+@vindex gnus-thread-score-function
+The function in the @code{gnus-thread-score-function} variable (default
+@code{+}) is used for calculating the total score of a thread. Useful
+functions might be @code{max}, @code{min}, or squared means, or whatever
+tickles your fancy.
+
+@findex gnus-article-sort-functions
+@findex gnus-article-sort-by-date
+@findex gnus-article-sort-by-score
+@findex gnus-article-sort-by-subject
+@findex gnus-article-sort-by-author
+@findex gnus-article-sort-by-number
+If you are using an unthreaded display for some strange reason or other,
+you have to fiddle with the @code{gnus-article-sort-functions} variable.
+It is very similar to the @code{gnus-thread-sort-functions}, except that
+it uses slightly different functions for article comparison. Available
+sorting predicate functions are @code{gnus-article-sort-by-number},
+@code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject},
+@code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}.
+
+If you want to sort an unthreaded summary display by subject, you could
+say something like:
+
+@lisp
+(setq gnus-article-sort-functions
+ '(gnus-article-sort-by-number
+ gnus-article-sort-by-subject))
+@end lisp
+
+
+
+@node Asynchronous Fetching
+@section Asynchronous Article Fetching
+@cindex asynchronous article fetching
+@cindex article pre-fetch
+@cindex pre-fetch
+
+If you read your news from an @sc{nntp} server that's far away, the
+network latencies may make reading articles a chore. You have to wait
+for a while after pressing @kbd{n} to go to the next article before the
+article appears. Why can't Gnus just go ahead and fetch the article
+while you are reading the previous one? Why not, indeed.
+
+First, some caveats. There are some pitfalls to using asynchronous
+article fetching, especially the way Gnus does it.
+
+Let's say you are reading article 1, which is short, and article 2 is
+quite long, and you are not interested in reading that. Gnus does not
+know this, so it goes ahead and fetches article 2. You decide to read
+article 3, but since Gnus is in the process of fetching article 2, the
+connection is blocked.
+
+To avoid these situations, Gnus will open two (count 'em two)
+connections to the server. Some people may think this isn't a very nice
+thing to do, but I don't see any real alternatives. Setting up that
+extra connection takes some time, so Gnus startup will be slower.
+
+Gnus will fetch more articles than you will read. This will mean that
+the link between your machine and the @sc{nntp} server will become more
+loaded than if you didn't use article pre-fetch. The server itself will
+also become more loaded---both with the extra article requests, and the
+extra connection.
+
+Ok, so now you know that you shouldn't really use this thing... unless
+you really want to.
+
+@vindex gnus-asynchronous
+Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should
+happen automatically.
+
+@vindex gnus-use-article-prefetch
+You can control how many articles are to be pre-fetched by setting
+@code{gnus-use-article-prefetch}. This is 30 by default, which means
+that when you read an article in the group, the backend will pre-fetch
+the next 30 articles. If this variable is @code{t}, the backend will
+pre-fetch all the articles it can without bound. If it is
+@code{nil}, no pre-fetching will be done.
+
+@vindex gnus-async-prefetch-article-p
+@findex gnus-async-read-p
+There are probably some articles that you don't want to pre-fetch---read
+articles, for instance. The @code{gnus-async-prefetch-article-p} variable controls whether an article is to be pre-fetched. This function should
+return non-@code{nil} when the article in question is to be
+pre-fetched. The default is @code{gnus-async-read-p}, which returns
+@code{nil} on read articles. The function is called with an article
+data structure as the only parameter.
+
+If, for instance, you wish to pre-fetch only unread articles shorter than 100 lines, you could say something like:
+
+@lisp
+(defun my-async-short-unread-p (data)
+ "Return non-nil for short, unread articles."
+ (and (gnus-data-unread-p data)
+ (< (mail-header-lines (gnus-data-header data))
+ 100)))
+
+(setq gnus-async-prefetch-article-p 'my-async-short-unread-p)
+@end lisp
+
+These functions will be called many, many times, so they should
+preferably be short and sweet to avoid slowing down Gnus too much.
+It's probably a good idea to byte-compile things like this.
+
+@vindex gnus-prefetched-article-deletion-strategy
+Articles have to be removed from the asynch buffer sooner or later. The
+@code{gnus-prefetched-article-deletion-strategy} says when to remove
+articles. This is a list that may contain the following elements:
+
+@table @code
+@item read
+Remove articles when they are read.
+
+@item exit
+Remove articles when exiting the group.
+@end table
+
+The default value is @code{(read exit)}.
+
+@c @vindex gnus-use-header-prefetch
+@c If @code{gnus-use-header-prefetch} is non-@code{nil}, prefetch articles
+@c from the next group.
+
+
+@node Article Caching
+@section Article Caching
+@cindex article caching
+@cindex caching
+
+If you have an @emph{extremely} slow @sc{nntp} connection, you may
+consider turning article caching on. Each article will then be stored
+locally under your home directory. As you may surmise, this could
+potentially use @emph{huge} amounts of disk space, as well as eat up all
+your inodes so fast it will make your head swim. In vodka.
+
+Used carefully, though, it could be just an easier way to save articles.
+
+@vindex gnus-use-long-file-name
+@vindex gnus-cache-directory
+@vindex gnus-use-cache
+To turn caching on, set @code{gnus-use-cache} to @code{t}. By default,
+all articles ticked or marked as dormant will then be copied
+over to your local cache (@code{gnus-cache-directory}). Whether this
+cache is flat or hierarchal is controlled by the
+@code{gnus-use-long-file-name} variable, as usual.
+
+When re-selecting a ticked or dormant article, it will be fetched from the
+cache instead of from the server. As articles in your cache will never
+expire, this might serve as a method of saving articles while still
+keeping them where they belong. Just mark all articles you want to save
+as dormant, and don't worry.
+
+When an article is marked as read, is it removed from the cache.
+
+@vindex gnus-cache-remove-articles
+@vindex gnus-cache-enter-articles
+The entering/removal of articles from the cache is controlled by the
+@code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles}
+variables. Both are lists of symbols. The first is @code{(ticked
+dormant)} by default, meaning that ticked and dormant articles will be
+put in the cache. The latter is @code{(read)} by default, meaning that
+articles marked as read are removed from the cache. Possibly
+symbols in these two lists are @code{ticked}, @code{dormant},
+@code{unread} and @code{read}.
+
+@findex gnus-jog-cache
+So where does the massive article-fetching and storing come into the
+picture? The @code{gnus-jog-cache} command will go through all
+subscribed newsgroups, request all unread articles, score them, and
+store them in the cache. You should only ever, ever ever ever, use this
+command if 1) your connection to the @sc{nntp} server is really, really,
+really slow and 2) you have a really, really, really huge disk.
+Seriously. One way to cut down on the number of articles downloaded is
+to score unwanted articles down and have them marked as read. They will
+not then be downloaded by this command.
+
+@vindex gnus-uncacheable-groups
+@vindex gnus-cacheable-groups
+It is likely that you do not want caching on all groups. For instance,
+if your @code{nnml} mail is located under your home directory, it makes no
+sense to cache it somewhere else under your home directory. Unless you
+feel that it's neat to use twice as much space.
+
+To limit the caching, you could set @code{gnus-cacheable-groups} to a
+regexp of groups to cache, @samp{^nntp} for instance, or set the
+@code{gnus-uncacheable-groups} regexp to @samp{^nnml}, for instance.
+Both variables are @code{nil} by default. If a group matches both
+variables, the group is not cached.
+
+@findex gnus-cache-generate-nov-databases
+@findex gnus-cache-generate-active
+@vindex gnus-cache-active-file
+The cache stores information on what articles it contains in its active
+file (@code{gnus-cache-active-file}). If this file (or any other parts
+of the cache) becomes all messed up for some reason or other, Gnus
+offers two functions that will try to set things right. @kbd{M-x
+gnus-cache-generate-nov-databases} will (re)build all the @sc{nov}
+files, and @kbd{gnus-cache-generate-active} will (re)generate the active
+file.
+
+
+@node Persistent Articles
+@section Persistent Articles
+@cindex persistent articles
+
+Closely related to article caching, we have @dfn{persistent articles}.
+In fact, it's just a different way of looking at caching, and much more
+useful in my opinion.
+
+Say you're reading a newsgroup, and you happen on to some valuable gem
+that you want to keep and treasure forever. You'd normally just save it
+(using one of the many saving commands) in some file. The problem with
+that is that it's just, well, yucky. Ideally you'd prefer just having
+the article remain in the group where you found it forever; untouched by
+the expiry going on at the news server.
+
+This is what a @dfn{persistent article} is---an article that just won't
+be deleted. It's implemented using the normal cache functions, but
+you use two explicit commands for managing persistent articles:
+
+@table @kbd
+
+@item *
+@kindex * (Summary)
+@findex gnus-cache-enter-article
+Make the current article persistent (@code{gnus-cache-enter-article}).
+
+@item M-*
+@kindex M-* (Summary)
+@findex gnus-cache-remove-article
+Remove the current article from the persistent articles
+(@code{gnus-cache-remove-article}). This will normally delete the
+article.
+@end table
+
+Both these commands understand the process/prefix convention.
+
+To avoid having all ticked articles (and stuff) entered into the cache,
+you should set @code{gnus-use-cache} to @code{passive} if you're just
+interested in persistent articles:
+
+@lisp
+(setq gnus-use-cache 'passive)
+@end lisp
+
+
+@node Article Backlog
+@section Article Backlog
+@cindex backlog
+@cindex article backlog
+
+If you have a slow connection, but the idea of using caching seems
+unappealing to you (and it is, really), you can help the situation some
+by switching on the @dfn{backlog}. This is where Gnus will buffer
+already read articles so that it doesn't have to re-fetch articles
+you've already read. This only helps if you are in the habit of
+re-selecting articles you've recently read, of course. If you never do
+that, turning the backlog on will slow Gnus down a little bit, and
+increase memory usage some.
+
+@vindex gnus-keep-backlog
+If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store
+at most @var{n} old articles in a buffer for later re-fetching. If this
+variable is non-@code{nil} and is not a number, Gnus will store
+@emph{all} read articles, which means that your Emacs will grow without
+bound before exploding and taking your machine down with you. I put
+that in there just to keep y'all on your toes.
+
+This variable is @code{nil} by default.
+
+
+@node Saving Articles
+@section Saving Articles
+@cindex saving articles
+
+Gnus can save articles in a number of ways. Below is the documentation
+for saving articles in a fairly straight-forward fashion (i.e., little
+processing of the article is done before it is saved). For a different
+approach (uudecoding, unsharing) you should use @code{gnus-uu}
+(@pxref{Decoding Articles}).
+
+@vindex gnus-save-all-headers
+If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete
+unwanted headers before saving the article.
+
+@vindex gnus-saved-headers
+If the preceding variable is @code{nil}, all headers that match the
+@code{gnus-saved-headers} regexp will be kept, while the rest will be
+deleted before saving.
+
+@table @kbd
+
+@item O o
+@itemx o
+@kindex O o (Summary)
+@kindex o (Summary)
+@findex gnus-summary-save-article
+@c @icon{gnus-summary-save-article}
+Save the current article using the default article saver
+(@code{gnus-summary-save-article}).
+
+@item O m
+@kindex O m (Summary)
+@findex gnus-summary-save-article-mail
+Save the current article in mail format
+(@code{gnus-summary-save-article-mail}).
+
+@item O r
+@kindex O r (Summary)
+@findex gnus-summary-save-article-rmail
+Save the current article in rmail format
+(@code{gnus-summary-save-article-rmail}).
+
+@item O f
+@kindex O f (Summary)
+@findex gnus-summary-save-article-file
+@c @icon{gnus-summary-save-article-file}
+Save the current article in plain file format
+(@code{gnus-summary-save-article-file}).
+
+@item O F
+@kindex O F (Summary)
+@findex gnus-summary-write-article-file
+Write the current article in plain file format, overwriting any previous
+file contents (@code{gnus-summary-write-article-file}).
+
+@item O b
+@kindex O b (Summary)
+@findex gnus-summary-save-article-body-file
+Save the current article body in plain file format
+(@code{gnus-summary-save-article-body-file}).
+
+@item O h
+@kindex O h (Summary)
+@findex gnus-summary-save-article-folder
+Save the current article in mh folder format
+(@code{gnus-summary-save-article-folder}).
+
+@item O v
+@kindex O v (Summary)
+@findex gnus-summary-save-article-vm
+Save the current article in a VM folder
+(@code{gnus-summary-save-article-vm}).
+
+@item O p
+@kindex O p (Summary)
+@findex gnus-summary-pipe-output
+Save the current article in a pipe. Uhm, like, what I mean is---Pipe
+the current article to a process (@code{gnus-summary-pipe-output}).
+@end table
+
+@vindex gnus-prompt-before-saving
+All these commands use the process/prefix convention
+(@pxref{Process/Prefix}). If you save bunches of articles using these
+functions, you might get tired of being prompted for files to save each
+and every article in. The prompting action is controlled by
+the @code{gnus-prompt-before-saving} variable, which is @code{always} by
+default, giving you that excessive prompting action you know and
+loathe. If you set this variable to @code{t} instead, you'll be prompted
+just once for each series of articles you save. If you like to really
+have Gnus do all your thinking for you, you can even set this variable
+to @code{nil}, which means that you will never be prompted for files to
+save articles in. Gnus will simply save all the articles in the default
+files.
+
+
+@vindex gnus-default-article-saver
+You can customize the @code{gnus-default-article-saver} variable to make
+Gnus do what you want it to. You can use any of the four ready-made
+functions below, or you can create your own.
+
+@table @code
+
+@item gnus-summary-save-in-rmail
+@findex gnus-summary-save-in-rmail
+@vindex gnus-rmail-save-name
+@findex gnus-plain-save-name
+This is the default format, @dfn{babyl}. Uses the function in the
+@code{gnus-rmail-save-name} variable to get a file name to save the
+article in. The default is @code{gnus-plain-save-name}.
+
+@item gnus-summary-save-in-mail
+@findex gnus-summary-save-in-mail
+@vindex gnus-mail-save-name
+Save in a Unix mail (mbox) file. Uses the function in the
+@code{gnus-mail-save-name} variable to get a file name to save the
+article in. The default is @code{gnus-plain-save-name}.
+
+@item gnus-summary-save-in-file
+@findex gnus-summary-save-in-file
+@vindex gnus-file-save-name
+@findex gnus-numeric-save-name
+Append the article straight to an ordinary file. Uses the function in
+the @code{gnus-file-save-name} variable to get a file name to save the
+article in. The default is @code{gnus-numeric-save-name}.
+
+@item gnus-summary-save-body-in-file
+@findex gnus-summary-save-body-in-file
+Append the article body to an ordinary file. Uses the function in the
+@code{gnus-file-save-name} variable to get a file name to save the
+article in. The default is @code{gnus-numeric-save-name}.
+
+@item gnus-summary-save-in-folder
+@findex gnus-summary-save-in-folder
+@findex gnus-folder-save-name
+@findex gnus-Folder-save-name
+@vindex gnus-folder-save-name
+@cindex rcvstore
+@cindex MH folders
+Save the article to an MH folder using @code{rcvstore} from the MH
+library. Uses the function in the @code{gnus-folder-save-name} variable
+to get a file name to save the article in. The default is
+@code{gnus-folder-save-name}, but you can also use
+@code{gnus-Folder-save-name}, which creates capitalized names.
+
+@item gnus-summary-save-in-vm
+@findex gnus-summary-save-in-vm
+Save the article in a VM folder. You have to have the VM mail
+reader to use this setting.
+@end table
+
+@vindex gnus-article-save-directory
+All of these functions, except for the last one, will save the article
+in the @code{gnus-article-save-directory}, which is initialized from the
+@code{SAVEDIR} environment variable. This is @file{~/News/} by
+default.
+
+As you can see above, the functions use different functions to find a
+suitable name of a file to save the article in. Below is a list of
+available functions that generate names:
+
+@table @code
+
+@item gnus-Numeric-save-name
+@findex gnus-Numeric-save-name
+File names like @file{~/News/Alt.andrea-dworkin/45}.
+
+@item gnus-numeric-save-name
+@findex gnus-numeric-save-name
+File names like @file{~/News/alt.andrea-dworkin/45}.
+
+@item gnus-Plain-save-name
+@findex gnus-Plain-save-name
+File names like @file{~/News/Alt.andrea-dworkin}.
+
+@item gnus-plain-save-name
+@findex gnus-plain-save-name
+File names like @file{~/News/alt.andrea-dworkin}.
+@end table
+
+@vindex gnus-split-methods
+You can have Gnus suggest where to save articles by plonking a regexp into
+the @code{gnus-split-methods} alist. For instance, if you would like to
+save articles related to Gnus in the file @file{gnus-stuff}, and articles
+related to VM in @code{vm-stuff}, you could set this variable to something
+like:
+
+@lisp
+(("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff")
+ ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff")
+ (my-choosing-function "../other-dir/my-stuff")
+ ((equal gnus-newsgroup-name "mail.misc") "mail-stuff"))
+@end lisp
+
+We see that this is a list where each element is a list that has two
+elements---the @dfn{match} and the @dfn{file}. The match can either be
+a string (in which case it is used as a regexp to match on the article
+head); it can be a symbol (which will be called as a function with the
+group name as a parameter); or it can be a list (which will be
+@code{eval}ed). If any of these actions have a non-@code{nil} result,
+the @dfn{file} will be used as a default prompt. In addition, the
+result of the operation itself will be used if the function or form
+called returns a string or a list of strings.
+
+You basically end up with a list of file names that might be used when
+saving the current article. (All ``matches'' will be used.) You will
+then be prompted for what you really want to use as a name, with file
+name completion over the results from applying this variable.
+
+This variable is @code{((gnus-article-archive-name))} by default, which
+means that Gnus will look at the articles it saves for an
+@code{Archive-name} line and use that as a suggestion for the file
+name.
+
+Here's an example function to clean up file names somewhat. If you have
+lots of mail groups called things like
+@samp{nnml:mail.whatever}, you may want to chop off the beginning of
+these group names before creating the file name to save to. The
+following will do just that:
+
+@lisp
+(defun my-save-name (group)
+ (when (string-match "^nnml:mail." group)
+ (substring group (match-end 0))))
+
+(setq gnus-split-methods
+ '((gnus-article-archive-name)
+ (my-save-name)))
+@end lisp
+
+
+@vindex gnus-use-long-file-name
+Finally, you have the @code{gnus-use-long-file-name} variable. If it is
+@code{nil}, all the preceding functions will replace all periods
+(@samp{.}) in the group names with slashes (@samp{/})---which means that
+the functions will generate hierarchies of directories instead of having
+all the files in the top level directory
+(@file{~/News/alt/andrea-dworkin} instead of
+@file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default
+on most systems. However, for historical reasons, this is @code{nil} on
+Xenix and usg-unix-v machines by default.
+
+This function also affects kill and score file names. If this variable
+is a list, and the list contains the element @code{not-score}, long file
+names will not be used for score files, if it contains the element
+@code{not-save}, long file names will not be used for saving, and if it
+contains the element @code{not-kill}, long file names will not be used
+for kill files.
+
+If you'd like to save articles in a hierarchy that looks something like
+a spool, you could
+
+@lisp
+(setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
+(setq gnus-default-article-saver 'gnus-summary-save-in-file) ; no encoding
+@end lisp
+
+Then just save with @kbd{o}. You'd then read this hierarchy with
+ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and
+the top level directory as the argument (@file{~/News/}). Then just walk
+around to the groups/directories with @code{nneething}.
+
+
+@node Decoding Articles
+@section Decoding Articles
+@cindex decoding articles
+
+Sometime users post articles (or series of articles) that have been
+encoded in some way or other. Gnus can decode them for you.
+
+@menu
+* Uuencoded Articles:: Uudecode articles.
+* Shell Archives:: Unshar articles.
+* PostScript Files:: Split PostScript.
+* Other Files:: Plain save and binhex.
+* Decoding Variables:: Variables for a happy decoding.
+* Viewing Files:: You want to look at the result of the decoding?
+@end menu
+
+@cindex series
+@cindex article series
+All these functions use the process/prefix convention
+(@pxref{Process/Prefix}) for finding out what articles to work on, with
+the extension that a ``single article'' means ``a single series''. Gnus
+can find out by itself what articles belong to a series, decode all the
+articles and unpack/view/save the resulting file(s).
+
+Gnus guesses what articles are in the series according to the following
+simplish rule: The subjects must be (nearly) identical, except for the
+last two numbers of the line. (Spaces are largely ignored, however.)
+
+For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus
+will find all the articles that match the regexp @samp{^cat.gif
+([0-9]+/[0-9]+).*$}.
+
+Subjects that are non-standard, like @samp{cat.gif (2/3) Part 6 of a
+series}, will not be properly recognized by any of the automatic viewing
+commands, and you have to mark the articles manually with @kbd{#}.
+
+
+@node Uuencoded Articles
+@subsection Uuencoded Articles
+@cindex uudecode
+@cindex uuencoded articles
+
+@table @kbd
+
+@item X u
+@kindex X u (Summary)
+@findex gnus-uu-decode-uu
+@c @icon{gnus-uu-decode-uu}
+Uudecodes the current series (@code{gnus-uu-decode-uu}).
+
+@item X U
+@kindex X U (Summary)
+@findex gnus-uu-decode-uu-and-save
+Uudecodes and saves the current series
+(@code{gnus-uu-decode-uu-and-save}).
+
+@item X v u
+@kindex X v u (Summary)
+@findex gnus-uu-decode-uu-view
+Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}).
+
+@item X v U
+@kindex X v U (Summary)
+@findex gnus-uu-decode-uu-and-save-view
+Uudecodes, views and saves the current series
+(@code{gnus-uu-decode-uu-and-save-view}).
+
+@end table
+
+Remember that these all react to the presence of articles marked with
+the process mark. If, for instance, you'd like to decode and save an
+entire newsgroup, you'd typically do @kbd{M P a}
+(@code{gnus-uu-mark-all}) and then @kbd{X U}
+(@code{gnus-uu-decode-uu-and-save}).
+
+All this is very much different from how @code{gnus-uu} worked with
+@sc{gnus 4.1}, where you had explicit keystrokes for everything under
+the sun. This version of @code{gnus-uu} generally assumes that you mark
+articles in some way (@pxref{Setting Process Marks}) and then press
+@kbd{X u}.
+
+@vindex gnus-uu-notify-files
+Note: When trying to decode articles that have names matching
+@code{gnus-uu-notify-files}, which is hard-coded to
+@samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will
+automatically post an article on @samp{comp.unix.wizards} saying that
+you have just viewed the file in question. This feature can't be turned
+off.
+
+
+@node Shell Archives
+@subsection Shell Archives
+@cindex unshar
+@cindex shell archives
+@cindex shared articles
+
+Shell archives (``shar files'') used to be a popular way to distribute
+sources, but it isn't used all that much today. In any case, we have
+some commands to deal with these:
+
+@table @kbd
+
+@item X s
+@kindex X s (Summary)
+@findex gnus-uu-decode-unshar
+Unshars the current series (@code{gnus-uu-decode-unshar}).
+
+@item X S
+@kindex X S (Summary)
+@findex gnus-uu-decode-unshar-and-save
+Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}).
+
+@item X v s
+@kindex X v s (Summary)
+@findex gnus-uu-decode-unshar-view
+Unshars and views the current series (@code{gnus-uu-decode-unshar-view}).
+
+@item X v S
+@kindex X v S (Summary)
+@findex gnus-uu-decode-unshar-and-save-view
+Unshars, views and saves the current series
+(@code{gnus-uu-decode-unshar-and-save-view}).
+@end table
+
+
+@node PostScript Files
+@subsection PostScript Files
+@cindex PostScript
+
+@table @kbd
+
+@item X p
+@kindex X p (Summary)
+@findex gnus-uu-decode-postscript
+Unpack the current PostScript series (@code{gnus-uu-decode-postscript}).
+
+@item X P
+@kindex X P (Summary)
+@findex gnus-uu-decode-postscript-and-save
+Unpack and save the current PostScript series
+(@code{gnus-uu-decode-postscript-and-save}).
+
+@item X v p
+@kindex X v p (Summary)
+@findex gnus-uu-decode-postscript-view
+View the current PostScript series
+(@code{gnus-uu-decode-postscript-view}).
+
+@item X v P
+@kindex X v P (Summary)
+@findex gnus-uu-decode-postscript-and-save-view
+View and save the current PostScript series
+(@code{gnus-uu-decode-postscript-and-save-view}).
+@end table
+
+
+@node Other Files
+@subsection Other Files
+
+@table @kbd
+@item X o
+@kindex X o (Summary)
+@findex gnus-uu-decode-save
+Save the current series
+(@code{gnus-uu-decode-save}).
+
+@item X b
+@kindex X b (Summary)
+@findex gnus-uu-decode-binhex
+Unbinhex the current series (@code{gnus-uu-decode-binhex}). This
+doesn't really work yet.
+@end table
+
+
+@node Decoding Variables
+@subsection Decoding Variables
+
+Adjective, not verb.
+
+@menu
+* Rule Variables:: Variables that say how a file is to be viewed.
+* Other Decode Variables:: Other decode variables.
+* Uuencoding and Posting:: Variables for customizing uuencoding.
+@end menu
+
+
+@node Rule Variables
+@subsubsection Rule Variables
+@cindex rule variables
+
+Gnus uses @dfn{rule variables} to decide how to view a file. All these
+variables are of the form
+
+@lisp
+ (list '(regexp1 command2)
+ '(regexp2 command2)
+ ...)
+@end lisp
+
+@table @code
+
+@item gnus-uu-user-view-rules
+@vindex gnus-uu-user-view-rules
+@cindex sox
+This variable is consulted first when viewing files. If you wish to use,
+for instance, @code{sox} to convert an @samp{.au} sound file, you could
+say something like:
+@lisp
+(setq gnus-uu-user-view-rules
+ (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\")))
+@end lisp
+
+@item gnus-uu-user-view-rules-end
+@vindex gnus-uu-user-view-rules-end
+This variable is consulted if Gnus couldn't make any matches from the
+user and default view rules.
+
+@item gnus-uu-user-archive-rules
+@vindex gnus-uu-user-archive-rules
+This variable can be used to say what commands should be used to unpack
+archives.
+@end table
+
+
+@node Other Decode Variables
+@subsubsection Other Decode Variables
+
+@table @code
+@vindex gnus-uu-grabbed-file-functions
+
+@item gnus-uu-grabbed-file-functions
+All functions in this list will be called right after each file has been
+successfully decoded---so that you can move or view files right away,
+and don't have to wait for all files to be decoded before you can do
+anything. Ready-made functions you can put in this list are:
+
+@table @code
+
+@item gnus-uu-grab-view
+@findex gnus-uu-grab-view
+View the file.
+
+@item gnus-uu-grab-move
+@findex gnus-uu-grab-move
+Move the file (if you're using a saving function.)
+@end table
+
+@item gnus-uu-be-dangerous
+@vindex gnus-uu-be-dangerous
+Specifies what to do if unusual situations arise during decoding. If
+@code{nil}, be as conservative as possible. If @code{t}, ignore things
+that didn't work, and overwrite existing files. Otherwise, ask each
+time.
+
+@item gnus-uu-ignore-files-by-name
+@vindex gnus-uu-ignore-files-by-name
+Files with name matching this regular expression won't be viewed.
+
+@item gnus-uu-ignore-files-by-type
+@vindex gnus-uu-ignore-files-by-type
+Files with a @sc{mime} type matching this variable won't be viewed.
+Note that Gnus tries to guess what type the file is based on the name.
+@code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly
+kludgey.
+
+@item gnus-uu-tmp-dir
+@vindex gnus-uu-tmp-dir
+Where @code{gnus-uu} does its work.
+
+@item gnus-uu-do-not-unpack-archives
+@vindex gnus-uu-do-not-unpack-archives
+Non-@code{nil} means that @code{gnus-uu} won't peek inside archives
+looking for files to display.
+
+@item gnus-uu-view-and-save
+@vindex gnus-uu-view-and-save
+Non-@code{nil} means that the user will always be asked to save a file
+after viewing it.
+
+@item gnus-uu-ignore-default-view-rules
+@vindex gnus-uu-ignore-default-view-rules
+Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing
+rules.
+
+@item gnus-uu-ignore-default-archive-rules
+@vindex gnus-uu-ignore-default-archive-rules
+Non-@code{nil} means that @code{gnus-uu} will ignore the default archive
+unpacking commands.
+
+@item gnus-uu-kill-carriage-return
+@vindex gnus-uu-kill-carriage-return
+Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns
+from articles.
+
+@item gnus-uu-unmark-articles-not-decoded
+@vindex gnus-uu-unmark-articles-not-decoded
+Non-@code{nil} means that @code{gnus-uu} will mark unsuccessfully
+decoded articles as unread.
+
+@item gnus-uu-correct-stripped-uucode
+@vindex gnus-uu-correct-stripped-uucode
+Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix
+uuencoded files that have had trailing spaces deleted.
+
+@item gnus-uu-pre-uudecode-hook
+@vindex gnus-uu-pre-uudecode-hook
+Hook run before sending a message to @code{uudecode}.
+
+@item gnus-uu-view-with-metamail
+@vindex gnus-uu-view-with-metamail
+@cindex metamail
+Non-@code{nil} means that @code{gnus-uu} will ignore the viewing
+commands defined by the rule variables and just fudge a @sc{mime}
+content type based on the file name. The result will be fed to
+@code{metamail} for viewing.
+
+@item gnus-uu-save-in-digest
+@vindex gnus-uu-save-in-digest
+Non-@code{nil} means that @code{gnus-uu}, when asked to save without
+decoding, will save in digests. If this variable is @code{nil},
+@code{gnus-uu} will just save everything in a file without any
+embellishments. The digesting almost conforms to RFC1153---no easy way
+to specify any meaningful volume and issue numbers were found, so I
+simply dropped them.
+
+@end table
+
+
+@node Uuencoding and Posting
+@subsubsection Uuencoding and Posting
+
+@table @code
+
+@item gnus-uu-post-include-before-composing
+@vindex gnus-uu-post-include-before-composing
+Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode
+before you compose the article. If this variable is @code{t}, you can
+either include an encoded file with @kbd{C-c C-i} or have one included
+for you when you post the article.
+
+@item gnus-uu-post-length
+@vindex gnus-uu-post-length
+Maximum length of an article. The encoded file will be split into how
+many articles it takes to post the entire file.
+
+@item gnus-uu-post-threaded
+@vindex gnus-uu-post-threaded
+Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a
+thread. This may not be smart, as no other decoder I have seen is able
+to follow threads when collecting uuencoded articles. (Well, I have
+seen one package that does that---@code{gnus-uu}, but somehow, I don't
+think that counts...) Default is @code{nil}.
+
+@item gnus-uu-post-separate-description
+@vindex gnus-uu-post-separate-description
+Non-@code{nil} means that the description will be posted in a separate
+article. The first article will typically be numbered (0/x). If this
+variable is @code{nil}, the description the user enters will be included
+at the beginning of the first article, which will be numbered (1/x).
+Default is @code{t}.
+
+@end table
+
+
+@node Viewing Files
+@subsection Viewing Files
+@cindex viewing files
+@cindex pseudo-articles
+
+After decoding, if the file is some sort of archive, Gnus will attempt
+to unpack the archive and see if any of the files in the archive can be
+viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz}
+containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will
+uncompress and de-tar the main file, and then view the two pictures.
+This unpacking process is recursive, so if the archive contains archives
+of archives, it'll all be unpacked.
+
+Finally, Gnus will normally insert a @dfn{pseudo-article} for each
+extracted file into the summary buffer. If you go to these
+``articles'', you will be prompted for a command to run (usually Gnus
+will make a suggestion), and then the command will be run.
+
+@vindex gnus-view-pseudo-asynchronously
+If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait
+until the viewing is done before proceeding.
+
+@vindex gnus-view-pseudos
+If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert
+the pseudo-articles into the summary buffer, but view them
+immediately. If this variable is @code{not-confirm}, the user won't even
+be asked for a confirmation before viewing is done.
+
+@vindex gnus-view-pseudos-separately
+If @code{gnus-view-pseudos-separately} is non-@code{nil}, one
+pseudo-article will be created for each file to be viewed. If
+@code{nil}, all files that use the same viewing command will be given as
+a list of parameters to that command.
+
+@vindex gnus-insert-pseudo-articles
+If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert
+pseudo-articles when decoding. It is @code{t} by default.
+
+So; there you are, reading your @emph{pseudo-articles} in your
+@emph{virtual newsgroup} from the @emph{virtual server}; and you think:
+Why isn't anything real anymore? How did we get here?
+
+
+@node Article Treatment
+@section Article Treatment
+
+Reading through this huge manual, you may have quite forgotten that the
+object of newsreaders is to actually, like, read what people have
+written. Reading articles. Unfortunately, people are quite bad at
+writing, so there are tons of functions and variables to make reading
+these articles easier.
+
+@menu
+* Article Highlighting:: You want to make the article look like fruit salad.
+* Article Fontisizing:: Making emphasized text look nice.
+* Article Hiding:: You also want to make certain info go away.
+* Article Washing:: Lots of way-neat functions to make life better.
+* Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
+* Article Date:: Grumble, UT!
+* Article Signature:: What is a signature?
+@end menu
+
+
+@node Article Highlighting
+@subsection Article Highlighting
+@cindex highlighting
+
+Not only do you want your article buffer to look like fruit salad, but
+you want it to look like technicolor fruit salad.
+
+@table @kbd
+
+@item W H a
+@kindex W H a (Summary)
+@findex gnus-article-highlight
+@findex gnus-article-maybe-highlight
+Do much highlighting of the current article
+(@code{gnus-article-highlight}). This function highlights header, cited
+text, the signature, and adds buttons to the body and the head.
+
+Most users would prefer using @code{gnus-article-maybe-highlight} in
+@code{gnus-article-display-hook} (@pxref{Customizing Articles}) instead.
+This is a bit less agressive---it highlights only the headers, the
+signature and adds buttons.
+
+@item W H h
+@kindex W H h (Summary)
+@findex gnus-article-highlight-headers
+@vindex gnus-header-face-alist
+Highlight the headers (@code{gnus-article-highlight-headers}). The
+highlighting will be done according to the @code{gnus-header-face-alist}
+variable, which is a list where each element has the form @var{(regexp
+name content)}. @var{regexp} is a regular expression for matching the
+header, @var{name} is the face used for highlighting the header name
+(@pxref{Faces and Fonts}) and @var{content} is the face for highlighting
+the header value. The first match made will be used. Note that
+@var{regexp} shouldn't have @samp{^} prepended---Gnus will add one.
+
+@item W H c
+@kindex W H c (Summary)
+@findex gnus-article-highlight-citation
+Highlight cited text (@code{gnus-article-highlight-citation}).
+
+Some variables to customize the citation highlights:
+
+@table @code
+@vindex gnus-cite-parse-max-size
+
+@item gnus-cite-parse-max-size
+If the article size if bigger than this variable (which is 25000 by
+default), no citation highlighting will be performed.
+
+@item gnus-cite-prefix-regexp
+@vindex gnus-cite-prefix-regexp
+Regexp matching the longest possible citation prefix on a line.
+
+@item gnus-cite-max-prefix
+@vindex gnus-cite-max-prefix
+Maximum possible length for a citation prefix (default 20).
+
+@item gnus-cite-face-list
+@vindex gnus-cite-face-list
+List of faces used for highlighting citations (@pxref{Faces and Fonts}).
+When there are citations from multiple articles in the same message,
+Gnus will try to give each citation from each article its own face.
+This should make it easier to see who wrote what.
+
+@item gnus-supercite-regexp
+@vindex gnus-supercite-regexp
+Regexp matching normal Supercite attribution lines.
+
+@item gnus-supercite-secondary-regexp
+@vindex gnus-supercite-secondary-regexp
+Regexp matching mangled Supercite attribution lines.
+
+@item gnus-cite-minimum-match-count
+@vindex gnus-cite-minimum-match-count
+Minimum number of identical prefixes we have to see before we believe
+that it's a citation.
+
+@item gnus-cite-attribution-prefix
+@vindex gnus-cite-attribution-prefix
+Regexp matching the beginning of an attribution line.
+
+@item gnus-cite-attribution-suffix
+@vindex gnus-cite-attribution-suffix
+Regexp matching the end of an attribution line.
+
+@item gnus-cite-attribution-face
+@vindex gnus-cite-attribution-face
+Face used for attribution lines. It is merged with the face for the
+cited text belonging to the attribution.
+
+@end table
+
+
+@item W H s
+@kindex W H s (Summary)
+@vindex gnus-signature-separator
+@vindex gnus-signature-face
+@findex gnus-article-highlight-signature
+Highlight the signature (@code{gnus-article-highlight-signature}).
+Everything after @code{gnus-signature-separator} (@pxref{Article
+Signature}) in an article will be considered a signature and will be
+highlighted with @code{gnus-signature-face}, which is @code{italic} by
+default.
+
+@end table
+
+@xref{Customizing Articles}, for how to highlight articles automatically.
+
+
+@node Article Fontisizing
+@subsection Article Fontisizing
+@cindex emphasis
+@cindex article emphasis
+
+@findex gnus-article-emphasize
+@kindex W e (Summary)
+People commonly add emphasis to words in news articles by writing things
+like @samp{_this_} or @samp{*this*}. Gnus can make this look nicer by
+running the article through the @kbd{W e}
+(@code{gnus-article-emphasize}) command.
+
+@vindex gnus-emphasis-alist
+How the emphasis is computed is controlled by the
+@code{gnus-emphasis-alist} variable. This is an alist where the first
+element is a regular expression to be matched. The second is a number
+that says what regular expression grouping is used to find the entire
+emphasized word. The third is a number that says what regexp grouping
+should be displayed and highlighted. (The text between these two
+groupings will be hidden.) The fourth is the face used for
+highlighting.
+
+@lisp
+(setq gnus-article-emphasis
+ '(("_\\(\\w+\\)_" 0 1 gnus-emphasis-underline)
+ ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold)))
+@end lisp
+
+@vindex gnus-emphasis-underline
+@vindex gnus-emphasis-bold
+@vindex gnus-emphasis-italic
+@vindex gnus-emphasis-underline-bold
+@vindex gnus-emphasis-underline-italic
+@vindex gnus-emphasis-bold-italic
+@vindex gnus-emphasis-underline-bold-italic
+By default, there are seven rules, and they use the following faces:
+@code{gnus-emphasis-bold}, @code{gnus-emphasis-italic},
+@code{gnus-emphasis-underline}, @code{gnus-emphasis-bold-italic},
+@code{gnus-emphasis-underline-italic},
+@code{gnus-emphasis-underline-bold}, and
+@code{gnus-emphasis-underline-bold-italic}.
+
+If you want to change these faces, you can either use @kbd{M-x
+customize}, or you can use @code{copy-face}. For instance, if you want
+to make @code{gnus-emphasis-italic} use a red face instead, you could
+say something like:
+
+@lisp
+(copy-face 'red 'gnus-emphasis-italic)
+@end lisp
+
+@xref{Customizing Articles}, for how to fontize articles automatically.
+
+
+@node Article Hiding
+@subsection Article Hiding
+@cindex article hiding
+
+Or rather, hiding certain things in each article. There usually is much
+too much cruft in most articles.
+
+@table @kbd
+
+@item W W a
+@kindex W W a (Summary)
+@findex gnus-article-hide
+Do quite a lot of hiding on the article buffer
+(@kbd{gnus-article-hide}). In particular, this function will hide
+headers, PGP, cited text and the signature.
+
+@item W W h
+@kindex W W h (Summary)
+@findex gnus-article-hide-headers
+Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding
+Headers}.
+
+@item W W b
+@kindex W W b (Summary)
+@findex gnus-article-hide-boring-headers
+Hide headers that aren't particularly interesting
+(@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}.
+
+@item W W s
+@kindex W W s (Summary)
+@findex gnus-article-hide-signature
+Hide signature (@code{gnus-article-hide-signature}). @xref{Article
+Signature}.
+
+@item W W p
+@kindex W W p (Summary)
+@findex gnus-article-hide-pgp
+@vindex gnus-article-hide-pgp-hook
+Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}). The
+@code{gnus-article-hide-pgp-hook} hook will be run after a @sc{pgp}
+signature has been hidden.
+
+@item W W P
+@kindex W W P (Summary)
+@findex gnus-article-hide-pem
+Hide @sc{pem} (privacy enhanced messages) cruft
+(@code{gnus-article-hide-pem}).
+
+@item W W c
+@kindex W W c (Summary)
+@findex gnus-article-hide-citation
+Hide citation (@code{gnus-article-hide-citation}). Some variables for
+customizing the hiding:
+
+@table @code
+
+@item gnus-cited-opened-text-button-line-format
+@itemx gnus-cited-closed-text-button-line-format
+@vindex gnus-cited-closed-text-button-line-format
+@vindex gnus-cited-opened-text-button-line-format
+Gnus adds buttons to show where the cited text has been hidden, and to
+allow toggle hiding the text. The format of the variable is specified
+by these format-like variable (@pxref{Formatting Variables}). These
+specs are valid:
+
+@table @samp
+@item b
+Starting point of the hidden text.
+@item e
+Ending point of the hidden text.
+@item l
+Number of characters in the hidden region.
+@item n
+Number of lines of hidden text.
+@end table
+
+@item gnus-cited-lines-visible
+@vindex gnus-cited-lines-visible
+The number of lines at the beginning of the cited text to leave shown.
+
+@end table
+
+@item W W C-c
+@kindex W W C-c (Summary)
+@findex gnus-article-hide-citation-maybe
+
+Hide citation (@code{gnus-article-hide-citation-maybe}) depending on the
+following two variables:
+
+@table @code
+@item gnus-cite-hide-percentage
+@vindex gnus-cite-hide-percentage
+If the cited text is of a bigger percentage than this variable (default
+50), hide the cited text.
+
+@item gnus-cite-hide-absolute
+@vindex gnus-cite-hide-absolute
+The cited text must have at least this length (default 10) before it
+is hidden.
+@end table
+
+@item W W C
+@kindex W W C (Summary)
+@findex gnus-article-hide-citation-in-followups
+Hide cited text in articles that aren't roots
+(@code{gnus-article-hide-citation-in-followups}). This isn't very
+useful as an interactive command, but might be a handy function to stick
+in @code{gnus-article-display-hook} (@pxref{Customizing Articles}).
+
+@end table
+
+All these ``hiding'' commands are toggles, but if you give a negative
+prefix to these commands, they will show what they have previously
+hidden. If you give a positive prefix, they will always hide.
+
+Also @pxref{Article Highlighting} for further variables for
+citation customization.
+
+@xref{Customizing Articles}, for how to hide article elements
+automatically.
+
+
+@node Article Washing
+@subsection Article Washing
+@cindex washing
+@cindex article washing
+
+We call this ``article washing'' for a really good reason. Namely, the
+@kbd{A} key was taken, so we had to use the @kbd{W} key instead.
+
+@dfn{Washing} is defined by us as ``changing something from something to
+something else'', but normally results in something looking better.
+Cleaner, perhaps.
+
+@table @kbd
+
+@item W l
+@kindex W l (Summary)
+@findex gnus-summary-stop-page-breaking
+Remove page breaks from the current article
+(@code{gnus-summary-stop-page-breaking}). @xref{Misc Article}, for page
+delimiters.
+
+@item W r
+@kindex W r (Summary)
+@findex gnus-summary-caesar-message
+@c @icon{gnus-summary-caesar-message}
+Do a Caesar rotate (rot13) on the article buffer
+(@code{gnus-summary-caesar-message}).
+Unreadable articles that tell you to read them with Caesar rotate or rot13.
+(Typically offensive jokes and such.)
+
+It's commonly called ``rot13'' because each letter is rotated 13
+positions in the alphabet, e. g. @samp{B} (letter #2) -> @samp{O} (letter
+#15). It is sometimes referred to as ``Caesar rotate'' because Caesar
+is rumored to have employed this form of, uh, somewhat weak encryption.
+
+@item W t
+@kindex W t (Summary)
+@findex gnus-summary-toggle-header
+Toggle whether to display all headers in the article buffer
+(@code{gnus-summary-toggle-header}).
+
+@item W v
+@kindex W v (Summary)
+@findex gnus-summary-verbose-header
+Toggle whether to display all headers in the article buffer permanently
+(@code{gnus-summary-verbose-header}).
+
+@item W m
+@kindex W m (Summary)
+@findex gnus-summary-toggle-mime
+Toggle whether to run the article through @sc{mime} before displaying
+(@code{gnus-summary-toggle-mime}).
+
+@item W o
+@kindex W o (Summary)
+@findex gnus-article-treat-overstrike
+Treat overstrike (@code{gnus-article-treat-overstrike}).
+
+@item W d
+@kindex W d (Summary)
+@findex gnus-article-treat-dumbquotes
+Treat M******** sm*rtq**t*s (@code{gnus-article-treat-dumbquotes}).
+
+@item W w
+@kindex W w (Summary)
+@findex gnus-article-fill-cited-article
+Do word wrap (@code{gnus-article-fill-cited-article}). If you use this
+function in @code{gnus-article-display-hook}, it should be run fairly
+late and certainly after any highlighting.
+
+You can give the command a numerical prefix to specify the width to use
+when filling.
+
+@item W c
+@kindex W c (Summary)
+@findex gnus-article-remove-cr
+Remove CR (i. e., @samp{^M}s on the end of the lines)
+(@code{gnus-article-remove-cr}).
+
+@item W q
+@kindex W q (Summary)
+@findex gnus-article-de-quoted-unreadable
+Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
+Quoted-Printable is one common @sc{mime} encoding employed when sending
+non-ASCII (i. e., 8-bit) articles. It typically makes strings like
+@samp{déjà vu} look like @samp{d=E9j=E0 vu}, which doesn't look very
+readable to me.
+
+@item W f
+@kindex W f (Summary)
+@cindex x-face
+@findex gnus-article-display-x-face
+@findex gnus-article-x-face-command
+@vindex gnus-article-x-face-command
+@vindex gnus-article-x-face-too-ugly
+Look for and display any X-Face headers
+(@code{gnus-article-display-x-face}). The command executed by this
+function is given by the @code{gnus-article-x-face-command} variable.
+If this variable is a string, this string will be executed in a
+sub-shell. If it is a function, this function will be called with the
+face as the argument. If the @code{gnus-article-x-face-too-ugly} (which
+is a regexp) matches the @code{From} header, the face will not be shown.
+The default action under Emacs is to fork off an @code{xv} to view the
+face; under XEmacs the default action is to display the face before the
+@code{From} header. (It's nicer if XEmacs has been compiled with X-Face
+support---that will make display somewhat faster. If there's no native
+X-Face support, Gnus will try to convert the @code{X-Face} header using
+external programs from the @code{pbmplus} package and friends.) If you
+want to have this function in the display hook, it should probably come
+last.
+
+@item W b
+@kindex W b (Summary)
+@findex gnus-article-add-buttons
+Add clickable buttons to the article (@code{gnus-article-add-buttons}).
+@xref{Article Buttons}.
+
+@item W B
+@kindex W B (Summary)
+@findex gnus-article-add-buttons-to-head
+Add clickable buttons to the article headers
+(@code{gnus-article-add-buttons-to-head}).
+
+@item W E l
+@kindex W E l (Summary)
+@findex gnus-article-strip-leading-blank-lines
+Remove all blank lines from the beginning of the article
+(@code{gnus-article-strip-leading-blank-lines}).
+
+@item W E m
+@kindex W E m (Summary)
+@findex gnus-article-strip-multiple-blank-lines
+Replace all blank lines with empty lines and then all multiple empty
+lines with a single empty line.
+(@code{gnus-article-strip-multiple-blank-lines}).
+
+@item W E t
+@kindex W E t (Summary)
+@findex gnus-article-remove-trailing-blank-lines
+Remove all blank lines at the end of the article
+(@code{gnus-article-remove-trailing-blank-lines}).
+
+@item W E a
+@kindex W E a (Summary)
+@findex gnus-article-strip-blank-lines
+Do all the three commands above
+(@code{gnus-article-strip-blank-lines}).
+
+@item W E A
+@kindex W E A (Summary)
+@findex gnus-article-strip-all-blank-lines
+Remove all blank lines
+(@code{gnus-article-strip-all-blank-lines}).
+
+@item W E s
+@kindex W E s (Summary)
+@findex gnus-article-strip-leading-space
+Remove all white space from the beginning of all lines of the article
+body (@code{gnus-article-strip-leading-space}).
+
+@end table
+
+@xref{Customizing Articles}, for how to wash articles automatically.
+
+
+@node Article Buttons
+@subsection Article Buttons
+@cindex buttons
+
+People often include references to other stuff in articles, and it would
+be nice if Gnus could just fetch whatever it is that people talk about
+with the minimum of fuzz when you hit @kbd{RET} or use the middle mouse
+button on these references.
+
+Gnus adds @dfn{buttons} to certain standard references by default:
+Well-formed URLs, mail addresses and Message-IDs. This is controlled by
+two variables, one that handles article bodies and one that handles
+article heads:
+
+@table @code
+
+@item gnus-button-alist
+@vindex gnus-button-alist
+This is an alist where each entry has this form:
+
+@lisp
+(REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
+@end lisp
+
+@table @var
+
+@item regexp
+All text that match this regular expression will be considered an
+external reference. Here's a typical regexp that matches embedded URLs:
+@samp{<URL:\\([^\n\r>]*\\)>}.
+
+@item button-par
+Gnus has to know which parts of the matches is to be highlighted. This
+is a number that says what sub-expression of the regexp is to be
+highlighted. If you want it all highlighted, you use 0 here.
+
+@item use-p
+This form will be @code{eval}ed, and if the result is non-@code{nil},
+this is considered a match. This is useful if you want extra sifting to
+avoid false matches.
+
+@item function
+This function will be called when you click on this button.
+
+@item data-par
+As with @var{button-par}, this is a sub-expression number, but this one
+says which part of the match is to be sent as data to @var{function}.
+
+@end table
+
+So the full entry for buttonizing URLs is then
+
+@lisp
+("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1)
+@end lisp
+
+@item gnus-header-button-alist
+@vindex gnus-header-button-alist
+This is just like the other alist, except that it is applied to the
+article head only, and that each entry has an additional element that is
+used to say what headers to apply the buttonize coding to:
+
+@lisp
+(HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR)
+@end lisp
+
+@var{HEADER} is a regular expression.
+
+@item gnus-button-url-regexp
+@vindex gnus-button-url-regexp
+A regular expression that matches embedded URLs. It is used in the
+default values of the variables above.
+
+@item gnus-article-button-face
+@vindex gnus-article-button-face
+Face used on buttons.
+
+@item gnus-article-mouse-face
+@vindex gnus-article-mouse-face
+Face used when the mouse cursor is over a button.
+
+@end table
+
+@xref{Customizing Articles}, for how to buttonize articles automatically.
+
+
+@node Article Date
+@subsection Article Date
+
+The date is most likely generated in some obscure timezone you've never
+heard of, so it's quite nice to be able to find out what the time was
+when the article was sent.
+
+@table @kbd
+
+@item W T u
+@kindex W T u (Summary)
+@findex gnus-article-date-ut
+Display the date in UT (aka. GMT, aka ZULU)
+(@code{gnus-article-date-ut}).
+
+@item W T i
+@kindex W T i (Summary)
+@findex gnus-article-date-iso8601
+@cindex ISO 8601
+Display the date in international format, aka. ISO 8601
+(@code{gnus-article-date-iso8601}).
+
+@item W T l
+@kindex W T l (Summary)
+@findex gnus-article-date-local
+Display the date in the local timezone (@code{gnus-article-date-local}).
+
+@item W T s
+@kindex W T s (Summary)
+@vindex gnus-article-time-format
+@findex gnus-article-date-user
+@findex format-time-string
+Display the date using a user-defined format
+(@code{gnus-article-date-user}). The format is specified by the
+@code{gnus-article-time-format} variable, and is a string that's passed
+to @code{format-time-string}. See the documentation of that variable
+for a list of possible format specs.
+
+@item W T e
+@kindex W T e (Summary)
+@findex gnus-article-date-lapsed
+@findex gnus-start-date-timer
+@findex gnus-stop-date-timer
+Say how much time has elapsed between the article was posted and now
+(@code{gnus-article-date-lapsed}). If you want to have this line
+updated continually, you can put
+
+@lisp
+(gnus-start-date-timer)
+@end lisp
+
+in your @file{.gnus.el} file, or you can run it off of some hook. If
+you want to stop the timer, you can use the @code{gnus-stop-date-timer}
+command.
+
+@item W T o
+@kindex W T o (Summary)
+@findex gnus-article-date-original
+Display the original date (@code{gnus-article-date-original}). This can
+be useful if you normally use some other conversion function and are
+worried that it might be doing something totally wrong. Say, claiming
+that the article was posted in 1854. Although something like that is
+@emph{totally} impossible. Don't you trust me? *titter*
+
+@end table
+
+@xref{Customizing Articles}, for how to display the date in your
+preferred format automatically.
+
+
+@node Article Signature
+@subsection Article Signature
+@cindex signatures
+@cindex article signature
+
+@vindex gnus-signature-separator
+Each article is divided into two parts---the head and the body. The
+body can be divided into a signature part and a text part. The variable
+that says what is to be considered a signature is
+@code{gnus-signature-separator}. This is normally the standard
+@samp{^-- $} as mandated by son-of-RFC 1036. However, many people use
+non-standard signature separators, so this variable can also be a list
+of regular expressions to be tested, one by one. (Searches are done
+from the end of the body towards the beginning.) One likely value is:
+
+@lisp
+(setq gnus-signature-separator
+ '("^-- $" ; The standard
+ "^-- *$" ; A common mangling
+ "^-------*$" ; Many people just use a looong
+ ; line of dashes. Shame!
+ "^ *--------*$" ; Double-shame!
+ "^________*$" ; Underscores are also popular
+ "^========*$")) ; Pervert!
+@end lisp
+
+The more permissive you are, the more likely it is that you'll get false
+positives.
+
+@vindex gnus-signature-limit
+@code{gnus-signature-limit} provides a limit to what is considered a
+signature.
+
+@enumerate
+@item
+If it is an integer, no signature may be longer (in characters) than
+that integer.
+@item
+If it is a floating point number, no signature may be longer (in lines)
+than that number.
+@item
+If it is a function, the function will be called without any parameters,
+and if it returns @code{nil}, there is no signature in the buffer.
+@item
+If it is a string, it will be used as a regexp. If it matches, the text
+in question is not a signature.
+@end enumerate
+
+This variable can also be a list where the elements may be of the types
+listed above. Here's an example:
+
+@lisp
+(setq gnus-signature-limit
+ '(200.0 "^---*Forwarded article"))
+@end lisp
+
+This means that if there are more than 200 lines after the signature
+separator, or the text after the signature separator is matched by
+the regular expression @samp{^---*Forwarded article}, then it isn't a
+signature after all.
+
+
+@node Article Commands
+@section Article Commands
+
+@table @kbd
+
+@item A P
+@cindex PostScript
+@cindex printing
+@kindex A P (Summary)
+@vindex gnus-ps-print-hook
+@findex gnus-summary-print-article
+Generate and print a PostScript image of the article buffer
+(@code{gnus-summary-print-article}). @code{gnus-ps-print-hook} will be
+run just before printing the buffer.
+
+@end table
+
+
+@node Summary Sorting
+@section Summary Sorting
+@cindex summary sorting
+
+You can have the summary buffer sorted in various ways, even though I
+can't really see why you'd want that.
+
+@table @kbd
+
+@item C-c C-s C-n
+@kindex C-c C-s C-n (Summary)
+@findex gnus-summary-sort-by-number
+Sort by article number (@code{gnus-summary-sort-by-number}).
+
+@item C-c C-s C-a
+@kindex C-c C-s C-a (Summary)
+@findex gnus-summary-sort-by-author
+Sort by author (@code{gnus-summary-sort-by-author}).
+
+@item C-c C-s C-s
+@kindex C-c C-s C-s (Summary)
+@findex gnus-summary-sort-by-subject
+Sort by subject (@code{gnus-summary-sort-by-subject}).
+
+@item C-c C-s C-d
+@kindex C-c C-s C-d (Summary)
+@findex gnus-summary-sort-by-date
+Sort by date (@code{gnus-summary-sort-by-date}).
+
+@item C-c C-s C-l
+@kindex C-c C-s C-l (Summary)
+@findex gnus-summary-sort-by-lines
+Sort by lines (@code{gnus-summary-sort-by-lines}).
+
+@item C-c C-s C-i
+@kindex C-c C-s C-i (Summary)
+@findex gnus-summary-sort-by-score
+Sort by score (@code{gnus-summary-sort-by-score}).
+@end table
+
+These functions will work both when you use threading and when you don't
+use threading. In the latter case, all summary lines will be sorted,
+line by line. In the former case, sorting will be done on a
+root-by-root basis, which might not be what you were looking for. To
+toggle whether to use threading, type @kbd{T T} (@pxref{Thread
+Commands}).
+
+
+@node Finding the Parent
+@section Finding the Parent
+@cindex parent articles
+@cindex referring articles
+
+@table @kbd
+@item ^
+@kindex ^ (Summary)
+@findex gnus-summary-refer-parent-article
+If you'd like to read the parent of the current article, and it is not
+displayed in the summary buffer, you might still be able to. That is,
+if the current group is fetched by @sc{nntp}, the parent hasn't expired
+and the @code{References} in the current article are not mangled, you
+can just press @kbd{^} or @kbd{A r}
+(@code{gnus-summary-refer-parent-article}). If everything goes well,
+you'll get the parent. If the parent is already displayed in the
+summary buffer, point will just move to this article.
+
+If given a positive numerical prefix, fetch that many articles back into
+the ancestry. If given a negative numerical prefix, fetch just that
+ancestor. So if you say @kbd{3 ^}, Gnus will fetch the parent, the
+grandparent and the grandgrandparent of the current article. If you say
+@kbd{-3 ^}, Gnus will only fetch the grandgrandparent of the current
+article.
+
+@item A R (Summary)
+@findex gnus-summary-refer-references
+@kindex A R (Summary)
+Fetch all articles mentioned in the @code{References} header of the
+article (@code{gnus-summary-refer-references}).
+
+@item A T (Summary)
+@findex gnus-summary-refer-thread
+@kindex A T (Summary)
+Display the full thread where the current article appears
+(@code{gnus-summary-refer-thread}). This command has to fetch all the
+headers in the current group to work, so it usually takes a while. If
+you do it often, you may consider setting @code{gnus-fetch-old-headers}
+to @code{invisible} (@pxref{Filling In Threads}). This won't have any
+visible effects normally, but it'll make this command work a whole lot
+faster. Of course, it'll make group entry somewhat slow.
+
+@vindex gnus-refer-thread-limit
+The @code{gnus-refer-thread-limit} variable says how many old (i. e.,
+articles before the first displayed in the current group) headers to
+fetch when doing this command. The default is 200. If @code{t}, all
+the available headers will be fetched. This variable can be overridden
+by giving the @kbd{A T} command a numerical prefix.
+
+@item M-^ (Summary)
+@findex gnus-summary-refer-article
+@kindex M-^ (Summary)
+@cindex Message-ID
+@cindex fetching by Message-ID
+You can also ask the @sc{nntp} server for an arbitrary article, no
+matter what group it belongs to. @kbd{M-^}
+(@code{gnus-summary-refer-article}) will ask you for a
+@code{Message-ID}, which is one of those long, hard-to-read thingies
+that look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You
+have to get it all exactly right. No fuzzy searches, I'm afraid.
+@end table
+
+The current select method will be used when fetching by
+@code{Message-ID} from non-news select method, but you can override this
+by giving this command a prefix.
+
+@vindex gnus-refer-article-method
+If the group you are reading is located on a backend that does not
+support fetching by @code{Message-ID} very well (like @code{nnspool}),
+you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It
+would, perhaps, be best if the @sc{nntp} server you consult is the one
+updating the spool you are reading from, but that's not really
+necessary.
+
+Most of the mail backends support fetching by @code{Message-ID}, but do
+not do a particularly excellent job at it. That is, @code{nnmbox} and
+@code{nnbabyl} are able to locate articles from any groups, while
+@code{nnml} and @code{nnfolder} are only able to locate articles that
+have been posted to the current group. (Anything else would be too time
+consuming.) @code{nnmh} does not support this at all.
+
+
+@node Alternative Approaches
+@section Alternative Approaches
+
+Different people like to read news using different methods. This being
+Gnus, we offer a small selection of minor modes for the summary buffers.
+
+@menu
+* Pick and Read:: First mark articles and then read them.
+* Binary Groups:: Auto-decode all articles.
+@end menu
+
+
+@node Pick and Read
+@subsection Pick and Read
+@cindex pick and read
+
+Some newsreaders (like @code{nn} and, uhm, @code{Netnews} on VM/CMS) use
+a two-phased reading interface. The user first marks in a summary
+buffer the articles she wants to read. Then she starts reading the
+articles with just an article buffer displayed.
+
+@findex gnus-pick-mode
+@kindex M-x gnus-pick-mode
+Gnus provides a summary buffer minor mode that allows
+this---@code{gnus-pick-mode}. This basically means that a few process
+mark commands become one-keystroke commands to allow easy marking, and
+it provides one additional command for switching to the summary buffer.
+
+Here are the available keystrokes when using pick mode:
+
+@table @kbd
+@item .
+@kindex . (Pick)
+@findex gnus-pick-article-or-thread
+Pick the article or thread on the current line
+(@code{gnus-pick-article-or-thread}). If the variable
+@code{gnus-thread-hide-subtree} is true, then this key selects the
+entire thread when used at the first article of the thread. Otherwise,
+it selects just the article. If given a numerical prefix, go to that
+thread or article and pick it. (The line number is normally displayed
+at the beginning of the summary pick lines.)
+
+@item SPACE
+@kindex SPACE (Pick)
+@findex gnus-pick-next-page
+Scroll the summary buffer up one page (@code{gnus-pick-next-page}). If
+at the end of the buffer, start reading the picked articles.
+
+@item u
+@kindex u (Pick)
+@findex gnus-pick-unmark-article-or-thread.
+Unpick the thread or article
+(@code{gnus-pick-unmark-article-or-thread}). If the variable
+@code{gnus-thread-hide-subtree} is true, then this key unpicks the
+thread if used at the first article of the thread. Otherwise it unpicks
+just the article. You can give this key a numerical prefix to unpick
+the thread or article at that line.
+
+@item RET
+@kindex RET (Pick)
+@findex gnus-pick-start-reading
+@vindex gnus-pick-display-summary
+Start reading the picked articles (@code{gnus-pick-start-reading}). If
+given a prefix, mark all unpicked articles as read first. If
+@code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer
+will still be visible when you are reading.
+
+@end table
+
+All the normal summary mode commands are still available in the
+pick-mode, with the exception of @kbd{u}. However @kbd{!} is available
+which is mapped to the same function
+@code{gnus-summary-tick-article-forward}.
+
+If this sounds like a good idea to you, you could say:
+
+@lisp
+(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
+@end lisp
+
+@vindex gnus-pick-mode-hook
+@code{gnus-pick-mode-hook} is run in pick minor mode buffers.
+
+@vindex gnus-mark-unpicked-articles-as-read
+If @code{gnus-mark-unpicked-articles-as-read} is non-@code{nil}, mark
+all unpicked articles as read. The default is @code{nil}.
+
+@vindex gnus-summary-pick-line-format
+The summary line format in pick mode is slightly different from the
+standard format. At the beginning of each line the line number is
+displayed. The pick mode line format is controlled by the
+@code{gnus-summary-pick-line-format} variable (@pxref{Formatting
+Variables}). It accepts the same format specs that
+@code{gnus-summary-line-format} does (@pxref{Summary Buffer Lines}).
+
+
+@node Binary Groups
+@subsection Binary Groups
+@cindex binary groups
+
+@findex gnus-binary-mode
+@kindex M-x gnus-binary-mode
+If you spend much time in binary groups, you may grow tired of hitting
+@kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode}
+is a minor mode for summary buffers that makes all ordinary Gnus article
+selection functions uudecode series of articles and display the result
+instead of just displaying the articles the normal way.
+
+@kindex g (Binary)
+@findex gnus-binary-show-article
+The only way, in fact, to see the actual articles is the @kbd{g}
+command, when you have turned on this mode
+(@code{gnus-binary-show-article}).
+
+@vindex gnus-binary-mode-hook
+@code{gnus-binary-mode-hook} is called in binary minor mode buffers.
+
+
+@node Tree Display
+@section Tree Display
+@cindex trees
+
+@vindex gnus-use-trees
+If you don't like the normal Gnus summary display, you might try setting
+@code{gnus-use-trees} to @code{t}. This will create (by default) an
+additional @dfn{tree buffer}. You can execute all summary mode commands
+in the tree buffer.
+
+There are a few variables to customize the tree display, of course:
+
+@table @code
+@item gnus-tree-mode-hook
+@vindex gnus-tree-mode-hook
+A hook called in all tree mode buffers.
+
+@item gnus-tree-mode-line-format
+@vindex gnus-tree-mode-line-format
+A format string for the mode bar in the tree mode buffers (@pxref{Mode
+Line Formatting}). The default is @samp{Gnus: %%b %S %Z}. For a list
+of valid specs, @pxref{Summary Buffer Mode Line}.
+
+@item gnus-selected-tree-face
+@vindex gnus-selected-tree-face
+Face used for highlighting the selected article in the tree buffer. The
+default is @code{modeline}.
+
+@item gnus-tree-line-format
+@vindex gnus-tree-line-format
+A format string for the tree nodes. The name is a bit of a misnomer,
+though---it doesn't define a line, but just the node. The default value
+is @samp{%(%[%3,3n%]%)}, which displays the first three characters of
+the name of the poster. It is vital that all nodes are of the same
+length, so you @emph{must} use @samp{%4,4n}-like specifiers.
+
+Valid specs are:
+
+@table @samp
+@item n
+The name of the poster.
+@item f
+The @code{From} header.
+@item N
+The number of the article.
+@item [
+The opening bracket.
+@item ]
+The closing bracket.
+@item s
+The subject.
+@end table
+
+@xref{Formatting Variables}.
+
+Variables related to the display are:
+
+@table @code
+@item gnus-tree-brackets
+@vindex gnus-tree-brackets
+This is used for differentiating between ``real'' articles and
+``sparse'' articles. The format is @var{((real-open . real-close)
+(sparse-open . sparse-close) (dummy-open . dummy-close))}, and the
+default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}) (?< . ?>))}.
+
+@item gnus-tree-parent-child-edges
+@vindex gnus-tree-parent-child-edges
+This is a list that contains the characters used for connecting parent
+nodes to their children. The default is @code{(?- ?\\ ?|)}.
+
+@end table
+
+@item gnus-tree-minimize-window
+@vindex gnus-tree-minimize-window
+If this variable is non-@code{nil}, Gnus will try to keep the tree
+buffer as small as possible to allow more room for the other Gnus
+windows. If this variable is a number, the tree buffer will never be
+higher than that number. The default is @code{t}. Note that if you
+have several windows displayed side-by-side in a frame and the tree
+buffer is one of these, minimizing the tree window will also resize all
+other windows displayed next to it.
+
+@item gnus-generate-tree-function
+@vindex gnus-generate-tree-function
+@findex gnus-generate-horizontal-tree
+@findex gnus-generate-vertical-tree
+The function that actually generates the thread tree. Two predefined
+functions are available: @code{gnus-generate-horizontal-tree} and
+@code{gnus-generate-vertical-tree} (which is the default).
+
+@end table
+
+Here's an example from a horizontal tree buffer:
+
+@example
+@{***@}-(***)-[odd]-[Gun]
+ | \[Jan]
+ | \[odd]-[Eri]
+ | \(***)-[Eri]
+ | \[odd]-[Paa]
+ \[Bjo]
+ \[Gun]
+ \[Gun]-[Jor]
+@end example
+
+Here's the same thread displayed in a vertical tree buffer:
+
+@example
+@{***@}
+ |--------------------------\-----\-----\
+(***) [Bjo] [Gun] [Gun]
+ |--\-----\-----\ |
+[odd] [Jan] [odd] (***) [Jor]
+ | | |--\
+[Gun] [Eri] [Eri] [odd]
+ |
+ [Paa]
+@end example
+
+If you're using horizontal trees, it might be nice to display the trees
+side-by-side with the summary buffer. You could add something like the
+following to your @file{.gnus.el} file:
+
+@lisp
+(setq gnus-use-trees t
+ gnus-generate-tree-function 'gnus-generate-horizontal-tree
+ gnus-tree-minimize-window nil)
+(gnus-add-configuration
+ '(article
+ (vertical 1.0
+ (horizontal 0.25
+ (summary 0.75 point)
+ (tree 1.0))
+ (article 1.0))))
+@end lisp
+
+@xref{Windows Configuration}.
+
+
+@node Mail Group Commands
+@section Mail Group Commands
+@cindex mail group commands
+
+Some commands only make sense in mail groups. If these commands are
+invalid in the current group, they will raise a hell and let you know.
+
+All these commands (except the expiry and edit commands) use the
+process/prefix convention (@pxref{Process/Prefix}).
+
+@table @kbd
+
+@item B e
+@kindex B e (Summary)
+@findex gnus-summary-expire-articles
+Expire all expirable articles in the group
+(@code{gnus-summary-expire-articles}).
+
+@item B M-C-e
+@kindex B M-C-e (Summary)
+@findex gnus-summary-expire-articles-now
+Delete all the expirable articles in the group
+(@code{gnus-summary-expire-articles-now}). This means that @strong{all}
+articles eligible for expiry in the current group will
+disappear forever into that big @file{/dev/null} in the sky.
+
+@item B DEL
+@kindex B DEL (Summary)
+@findex gnus-summary-delete-article
+@c @icon{gnus-summary-mail-delete}
+Delete the mail article. This is ``delete'' as in ``delete it from your
+disk forever and ever, never to return again.'' Use with caution.
+(@code{gnus-summary-delete-article}).
+
+@item B m
+@kindex B m (Summary)
+@cindex move mail
+@findex gnus-summary-move-article
+Move the article from one mail group to another
+(@code{gnus-summary-move-article}).
+
+@item B c
+@kindex B c (Summary)
+@cindex copy mail
+@findex gnus-summary-copy-article
+@c @icon{gnus-summary-mail-copy}
+Copy the article from one group (mail group or not) to a mail group
+(@code{gnus-summary-copy-article}).
+
+@item B B
+@kindex B B (Summary)
+@cindex crosspost mail
+@findex gnus-summary-crosspost-article
+Crosspost the current article to some other group
+(@code{gnus-summary-crosspost-article}). This will create a new copy of
+the article in the other group, and the Xref headers of the article will
+be properly updated.
+
+@item B i
+@kindex B i (Summary)
+@findex gnus-summary-import-article
+Import an arbitrary file into the current mail newsgroup
+(@code{gnus-summary-import-article}). You will be prompted for a file
+name, a @code{From} header and a @code{Subject} header.
+
+@item B r
+@kindex B r (Summary)
+@findex gnus-summary-respool-article
+Respool the mail article (@code{gnus-summary-respool-article}).
+@code{gnus-summary-respool-default-method} will be used as the default
+select method when respooling. This variable is @code{nil} by default,
+which means that the current group select method will be used instead.
+
+@item B w
+@itemx e
+@kindex B w (Summary)
+@kindex e (Summary)
+@findex gnus-summary-edit-article
+@kindex C-c C-c (Article)
+Edit the current article (@code{gnus-summary-edit-article}). To finish
+editing and make the changes permanent, type @kbd{C-c C-c}
+(@kbd{gnus-summary-edit-article-done}). If you give a prefix to the
+@kbd{C-c C-c} command, Gnus won't re-highlight the article.
+
+@item B q
+@kindex B q (Summary)
+@findex gnus-summary-respool-query
+If you want to re-spool an article, you might be curious as to what group
+the article will end up in before you do the re-spooling. This command
+will tell you (@code{gnus-summary-respool-query}).
+
+@item B t
+@kindex B t (Summary)
+@findex gnus-summary-respool-trace
+Similarly, this command will display all fancy splitting patterns used
+when repooling, if any (@code{gnus-summary-respool-trace}).
+
+@item B p
+@kindex B p (Summary)
+@findex gnus-summary-article-posted-p
+Some people have a tendency to send you "courtesy" copies when they
+follow up to articles you have posted. These usually have a
+@code{Newsgroups} header in them, but not always. This command
+(@code{gnus-summary-article-posted-p}) will try to fetch the current
+article from your news server (or rather, from
+@code{gnus-refer-article-method} or @code{gnus-select-method}) and will
+report back whether it found the article or not. Even if it says that
+it didn't find the article, it may have been posted anyway---mail
+propagation is much faster than news propagation, and the news copy may
+just not have arrived yet.
+
+@end table
+
+@vindex gnus-move-split-methods
+@cindex moving articles
+If you move (or copy) articles regularly, you might wish to have Gnus
+suggest where to put the articles. @code{gnus-move-split-methods} is a
+variable that uses the same syntax as @code{gnus-split-methods}
+(@pxref{Saving Articles}). You may customize that variable to create
+suggestions you find reasonable.
+
+@lisp
+(setq gnus-move-split-methods
+ '(("^From:.*Lars Magne" "nnml:junk")
+ ("^Subject:.*gnus" "nnfolder:important")
+ (".*" "nnml:misc")))
+@end lisp
+
+
+@node Various Summary Stuff
+@section Various Summary Stuff
+
+@menu
+* Summary Group Information:: Information oriented commands.
+* Searching for Articles:: Multiple article commands.
+* Summary Generation Commands:: (Re)generating the summary buffer.
+* Really Various Summary Commands:: Those pesky non-conformant commands.
+@end menu
+
+@table @code
+@vindex gnus-summary-mode-hook
+@item gnus-summary-mode-hook
+This hook is called when creating a summary mode buffer.
+
+@vindex gnus-summary-generate-hook
+@item gnus-summary-generate-hook
+This is called as the last thing before doing the threading and the
+generation of the summary buffer. It's quite convenient for customizing
+the threading variables based on what data the newsgroup has. This hook
+is called from the summary buffer after most summary buffer variables
+have been set.
+
+@vindex gnus-summary-prepare-hook
+@item gnus-summary-prepare-hook
+It is called after the summary buffer has been generated. You might use
+it to, for instance, highlight lines or modify the look of the buffer in
+some other ungodly manner. I don't care.
+
+@vindex gnus-summary-ignore-duplicates
+@item gnus-summary-ignore-duplicates
+When Gnus discovers two articles that have the same @code{Message-ID},
+it has to do something drastic. No articles are allowed to have the
+same @code{Message-ID}, but this may happen when reading mail from some
+sources. Gnus allows you to customize what happens with this variable.
+If it is @code{nil} (which is the default), Gnus will rename the
+@code{Message-ID} (for display purposes only) and display the article as
+any other article. If this variable is @code{t}, it won't display the
+article---it'll be as if it never existed.
+
+@end table
+
+
+@node Summary Group Information
+@subsection Summary Group Information
+
+@table @kbd
+
+@item H f
+@kindex H f (Summary)
+@findex gnus-summary-fetch-faq
+@vindex gnus-group-faq-directory
+Try to fetch the FAQ (list of frequently asked questions) for the
+current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the
+FAQ from @code{gnus-group-faq-directory}, which is usually a directory
+on a remote machine. This variable can also be a list of directories.
+In that case, giving a prefix to this command will allow you to choose
+between the various sites. @code{ange-ftp} or @code{efs} will probably
+be used for fetching the file.
+
+@item H d
+@kindex H d (Summary)
+@findex gnus-summary-describe-group
+Give a brief description of the current group
+(@code{gnus-summary-describe-group}). If given a prefix, force
+rereading the description from the server.
+
+@item H h
+@kindex H h (Summary)
+@findex gnus-summary-describe-briefly
+Give an extremely brief description of the most important summary
+keystrokes (@code{gnus-summary-describe-briefly}).
+
+@item H i
+@kindex H i (Summary)
+@findex gnus-info-find-node
+Go to the Gnus info node (@code{gnus-info-find-node}).
+@end table
+
+
+@node Searching for Articles
+@subsection Searching for Articles
+
+@table @kbd
+
+@item M-s
+@kindex M-s (Summary)
+@findex gnus-summary-search-article-forward
+Search through all subsequent articles for a regexp
+(@code{gnus-summary-search-article-forward}).
+
+@item M-r
+@kindex M-r (Summary)
+@findex gnus-summary-search-article-backward
+Search through all previous articles for a regexp
+(@code{gnus-summary-search-article-backward}).
+
+@item &
+@kindex & (Summary)
+@findex gnus-summary-execute-command
+This command will prompt you for a header field, a regular expression to
+match on this field, and a command to be executed if the match is made
+(@code{gnus-summary-execute-command}). If given a prefix, search
+backward instead.
+
+@item M-&
+@kindex M-& (Summary)
+@findex gnus-summary-universal-argument
+Perform any operation on all articles that have been marked with
+the process mark (@code{gnus-summary-universal-argument}).
+@end table
+
+@node Summary Generation Commands
+@subsection Summary Generation Commands
+
+@table @kbd
+
+@item Y g
+@kindex Y g (Summary)
+@findex gnus-summary-prepare
+Regenerate the current summary buffer (@code{gnus-summary-prepare}).
+
+@item Y c
+@kindex Y c (Summary)
+@findex gnus-summary-insert-cached-articles
+Pull all cached articles (for the current group) into the summary buffer
+(@code{gnus-summary-insert-cached-articles}).
+
+@end table
+
+
+@node Really Various Summary Commands
+@subsection Really Various Summary Commands
+
+@table @kbd
+
+@item C-d
+@kindex C-d (Summary)
+@findex gnus-summary-enter-digest-group
+If the current article is a collection of other articles (for instance,
+a digest), you might use this command to enter a group based on the that
+article (@code{gnus-summary-enter-digest-group}). Gnus will try to
+guess what article type is currently displayed unless you give a prefix
+to this command, which forces a ``digest'' interpretation. Basically,
+whenever you see a message that is a collection of other messages of
+some format, you @kbd{C-d} and read these messages in a more convenient
+fashion.
+
+@item M-C-d
+@kindex M-C-d (Summary)
+@findex gnus-summary-read-document
+This command is very similar to the one above, but lets you gather
+several documents into one biiig group
+(@code{gnus-summary-read-document}). It does this by opening several
+@code{nndoc} groups for each document, and then opening an
+@code{nnvirtual} group on top of these @code{nndoc} groups. This
+command understands the process/prefix convention
+(@pxref{Process/Prefix}).
+
+@item C-t
+@kindex C-t (Summary)
+@findex gnus-summary-toggle-truncation
+Toggle truncation of summary lines
+(@code{gnus-summary-toggle-truncation}). This will probably confuse the
+line centering function in the summary buffer, so it's not a good idea
+to have truncation switched off while reading articles.
+
+@item =
+@kindex = (Summary)
+@findex gnus-summary-expand-window
+Expand the summary buffer window (@code{gnus-summary-expand-window}).
+If given a prefix, force an @code{article} window configuration.
+
+@item M-C-e
+@kindex M-C-e (Summary)
+@findex gnus-summary-edit-parameters
+Edit the group parameters (@pxref{Group Parameters}) of the current
+group (@code{gnus-summary-edit-parameters}).
+
+@end table
+
+
+@node Exiting the Summary Buffer
+@section Exiting the Summary Buffer
+@cindex summary exit
+@cindex exiting groups
+
+Exiting from the summary buffer will normally update all info on the
+group and return you to the group buffer.
+
+@table @kbd
+
+@item Z Z
+@itemx q
+@kindex Z Z (Summary)
+@kindex q (Summary)
+@findex gnus-summary-exit
+@vindex gnus-summary-exit-hook
+@vindex gnus-summary-prepare-exit-hook
+@c @icon{gnus-summary-exit}
+Exit the current group and update all information on the group
+(@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is
+called before doing much of the exiting, which calls
+@code{gnus-summary-expire-articles} by default.
+@code{gnus-summary-exit-hook} is called after finishing the exit
+process. @code{gnus-group-no-more-groups-hook} is run when returning to
+group mode having no more (unread) groups.
+
+@item Z E
+@itemx Q
+@kindex Z E (Summary)
+@kindex Q (Summary)
+@findex gnus-summary-exit-no-update
+Exit the current group without updating any information on the group
+(@code{gnus-summary-exit-no-update}).
+
+@item Z c
+@itemx c
+@kindex Z c (Summary)
+@kindex c (Summary)
+@findex gnus-summary-catchup-and-exit
+@c @icon{gnus-summary-catchup-and-exit}
+Mark all unticked articles in the group as read and then exit
+(@code{gnus-summary-catchup-and-exit}).
+
+@item Z C
+@kindex Z C (Summary)
+@findex gnus-summary-catchup-all-and-exit
+Mark all articles, even the ticked ones, as read and then exit
+(@code{gnus-summary-catchup-all-and-exit}).
+
+@item Z n
+@kindex Z n (Summary)
+@findex gnus-summary-catchup-and-goto-next-group
+Mark all articles as read and go to the next group
+(@code{gnus-summary-catchup-and-goto-next-group}).
+
+@item Z R
+@kindex Z R (Summary)
+@findex gnus-summary-reselect-current-group
+Exit this group, and then enter it again
+(@code{gnus-summary-reselect-current-group}). If given a prefix, select
+all articles, both read and unread.
+
+@item Z G
+@itemx M-g
+@kindex Z G (Summary)
+@kindex M-g (Summary)
+@findex gnus-summary-rescan-group
+@c @icon{gnus-summary-mail-get}
+Exit the group, check for new articles in the group, and select the
+group (@code{gnus-summary-rescan-group}). If given a prefix, select all
+articles, both read and unread.
+
+@item Z N
+@kindex Z N (Summary)
+@findex gnus-summary-next-group
+Exit the group and go to the next group
+(@code{gnus-summary-next-group}).
+
+@item Z P
+@kindex Z P (Summary)
+@findex gnus-summary-prev-group
+Exit the group and go to the previous group
+(@code{gnus-summary-prev-group}).
+
+@item Z s
+@kindex Z s (Summary)
+@findex gnus-summary-save-newsrc
+Save the current number of read/marked articles in the dribble buffer
+and then save the dribble buffer (@code{gnus-summary-save-newsrc}). If
+given a prefix, also save the @file{.newsrc} file(s). Using this
+command will make exit without updating (the @kbd{Q} command) worthless.
+@end table
+
+@vindex gnus-exit-group-hook
+@code{gnus-exit-group-hook} is called when you exit the current
+group.
+
+@findex gnus-summary-wake-up-the-dead
+@findex gnus-dead-summary-mode
+@vindex gnus-kill-summary-on-exit
+If you're in the habit of exiting groups, and then changing your mind
+about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
+If you do that, Gnus won't kill the summary buffer when you exit it.
+(Quelle surprise!) Instead it will change the name of the buffer to
+something like @samp{*Dead Summary ... *} and install a minor mode
+called @code{gnus-dead-summary-mode}. Now, if you switch back to this
+buffer, you'll find that all keys are mapped to a function called
+@code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
+summary buffer will result in a live, normal summary buffer.
+
+There will never be more than one dead summary buffer at any one time.
+
+@vindex gnus-use-cross-reference
+The data on the current group will be updated (which articles you have
+read, which articles you have replied to, etc.) when you exit the
+summary buffer. If the @code{gnus-use-cross-reference} variable is
+@code{t} (which is the default), articles that are cross-referenced to
+this group and are marked as read, will also be marked as read in the
+other subscribed groups they were cross-posted to. If this variable is
+neither @code{nil} nor @code{t}, the article will be marked as read in
+both subscribed and unsubscribed groups (@pxref{Crosspost Handling}).
+
+
+@node Crosspost Handling
+@section Crosspost Handling
+
+@cindex velveeta
+@cindex spamming
+Marking cross-posted articles as read ensures that you'll never have to
+read the same article more than once. Unless, of course, somebody has
+posted it to several groups separately. Posting the same article to
+several groups (not cross-posting) is called @dfn{spamming}, and you are
+by law required to send nasty-grams to anyone who perpetrates such a
+heinous crime. You may want to try NoCeM handling to filter out spam
+(@pxref{NoCeM}).
+
+Remember: Cross-posting is kinda ok, but posting the same article
+separately to several groups is not. Massive cross-posting (aka.
+@dfn{velveeta}) is to be avoided at all costs, and you can even use the
+@code{gnus-summary-mail-crosspost-complaint} command to complain about
+excessive crossposting (@pxref{Summary Mail Commands}).
+
+@cindex cross-posting
+@cindex Xref
+@cindex @sc{nov}
+One thing that may cause Gnus to not do the cross-posting thing
+correctly is if you use an @sc{nntp} server that supports @sc{xover}
+(which is very nice, because it speeds things up considerably) which
+does not include the @code{Xref} header in its @sc{nov} lines. This is
+Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing
+even with @sc{xover} by registering the @code{Xref} lines of all
+articles you actually read, but if you kill the articles, or just mark
+them as read without reading them, Gnus will not get a chance to snoop
+the @code{Xref} lines out of these articles, and will be unable to use
+the cross reference mechanism.
+
+@cindex LIST overview.fmt
+@cindex overview.fmt
+To check whether your @sc{nntp} server includes the @code{Xref} header
+in its overview files, try @samp{telnet your.nntp.server nntp},
+@samp{MODE READER} on @code{inn} servers, and then say @samp{LIST
+overview.fmt}. This may not work, but if it does, and the last line you
+get does not read @samp{Xref:full}, then you should shout and whine at
+your news admin until she includes the @code{Xref} header in the
+overview files.
+
+@vindex gnus-nov-is-evil
+If you want Gnus to get the @code{Xref}s right all the time, you have to
+set @code{gnus-nov-is-evil} to @code{t}, which slows things down
+considerably.
+
+C'est la vie.
+
+For an alternative approach, @pxref{Duplicate Suppression}.
+
+
+@node Duplicate Suppression
+@section Duplicate Suppression
+
+By default, Gnus tries to make sure that you don't have to read the same
+article more than once by utilizing the crossposting mechanism
+(@pxref{Crosspost Handling}). However, that simple and efficient
+approach may not work satisfactory for some users for various
+reasons.
+
+@enumerate
+@item
+The @sc{nntp} server may fail to generate the @code{Xref} header. This
+is evil and not very common.
+
+@item
+The @sc{nntp} server may fail to include the @code{Xref} header in the
+@file{.overview} data bases. This is evil and all too common, alas.
+
+@item
+You may be reading the same group (or several related groups) from
+different @sc{nntp} servers.
+
+@item
+You may be getting mail that duplicates articles posted to groups.
+@end enumerate
+
+I'm sure there are other situations where @code{Xref} handling fails as
+well, but these four are the most common situations.
+
+If, and only if, @code{Xref} handling fails for you, then you may
+consider switching on @dfn{duplicate suppression}. If you do so, Gnus
+will remember the @code{Message-ID}s of all articles you have read or
+otherwise marked as read, and then, as if by magic, mark them as read
+all subsequent times you see them---in @emph{all} groups. Using this
+mechanism is quite likely to be somewhat inefficient, but not overly
+so. It's certainly preferable to reading the same articles more than
+once.
+
+Duplicate suppression is not a very subtle instrument. It's more like a
+sledge hammer than anything else. It works in a very simple
+fashion---if you have marked an article as read, it adds this Message-ID
+to a cache. The next time it sees this Message-ID, it will mark the
+article as read with the @samp{M} mark. It doesn't care what group it
+saw the article in.
+
+@table @code
+@item gnus-suppress-duplicates
+@vindex gnus-suppress-duplicates
+If non-@code{nil}, suppress duplicates.
+
+@item gnus-save-duplicate-list
+@vindex gnus-save-duplicate-list
+If non-@code{nil}, save the list of duplicates to a file. This will
+make startup and shutdown take longer, so the default is @code{nil}.
+However, this means that only duplicate articles read in a single Gnus
+session are suppressed.
+
+@item gnus-duplicate-list-length
+@vindex gnus-duplicate-list-length
+This variable says how many @code{Message-ID}s to keep in the duplicate
+suppression list. The default is 10000.
+
+@item gnus-duplicate-file
+@vindex gnus-duplicate-file
+The name of the file to store the duplicate suppression list in. The
+default is @file{~/News/suppression}.
+@end table
+
+If you have a tendency to stop and start Gnus often, setting
+@code{gnus-save-duplicate-list} to @code{t} is probably a good idea. If
+you leave Gnus running for weeks on end, you may have it @code{nil}. On
+the other hand, saving the list makes startup and shutdown much slower,
+so that means that if you stop and start Gnus often, you should set
+@code{gnus-save-duplicate-list} to @code{nil}. Uhm. I'll leave this up
+to you to figure out, I think.
+
+
+@node The Article Buffer
+@chapter The Article Buffer
+@cindex article buffer
+
+The articles are displayed in the article buffer, of which there is only
+one. All the summary buffers share the same article buffer unless you
+tell Gnus otherwise.
+
+@menu
+* Hiding Headers:: Deciding what headers should be displayed.
+* Using MIME:: Pushing articles through @sc{mime} before reading them.
+* Customizing Articles:: Tailoring the look of the articles.
+* Article Keymap:: Keystrokes available in the article buffer.
+* Misc Article:: Other stuff.
+@end menu
+
+
+@node Hiding Headers
+@section Hiding Headers
+@cindex hiding headers
+@cindex deleting headers
+
+The top section of each article is the @dfn{head}. (The rest is the
+@dfn{body}, but you may have guessed that already.)
+
+@vindex gnus-show-all-headers
+There is a lot of useful information in the head: the name of the person
+who wrote the article, the date it was written and the subject of the
+article. That's well and nice, but there's also lots of information
+most people do not want to see---what systems the article has passed
+through before reaching you, the @code{Message-ID}, the
+@code{References}, etc. ad nauseum---and you'll probably want to get rid
+of some of those lines. If you want to keep all those lines in the
+article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
+
+Gnus provides you with two variables for sifting headers:
+
+@table @code
+
+@item gnus-visible-headers
+@vindex gnus-visible-headers
+If this variable is non-@code{nil}, it should be a regular expression
+that says what headers you wish to keep in the article buffer. All
+headers that do not match this variable will be hidden.
+
+For instance, if you only want to see the name of the person who wrote
+the article and the subject, you'd say:
+
+@lisp
+(setq gnus-visible-headers "^From:\\|^Subject:")
+@end lisp
+
+This variable can also be a list of regexps to match headers to
+remain visible.
+
+@item gnus-ignored-headers
+@vindex gnus-ignored-headers
+This variable is the reverse of @code{gnus-visible-headers}. If this
+variable is set (and @code{gnus-visible-headers} is @code{nil}), it
+should be a regular expression that matches all lines that you want to
+hide. All lines that do not match this variable will remain visible.
+
+For instance, if you just want to get rid of the @code{References} line
+and the @code{Xref} line, you might say:
+
+@lisp
+(setq gnus-ignored-headers "^References:\\|^Xref:")
+@end lisp
+
+This variable can also be a list of regexps to match headers to
+be removed.
+
+Note that if @code{gnus-visible-headers} is non-@code{nil}, this
+variable will have no effect.
+
+@end table
+
+@vindex gnus-sorted-header-list
+Gnus can also sort the headers for you. (It does this by default.) You
+can control the sorting by setting the @code{gnus-sorted-header-list}
+variable. It is a list of regular expressions that says in what order
+the headers are to be displayed.
+
+For instance, if you want the name of the author of the article first,
+and then the subject, you might say something like:
+
+@lisp
+(setq gnus-sorted-header-list '("^From:" "^Subject:"))
+@end lisp
+
+Any headers that are to remain visible, but are not listed in this
+variable, will be displayed in random order after all the headers listed in this variable.
+
+@findex gnus-article-hide-boring-headers
+@vindex gnus-article-display-hook
+@vindex gnus-boring-article-headers
+You can hide further boring headers by entering
+@code{gnus-article-hide-boring-headers} into
+@code{gnus-article-display-hook}. What this function does depends on
+the @code{gnus-boring-article-headers} variable. It's a list, but this
+list doesn't actually contain header names. Instead is lists various
+@dfn{boring conditions} that Gnus can check and remove from sight.
+
+These conditions are:
+@table @code
+@item empty
+Remove all empty headers.
+@item followup-to
+Remove the @code{Followup-To} header if it is identical to the
+@code{Newsgroups} header.
+@item reply-to
+Remove the @code{Reply-To} header if it lists the same address as the
+@code{From} header.
+@item newsgroups
+Remove the @code{Newsgroups} header if it only contains the current group
+name.
+@item date
+Remove the @code{Date} header if the article is less than three days
+old.
+@item long-to
+Remove the @code{To} header if it is very long.
+@item many-to
+Remove all @code{To} headers if there are more than one.
+@end table
+
+To include the four three elements, you could say something like;
+
+@lisp
+(setq gnus-boring-article-headers
+ '(empty followup-to reply-to))
+@end lisp
+
+This is also the default value for this variable.
+
+
+@node Using MIME
+@section Using @sc{mime}
+@cindex @sc{mime}
+
+Mime is a standard for waving your hands through the air, aimlessly,
+while people stand around yawning.
+
+@sc{mime}, however, is a standard for encoding your articles, aimlessly,
+while all newsreaders die of fear.
+
+@sc{mime} may specify what character set the article uses, the encoding
+of the characters, and it also makes it possible to embed pictures and
+other naughty stuff in innocent-looking articles.
+
+@vindex gnus-show-mime
+@vindex gnus-show-mime-method
+@vindex gnus-strict-mime
+@findex metamail-buffer
+Gnus handles @sc{mime} by pushing the articles through
+@code{gnus-show-mime-method}, which is @code{metamail-buffer} by
+default. This function calls the external @code{metamail} program to
+actually do the work. One common problem with this program is that is
+thinks that it can't display 8-bit things in the Emacs buffer. To tell
+it the truth, put something like the following in your
+@file{.bash_profile} file. (You do use @code{bash}, don't you?)
+
+@example
+export MM_CHARSET="iso-8859-1"
+@end example
+
+For more information on @code{metamail}, see its manual page.
+
+Set @code{gnus-show-mime} to @code{t} if you want to use
+@sc{mime} all the time. However, if @code{gnus-strict-mime} is
+non-@code{nil}, the @sc{mime} method will only be used if there are
+@sc{mime} headers in the article. If you have @code{gnus-show-mime}
+set, then you'll see some unfortunate display glitches in the article
+buffer. These can't be avoided.
+
+It might be best to just use the toggling functions from the summary
+buffer to avoid getting nasty surprises. (For instance, you enter the
+group @samp{alt.sing-a-long} and, before you know it, @sc{mime} has
+decoded the sound file in the article and some horrible sing-a-long song
+comes screaming out your speakers, and you can't find the volume
+button, because there isn't one, and people are starting to look at you,
+and you try to stop the program, but you can't, and you can't find the
+program to control the volume, and everybody else in the room suddenly
+decides to look at you disdainfully, and you'll feel rather stupid.)
+
+Any similarity to real events and people is purely coincidental. Ahem.
+
+
+@node Customizing Articles
+@section Customizing Articles
+@cindex article customization
+
+@vindex gnus-article-display-hook
+The @code{gnus-article-display-hook} is called after the article has
+been inserted into the article buffer. It is meant to handle all
+treatment of the article before it is displayed.
+
+@findex gnus-article-maybe-highlight
+@findex gnus-article-maybe-hide-headers
+By default this hook just contains
+@code{gnus-article-maybe-hide-headers},
+@code{gnus-hide-boring-headers}, @code{gnus-article-treat-overstrike},
+and @code{gnus-article-maybe-highlight} (and under XEmacs,
+@code{gnus-article-display-x-face}), but there are thousands, nay
+millions, of functions you can put in this hook. For an overview of
+functions @pxref{Article Highlighting}, @pxref{Article Hiding},
+@pxref{Article Washing}, @pxref{Article Buttons} and @pxref{Article
+Date}. Note that the order of functions in this hook might affect
+things, so you may have to fiddle a bit to get the desired results.
+
+You can, of course, write your own functions. The functions are called
+from the article buffer, and you can do anything you like, pretty much.
+There is no information that you have to keep in the buffer---you can
+change everything. However, you shouldn't delete any headers. Instead
+make them invisible if you want to make them go away.
+
+
+@node Article Keymap
+@section Article Keymap
+
+Most of the keystrokes in the summary buffer can also be used in the
+article buffer. They should behave as if you typed them in the summary
+buffer, which means that you don't actually have to have a summary
+buffer displayed while reading. You can do it all from the article
+buffer.
+
+A few additional keystrokes are available:
+
+@table @kbd
+
+@item SPACE
+@kindex SPACE (Article)
+@findex gnus-article-next-page
+Scroll forwards one page (@code{gnus-article-next-page}).
+
+@item DEL
+@kindex DEL (Article)
+@findex gnus-article-prev-page
+Scroll backwards one page (@code{gnus-article-prev-page}).
+
+@item C-c ^
+@kindex C-c ^ (Article)
+@findex gnus-article-refer-article
+If point is in the neighborhood of a @code{Message-ID} and you press
+@kbd{C-c ^}, Gnus will try to get that article from the server
+(@code{gnus-article-refer-article}).
+
+@item C-c C-m
+@kindex C-c C-m (Article)
+@findex gnus-article-mail
+Send a reply to the address near point (@code{gnus-article-mail}). If
+given a prefix, include the mail.
+
+@item s
+@kindex s (Article)
+@findex gnus-article-show-summary
+Reconfigure the buffers so that the summary buffer becomes visible
+(@code{gnus-article-show-summary}).
+
+@item ?
+@kindex ? (Article)
+@findex gnus-article-describe-briefly
+Give a very brief description of the available keystrokes
+(@code{gnus-article-describe-briefly}).
+
+@item TAB
+@kindex TAB (Article)
+@findex gnus-article-next-button
+Go to the next button, if any (@code{gnus-article-next-button}). This
+only makes sense if you have buttonizing turned on.
+
+@item M-TAB
+@kindex M-TAB (Article)
+@findex gnus-article-prev-button
+Go to the previous button, if any (@code{gnus-article-prev-button}).
+
+@end table
+
+
+@node Misc Article
+@section Misc Article
+
+@table @code
+
+@item gnus-single-article-buffer
+@vindex gnus-single-article-buffer
+If non-@code{nil}, use the same article buffer for all the groups.
+(This is the default.) If @code{nil}, each group will have its own
+article buffer.
+
+@vindex gnus-article-prepare-hook
+@item gnus-article-prepare-hook
+This hook is called right after the article has been inserted into the
+article buffer. It is mainly intended for functions that do something
+depending on the contents; it should probably not be used for changing
+the contents of the article buffer.
+
+@vindex gnus-article-display-hook
+@item gnus-article-display-hook
+This hook is called as the last thing when displaying an article, and is
+intended for modifying the contents of the buffer, doing highlights,
+hiding headers, and the like.
+
+@item gnus-article-mode-hook
+@vindex gnus-article-mode-hook
+Hook called in article mode buffers.
+
+@item gnus-article-mode-syntax-table
+@vindex gnus-article-mode-syntax-table
+Syntax table used in article buffers. It is initialized from
+@code{text-mode-syntax-table}.
+
+@vindex gnus-article-mode-line-format
+@item gnus-article-mode-line-format
+This variable is a format string along the same lines as
+@code{gnus-summary-mode-line-format} (@pxref{Mode Line Formatting}). It
+accepts the same format specifications as that variable, with one
+extension:
+
+@table @samp
+@item w
+The @dfn{wash status} of the article. This is a short string with one
+character for each possible article wash operation that may have been
+performed.
+@end table
+
+@vindex gnus-break-pages
+
+@item gnus-break-pages
+Controls whether @dfn{page breaking} is to take place. If this variable
+is non-@code{nil}, the articles will be divided into pages whenever a
+page delimiter appears in the article. If this variable is @code{nil},
+paging will not be done.
+
+@item gnus-page-delimiter
+@vindex gnus-page-delimiter
+This is the delimiter mentioned above. By default, it is @samp{^L}
+(formfeed).
+@end table
+
+
+@node Composing Messages
+@chapter Composing Messages
+@cindex composing messages
+@cindex messages
+@cindex mail
+@cindex sending mail
+@cindex reply
+@cindex followup
+@cindex post
+
+@kindex C-c C-c (Post)
+All commands for posting and mailing will put you in a message buffer
+where you can edit the article all you like, before you send the article
+by pressing @kbd{C-c C-c}. @xref{Top, , Top, message, The Message
+Manual}. If you are in a foreign news group, and you wish to post the
+article using the foreign server, you can give a prefix to @kbd{C-c C-c}
+to make Gnus try to post using the foreign server.
+
+@menu
+* Mail:: Mailing and replying.
+* Post:: Posting and following up.
+* Posting Server:: What server should you post via?
+* Mail and Post:: Mailing and posting at the same time.
+* Archived Messages:: Where Gnus stores the messages you've sent.
+* Posting Styles:: An easier way to specify who you are.
+* Drafts:: Postponing messages and rejected messages.
+* Rejected Articles:: What happens if the server doesn't like your article?
+@end menu
+
+Also see @pxref{Canceling and Superseding} for information on how to
+remove articles you shouldn't have posted.
+
+
+@node Mail
+@section Mail
+
+Variables for customizing outgoing mail:
+
+@table @code
+@item gnus-uu-digest-headers
+@vindex gnus-uu-digest-headers
+List of regexps to match headers included in digested messages. The
+headers will be included in the sequence they are matched.
+
+@item gnus-add-to-list
+@vindex gnus-add-to-list
+If non-@code{nil}, add a @code{to-list} group parameter to mail groups
+that have none when you do a @kbd{a}.
+
+@end table
+
+
+@node Post
+@section Post
+
+Variables for composing news articles:
+
+@table @code
+@item gnus-sent-message-ids-file
+@vindex gnus-sent-message-ids-file
+Gnus will keep a @code{Message-ID} history file of all the mails it has
+sent. If it discovers that it has already sent a mail, it will ask the
+user whether to re-send the mail. (This is primarily useful when
+dealing with @sc{soup} packets and the like where one is apt to send the
+same packet multiple times.) This variable says what the name of this
+history file is. It is @file{~/News/Sent-Message-IDs} by default. Set
+this variable to @code{nil} if you don't want Gnus to keep a history
+file.
+
+@item gnus-sent-message-ids-length
+@vindex gnus-sent-message-ids-length
+This variable says how many @code{Message-ID}s to keep in the history
+file. It is 1000 by default.
+
+@end table
+
+
+@node Posting Server
+@section Posting Server
+
+When you press those magical @kbd{C-c C-c} keys to ship off your latest
+(extremely intelligent, of course) article, where does it go?
+
+Thank you for asking. I hate you.
+
+@vindex gnus-post-method
+
+It can be quite complicated. Normally, Gnus will use the same native
+server. However. If your native server doesn't allow posting, just
+reading, you probably want to use some other server to post your
+(extremely intelligent and fabulously interesting) articles. You can
+then set the @code{gnus-post-method} to some other method:
+
+@lisp
+(setq gnus-post-method '(nnspool ""))
+@end lisp
+
+Now, if you've done this, and then this server rejects your article, or
+this server is down, what do you do then? To override this variable you
+can use a non-zero prefix to the @kbd{C-c C-c} command to force using
+the ``current'' server for posting.
+
+If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command,
+Gnus will prompt you for what method to use for posting.
+
+You can also set @code{gnus-post-method} to a list of select methods.
+If that's the case, Gnus will always prompt you for what method to use
+for posting.
+
+Finally, if you want to always post using the same select method as
+you're reading from (which might be convenient if you're reading lots of
+groups from different private servers), you can set this variable to
+@code{current}.
+
+
+@node Mail and Post
+@section Mail and Post
+
+Here's a list of variables relevant to both mailing and
+posting:
+
+@table @code
+@item gnus-mailing-list-groups
+@findex gnus-mailing-list-groups
+@cindex mailing lists
+
+If your news server offers groups that are really mailing lists
+gatewayed to the @sc{nntp} server, you can read those groups without
+problems, but you can't post/followup to them without some difficulty.
+One solution is to add a @code{to-address} to the group parameters
+(@pxref{Group Parameters}). An easier thing to do is set the
+@code{gnus-mailing-list-groups} to a regexp that matches the groups that
+really are mailing lists. Then, at least, followups to the mailing
+lists will work most of the time. Posting to these groups (@kbd{a}) is
+still a pain, though.
+
+@end table
+
+You may want to do spell-checking on messages that you send out. Or, if
+you don't want to spell-check by hand, you could add automatic
+spell-checking via the @code{ispell} package:
+
+@cindex ispell
+@findex ispell-message
+@lisp
+(add-hook 'message-send-hook 'ispell-message)
+@end lisp
+
+
+@node Archived Messages
+@section Archived Messages
+@cindex archived messages
+@cindex sent messages
+
+Gnus provides a few different methods for storing the mail and news you
+send. The default method is to use the @dfn{archive virtual server} to
+store the messages. If you want to disable this completely, the
+@code{gnus-message-archive-group} variable should be @code{nil}, which
+is the default.
+
+@vindex gnus-message-archive-method
+@code{gnus-message-archive-method} says what virtual server Gnus is to
+use to store sent messages. The default is:
+
+@lisp
+(nnfolder "archive"
+ (nnfolder-directory "~/Mail/archive")
+ (nnfolder-active-file "~/Mail/archive/active")
+ (nnfolder-get-new-mail nil)
+ (nnfolder-inhibit-expiry t))
+@end lisp
+
+You can, however, use any mail select method (@code{nnml},
+@code{nnmbox}, etc.). @code{nnfolder} is a quite likeable select method
+for doing this sort of thing, though. If you don't like the default
+directory chosen, you could say something like:
+
+@lisp
+(setq gnus-message-archive-method
+ '(nnfolder "archive"
+ (nnfolder-inhibit-expiry t)
+ (nnfolder-active-file "~/News/sent-mail/active")
+ (nnfolder-directory "~/News/sent-mail/")))
+@end lisp
+
+@vindex gnus-message-archive-group
+@cindex Gcc
+Gnus will insert @code{Gcc} headers in all outgoing messages that point
+to one or more group(s) on that server. Which group to use is
+determined by the @code{gnus-message-archive-group} variable.
+
+This variable can be used to do the following:
+
+@itemize @bullet
+@item a string
+Messages will be saved in that group.
+@item a list of strings
+Messages will be saved in all those groups.
+@item an alist of regexps, functions and forms
+When a key ``matches'', the result is used.
+@item @code{nil}
+No message archiving will take place. This is the default.
+@end itemize
+
+Let's illustrate:
+
+Just saving to a single group called @samp{MisK}:
+@lisp
+(setq gnus-message-archive-group "MisK")
+@end lisp
+
+Saving to two groups, @samp{MisK} and @samp{safe}:
+@lisp
+(setq gnus-message-archive-group '("MisK" "safe"))
+@end lisp
+
+Save to different groups based on what group you are in:
+@lisp
+(setq gnus-message-archive-group
+ '(("^alt" "sent-to-alt")
+ ("mail" "sent-to-mail")
+ (".*" "sent-to-misc")))
+@end lisp
+
+More complex stuff:
+@lisp
+(setq gnus-message-archive-group
+ '((if (message-news-p)
+ "misc-news"
+ "misc-mail")))
+@end lisp
+
+How about storing all news messages in one file, but storing all mail
+messages in one file per month:
+
+@lisp
+(setq gnus-message-archive-group
+ '((if (message-news-p)
+ "misc-news"
+ (concat "mail." (format-time-string
+ "%Y-%m" (current-time))))))
+@end lisp
+
+(XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to
+use a different value for @code{gnus-message-archive-group} there.)
+
+Now, when you send a message off, it will be stored in the appropriate
+group. (If you want to disable storing for just one particular message,
+you can just remove the @code{Gcc} header that has been inserted.) The
+archive group will appear in the group buffer the next time you start
+Gnus, or the next time you press @kbd{F} in the group buffer. You can
+enter it and read the articles in it just like you'd read any other
+group. If the group gets really big and annoying, you can simply rename
+if (using @kbd{G r} in the group buffer) to something
+nice---@samp{misc-mail-september-1995}, or whatever. New messages will
+continue to be stored in the old (now empty) group.
+
+That's the default method of archiving sent messages. Gnus offers a
+different way for the people who don't like the default method. In that
+case you should set @code{gnus-message-archive-group} to @code{nil};
+this will disable archiving.
+
+@table @code
+@item gnus-outgoing-message-group
+@vindex gnus-outgoing-message-group
+All outgoing messages will be put in this group. If you want to store
+all your outgoing mail and articles in the group @samp{nnml:archive},
+you set this variable to that value. This variable can also be a list of
+group names.
+
+If you want to have greater control over what group to put each
+message in, you can set this variable to a function that checks the
+current newsgroup name and then returns a suitable group name (or list
+of names).
+
+This variable can be used instead of @code{gnus-message-archive-group},
+but the latter is the preferred method.
+@end table
+
+
+@node Posting Styles
+@section Posting Styles
+@cindex posting styles
+@cindex styles
+
+All them variables, they make my head swim.
+
+So what if you want a different @code{Organization} and signature based
+on what groups you post to? And you post both from your home machine
+and your work machine, and you want different @code{From} lines, and so
+on?
+
+@vindex gnus-posting-styles
+One way to do stuff like that is to write clever hooks that change the
+variables you need to have changed. That's a bit boring, so somebody
+came up with the bright idea of letting the user specify these things in
+a handy alist. Here's an example of a @code{gnus-posting-styles}
+variable:
+
+@lisp
+((".*"
+ (signature "Peace and happiness")
+ (organization "What me?"))
+ ("^comp"
+ (signature "Death to everybody"))
+ ("comp.emacs.i-love-it"
+ (organization "Emacs is it")))
+@end lisp
+
+As you might surmise from this example, this alist consists of several
+@dfn{styles}. Each style will be applicable if the first element
+``matches'', in some form or other. The entire alist will be iterated
+over, from the beginning towards the end, and each match will be
+applied, which means that attributes in later styles that match override
+the same attributes in earlier matching styles. So
+@samp{comp.programming.literate} will have the @samp{Death to everybody}
+signature and the @samp{What me?} @code{Organization} header.
+
+The first element in each style is called the @code{match}. If it's a
+string, then Gnus will try to regexp match it against the group name.
+If it's a function symbol, that function will be called with no
+arguments. If it's a variable symbol, then the variable will be
+referenced. If it's a list, then that list will be @code{eval}ed. In
+any case, if this returns a non-@code{nil} value, then the style is said
+to @dfn{match}.
+
+Each style may contain a arbitrary amount of @dfn{attributes}. Each
+attribute consists of a @var{(name . value)} pair. The attribute name
+can be one of @code{signature}, @code{signature-file},
+@code{organization}, @code{address}, @code{name} or @code{body}. The
+attribute name can also be a string. In that case, this will be used as
+a header name, and the value will be inserted in the headers of the
+article.
+
+The attribute value can be a string (used verbatim), a function (the
+return value will be used), a variable (its value will be used) or a
+list (it will be @code{eval}ed and the return value will be used).
+
+If you wish to check whether the message you are about to compose is
+meant to be a news article or a mail message, you can check the values
+of the two dynamically bound variables @code{message-this-is-news} and
+@code{message-this-is-mail}.
+
+@vindex message-this-is-mail
+@vindex message-this-is-news
+
+So here's a new example:
+
+@lisp
+(setq gnus-posting-styles
+ '((".*"
+ (signature-file "~/.signature")
+ (name "User Name")
+ ("X-Home-Page" (getenv "WWW_HOME"))
+ (organization "People's Front Against MWM"))
+ ("^rec.humor"
+ (signature my-funny-signature-randomizer))
+ ((equal (system-name) "gnarly")
+ (signature my-quote-randomizer))
+ (message-this-is-news
+ (signature my-news-signature))
+ (posting-from-work-p
+ (signature-file "~/.work-signature")
+ (address "user@@bar.foo")
+ (body "You are fired.\n\nSincerely, your boss.")
+ (organization "Important Work, Inc"))
+ ("^nn.+:"
+ (signature-file "~/.mail-signature"))))
+@end lisp
+
+
+@node Drafts
+@section Drafts
+@cindex drafts
+
+If you are writing a message (mail or news) and suddenly remember that
+you have a steak in the oven (or some pesto in the food processor, you
+craaazy vegetarians), you'll probably wish there was a method to save
+the message you are writing so that you can continue editing it some
+other day, and send it when you feel its finished.
+
+Well, don't worry about it. Whenever you start composing a message of
+some sort using the Gnus mail and post commands, the buffer you get will
+automatically associate to an article in a special @dfn{draft} group.
+If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the
+article will be saved there. (Auto-save files also go to the draft
+group.)
+
+@cindex nndraft
+@vindex nndraft-directory
+The draft group is a special group (which is implemented as an
+@code{nndraft} group, if you absolutely have to know) called
+@samp{nndraft:drafts}. The variable @code{nndraft-directory} says where
+@code{nndraft} is to store its files. What makes this group special is
+that you can't tick any articles in it or mark any articles as
+read---all articles in the group are permanently unread.
+
+If the group doesn't exist, it will be created and you'll be subscribed
+to it. The only way to make it disappear from the Group buffer is to
+unsubscribe it.
+
+@c @findex gnus-dissociate-buffer-from-draft
+@c @kindex C-c M-d (Mail)
+@c @kindex C-c M-d (Post)
+@c @findex gnus-associate-buffer-with-draft
+@c @kindex C-c C-d (Mail)
+@c @kindex C-c C-d (Post)
+@c If you're writing some super-secret message that you later want to
+@c encode with PGP before sending, you may wish to turn the auto-saving
+@c (and association with the draft group) off. You never know who might be
+@c interested in reading all your extremely valuable and terribly horrible
+@c and interesting secrets. The @kbd{C-c M-d}
+@c (@code{gnus-dissociate-buffer-from-draft}) command does that for you.
+@c If you change your mind and want to turn the auto-saving back on again,
+@c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that.
+@c
+@c @vindex gnus-use-draft
+@c To leave association with the draft group off by default, set
+@c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default.
+
+@findex gnus-draft-edit-message
+@kindex D e (Draft)
+When you want to continue editing the article, you simply enter the
+draft group and push @kbd{D e} (@code{gnus-draft-edit-message}) to do
+that. You will be placed in a buffer where you left off.
+
+Rejected articles will also be put in this draft group (@pxref{Rejected
+Articles}).
+
+@findex gnus-draft-send-all-messages
+@findex gnus-draft-send-message
+If you have lots of rejected messages you want to post (or mail) without
+doing further editing, you can use the @kbd{D s} command
+(@code{gnus-draft-send-message}). This command understands the
+process/prefix convention (@pxref{Process/Prefix}). The @kbd{D S}
+command (@code{gnus-draft-send-all-messages}) will ship off all messages
+in the buffer.
+
+If you have some messages that you wish not to send, you can use the
+@kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message
+as unsendable. This is a toggling command.
+
+
+@node Rejected Articles
+@section Rejected Articles
+@cindex rejected articles
+
+Sometimes a news server will reject an article. Perhaps the server
+doesn't like your face. Perhaps it just feels miserable. Perhaps
+@emph{there be demons}. Perhaps you have included too much cited text.
+Perhaps the disk is full. Perhaps the server is down.
+
+These situations are, of course, totally beyond the control of Gnus.
+(Gnus, of course, loves the way you look, always feels great, has angels
+fluttering around inside of it, doesn't care about how much cited text
+you include, never runs full and never goes down.) So Gnus saves these
+articles until some later time when the server feels better.
+
+The rejected articles will automatically be put in a special draft group
+(@pxref{Drafts}). When the server comes back up again, you'd then
+typically enter that group and send all the articles off.
+
+
+@node Select Methods
+@chapter Select Methods
+@cindex foreign groups
+@cindex select methods
+
+A @dfn{foreign group} is a group not read by the usual (or
+default) means. It could be, for instance, a group from a different
+@sc{nntp} server, it could be a virtual group, or it could be your own
+personal mail group.
+
+A foreign group (or any group, really) is specified by a @dfn{name} and
+a @dfn{select method}. To take the latter first, a select method is a
+list where the first element says what backend to use (e.g. @code{nntp},
+@code{nnspool}, @code{nnml}) and the second element is the @dfn{server
+name}. There may be additional elements in the select method, where the
+value may have special meaning for the backend in question.
+
+One could say that a select method defines a @dfn{virtual server}---so
+we do just that (@pxref{The Server Buffer}).
+
+The @dfn{name} of the group is the name the backend will recognize the
+group as.
+
+For instance, the group @samp{soc.motss} on the @sc{nntp} server
+@samp{some.where.edu} will have the name @samp{soc.motss} and select
+method @code{(nntp "some.where.edu")}. Gnus will call this group
+@samp{nntp+some.where.edu:soc.motss}, even though the @code{nntp}
+backend just knows this group as @samp{soc.motss}.
+
+The different methods all have their peculiarities, of course.
+
+@menu
+* The Server Buffer:: Making and editing virtual servers.
+* Getting News:: Reading USENET news with Gnus.
+* Getting Mail:: Reading your personal mail with Gnus.
+* Other Sources:: Reading directories, files, SOUP packets.
+* Combined Groups:: Combining groups into one group.
+* Gnus Unplugged:: Reading news and mail offline.
+@end menu
+
+
+@node The Server Buffer
+@section The Server Buffer
+
+Traditionally, a @dfn{server} is a machine or a piece of software that
+one connects to, and then requests information from. Gnus does not
+connect directly to any real servers, but does all transactions through
+one backend or other. But that's just putting one layer more between
+the actual media and Gnus, so we might just as well say that each
+backend represents a virtual server.
+
+For instance, the @code{nntp} backend may be used to connect to several
+different actual @sc{nntp} servers, or, perhaps, to many different ports
+on the same actual @sc{nntp} server. You tell Gnus which backend to
+use, and what parameters to set by specifying a @dfn{select method}.
+
+These select method specifications can sometimes become quite
+complicated---say, for instance, that you want to read from the
+@sc{nntp} server @samp{news.funet.fi} on port number 13, which
+hangs if queried for @sc{nov} headers and has a buggy select. Ahem.
+Anyways, if you had to specify that for each group that used this
+server, that would be too much work, so Gnus offers a way of naming
+select methods, which is what you do in the server buffer.
+
+To enter the server buffer, use the @kbd{^}
+(@code{gnus-group-enter-server-mode}) command in the group buffer.
+
+@menu
+* Server Buffer Format:: You can customize the look of this buffer.
+* Server Commands:: Commands to manipulate servers.
+* Example Methods:: Examples server specifications.
+* Creating a Virtual Server:: An example session.
+* Server Variables:: Which variables to set.
+* Servers and Methods:: You can use server names as select methods.
+* Unavailable Servers:: Some servers you try to contact may be down.
+@end menu
+
+@vindex gnus-server-mode-hook
+@code{gnus-server-mode-hook} is run when creating the server buffer.
+
+
+@node Server Buffer Format
+@subsection Server Buffer Format
+@cindex server buffer format
+
+@vindex gnus-server-line-format
+You can change the look of the server buffer lines by changing the
+@code{gnus-server-line-format} variable. This is a @code{format}-like
+variable, with some simple extensions:
+
+@table @samp
+
+@item h
+How the news is fetched---the backend name.
+
+@item n
+The name of this server.
+
+@item w
+Where the news is to be fetched from---the address.
+
+@item s
+The opened/closed/denied status of the server.
+@end table
+
+@vindex gnus-server-mode-line-format
+The mode line can also be customized by using the
+@code{gnus-server-mode-line-format} variable (@pxref{Mode Line
+Formatting}). The following specs are understood:
+
+@table @samp
+@item S
+Server name.
+
+@item M
+Server method.
+@end table
+
+Also @pxref{Formatting Variables}.
+
+
+@node Server Commands
+@subsection Server Commands
+@cindex server commands
+
+@table @kbd
+
+@item a
+@kindex a (Server)
+@findex gnus-server-add-server
+Add a new server (@code{gnus-server-add-server}).
+
+@item e
+@kindex e (Server)
+@findex gnus-server-edit-server
+Edit a server (@code{gnus-server-edit-server}).
+
+@item SPACE
+@kindex SPACE (Server)
+@findex gnus-server-read-server
+Browse the current server (@code{gnus-server-read-server}).
+
+@item q
+@kindex q (Server)
+@findex gnus-server-exit
+Return to the group buffer (@code{gnus-server-exit}).
+
+@item k
+@kindex k (Server)
+@findex gnus-server-kill-server
+Kill the current server (@code{gnus-server-kill-server}).
+
+@item y
+@kindex y (Server)
+@findex gnus-server-yank-server
+Yank the previously killed server (@code{gnus-server-yank-server}).
+
+@item c
+@kindex c (Server)
+@findex gnus-server-copy-server
+Copy the current server (@code{gnus-server-copy-server}).
+
+@item l
+@kindex l (Server)
+@findex gnus-server-list-servers
+List all servers (@code{gnus-server-list-servers}).
+
+@item s
+@kindex s (Server)
+@findex gnus-server-scan-server
+Request that the server scan its sources for new articles
+(@code{gnus-server-scan-server}). This is mainly sensible with mail
+servers.
+
+@item g
+@kindex g (Server)
+@findex gnus-server-regenerate-server
+Request that the server regenerate all its data structures
+(@code{gnus-server-regenerate-server}). This can be useful if you have
+a mail backend that has gotten out of synch.
+
+@end table
+
+
+@node Example Methods
+@subsection Example Methods
+
+Most select methods are pretty simple and self-explanatory:
+
+@lisp
+(nntp "news.funet.fi")
+@end lisp
+
+Reading directly from the spool is even simpler:
+
+@lisp
+(nnspool "")
+@end lisp
+
+As you can see, the first element in a select method is the name of the
+backend, and the second is the @dfn{address}, or @dfn{name}, if you
+will.
+
+After these two elements, there may be an arbitrary number of
+@var{(variable form)} pairs.
+
+To go back to the first example---imagine that you want to read from
+port 15 on that machine. This is what the select method should
+look like then:
+
+@lisp
+(nntp "news.funet.fi" (nntp-port-number 15))
+@end lisp
+
+You should read the documentation to each backend to find out what
+variables are relevant, but here's an @code{nnmh} example:
+
+@code{nnmh} is a mail backend that reads a spool-like structure. Say
+you have two structures that you wish to access: One is your private
+mail spool, and the other is a public one. Here's the possible spec for
+your private mail:
+
+@lisp
+(nnmh "private" (nnmh-directory "~/private/mail/"))
+@end lisp
+
+(This server is then called @samp{private}, but you may have guessed
+that.)
+
+Here's the method for a public spool:
+
+@lisp
+(nnmh "public"
+ (nnmh-directory "/usr/information/spool/")
+ (nnmh-get-new-mail nil))
+@end lisp
+
+If you are behind a firewall and only have access to the @sc{nntp}
+server from the firewall machine, you can instruct Gnus to @code{rlogin}
+on the firewall machine and telnet from there to the @sc{nntp} server.
+Doing this can be rather fiddly, but your virtual server definition
+should probably look something like this:
+
+@lisp
+(nntp "firewall"
+ (nntp-address "the.firewall.machine")
+ (nntp-open-connection-function nntp-open-rlogin)
+ (nntp-end-of-line "\n")
+ (nntp-rlogin-parameters
+ ("telnet" "the.real.nntp.host" "nntp")))
+@end lisp
+
+If you want to use the wonderful @code{ssh} program to provide a
+compressed connection over the modem line, you could create a virtual
+server that would look something like this:
+
+@lisp
+(nntp "news"
+ (nntp-address "copper.uio.no")
+ (nntp-rlogin-program "ssh")
+ (nntp-open-connection-function nntp-open-rlogin)
+ (nntp-end-of-line "\n")
+ (nntp-rlogin-parameters
+ ("telnet" "news.uio.no" "nntp")))
+@end lisp
+
+This means that you have to have set up @code{ssh-agent} correctly to
+provide automatic authorization, of course. And to get a compressed
+connection, you have to have the @samp{Compression} option in the
+@code{ssh} @file{config} file.
+
+
+@node Creating a Virtual Server
+@subsection Creating a Virtual Server
+
+If you're saving lots of articles in the cache by using persistent
+articles, you may want to create a virtual server to read the cache.
+
+First you need to add a new server. The @kbd{a} command does that. It
+would probably be best to use @code{nnspool} to read the cache. You
+could also use @code{nnml} or @code{nnmh}, though.
+
+Type @kbd{a nnspool RET cache RET}.
+
+You should now have a brand new @code{nnspool} virtual server called
+@samp{cache}. You now need to edit it to have the right definitions.
+Type @kbd{e} to edit the server. You'll be entered into a buffer that
+will contain the following:
+
+@lisp
+(nnspool "cache")
+@end lisp
+
+Change that to:
+
+@lisp
+(nnspool "cache"
+ (nnspool-spool-directory "~/News/cache/")
+ (nnspool-nov-directory "~/News/cache/")
+ (nnspool-active-file "~/News/cache/active"))
+@end lisp
+
+Type @kbd{C-c C-c} to return to the server buffer. If you now press
+@kbd{RET} over this virtual server, you should be entered into a browse
+buffer, and you should be able to enter any of the groups displayed.
+
+
+@node Server Variables
+@subsection Server Variables
+
+One sticky point when defining variables (both on backends and in Emacs
+in general) is that some variables are typically initialized from other
+variables when the definition of the variables is being loaded. If you
+change the "base" variable after the variables have been loaded, you
+won't change the "derived" variables.
+
+This typically affects directory and file variables. For instance,
+@code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml}
+directory variables are initialized from that variable, so
+@code{nnml-active-file} will be @file{~/Mail/active}. If you define a
+new virtual @code{nnml} server, it will @emph{not} suffice to set just
+@code{nnml-directory}---you have to explicitly set all the file
+variables to be what you want them to be. For a complete list of
+variables for each backend, see each backend's section later in this
+manual, but here's an example @code{nnml} definition:
+
+@lisp
+(nnml "public"
+ (nnml-directory "~/my-mail/")
+ (nnml-active-file "~/my-mail/active")
+ (nnml-newsgroups-file "~/my-mail/newsgroups"))
+@end lisp
+
+
+@node Servers and Methods
+@subsection Servers and Methods
+
+Wherever you would normally use a select method
+(e.g. @code{gnus-secondary-select-method}, in the group select method,
+when browsing a foreign server) you can use a virtual server name
+instead. This could potentially save lots of typing. And it's nice all
+over.
+
+
+@node Unavailable Servers
+@subsection Unavailable Servers
+
+If a server seems to be unreachable, Gnus will mark that server as
+@code{denied}. That means that any subsequent attempt to make contact
+with that server will just be ignored. ``It can't be opened,'' Gnus
+will tell you, without making the least effort to see whether that is
+actually the case or not.
+
+That might seem quite naughty, but it does make sense most of the time.
+Let's say you have 10 groups subscribed to on server
+@samp{nephelococcygia.com}. This server is located somewhere quite far
+away from you and the machine is quite slow, so it takes 1 minute just
+to find out that it refuses connection to you today. If Gnus were to
+attempt to do that 10 times, you'd be quite annoyed, so Gnus won't
+attempt to do that. Once it has gotten a single ``connection refused'',
+it will regard that server as ``down''.
+
+So, what happens if the machine was only feeling unwell temporarily?
+How do you test to see whether the machine has come up again?
+
+You jump to the server buffer (@pxref{The Server Buffer}) and poke it
+with the following commands:
+
+@table @kbd
+
+@item O
+@kindex O (Server)
+@findex gnus-server-open-server
+Try to establish connection to the server on the current line
+(@code{gnus-server-open-server}).
+
+@item C
+@kindex C (Server)
+@findex gnus-server-close-server
+Close the connection (if any) to the server
+(@code{gnus-server-close-server}).
+
+@item D
+@kindex D (Server)
+@findex gnus-server-deny-server
+Mark the current server as unreachable
+(@code{gnus-server-deny-server}).
+
+@item M-o
+@kindex M-o (Server)
+@findex gnus-server-open-all-servers
+Open the connections to all servers in the buffer
+(@code{gnus-server-open-all-servers}).
+
+@item M-c
+@kindex M-c (Server)
+@findex gnus-server-close-all-servers
+Close the connections to all servers in the buffer
+(@code{gnus-server-close-all-servers}).
+
+@item R
+@kindex R (Server)
+@findex gnus-server-remove-denials
+Remove all marks to whether Gnus was denied connection from any servers
+(@code{gnus-server-remove-denials}).
+
+@end table
+
+
+@node Getting News
+@section Getting News
+@cindex reading news
+@cindex news backends
+
+A newsreader is normally used for reading news. Gnus currently provides
+only two methods of getting news---it can read from an @sc{nntp} server,
+or it can read from a local spool.
+
+@menu
+* NNTP:: Reading news from an @sc{nntp} server.
+* News Spool:: Reading news from the local spool.
+@end menu
+
+
+@node NNTP
+@subsection @sc{nntp}
+@cindex nntp
+
+Subscribing to a foreign group from an @sc{nntp} server is rather easy.
+You just specify @code{nntp} as method and the address of the @sc{nntp}
+server as the, uhm, address.
+
+If the @sc{nntp} server is located at a non-standard port, setting the
+third element of the select method to this port number should allow you
+to connect to the right port. You'll have to edit the group info for
+that (@pxref{Foreign Groups}).
+
+The name of the foreign group can be the same as a native group. In
+fact, you can subscribe to the same group from as many different servers
+you feel like. There will be no name collisions.
+
+The following variables can be used to create a virtual @code{nntp}
+server:
+
+@table @code
+
+@item nntp-server-opened-hook
+@vindex nntp-server-opened-hook
+@cindex @sc{mode reader}
+@cindex authinfo
+@cindex authentification
+@cindex nntp authentification
+@findex nntp-send-authinfo
+@findex nntp-send-mode-reader
+is run after a connection has been made. It can be used to send
+commands to the @sc{nntp} server after it has been contacted. By
+default it sends the command @code{MODE READER} to the server with the
+@code{nntp-send-mode-reader} function. This function should always be
+present in this hook.
+
+@item nntp-authinfo-function
+@vindex nntp-authinfo-function
+@findex nntp-send-authinfo
+@vindex nntp-authinfo-file
+This function will be used to send @samp{AUTHINFO} to the @sc{nntp}
+server. The default function is @code{nntp-send-authinfo}, which looks
+through your @file{~/.authinfo} (or whatever you've set the
+@code{nntp-authinfo-file} variable to) for applicable entries. If none
+are found, it will prompt you for a login name and a password. The
+format of the @file{~/.authinfo} file is (almost) the same as the
+@code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp}
+manual page, but here are the salient facts:
+
+@enumerate
+@item
+The file contains one or more line, each of which define one server.
+
+@item
+Each line may contain an arbitrary number of token/value pairs. The
+valid tokens include @samp{machine}, @samp{login}, @samp{password},
+@samp{default} and @samp{force}. (The latter is not a valid
+@file{.netrc}/@code{ftp} token, which is the only way the
+@file{.authinfo} file format deviates from the @file{.netrc} file
+format.)
+
+@end enumerate
+
+Here's an example file:
+
+@example
+machine news.uio.no login larsi password geheimnis
+machine nntp.ifi.uio.no login larsi force yes
+@end example
+
+The token/value pairs may appear in any order; @samp{machine} doesn't
+have to be first, for instance.
+
+In this example, both login name and password have been supplied for the
+former server, while the latter has only the login name listed, and the
+user will be prompted for the password. The latter also has the
+@samp{force} tag, which means that the authinfo will be sent to the
+@var{nntp} server upon connection; the default (i.e., when there is not
+@samp{force} tag) is to not send authinfo to the @var{nntp} server
+until the @var{nntp} server asks for it.
+
+You can also add @samp{default} lines that will apply to all servers
+that don't have matching @samp{machine} lines.
+
+@example
+default force yes
+@end example
+
+This will force sending @samp{AUTHINFO} commands to all servers not
+previously mentioned.
+
+Remember to not leave the @file{~/.authinfo} file world-readable.
+
+@item nntp-server-action-alist
+@vindex nntp-server-action-alist
+This is a list of regexps to match on server types and actions to be
+taken when matches are made. For instance, if you want Gnus to beep
+every time you connect to innd, you could say something like:
+
+@lisp
+(setq nntp-server-action-alist
+ '(("innd" (ding))))
+@end lisp
+
+You probably don't want to do that, though.
+
+The default value is
+
+@lisp
+'(("nntpd 1\\.5\\.11t"
+ (remove-hook 'nntp-server-opened-hook 'nntp-send-mode-reader)))
+@end lisp
+
+This ensures that Gnus doesn't send the @code{MODE READER} command to
+nntpd 1.5.11t, since that command chokes that server, I've been told.
+
+@item nntp-maximum-request
+@vindex nntp-maximum-request
+If the @sc{nntp} server doesn't support @sc{nov} headers, this backend
+will collect headers by sending a series of @code{head} commands. To
+speed things up, the backend sends lots of these commands without
+waiting for reply, and then reads all the replies. This is controlled
+by the @code{nntp-maximum-request} variable, and is 400 by default. If
+your network is buggy, you should set this to 1.
+
+@item nntp-connection-timeout
+@vindex nntp-connection-timeout
+If you have lots of foreign @code{nntp} groups that you connect to
+regularly, you're sure to have problems with @sc{nntp} servers not
+responding properly, or being too loaded to reply within reasonable
+time. This is can lead to awkward problems, which can be helped
+somewhat by setting @code{nntp-connection-timeout}. This is an integer
+that says how many seconds the @code{nntp} backend should wait for a
+connection before giving up. If it is @code{nil}, which is the default,
+no timeouts are done.
+
+@c @item nntp-command-timeout
+@c @vindex nntp-command-timeout
+@c @cindex PPP connections
+@c @cindex dynamic IP addresses
+@c If you're running Gnus on a machine that has a dynamically assigned
+@c address, Gnus may become confused. If the address of your machine
+@c changes after connecting to the @sc{nntp} server, Gnus will simply sit
+@c waiting forever for replies from the server. To help with this
+@c unfortunate problem, you can set this command to a number. Gnus will
+@c then, if it sits waiting for a reply from the server longer than that
+@c number of seconds, shut down the connection, start a new one, and resend
+@c the command. This should hopefully be transparent to the user. A
+@c likely number is 30 seconds.
+@c
+@c @item nntp-retry-on-break
+@c @vindex nntp-retry-on-break
+@c If this variable is non-@code{nil}, you can also @kbd{C-g} if Gnus
+@c hangs. This will have much the same effect as the command timeout
+@c described above.
+
+@item nntp-server-hook
+@vindex nntp-server-hook
+This hook is run as the last step when connecting to an @sc{nntp}
+server.
+
+@findex nntp-open-rlogin
+@findex nntp-open-telnet
+@findex nntp-open-network-stream
+@item nntp-open-connection-function
+@vindex nntp-open-connection-function
+This function is used to connect to the remote system. Four pre-made
+functions are supplied:
+
+@table @code
+@item nntp-open-network-stream
+This is the default, and simply connects to some port or other on the
+remote system.
+
+@item nntp-open-rlogin
+Does an @samp{rlogin} on the
+remote system, and then does a @samp{telnet} to the @sc{nntp} server
+available there.
+
+@code{nntp-open-rlogin}-related variables:
+
+@table @code
+
+@item nntp-rlogin-program
+@vindex nntp-rlogin-program
+Program used to log in on remote machines. The default is @samp{rsh},
+but @samp{ssh} is a popular alternative.
+
+@item nntp-rlogin-parameters
+@vindex nntp-rlogin-parameters
+This list will be used as the parameter list given to @code{rsh}.
+
+@item nntp-rlogin-user-name
+@vindex nntp-rlogin-user-name
+User name on the remote system.
+
+@end table
+
+@item nntp-open-telnet
+Does a @samp{telnet} to the remote system and then another @samp{telnet}
+to get to the @sc{nntp} server.
+
+@code{nntp-open-telnet}-related variables:
+
+@table @code
+@item nntp-telnet-command
+@vindex nntp-telnet-command
+Command used to start @code{telnet}.
+
+@item nntp-telnet-switches
+@vindex nntp-telnet-switches
+List of strings to be used as the switches to the @code{telnet} command.
+
+@item nntp-telnet-user-name
+@vindex nntp-telnet-user-name
+User name for log in on the remote system.
+
+@item nntp-telnet-passwd
+@vindex nntp-telnet-passwd
+Password to use when logging in.
+
+@item nntp-telnet-parameters
+@vindex nntp-telnet-parameters
+A list of strings executed as a command after logging in
+via @code{telnet}.
+
+@item nntp-telnet-shell-prompt
+@vindex nntp-telnet-shell-prompt
+Regexp matching the shell prompt on the remote machine. The default is
+@samp{bash\\|\$ *\r?$\\|> *\r?}.
+
+@item nntp-open-telnet-envuser
+@vindex nntp-open-telnet-envuser
+If non-@code{nil}, the @code{telnet} session (client and server both)
+will support the @code{ENVIRON} option and not prompt for login name.
+This works for Solaris @code{telnet}, for instance.
+
+@end table
+
+@findex nntp-open-ssl-stream
+@item nntp-open-ssl-stream
+Opens a connection to a server over a @dfn{secure} channel. To use this
+you must have SSLay installed
+(@file{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL}, and you also need
+@file{ssl.el} (from the W3 distributeion, for instance). You then
+define a server as follows:
+
+@lisp
+;; Type `C-c C-c' after you've finished editing.
+;;
+;; "snews" is port 563 and is predefined in our /etc/services
+;;
+(nntp "snews.bar.com"
+ (nntp-open-connection-function nntp-open-ssl-stream)
+ (nntp-port-number "snews")
+ (nntp-address "snews.bar.com"))
+@end lisp
+
+@end table
+
+@item nntp-end-of-line
+@vindex nntp-end-of-line
+String to use as end-of-line marker when talking to the @sc{nntp}
+server. This is @samp{\r\n} by default, but should be @samp{\n} when
+using @code{rlogin} to talk to the server.
+
+@item nntp-rlogin-user-name
+@vindex nntp-rlogin-user-name
+User name on the remote system when using the @code{rlogin} connect
+function.
+
+@item nntp-address
+@vindex nntp-address
+The address of the remote system running the @sc{nntp} server.
+
+@item nntp-port-number
+@vindex nntp-port-number
+Port number to connect to when using the @code{nntp-open-network-stream}
+connect function.
+
+@item nntp-buggy-select
+@vindex nntp-buggy-select
+Set this to non-@code{nil} if your select routine is buggy.
+
+@item nntp-nov-is-evil
+@vindex nntp-nov-is-evil
+If the @sc{nntp} server does not support @sc{nov}, you could set this
+variable to @code{t}, but @code{nntp} usually checks automatically whether @sc{nov}
+can be used.
+
+@item nntp-xover-commands
+@vindex nntp-xover-commands
+@cindex nov
+@cindex XOVER
+List of strings used as commands to fetch @sc{nov} lines from a
+server. The default value of this variable is @code{("XOVER"
+"XOVERVIEW")}.
+
+@item nntp-nov-gap
+@vindex nntp-nov-gap
+@code{nntp} normally sends just one big request for @sc{nov} lines to
+the server. The server responds with one huge list of lines. However,
+if you have read articles 2-5000 in the group, and only want to read
+article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
+lines that you will not need. This variable says how
+big a gap between two consecutive articles is allowed to be before the
+@code{XOVER} request is split into several request. Note that if your
+network is fast, setting this variable to a really small number means
+that fetching will probably be slower. If this variable is @code{nil},
+@code{nntp} will never split requests. The default is 5.
+
+@item nntp-prepare-server-hook
+@vindex nntp-prepare-server-hook
+A hook run before attempting to connect to an @sc{nntp} server.
+
+@item nntp-warn-about-losing-connection
+@vindex nntp-warn-about-losing-connection
+If this variable is non-@code{nil}, some noise will be made when a
+server closes connection.
+
+@item nntp-record-commands
+@vindex nntp-record-commands
+If non-@code{nil}, @code{nntp} will log all commands it sends to the
+@sc{nntp} server (along with a timestep) in the @samp{*nntp-log*}
+buffer. This is useful if you are debugging a Gnus/@sc{nntp} connection
+that doesn't seem to work.
+
+@end table
+
+
+@node News Spool
+@subsection News Spool
+@cindex nnspool
+@cindex news spool
+
+Subscribing to a foreign group from the local spool is extremely easy,
+and might be useful, for instance, to speed up reading groups that
+contain very big articles---@samp{alt.binaries.pictures.furniture}, for
+instance.
+
+Anyways, you just specify @code{nnspool} as the method and @code{""} (or
+anything else) as the address.
+
+If you have access to a local spool, you should probably use that as the
+native select method (@pxref{Finding the News}). It is normally faster
+than using an @code{nntp} select method, but might not be. It depends.
+You just have to try to find out what's best at your site.
+
+@table @code
+
+@item nnspool-inews-program
+@vindex nnspool-inews-program
+Program used to post an article.
+
+@item nnspool-inews-switches
+@vindex nnspool-inews-switches
+Parameters given to the inews program when posting an article.
+
+@item nnspool-spool-directory
+@vindex nnspool-spool-directory
+Where @code{nnspool} looks for the articles. This is normally
+@file{/usr/spool/news/}.
+
+@item nnspool-nov-directory
+@vindex nnspool-nov-directory
+Where @code{nnspool} will look for @sc{nov} files. This is normally
+@file{/usr/spool/news/over.view/}.
+
+@item nnspool-lib-dir
+@vindex nnspool-lib-dir
+Where the news lib dir is (@file{/usr/lib/news/} by default).
+
+@item nnspool-active-file
+@vindex nnspool-active-file
+The path to the active file.
+
+@item nnspool-newsgroups-file
+@vindex nnspool-newsgroups-file
+The path to the group descriptions file.
+
+@item nnspool-history-file
+@vindex nnspool-history-file
+The path to the news history file.
+
+@item nnspool-active-times-file
+@vindex nnspool-active-times-file
+The path to the active date file.
+
+@item nnspool-nov-is-evil
+@vindex nnspool-nov-is-evil
+If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files
+that it finds.
+
+@item nnspool-sift-nov-with-sed
+@vindex nnspool-sift-nov-with-sed
+@cindex sed
+If non-@code{nil}, which is the default, use @code{sed} to get the
+relevant portion from the overview file. If nil, @code{nnspool} will
+load the entire file into a buffer and process it there.
+
+@end table
+
+
+@node Getting Mail
+@section Getting Mail
+@cindex reading mail
+@cindex mail
+
+Reading mail with a newsreader---isn't that just plain WeIrD? But of
+course.
+
+@menu
+* Getting Started Reading Mail:: A simple cookbook example.
+* Splitting Mail:: How to create mail groups.
+* Mail Backend Variables:: Variables for customizing mail handling.
+* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail.
+* Mail and Procmail:: Reading mail groups that procmail create.
+* Incorporating Old Mail:: What about the old mail you have?
+* Expiring Mail:: Getting rid of unwanted mail.
+* Washing Mail:: Removing gruft from the mail you get.
+* Duplicates:: Dealing with duplicated mail.
+* Not Reading Mail:: Using mail backends for reading other files.
+* Choosing a Mail Backend:: Gnus can read a variety of mail formats.
+@end menu
+
+
+@node Getting Started Reading Mail
+@subsection Getting Started Reading Mail
+
+It's quite easy to use Gnus to read your new mail. You just plonk the
+mail backend of your choice into @code{gnus-secondary-select-methods},
+and things will happen automatically.
+
+For instance, if you want to use @code{nnml} (which is a "one file per
+mail" backend), you could put the following in your @file{.gnus} file:
+
+@lisp
+(setq gnus-secondary-select-methods
+ '((nnml "private")))
+@end lisp
+
+Now, the next time you start Gnus, this backend will be queried for new
+articles, and it will move all the messages in your spool file to its
+directory, which is @code{~/Mail/} by default. The new group that will
+be created (@samp{mail.misc}) will be subscribed, and you can read it
+like any other group.
+
+You will probably want to split the mail into several groups, though:
+
+@lisp
+(setq nnmail-split-methods
+ '(("junk" "^From:.*Lars Ingebrigtsen")
+ ("crazy" "^Subject:.*die\\|^Organization:.*flabby")
+ ("other" "")))
+@end lisp
+
+This will result in three new @code{nnml} mail groups being created:
+@samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the
+mail that doesn't fit into the first two groups will be placed in the
+last group.
+
+This should be sufficient for reading mail with Gnus. You might want to
+give the other sections in this part of the manual a perusal, though.
+Especially @pxref{Choosing a Mail Backend} and @pxref{Expiring Mail}.
+
+
+@node Splitting Mail
+@subsection Splitting Mail
+@cindex splitting mail
+@cindex mail splitting
+
+@vindex nnmail-split-methods
+The @code{nnmail-split-methods} variable says how the incoming mail is
+to be split into groups.
+
+@lisp
+(setq nnmail-split-methods
+ '(("mail.junk" "^From:.*Lars Ingebrigtsen")
+ ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby")
+ ("mail.other" "")))
+@end lisp
+
+This variable is a list of lists, where the first element of each of
+these lists is the name of the mail group (they do not have to be called
+something beginning with @samp{mail}, by the way), and the second
+element is a regular expression used on the header of each mail to
+determine if it belongs in this mail group. The first string may
+contain @samp{\\1} forms, like the ones used by @code{replace-match} to
+insert sub-expressions from the matched text. For instance:
+
+@lisp
+("list.\\1" "From:.*\\(.*\\)-list@@majordomo.com")
+@end lisp
+
+The second element can also be a function. In that case, it will be
+called narrowed to the headers with the first element of the rule as the
+argument. It should return a non-@code{nil} value if it thinks that the
+mail belongs in that group.
+
+The last of these groups should always be a general one, and the regular
+expression should @emph{always} be @samp{} so that it matches any mails
+that haven't been matched by any of the other regexps. (These rules are
+processed from the beginning of the alist toward the end. The first
+rule to make a match will "win", unless you have crossposting enabled.
+In that case, all matching rules will "win".)
+
+If you like to tinker with this yourself, you can set this variable to a
+function of your choice. This function will be called without any
+arguments in a buffer narrowed to the headers of an incoming mail
+message. The function should return a list of group names that it
+thinks should carry this mail message.
+
+Note that the mail backends are free to maul the poor, innocent,
+incoming headers all they want to. They all add @code{Lines} headers;
+some add @code{X-Gnus-Group} headers; most rename the Unix mbox
+@code{From<SPACE>} line to something else.
+
+@vindex nnmail-crosspost
+The mail backends all support cross-posting. If several regexps match,
+the mail will be ``cross-posted'' to all those groups.
+@code{nnmail-crosspost} says whether to use this mechanism or not. Note
+that no articles are crossposted to the general (@samp{}) group.
+
+@vindex nnmail-crosspost-link-function
+@cindex crosspost
+@cindex links
+@code{nnmh} and @code{nnml} makes crossposts by creating hard links to
+the crossposted articles. However, not all file systems support hard
+links. If that's the case for you, set
+@code{nnmail-crosspost-link-function} to @code{copy-file}. (This
+variable is @code{add-name-to-file} by default.)
+
+@kindex M-x nnmail-split-history
+@kindex nnmail-split-history
+If you wish to see where the previous mail split put the messages, you
+can use the @kbd{M-x nnmail-split-history} command.
+
+Gnus gives you all the opportunity you could possibly want for shooting
+yourself in the foot. Let's say you create a group that will contain
+all the mail you get from your boss. And then you accidentally
+unsubscribe from the group. Gnus will still put all the mail from your
+boss in the unsubscribed group, and so, when your boss mails you ``Have
+that report ready by Monday or you're fired!'', you'll never see it and,
+come Tuesday, you'll still believe that you're gainfully employed while
+you really should be out collecting empty bottles to save up for next
+month's rent money.
+
+
+@node Mail Backend Variables
+@subsection Mail Backend Variables
+
+These variables are (for the most part) pertinent to all the various
+mail backends.
+
+@table @code
+@vindex nnmail-read-incoming-hook
+@item nnmail-read-incoming-hook
+The mail backends all call this hook after reading new mail. You can
+use this hook to notify any mail watch programs, if you want to.
+
+@vindex nnmail-spool-file
+@item nnmail-spool-file
+@cindex POP mail
+@cindex MAILHOST
+@cindex movemail
+@vindex nnmail-pop-password
+@vindex nnmail-pop-password-required
+The backends will look for new mail in this file. If this variable is
+@code{nil}, the mail backends will never attempt to fetch mail by
+themselves. If you are using a POP mail server and your name is
+@samp{larsi}, you should set this variable to @samp{po:larsi}. If
+your name is not @samp{larsi}, you should probably modify that
+slightly, but you may have guessed that already, you smart & handsome
+devil! You can also set this variable to @code{pop}, and Gnus will try
+to figure out the POP mail string by itself. In any case, Gnus will
+call @code{movemail} which will contact the POP server named in the
+@code{MAILHOST} environment variable. If the POP server needs a
+password, you can either set @code{nnmail-pop-password-required} to
+@code{t} and be prompted for the password, or set
+@code{nnmail-pop-password} to the password itself.
+
+@code{nnmail-spool-file} can also be a list of mailboxes.
+
+Your Emacs has to have been configured with @samp{--with-pop} before
+compilation. This is the default, but some installations have it
+switched off.
+
+When you use a mail backend, Gnus will slurp all your mail from your
+inbox and plonk it down in your home directory. Gnus doesn't move any
+mail if you're not using a mail backend---you have to do a lot of magic
+invocations first. At the time when you have finished drawing the
+pentagram, lightened the candles, and sacrificed the goat, you really
+shouldn't be too surprised when Gnus moves your mail.
+
+@vindex nnmail-use-procmail
+@vindex nnmail-procmail-suffix
+@item nnmail-use-procmail
+If non-@code{nil}, the mail backends will look in
+@code{nnmail-procmail-directory} for incoming mail. All the files in
+that directory that have names ending in @code{nnmail-procmail-suffix}
+will be considered incoming mailboxes, and will be searched for new
+mail.
+
+@vindex nnmail-crash-box
+@item nnmail-crash-box
+When a mail backend reads a spool file, mail is first moved to this
+file, which is @file{~/.gnus-crash-box} by default. If this file
+already exists, it will always be read (and incorporated) before any
+other spool files.
+
+@vindex nnmail-prepare-incoming-hook
+@item nnmail-prepare-incoming-hook
+This is run in a buffer that holds all the new incoming mail, and can be
+used for, well, anything, really.
+
+@vindex nnmail-split-hook
+@item nnmail-split-hook
+@findex article-decode-rfc1522
+@findex RFC1522 decoding
+Hook run in the buffer where the mail headers of each message is kept
+just before the splitting based on these headers is done. The hook is
+free to modify the buffer contents in any way it sees fit---the buffer
+is discarded after the splitting has been done, and no changes performed
+in the buffer will show up in any files. @code{gnus-article-decode-rfc1522}
+is one likely function to add to this hook.
+
+@vindex nnmail-pre-get-new-mail-hook
+@vindex nnmail-post-get-new-mail-hook
+@item nnmail-pre-get-new-mail-hook
+@itemx nnmail-post-get-new-mail-hook
+These are two useful hooks executed when treating new incoming
+mail---@code{nnmail-pre-get-new-mail-hook} (is called just before
+starting to handle the new mail) and
+@code{nnmail-post-get-new-mail-hook} (is called when the mail handling
+is done). Here's and example of using these two hooks to change the
+default file modes the new mail files get:
+
+@lisp
+(add-hook 'gnus-pre-get-new-mail-hook
+ (lambda () (set-default-file-modes 511)))
+
+(add-hook 'gnus-post-get-new-mail-hook
+ (lambda () (set-default-file-modes 551)))
+@end lisp
+
+@item nnmail-tmp-directory
+@vindex nnmail-tmp-directory
+This variable says where to move incoming mail to -- while processing
+it. This is usually done in the same directory that the mail backend
+inhabits (e.g., @file{~/Mail/}), but if this variable is non-@code{nil},
+it will be used instead.
+
+@item nnmail-movemail-program
+@vindex nnmail-movemail-program
+This program is executed to move mail from the user's inbox to her home
+directory. The default is @samp{movemail}.
+
+This can also be a function. In that case, the function will be called
+with two parameters -- the name of the inbox, and the file to be moved
+to.
+
+@item nnmail-delete-incoming
+@vindex nnmail-delete-incoming
+@cindex incoming mail files
+@cindex deleting incoming files
+If non-@code{nil}, the mail backends will delete the temporary incoming
+file after splitting mail into the proper groups. This is @code{t} by
+default.
+
+@c This is @code{nil} by
+@c default for reasons of security.
+
+@c Since Red Gnus is an alpha release, it is to be expected to lose mail.
+(No Gnus release since (ding) Gnus 0.10 (or something like that) have
+lost mail, I think, but that's not the point. (Except certain versions
+of Red Gnus.)) By not deleting the Incoming* files, one can be sure not
+to lose mail -- if Gnus totally whacks out, one can always recover what
+was lost.
+
+You may delete the @file{Incoming*} files at will.
+
+@item nnmail-use-long-file-names
+@vindex nnmail-use-long-file-names
+If non-@code{nil}, the mail backends will use long file and directory
+names. Groups like @samp{mail.misc} will end up in directories
+(assuming use of @code{nnml} backend) or files (assuming use of
+@code{nnfolder} backend) like @file{mail.misc}. If it is @code{nil},
+the same group will end up in @file{mail/misc}.
+
+@item nnmail-delete-file-function
+@vindex nnmail-delete-file-function
+@findex delete-file
+Function called to delete files. It is @code{delete-file} by default.
+
+@item nnmail-cache-accepted-message-ids
+@vindex nnmail-cache-accepted-message-ids
+If non-@code{nil}, put the @code{Message-ID}s of articles imported into
+the backend (via @code{Gcc}, for instance) into the mail duplication
+discovery cache. The default is @code{nil}.
+
+@end table
+
+
+@node Fancy Mail Splitting
+@subsection Fancy Mail Splitting
+@cindex mail splitting
+@cindex fancy mail splitting
+
+@vindex nnmail-split-fancy
+@findex nnmail-split-fancy
+If the rather simple, standard method for specifying how to split mail
+doesn't allow you to do what you want, you can set
+@code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can
+play with the @code{nnmail-split-fancy} variable.
+
+Let's look at an example value of this variable first:
+
+@lisp
+;; Messages from the mailer daemon are not crossposted to any of
+;; the ordinary groups. Warnings are put in a separate group
+;; from real errors.
+(| ("from" mail (| ("subject" "warn.*" "mail.warning")
+ "mail.misc"))
+ ;; Non-error messages are crossposted to all relevant
+ ;; groups, but we don't crosspost between the group for the
+ ;; (ding) list and the group for other (ding) related mail.
+ (& (| (any "ding@@ifi\\.uio\\.no" "ding.list")
+ ("subject" "ding" "ding.misc"))
+ ;; Other mailing lists...
+ (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
+ (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
+ ;; People...
+ (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen"))
+ ;; Unmatched mail goes to the catch all group.
+ "misc.misc")
+@end lisp
+
+This variable has the format of a @dfn{split}. A split is a (possibly)
+recursive structure where each split may contain other splits. Here are
+the five possible split syntaxes:
+
+@enumerate
+
+@item
+@samp{group}: If the split is a string, that will be taken as a group
+name. Normal regexp match expansion will be done. See below for
+examples.
+
+@item
+@var{(FIELD VALUE SPLIT)}: If the split is a list, the first element of
+which is a string, then store the message as specified by SPLIT, if
+header FIELD (a regexp) contains VALUE (also a regexp).
+
+@item
+@var{(| SPLIT...)}: If the split is a list, and the first element is
+@code{|} (vertical bar), then process each SPLIT until one of them
+matches. A SPLIT is said to match if it will cause the mail message to
+be stored in one or more groups.
+
+@item
+@var{(& SPLIT...)}: If the split is a list, and the first element is
+@code{&}, then process all SPLITs in the list.
+
+@item
+@code{junk}: If the split is the symbol @code{junk}, then don't save
+this message. Use with extreme caution.
+
+@item
+@var{(: function arg1 arg2 ...)}: If the split is a list, and the first
+element is @code{:}, then the second element will be called as a
+function with @var{args} given as arguments. The function should return
+a SPLIT.
+
+@item
+@code{nil}: If the split is @code{nil}, it is ignored.
+
+@end enumerate
+
+In these splits, @var{FIELD} must match a complete field name.
+@var{VALUE} must match a complete word according to the fundamental mode
+syntax table. You can use @code{.*} in the regexps to match partial
+field names or words. In other words, all @var{VALUE}'s are wrapped in
+@samp{\<} and @samp{\>} pairs.
+
+@vindex nnmail-split-abbrev-alist
+@var{FIELD} and @var{VALUE} can also be lisp symbols, in that case they
+are expanded as specified by the variable
+@code{nnmail-split-abbrev-alist}. This is an alist of cons cells, where
+the @code{car} of a cell contains the key, and the @code{cdr} contains the associated
+value.
+
+@vindex nnmail-split-fancy-syntax-table
+@code{nnmail-split-fancy-syntax-table} is the syntax table in effect
+when all this splitting is performed.
+
+If you want to have Gnus create groups dynamically based on some
+information in the headers (i.e., do @code{replace-match}-like
+substitutions in the group names), you can say things like:
+
+@example
+(any "debian-\\b\\(\\w+\\)@@lists.debian.org" "mail.debian.\\1")
+@end example
+
+If the string contains the element @samp{\&}, then the previously
+matched string will be substituted. Similarly, the elements @samp{\\1}
+up to @samp{\\9} will be substituted with the text matched by the
+groupings 1 through 9.
+
+
+@node Mail and Procmail
+@subsection Mail and Procmail
+@cindex procmail
+
+@cindex slocal
+@cindex elm
+Many people use @code{procmail} (or some other mail filter program or
+external delivery agent---@code{slocal}, @code{elm}, etc) to split
+incoming mail into groups. If you do that, you should set
+@code{nnmail-spool-file} to @code{procmail} to ensure that the mail
+backends never ever try to fetch mail by themselves.
+
+If you have a combined @code{procmail}/POP/mailbox setup, you can do
+something like the following:
+
+@vindex nnmail-use-procmail
+@lisp
+(setq nnmail-use-procmail t)
+(setq nnmail-spool-file
+ '("/usr/spool/mail/my-name" "po:my-name"))
+@end lisp
+
+This also means that you probably don't want to set
+@code{nnmail-split-methods} either, which has some, perhaps, unexpected
+side effects.
+
+When a mail backend is queried for what groups it carries, it replies
+with the contents of that variable, along with any groups it has figured
+out that it carries by other means. None of the backends, except
+@code{nnmh}, actually go out to the disk and check what groups actually
+exist. (It's not trivial to distinguish between what the user thinks is
+a basis for a newsgroup and what is just a plain old file or directory.)
+
+This means that you have to tell Gnus (and the backends) by hand what
+groups exist.
+
+Let's take the @code{nnmh} backend as an example:
+
+The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}.
+There are three folders, @file{foo}, @file{bar} and @file{mail.baz}.
+
+Go to the group buffer and type @kbd{G m}. When prompted, answer
+@samp{foo} for the name and @samp{nnmh} for the method. Repeat
+twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure
+to include all your mail groups.
+
+That's it. You are now set to read your mail. An active file for this
+method will be created automatically.
+
+@vindex nnmail-procmail-suffix
+@vindex nnmail-procmail-directory
+If you use @code{nnfolder} or any other backend that store more than a
+single article in each file, you should never have procmail add mails to
+the file that Gnus sees. Instead, procmail should put all incoming mail
+in @code{nnmail-procmail-directory}. To arrive at the file name to put
+the incoming mail in, append @code{nnmail-procmail-suffix} to the group
+name. The mail backends will read the mail from these files.
+
+@vindex nnmail-resplit-incoming
+When Gnus reads a file called @file{mail.misc.spool}, this mail will be
+put in the @code{mail.misc}, as one would expect. However, if you want
+Gnus to split the mail the normal way, you could set
+@code{nnmail-resplit-incoming} to @code{t}.
+
+@vindex nnmail-keep-last-article
+If you use @code{procmail} to split things directly into an @code{nnmh}
+directory (which you shouldn't do), you should set
+@code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from
+ever expiring the final article (i.e., the article with the highest
+article number) in a mail newsgroup. This is quite, quite important.
+
+Here's an example setup: The incoming spools are located in
+@file{~/incoming/} and have @samp{""} as suffixes (i.e., the incoming
+spool files have the same names as the equivalent groups). The
+@code{nnfolder} backend is to be used as the mail interface, and the
+@code{nnfolder} directory is @file{~/fMail/}.
+
+@lisp
+(setq nnfolder-directory "~/fMail/")
+(setq nnmail-spool-file 'procmail)
+(setq nnmail-procmail-directory "~/incoming/")
+(setq gnus-secondary-select-methods '((nnfolder "")))
+(setq nnmail-procmail-suffix "")
+@end lisp
+
+
+@node Incorporating Old Mail
+@subsection Incorporating Old Mail
+
+Most people have lots of old mail stored in various file formats. If
+you have set up Gnus to read mail using one of the spiffy Gnus mail
+backends, you'll probably wish to have that old mail incorporated into
+your mail groups.
+
+Doing so can be quite easy.
+
+To take an example: You're reading mail using @code{nnml}
+(@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a
+satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox
+file filled with important, but old, mail. You want to move it into
+your @code{nnml} groups.
+
+Here's how:
+
+@enumerate
+@item
+Go to the group buffer.
+
+@item
+Type `G f' and give the path to the mbox file when prompted to create an
+@code{nndoc} group from the mbox file (@pxref{Foreign Groups}).
+
+@item
+Type `SPACE' to enter the newly created group.
+
+@item
+Type `M P b' to process-mark all articles in this group's buffer
+(@pxref{Setting Process Marks}).
+
+@item
+Type `B r' to respool all the process-marked articles, and answer
+@samp{nnml} when prompted (@pxref{Mail Group Commands}).
+@end enumerate
+
+All the mail messages in the mbox file will now also be spread out over
+all your @code{nnml} groups. Try entering them and check whether things
+have gone without a glitch. If things look ok, you may consider
+deleting the mbox file, but I wouldn't do that unless I was absolutely
+sure that all the mail has ended up where it should be.
+
+Respooling is also a handy thing to do if you're switching from one mail
+backend to another. Just respool all the mail in the old mail groups
+using the new mail backend.
+
+
+@node Expiring Mail
+@subsection Expiring Mail
+@cindex article expiry
+
+Traditional mail readers have a tendency to remove mail articles when
+you mark them as read, in some way. Gnus takes a fundamentally
+different approach to mail reading.
+
+Gnus basically considers mail just to be news that has been received in
+a rather peculiar manner. It does not think that it has the power to
+actually change the mail, or delete any mail messages. If you enter a
+mail group, and mark articles as ``read'', or kill them in some other
+fashion, the mail articles will still exist on the system. I repeat:
+Gnus will not delete your old, read mail. Unless you ask it to, of
+course.
+
+To make Gnus get rid of your unwanted mail, you have to mark the
+articles as @dfn{expirable}. This does not mean that the articles will
+disappear right away, however. In general, a mail article will be
+deleted from your system if, 1) it is marked as expirable, AND 2) it is
+more than one week old. If you do not mark an article as expirable, it
+will remain on your system until hell freezes over. This bears
+repeating one more time, with some spurious capitalizations: IF you do
+NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES.
+
+@vindex gnus-auto-expirable-newsgroups
+You do not have to mark articles as expirable by hand. Groups that
+match the regular expression @code{gnus-auto-expirable-newsgroups} will
+have all articles that you read marked as expirable automatically. All
+articles marked as expirable have an @samp{E} in the first
+column in the summary buffer.
+
+By default, if you have auto expiry switched on, Gnus will mark all the
+articles you read as expirable, no matter if they were read or unread
+before. To avoid having articles marked as read marked as expirable
+automatically, you can put something like the following in your
+@file{.gnus} file:
+
+@vindex gnus-mark-article-hook
+@lisp
+(remove-hook 'gnus-mark-article-hook
+ 'gnus-summary-mark-read-and-unread-as-read)
+(add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read)
+@end lisp
+
+Note that making a group auto-expirable doesn't mean that all read
+articles are expired---only the articles marked as expirable
+will be expired. Also note that using the @kbd{d} command won't make
+groups expirable---only semi-automatic marking of articles as read will
+mark the articles as expirable in auto-expirable groups.
+
+Let's say you subscribe to a couple of mailing lists, and you want the
+articles you have read to disappear after a while:
+
+@lisp
+(setq gnus-auto-expirable-newsgroups
+ "mail.nonsense-list\\|mail.nice-list")
+@end lisp
+
+Another way to have auto-expiry happen is to have the element
+@code{auto-expire} in the group parameters of the group.
+
+If you use adaptive scoring (@pxref{Adaptive Scoring}) and
+auto-expiring, you'll have problems. Auto-expiring and adaptive scoring
+don't really mix very well.
+
+@vindex nnmail-expiry-wait
+The @code{nnmail-expiry-wait} variable supplies the default time an
+expirable article has to live. Gnus starts counting days from when the
+message @emph{arrived}, not from when it was sent. The default is seven
+days.
+
+Gnus also supplies a function that lets you fine-tune how long articles
+are to live, based on what group they are in. Let's say you want to
+have one month expiry period in the @samp{mail.private} group, a one day
+expiry period in the @samp{mail.junk} group, and a six day expiry period
+everywhere else:
+
+@vindex nnmail-expiry-wait-function
+@lisp
+(setq nnmail-expiry-wait-function
+ (lambda (group)
+ (cond ((string= group "mail.private")
+ 31)
+ ((string= group "mail.junk")
+ 1)
+ ((string= group "important")
+ 'never)
+ (t
+ 6))))
+@end lisp
+
+The group names this function is fed are ``unadorned'' group
+names---no @samp{nnml:} prefixes and the like.
+
+The @code{nnmail-expiry-wait} variable and
+@code{nnmail-expiry-wait-function} function can either be a number (not
+necessarily an integer) or one of the symbols @code{immediate} or
+@code{never}.
+
+You can also use the @code{expiry-wait} group parameter to selectively
+change the expiry period (@pxref{Group Parameters}).
+
+@vindex nnmail-keep-last-article
+If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never
+expire the final article in a mail newsgroup. This is to make life
+easier for procmail users.
+
+@vindex gnus-total-expirable-newsgroups
+By the way: That line up there, about Gnus never expiring non-expirable
+articles, is a lie. If you put @code{total-expire} in the group
+parameters, articles will not be marked as expirable, but all read
+articles will be put through the expiry process. Use with extreme
+caution. Even more dangerous is the
+@code{gnus-total-expirable-newsgroups} variable. All groups that match
+this regexp will have all read articles put through the expiry process,
+which means that @emph{all} old mail articles in the groups in question
+will be deleted after a while. Use with extreme caution, and don't come
+crying to me when you discover that the regexp you used matched the
+wrong group and all your important mail has disappeared. Be a
+@emph{man}! Or a @emph{woman}! Whatever you feel more comfortable
+with! So there!
+
+Most people make most of their mail groups total-expirable, though.
+
+
+@node Washing Mail
+@subsection Washing Mail
+@cindex mail washing
+@cindex list server brain damage
+@cindex incoming mail treatment
+
+Mailers and list servers are notorious for doing all sorts of really,
+really stupid things with mail. ``Hey, RFC822 doesn't explicitly
+prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the
+end of all lines passing through our server, so let's do that!!!!1!''
+Yes, but RFC822 wasn't designed to be read by morons. Things that were
+considered to be self-evident were not discussed. So. Here we are.
+
+Case in point: The German version of Microsoft Exchange adds @samp{AW:
+} to the subjects of replies instead of @samp{Re: }. I could pretend to
+be shocked and dismayed by this, but I haven't got the energy. It is to
+laugh.
+
+Gnus provides a plethora of functions for washing articles while
+displaying them, but it might be nicer to do the filtering before
+storing the mail to disc. For that purpose, we have three hooks and
+various functions that can be put in these hooks.
+
+@table @code
+@item nnmail-prepare-incoming-hook
+@vindex nnmail-prepare-incoming-hook
+This hook is called before doing anything with the mail and is meant for
+grand, sweeping gestures. Functions to be used include:
+
+@table @code
+@item nnheader-ms-strip-cr
+@findex nnheader-ms-strip-cr
+Remove trailing carriage returns from each line. This is default on
+Emacs running on MS machines.
+
+@end table
+
+@item nnmail-prepare-incoming-header-hook
+@vindex nnmail-prepare-incoming-header-hook
+This hook is called narrowed to each header. It can be used when
+cleaning up the headers. Functions that can be used include:
+
+@table @code
+@item nnmail-remove-leading-whitespace
+@findex nnmail-remove-leading-whitespace
+Clear leading white space that ``helpful'' listservs have added to the
+headers to make them look nice. Aaah.
+
+@item nnmail-remove-list-identifiers
+@findex nnmail-remove-list-identifiers
+Some list servers add an identifier---for example, @samp{(idm)}---to the
+beginning of all @code{Subject} headers. I'm sure that's nice for
+people who use stone age mail readers. This function will remove
+strings that match the @code{nnmail-list-identifiers} regexp, which can
+also be a list of regexp.
+
+For instance, if you want to remove the @samp{(idm)} and the
+@samp{nagnagnag} identifiers:
+
+@lisp
+(setq nnmail-list-identifiers
+ '("(idm)" "nagnagnag"))
+@end lisp
+
+@item nnmail-remove-tabs
+@findex nnmail-remove-tabs
+Translate all @samp{TAB} characters into @samp{SPACE} characters.
+
+@end table
+
+@item nnmail-prepare-incoming-message-hook
+@vindex nnmail-prepare-incoming-message-hook
+This hook is called narrowed to each message. Functions to be used
+include:
+
+@table @code
+@item article-de-quoted-unreadable
+@findex article-de-quoted-unreadable
+Decode Quoted Readable encoding.
+
+@end table
+@end table
+
+
+@node Duplicates
+@subsection Duplicates
+
+@vindex nnmail-treat-duplicates
+@vindex nnmail-message-id-cache-length
+@vindex nnmail-message-id-cache-file
+@cindex duplicate mails
+If you are a member of a couple of mailing lists, you will sometimes
+receive two copies of the same mail. This can be quite annoying, so
+@code{nnmail} checks for and treats any duplicates it might find. To do
+this, it keeps a cache of old @code{Message-ID}s---
+@code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
+default. The approximate maximum number of @code{Message-ID}s stored
+there is controlled by the @code{nnmail-message-id-cache-length}
+variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
+stored.) If all this sounds scary to you, you can set
+@code{nnmail-treat-duplicates} to @code{warn} (which is what it is by
+default), and @code{nnmail} won't delete duplicate mails. Instead it
+will insert a warning into the head of the mail saying that it thinks
+that this is a duplicate of a different message.
+
+This variable can also be a function. If that's the case, the function
+will be called from a buffer narrowed to the message in question with
+the @code{Message-ID} as a parameter. The function must return either
+@code{nil}, @code{warn}, or @code{delete}.
+
+You can turn this feature off completely by setting the variable to
+@code{nil}.
+
+If you want all the duplicate mails to be put into a special
+@dfn{duplicates} group, you could do that using the normal mail split
+methods:
+
+@lisp
+(setq nnmail-split-fancy
+ '(| ;; Messages duplicates go to a separate group.
+ ("gnus-warning" "duplication of message" "duplicate")
+ ;; Message from daemons, postmaster, and the like to another.
+ (any mail "mail.misc")
+ ;; Other rules.
+ [ ... ] ))
+@end lisp
+
+Or something like:
+@lisp
+(setq nnmail-split-methods
+ '(("duplicates" "^Gnus-Warning:")
+ ;; Other rules.
+ [...]))
+@end lisp
+
+Here's a neat feature: If you know that the recipient reads her mail
+with Gnus, and that she has @code{nnmail-treat-duplicates} set to
+@code{delete}, you can send her as many insults as you like, just by
+using a @code{Message-ID} of a mail that you know that she's already
+received. Think of all the fun! She'll never see any of it! Whee!
+
+
+@node Not Reading Mail
+@subsection Not Reading Mail
+
+If you start using any of the mail backends, they have the annoying
+habit of assuming that you want to read mail with them. This might not
+be unreasonable, but it might not be what you want.
+
+If you set @code{nnmail-spool-file} to @code{nil}, none of the backends
+will ever attempt to read incoming mail, which should help.
+
+@vindex nnbabyl-get-new-mail
+@vindex nnmbox-get-new-mail
+@vindex nnml-get-new-mail
+@vindex nnmh-get-new-mail
+@vindex nnfolder-get-new-mail
+This might be too much, if, for instance, you are reading mail quite
+happily with @code{nnml} and just want to peek at some old @sc{rmail}
+file you have stashed away with @code{nnbabyl}. All backends have
+variables called backend-@code{get-new-mail}. If you want to disable
+the @code{nnbabyl} mail reading, you edit the virtual server for the
+group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}.
+
+All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook}
+narrowed to the article to be saved before saving it when reading
+incoming mail.
+
+
+@node Choosing a Mail Backend
+@subsection Choosing a Mail Backend
+
+Gnus will read the mail spool when you activate a mail group. The mail
+file is first copied to your home directory. What happens after that
+depends on what format you want to store your mail in.
+
+@menu
+* Unix Mail Box:: Using the (quite) standard Un*x mbox.
+* Rmail Babyl:: Emacs programs use the rmail babyl format.
+* Mail Spool:: Store your mail in a private spool?
+* MH Spool:: An mhspool-like backend.
+* Mail Folders:: Having one file for each group.
+@end menu
+
+
+@node Unix Mail Box
+@subsubsection Unix Mail Box
+@cindex nnmbox
+@cindex unix mail box
+
+@vindex nnmbox-active-file
+@vindex nnmbox-mbox-file
+The @dfn{nnmbox} backend will use the standard Un*x mbox file to store
+mail. @code{nnmbox} will add extra headers to each mail article to say
+which group it belongs in.
+
+Virtual server settings:
+
+@table @code
+@item nnmbox-mbox-file
+@vindex nnmbox-mbox-file
+The name of the mail box in the user's home directory.
+
+@item nnmbox-active-file
+@vindex nnmbox-active-file
+The name of the active file for the mail box.
+
+@item nnmbox-get-new-mail
+@vindex nnmbox-get-new-mail
+If non-@code{nil}, @code{nnmbox} will read incoming mail and split it
+into groups.
+@end table
+
+
+@node Rmail Babyl
+@subsubsection Rmail Babyl
+@cindex nnbabyl
+@cindex rmail mbox
+
+@vindex nnbabyl-active-file
+@vindex nnbabyl-mbox-file
+The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail
+mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail
+article to say which group it belongs in.
+
+Virtual server settings:
+
+@table @code
+@item nnbabyl-mbox-file
+@vindex nnbabyl-mbox-file
+The name of the rmail mbox file.
+
+@item nnbabyl-active-file
+@vindex nnbabyl-active-file
+The name of the active file for the rmail box.
+
+@item nnbabyl-get-new-mail
+@vindex nnbabyl-get-new-mail
+If non-@code{nil}, @code{nnbabyl} will read incoming mail.
+@end table
+
+
+@node Mail Spool
+@subsubsection Mail Spool
+@cindex nnml
+@cindex mail @sc{nov} spool
+
+The @dfn{nnml} spool mail format isn't compatible with any other known
+format. It should be used with some caution.
+
+@vindex nnml-directory
+If you use this backend, Gnus will split all incoming mail into files,
+one file for each mail, and put the articles into the corresponding
+directories under the directory specified by the @code{nnml-directory}
+variable. The default value is @file{~/Mail/}.
+
+You do not have to create any directories beforehand; Gnus will take
+care of all that.
+
+If you have a strict limit as to how many files you are allowed to store
+in your account, you should not use this backend. As each mail gets its
+own file, you might very well occupy thousands of inodes within a few
+weeks. If this is no problem for you, and it isn't a problem for you
+having your friendly systems administrator walking around, madly,
+shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should
+know that this is probably the fastest format to use. You do not have
+to trudge through a big mbox file just to read your new mail.
+
+@code{nnml} is probably the slowest backend when it comes to article
+splitting. It has to create lots of files, and it also generates
+@sc{nov} databases for the incoming mails. This makes it the fastest
+backend when it comes to reading mail.
+
+Virtual server settings:
+
+@table @code
+@item nnml-directory
+@vindex nnml-directory
+All @code{nnml} directories will be placed under this directory.
+
+@item nnml-active-file
+@vindex nnml-active-file
+The active file for the @code{nnml} server.
+
+@item nnml-newsgroups-file
+@vindex nnml-newsgroups-file
+The @code{nnml} group descriptions file. @xref{Newsgroups File
+Format}.
+
+@item nnml-get-new-mail
+@vindex nnml-get-new-mail
+If non-@code{nil}, @code{nnml} will read incoming mail.
+
+@item nnml-nov-is-evil
+@vindex nnml-nov-is-evil
+If non-@code{nil}, this backend will ignore any @sc{nov} files.
+
+@item nnml-nov-file-name
+@vindex nnml-nov-file-name
+The name of the @sc{nov} files. The default is @file{.overview}.
+
+@item nnml-prepare-save-mail-hook
+@vindex nnml-prepare-save-mail-hook
+Hook run narrowed to an article before saving.
+
+@end table
+
+@findex nnml-generate-nov-databases
+If your @code{nnml} groups and @sc{nov} files get totally out of whack,
+you can do a complete update by typing @kbd{M-x
+nnml-generate-nov-databases}. This command will trawl through the
+entire @code{nnml} hierarchy, looking at each and every article, so it
+might take a while to complete. A better interface to this
+functionality can be found in the server buffer (@pxref{Server
+Commands}).
+
+
+@node MH Spool
+@subsubsection MH Spool
+@cindex nnmh
+@cindex mh-e mail spool
+
+@code{nnmh} is just like @code{nnml}, except that is doesn't generate
+@sc{nov} databases and it doesn't keep an active file. This makes
+@code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also
+makes it easier to write procmail scripts for.
+
+Virtual server settings:
+
+@table @code
+@item nnmh-directory
+@vindex nnmh-directory
+All @code{nnmh} directories will be located under this directory.
+
+@item nnmh-get-new-mail
+@vindex nnmh-get-new-mail
+If non-@code{nil}, @code{nnmh} will read incoming mail.
+
+@item nnmh-be-safe
+@vindex nnmh-be-safe
+If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
+sure that the articles in the folder are actually what Gnus thinks they
+are. It will check date stamps and stat everything in sight, so
+setting this to @code{t} will mean a serious slow-down. If you never
+use anything but Gnus to read the @code{nnmh} articles, you do not have
+to set this variable to @code{t}.
+@end table
+
+
+@node Mail Folders
+@subsubsection Mail Folders
+@cindex nnfolder
+@cindex mbox folders
+@cindex mail folders
+
+@code{nnfolder} is a backend for storing each mail group in a separate
+file. Each file is in the standard Un*x mbox format. @code{nnfolder}
+will add extra headers to keep track of article numbers and arrival
+dates.
+
+Virtual server settings:
+
+@table @code
+@item nnfolder-directory
+@vindex nnfolder-directory
+All the @code{nnfolder} mail boxes will be stored under this directory.
+
+@item nnfolder-active-file
+@vindex nnfolder-active-file
+The name of the active file.
+
+@item nnfolder-newsgroups-file
+@vindex nnfolder-newsgroups-file
+The name of the group descriptions file. @xref{Newsgroups File Format}.
+
+@item nnfolder-get-new-mail
+@vindex nnfolder-get-new-mail
+If non-@code{nil}, @code{nnfolder} will read incoming mail.
+
+@item nnfolder-save-buffer-hook
+@vindex nnfolder-save-buffer-hook
+@cindex backup files
+Hook run before saving the folders. Note that Emacs does the normal
+backup renaming of files even with the @code{nnfolder} buffers. If you
+wish to switch this off, you could say something like the following in
+your @file{.emacs} file:
+
+@lisp
+(defun turn-off-backup ()
+ (set (make-local-variable 'backup-inhibited) t))
+
+(add-hook 'nnfolder-save-buffer-hook 'turn-off-backup)
+@end lisp
+
+@end table
+
+
+@findex nnfolder-generate-active-file
+@kindex M-x nnfolder-generate-active-file
+If you have lots of @code{nnfolder}-like files you'd like to read with
+@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file}
+command to make @code{nnfolder} aware of all likely files in
+@code{nnfolder-directory}.
+
+
+@node Other Sources
+@section Other Sources
+
+Gnus can do more than just read news or mail. The methods described
+below allow Gnus to view directories and files as if they were
+newsgroups.
+
+@menu
+* Directory Groups:: You can read a directory as if it was a newsgroup.
+* Anything Groups:: Dired? Who needs dired?
+* Document Groups:: Single files can be the basis of a group.
+* SOUP:: Reading @sc{SOUP} packets ``offline''.
+* Web Searches:: Creating groups from articles that match a string.
+* Mail-To-News Gateways:: Posting articles via mail-to-news gateways.
+@end menu
+
+
+@node Directory Groups
+@subsection Directory Groups
+@cindex nndir
+@cindex directory groups
+
+If you have a directory that has lots of articles in separate files in
+it, you might treat it as a newsgroup. The files have to have numerical
+names, of course.
+
+This might be an opportune moment to mention @code{ange-ftp} (and its
+successor @code{efs}), that most wonderful of all wonderful Emacs
+packages. When I wrote @code{nndir}, I didn't think much about it---a
+backend to read directories. Big deal.
+
+@code{ange-ftp} changes that picture dramatically. For instance, if you
+enter the @code{ange-ftp} file name
+@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name,
+@code{ange-ftp} or @code{efs} will actually allow you to read this
+directory over at @samp{sina} as a newsgroup. Distributed news ahoy!
+
+@code{nndir} will use @sc{nov} files if they are present.
+
+@code{nndir} is a ``read-only'' backend---you can't delete or expire
+articles with this method. You can use @code{nnmh} or @code{nnml} for
+whatever you use @code{nndir} for, so you could switch to any of those
+methods if you feel the need to have a non-read-only @code{nndir}.
+
+
+@node Anything Groups
+@subsection Anything Groups
+@cindex nneething
+
+From the @code{nndir} backend (which reads a single spool-like
+directory), it's just a hop and a skip to @code{nneething}, which
+pretends that any arbitrary directory is a newsgroup. Strange, but
+true.
+
+When @code{nneething} is presented with a directory, it will scan this
+directory and assign article numbers to each file. When you enter such
+a group, @code{nneething} must create ``headers'' that Gnus can use.
+After all, Gnus is a newsreader, in case you're
+forgetting. @code{nneething} does this in a two-step process. First, it
+snoops each file in question. If the file looks like an article (i.e.,
+the first few lines look like headers), it will use this as the head.
+If this is just some arbitrary file without a head (e.g. a C source
+file), @code{nneething} will cobble up a header out of thin air. It
+will use file ownership, name and date and do whatever it can with these
+elements.
+
+All this should happen automatically for you, and you will be presented
+with something that looks very much like a newsgroup. Totally like a
+newsgroup, to be precise. If you select an article, it will be displayed
+in the article buffer, just as usual.
+
+If you select a line that represents a directory, Gnus will pop you into
+a new summary buffer for this @code{nneething} group. And so on. You can
+traverse the entire disk this way, if you feel like, but remember that
+Gnus is not dired, really, and does not intend to be, either.
+
+There are two overall modes to this action---ephemeral or solid. When
+doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus
+will not store information on what files you have read, and what files
+are new, and so on. If you create a solid @code{nneething} group the
+normal way with @kbd{G m}, Gnus will store a mapping table between
+article numbers and file names, and you can treat this group like any
+other groups. When you activate a solid @code{nneething} group, you will
+be told how many unread articles it contains, etc., etc.
+
+Some variables:
+
+@table @code
+@item nneething-map-file-directory
+@vindex nneething-map-file-directory
+All the mapping files for solid @code{nneething} groups will be stored
+in this directory, which defaults to @file{~/.nneething/}.
+
+@item nneething-exclude-files
+@vindex nneething-exclude-files
+All files that match this regexp will be ignored. Nice to use to exclude
+auto-save files and the like, which is what it does by default.
+
+@item nneething-map-file
+@vindex nneething-map-file
+Name of the map files.
+@end table
+
+
+@node Document Groups
+@subsection Document Groups
+@cindex nndoc
+@cindex documentation group
+@cindex help group
+
+@code{nndoc} is a cute little thing that will let you read a single file
+as a newsgroup. Several files types are supported:
+
+@table @code
+@cindex babyl
+@cindex rmail mbox
+
+@item babyl
+The babyl (rmail) mail box.
+@cindex mbox
+@cindex Unix mbox
+
+@item mbox
+The standard Unix mbox file.
+
+@cindex MMDF mail box
+@item mmdf
+The MMDF mail box format.
+
+@item news
+Several news articles appended into a file.
+
+@item rnews
+@cindex rnews batch files
+The rnews batch transport format.
+@cindex forwarded messages
+
+@item forward
+Forwarded articles.
+
+@item mime-parts
+MIME multipart messages, besides digests.
+
+@item mime-digest
+@cindex digest
+@cindex MIME digest
+@cindex 1153 digest
+@cindex RFC 1153 digest
+@cindex RFC 341 digest
+MIME (RFC 1341) digest format.
+
+@item standard-digest
+The standard (RFC 1153) digest format.
+
+@item slack-digest
+Non-standard digest format---matches most things, but does it badly.
+@end table
+
+You can also use the special ``file type'' @code{guess}, which means
+that @code{nndoc} will try to guess what file type it is looking at.
+@code{digest} means that @code{nndoc} should guess what digest type the
+file is.
+
+@code{nndoc} will not try to change the file or insert any extra headers into
+it---it will simply, like, let you use the file as the basis for a
+group. And that's it.
+
+If you have some old archived articles that you want to insert into your
+new & spiffy Gnus mail backend, @code{nndoc} can probably help you with
+that. Say you have an old @file{RMAIL} file with mail that you now want
+to split into your new @code{nnml} groups. You look at that file using
+@code{nndoc} (using the @kbd{G f} command in the group buffer
+(@pxref{Foreign Groups})), set the process mark on all the articles in
+the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r})
+using @code{nnml}. If all goes well, all the mail in the @file{RMAIL}
+file is now also stored in lots of @code{nnml} directories, and you can
+delete that pesky @file{RMAIL} file. If you have the guts!
+
+Virtual server variables:
+
+@table @code
+@item nndoc-article-type
+@vindex nndoc-article-type
+This should be one of @code{mbox}, @code{babyl}, @code{digest},
+@code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934},
+@code{rfc822-forward}, @code{mime-parts}, @code{mime-digest},
+@code{standard-digest}, @code{slack-digest}, @code{clari-briefs} or
+@code{guess}.
+
+@item nndoc-post-type
+@vindex nndoc-post-type
+This variable says whether Gnus is to consider the group a news group or
+a mail group. There are two valid values: @code{mail} (the default)
+and @code{news}.
+@end table
+
+@menu
+* Document Server Internals:: How to add your own document types.
+@end menu
+
+
+@node Document Server Internals
+@subsubsection Document Server Internals
+
+Adding new document types to be recognized by @code{nndoc} isn't
+difficult. You just have to whip up a definition of what the document
+looks like, write a predicate function to recognize that document type,
+and then hook into @code{nndoc}.
+
+First, here's an example document type definition:
+
+@example
+(mmdf
+ (article-begin . "^\^A\^A\^A\^A\n")
+ (body-end . "^\^A\^A\^A\^A\n"))
+@end example
+
+The definition is simply a unique @dfn{name} followed by a series of
+regexp pseudo-variable settings. Below are the possible
+variables---don't be daunted by the number of variables; most document
+types can be defined with very few settings:
+
+@table @code
+@item first-article
+If present, @code{nndoc} will skip past all text until it finds
+something that match this regexp. All text before this will be
+totally ignored.
+
+@item article-begin
+This setting has to be present in all document type definitions. It
+says what the beginning of each article looks like.
+
+@item head-begin-function
+If present, this should be a function that moves point to the head of
+the article.
+
+@item nndoc-head-begin
+If present, this should be a regexp that matches the head of the
+article.
+
+@item nndoc-head-end
+This should match the end of the head of the article. It defaults to
+@samp{^$}---the empty line.
+
+@item body-begin-function
+If present, this function should move point to the beginning of the body
+of the article.
+
+@item body-begin
+This should match the beginning of the body of the article. It defaults
+to @samp{^\n}.
+
+@item body-end-function
+If present, this function should move point to the end of the body of
+the article.
+
+@item body-end
+If present, this should match the end of the body of the article.
+
+@item file-end
+If present, this should match the end of the file. All text after this
+regexp will be totally ignored.
+
+@end table
+
+So, using these variables @code{nndoc} is able to dissect a document
+file into a series of articles, each with a head and a body. However, a
+few more variables are needed since not all document types are all that
+news-like---variables needed to transform the head or the body into
+something that's palatable for Gnus:
+
+@table @code
+@item prepare-body-function
+If present, this function will be called when requesting an article. It
+will be called with point at the start of the body, and is useful if the
+document has encoded some parts of its contents.
+
+@item article-transform-function
+If present, this function is called when requesting an article. It's
+meant to be used for more wide-ranging transformation of both head and
+body of the article.
+
+@item generate-head-function
+If present, this function is called to generate a head that Gnus can
+understand. It is called with the article number as a parameter, and is
+expected to generate a nice head for the article in question. It is
+called when requesting the headers of all articles.
+
+@end table
+
+Let's look at the most complicated example I can come up with---standard
+digests:
+
+@example
+(standard-digest
+ (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+"))
+ (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+"))
+ (prepare-body-function . nndoc-unquote-dashes)
+ (body-end-function . nndoc-digest-body-end)
+ (head-end . "^ ?$")
+ (body-begin . "^ ?\n")
+ (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$")
+ (subtype digest guess))
+@end example
+
+We see that all text before a 70-width line of dashes is ignored; all
+text after a line that starts with that @samp{^End of} is also ignored;
+each article begins with a 30-width line of dashes; the line separating
+the head from the body may contain a single space; and that the body is
+run through @code{nndoc-unquote-dashes} before being delivered.
+
+To hook your own document definition into @code{nndoc}, use the
+@code{nndoc-add-type} function. It takes two parameters---the first is
+the definition itself and the second (optional) parameter says where in
+the document type definition alist to put this definition. The alist is
+traversed sequentially, and @code{nndoc-TYPE-type-p} is called for a given type @code{TYPE}. So @code{nndoc-mmdf-type-p} is called to see whether a document
+is of @code{mmdf} type, and so on. These type predicates should return
+@code{nil} if the document is not of the correct type; @code{t} if it is
+of the correct type; and a number if the document might be of the
+correct type. A high number means high probability; a low number means
+low probability with @samp{0} being the lowest valid number.
+
+
+@node SOUP
+@subsection SOUP
+@cindex SOUP
+@cindex offline
+
+In the PC world people often talk about ``offline'' newsreaders. These
+are thingies that are combined reader/news transport monstrosities.
+With built-in modem programs. Yecchh!
+
+Of course, us Unix Weenie types of human beans use things like
+@code{uucp} and, like, @code{nntpd} and set up proper news and mail
+transport things like Ghod intended. And then we just use normal
+newsreaders.
+
+However, it can sometimes be convenient to do something a that's a bit
+easier on the brain if you have a very slow modem, and you're not really
+that interested in doing things properly.
+
+A file format called @sc{soup} has been developed for transporting news
+and mail from servers to home machines and back again. It can be a bit
+fiddly.
+
+First some terminology:
+
+@table @dfn
+
+@item server
+This is the machine that is connected to the outside world and where you
+get news and/or mail from.
+
+@item home machine
+This is the machine that you want to do the actual reading and responding
+on. It is typically not connected to the rest of the world in any way.
+
+@item packet
+Something that contains messages and/or commands. There are two kinds
+of packets:
+
+@table @dfn
+@item message packets
+These are packets made at the server, and typically contain lots of
+messages for you to read. These are called @file{SoupoutX.tgz} by
+default, where @var{X} is a number.
+
+@item response packets
+These are packets made at the home machine, and typically contains
+replies that you've written. These are called @file{SoupinX.tgz} by
+default, where @var{X} is a number.
+
+@end table
+
+@end table
+
+
+@enumerate
+
+@item
+You log in on the server and create a @sc{soup} packet. You can either
+use a dedicated @sc{soup} thingie (like the @code{awk} program), or you
+can use Gnus to create the packet with its @sc{soup} commands (@kbd{O
+s} and/or @kbd{G s b}; and then @kbd{G s p}) (@pxref{SOUP Commands}).
+
+@item
+You transfer the packet home. Rail, boat, car or modem will do fine.
+
+@item
+You put the packet in your home directory.
+
+@item
+You fire up Gnus on your home machine using the @code{nnsoup} backend as
+the native or secondary server.
+
+@item
+You read articles and mail and answer and followup to the things you
+want (@pxref{SOUP Replies}).
+
+@item
+You do the @kbd{G s r} command to pack these replies into a @sc{soup}
+packet.
+
+@item
+You transfer this packet to the server.
+
+@item
+You use Gnus to mail this packet out with the @kbd{G s s} command.
+
+@item
+You then repeat until you die.
+
+@end enumerate
+
+So you basically have a bipartite system---you use @code{nnsoup} for
+reading and Gnus for packing/sending these @sc{soup} packets.
+
+@menu
+* SOUP Commands:: Commands for creating and sending @sc{soup} packets
+* SOUP Groups:: A backend for reading @sc{soup} packets.
+* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news.
+@end menu
+
+
+@node SOUP Commands
+@subsubsection SOUP Commands
+
+These are commands for creating and manipulating @sc{soup} packets.
+
+@table @kbd
+@item G s b
+@kindex G s b (Group)
+@findex gnus-group-brew-soup
+Pack all unread articles in the current group
+(@code{gnus-group-brew-soup}). This command understands the
+process/prefix convention.
+
+@item G s w
+@kindex G s w (Group)
+@findex gnus-soup-save-areas
+Save all @sc{soup} data files (@code{gnus-soup-save-areas}).
+
+@item G s s
+@kindex G s s (Group)
+@findex gnus-soup-send-replies
+Send all replies from the replies packet
+(@code{gnus-soup-send-replies}).
+
+@item G s p
+@kindex G s p (Group)
+@findex gnus-soup-pack-packet
+Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}).
+
+@item G s r
+@kindex G s r (Group)
+@findex nnsoup-pack-replies
+Pack all replies into a replies packet (@code{nnsoup-pack-replies}).
+
+@item O s
+@kindex O s (Summary)
+@findex gnus-soup-add-article
+This summary-mode command adds the current article to a @sc{soup} packet
+(@code{gnus-soup-add-article}). It understands the process/prefix
+convention (@pxref{Process/Prefix}).
+
+@end table
+
+
+There are a few variables to customize where Gnus will put all these
+thingies:
+
+@table @code
+
+@item gnus-soup-directory
+@vindex gnus-soup-directory
+Directory where Gnus will save intermediate files while composing
+@sc{soup} packets. The default is @file{~/SoupBrew/}.
+
+@item gnus-soup-replies-directory
+@vindex gnus-soup-replies-directory
+This is what Gnus will use as a temporary directory while sending our
+reply packets. @file{~/SoupBrew/SoupReplies/} is the default.
+
+@item gnus-soup-prefix-file
+@vindex gnus-soup-prefix-file
+Name of the file where Gnus stores the last used prefix. The default is
+@samp{gnus-prefix}.
+
+@item gnus-soup-packer
+@vindex gnus-soup-packer
+A format string command for packing a @sc{soup} packet. The default is
+@samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}.
+
+@item gnus-soup-unpacker
+@vindex gnus-soup-unpacker
+Format string command for unpacking a @sc{soup} packet. The default is
+@samp{gunzip -c %s | tar xvf -}.
+
+@item gnus-soup-packet-directory
+@vindex gnus-soup-packet-directory
+Where Gnus will look for reply packets. The default is @file{~/}.
+
+@item gnus-soup-packet-regexp
+@vindex gnus-soup-packet-regexp
+Regular expression matching @sc{soup} reply packets in
+@code{gnus-soup-packet-directory}.
+
+@end table
+
+
+@node SOUP Groups
+@subsubsection @sc{soup} Groups
+@cindex nnsoup
+
+@code{nnsoup} is the backend for reading @sc{soup} packets. It will
+read incoming packets, unpack them, and put them in a directory where
+you can read them at leisure.
+
+These are the variables you can use to customize its behavior:
+
+@table @code
+
+@item nnsoup-tmp-directory
+@vindex nnsoup-tmp-directory
+When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this
+directory. (@file{/tmp/} by default.)
+
+@item nnsoup-directory
+@vindex nnsoup-directory
+@code{nnsoup} then moves each message and index file to this directory.
+The default is @file{~/SOUP/}.
+
+@item nnsoup-replies-directory
+@vindex nnsoup-replies-directory
+All replies will be stored in this directory before being packed into a
+reply packet. The default is @file{~/SOUP/replies/"}.
+
+@item nnsoup-replies-format-type
+@vindex nnsoup-replies-format-type
+The @sc{soup} format of the replies packets. The default is @samp{?n}
+(rnews), and I don't think you should touch that variable. I probably
+shouldn't even have documented it. Drats! Too late!
+
+@item nnsoup-replies-index-type
+@vindex nnsoup-replies-index-type
+The index type of the replies packet. The default is @samp{?n}, which
+means ``none''. Don't fiddle with this one either!
+
+@item nnsoup-active-file
+@vindex nnsoup-active-file
+Where @code{nnsoup} stores lots of information. This is not an ``active
+file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose
+this file or mess it up in any way, you're dead. The default is
+@file{~/SOUP/active}.
+
+@item nnsoup-packer
+@vindex nnsoup-packer
+Format string command for packing a reply @sc{soup} packet. The default
+is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}.
+
+@item nnsoup-unpacker
+@vindex nnsoup-unpacker
+Format string command for unpacking incoming @sc{soup} packets. The
+default is @samp{gunzip -c %s | tar xvf -}.
+
+@item nnsoup-packet-directory
+@vindex nnsoup-packet-directory
+Where @code{nnsoup} will look for incoming packets. The default is
+@file{~/}.
+
+@item nnsoup-packet-regexp
+@vindex nnsoup-packet-regexp
+Regular expression matching incoming @sc{soup} packets. The default is
+@samp{Soupout}.
+
+@item nnsoup-always-save
+@vindex nnsoup-always-save
+If non-@code{nil}, save the replies buffer after each posted message.
+
+@end table
+
+
+@node SOUP Replies
+@subsubsection SOUP Replies
+
+Just using @code{nnsoup} won't mean that your postings and mailings end
+up in @sc{soup} reply packets automagically. You have to work a bit
+more for that to happen.
+
+@findex nnsoup-set-variables
+The @code{nnsoup-set-variables} command will set the appropriate
+variables to ensure that all your followups and replies end up in the
+@sc{soup} system.
+
+In specific, this is what it does:
+
+@lisp
+(setq message-send-news-function 'nnsoup-request-post)
+(setq message-send-mail-function 'nnsoup-request-mail)
+@end lisp
+
+And that's it, really. If you only want news to go into the @sc{soup}
+system you just use the first line. If you only want mail to be
+@sc{soup}ed you use the second.
+
+
+@node Web Searches
+@subsection Web Searches
+@cindex nnweb
+@cindex DejaNews
+@cindex Alta Vista
+@cindex InReference
+@cindex Usenet searches
+@cindex searching the Usenet
+
+It's, like, too neat to search the Usenet for articles that match a
+string, but it, like, totally @emph{sucks}, like, totally, to use one of
+those, like, Web browsers, and you, like, have to, rilly, like, look at
+the commercials, so, like, with Gnus you can do @emph{rad}, rilly,
+searches without having to use a browser.
+
+The @code{nnweb} backend allows an easy interface to the mighty search
+engine. You create an @code{nnweb} group, enter a search pattern, and
+then enter the group and read the articles like you would any normal
+group. The @kbd{G w} command in the group buffer (@pxref{Foreign
+Groups}) will do this in an easy-to-use fashion.
+
+@code{nnweb} groups don't really lend themselves to being solid
+groups---they have a very fleeting idea of article numbers. In fact,
+each time you enter an @code{nnweb} group (not even changing the search
+pattern), you are likely to get the articles ordered in a different
+manner. Not even using duplicate suppression (@pxref{Duplicate
+Suppression}) will help, since @code{nnweb} doesn't even know the
+@code{Message-ID} of the articles before reading them using some search
+engines (DejaNews, for instance). The only possible way to keep track
+of which articles you've read is by scoring on the @code{Date}
+header---mark all articles posted before the last date you read the
+group as read.
+
+If the search engine changes its output substantially, @code{nnweb}
+won't be able to parse it and will fail. One could hardly fault the Web
+providers if they were to do this---their @emph{raison d'être} is to
+make money off of advertisements, not to provide services to the
+community. Since @code{nnweb} washes the ads off all the articles, one
+might think that the providers might be somewhat miffed. We'll see.
+
+You must have the @code{url} and @code{w3} package installed to be able
+to use @code{nnweb}.
+
+Virtual server variables:
+
+@table @code
+@item nnweb-type
+@vindex nnweb-type
+What search engine type is being used. The currently supported types
+are @code{dejanews}, @code{dejanewsold}, @code{altavista} and
+@code{reference}.
+
+@item nnweb-search
+@vindex nnweb-search
+The search string to feed to the search engine.
+
+@item nnweb-max-hits
+@vindex nnweb-max-hits
+Advisory maximum number of hits per search to display. The default is
+100.
+
+@item nnweb-type-definition
+@vindex nnweb-type-definition
+Type-to-definition alist. This alist says what @code{nnweb} should do
+with the various search engine types. The following elements must be
+present:
+
+@table @code
+@item article
+Function to decode the article and provide something that Gnus
+understands.
+
+@item map
+Function to create an article number to message header and URL alist.
+
+@item search
+Function to send the search string to the search engine.
+
+@item address
+The address the aforementioned function should send the search string
+to.
+
+@item id
+Format string URL to fetch an article by @code{Message-ID}.
+@end table
+
+@end table
+
+
+
+@node Mail-To-News Gateways
+@subsection Mail-To-News Gateways
+@cindex mail-to-news gateways
+@cindex gateways
+
+If your local @code{nntp} server doesn't allow posting, for some reason
+or other, you can post using one of the numerous mail-to-news gateways.
+The @code{nngateway} backend provides the interface.
+
+Note that you can't read anything from this backend---it can only be
+used to post with.
+
+Server variables:
+
+@table @code
+@item nngateway-address
+@vindex nngateway-address
+This is the address of the mail-to-news gateway.
+
+@item nngateway-header-transformation
+@vindex nngateway-header-transformation
+News headers often have to be transformed in some odd way or other
+for the mail-to-news gateway to accept it. This variable says what
+transformation should be called, and defaults to
+@code{nngateway-simple-header-transformation}. The function is called
+narrowed to the headers to be transformed and with one parameter---the
+gateway address.
+
+This default function just inserts a new @code{To} header based on the
+@code{Newsgroups} header and the gateway address.
+For instance, an article with this @code{Newsgroups} header:
+
+@example
+Newsgroups: alt.religion.emacs
+@end example
+
+will get this @code{From} header inserted:
+
+@example
+To: alt-religion-emacs@@GATEWAY
+@end example
+
+The following pre-defined functions exist:
+
+@findex nngateway-simple-header-transformation
+@table @code
+
+@item nngateway-simple-header-transformation
+Creates a @code{To} header that looks like
+@var{newsgroup}@@@code{nngateway-address}.
+
+@findex nngateway-mail2news-header-transformation
+
+@item nngateway-mail2news-header-transformation
+Creates a @code{To} header that looks like
+@code{nngateway-address}.
+
+Here's an example:
+
+@lisp
+(setq gnus-post-method
+ '(nngateway "mail2news@@replay.com"
+ (nngateway-header-transformation
+ nngateway-mail2news-header-transformation)))
+@end lisp
+
+@end table
+
+
+@end table
+
+So, to use this, simply say something like:
+
+@lisp
+(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS"))
+@end lisp
+
+
+@node Combined Groups
+@section Combined Groups
+
+Gnus allows combining a mixture of all the other group types into bigger
+groups.
+
+@menu
+* Virtual Groups:: Combining articles from many groups.
+* Kibozed Groups:: Looking through parts of the newsfeed for articles.
+@end menu
+
+
+@node Virtual Groups
+@subsection Virtual Groups
+@cindex nnvirtual
+@cindex virtual groups
+@cindex merging groups
+
+An @dfn{nnvirtual group} is really nothing more than a collection of
+other groups.
+
+For instance, if you are tired of reading many small groups, you can
+put them all in one big group, and then grow tired of reading one
+big, unwieldy group. The joys of computing!
+
+You specify @code{nnvirtual} as the method. The address should be a
+regexp to match component groups.
+
+All marks in the virtual group will stick to the articles in the
+component groups. So if you tick an article in a virtual group, the
+article will also be ticked in the component group from whence it came.
+(And vice versa---marks from the component groups will also be shown in
+the virtual group.)
+
+Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
+newsgroups into one, big, happy newsgroup:
+
+@lisp
+(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*")
+@end lisp
+
+The component groups can be native or foreign; everything should work
+smoothly, but if your computer explodes, it was probably my fault.
+
+Collecting the same group from several servers might actually be a good
+idea if users have set the Distribution header to limit distribution.
+If you would like to read @samp{soc.motss} both from a server in Japan
+and a server in Norway, you could use the following as the group regexp:
+
+@example
+"^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$"
+@end example
+
+(Remember, though, that if you're creating the group with @kbd{G m}, you
+shouldn't double the backslashes, and you should leave off the quote
+characters at the beginning and the end of the string.)
+
+This should work kinda smoothly---all articles from both groups should
+end up in this one, and there should be no duplicates. Threading (and
+the rest) will still work as usual, but there might be problems with the
+sequence of articles. Sorting on date might be an option here
+(@pxref{Selecting a Group}).
+
+One limitation, however---all groups included in a virtual
+group have to be alive (i.e., subscribed or unsubscribed). Killed or
+zombie groups can't be component groups for @code{nnvirtual} groups.
+
+@vindex nnvirtual-always-rescan
+If the @code{nnvirtual-always-rescan} is non-@code{nil},
+@code{nnvirtual} will always scan groups for unread articles when
+entering a virtual group. If this variable is @code{nil} (which is the
+default) and you read articles in a component group after the virtual
+group has been activated, the read articles from the component group
+will show up when you enter the virtual group. You'll also see this
+effect if you have two virtual groups that have a component group in
+common. If that's the case, you should set this variable to @code{t}.
+Or you can just tap @code{M-g} on the virtual group every time before
+you enter it---it'll have much the same effect.
+
+@code{nnvirtual} can have both mail and news groups as component groups.
+When responding to articles in @code{nnvirtual} groups, @code{nnvirtual}
+has to ask the backend of the component group the article comes from
+whether it is a news or mail backend. However, when you do a @kbd{^},
+there is typically no sure way for the component backend to know this,
+and in that case @code{nnvirtual} tells Gnus that the article came from a
+not-news backend. (Just to be on the safe side.)
+
+@kbd{C-c C-t} in the message buffer will insert the @code{Newsgroups}
+line from the article you respond to in these cases.
+
+
+
+@node Kibozed Groups
+@subsection Kibozed Groups
+@cindex nnkiboze
+@cindex kibozing
+
+@dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of)
+the news feed''. @code{nnkiboze} is a backend that will do this for
+you. Oh joy! Now you can grind any @sc{nntp} server down to a halt
+with useless requests! Oh happiness!
+
+@kindex G k (Group)
+To create a kibozed group, use the @kbd{G k} command in the group
+buffer.
+
+The address field of the @code{nnkiboze} method is, as with
+@code{nnvirtual}, a regexp to match groups to be ``included'' in the
+@code{nnkiboze} group. That's where most similarities between @code{nnkiboze}
+and @code{nnvirtual} end.
+
+In addition to this regexp detailing component groups, an @code{nnkiboze} group
+must have a score file to say what articles are to be included in
+the group (@pxref{Scoring}).
+
+@kindex M-x nnkiboze-generate-groups
+@findex nnkiboze-generate-groups
+You must run @kbd{M-x nnkiboze-generate-groups} after creating the
+@code{nnkiboze} groups you want to have. This command will take time. Lots of
+time. Oodles and oodles of time. Gnus has to fetch the headers from
+all the articles in all the component groups and run them through the
+scoring process to determine if there are any articles in the groups
+that are to be part of the @code{nnkiboze} groups.
+
+Please limit the number of component groups by using restrictive
+regexps. Otherwise your sysadmin may become annoyed with you, and the
+@sc{nntp} site may throw you off and never let you back in again.
+Stranger things have happened.
+
+@code{nnkiboze} component groups do not have to be alive---they can be dead,
+and they can be foreign. No restrictions.
+
+@vindex nnkiboze-directory
+The generation of an @code{nnkiboze} group means writing two files in
+@code{nnkiboze-directory}, which is @file{~/News/} by default. One
+contains the @sc{nov} header lines for all the articles in the group,
+and the other is an additional @file{.newsrc} file to store information
+on what groups have been searched through to find component articles.
+
+Articles marked as read in the @code{nnkiboze} group will have
+their @sc{nov} lines removed from the @sc{nov} file.
+
+
+@node Gnus Unplugged
+@section Gnus Unplugged
+@cindex offline
+@cindex unplugged
+@cindex Agent
+@cindex Gnus Agent
+@cindex Gnus Unplugged
+
+In olden times (ca. February '88), people used to run their newsreaders
+on big machines with permanent connections to the net. News transport
+was dealt with by news servers, and all the newsreaders had to do was to
+read news. Believe it or not.
+
+Nowadays most people read news and mail at home, and use some sort of
+modem to connect to the net. To avoid running up huge phone bills, it
+would be nice to have a way to slurp down all the news and mail, hang up
+the phone, read for several hours, and then upload any responses you
+have to make. And then you repeat the procedure.
+
+Of course, you can use news servers for doing this as well. I've used
+@code{inn} together with @code{slurp}, @code{pop} and @code{sendmail}
+for some years, but doing that's a bore. Moving the news server
+functionality up to the newsreader makes sense if you're the only person
+reading news on a machine.
+
+Using Gnus as an ``offline'' newsreader is quite simple.
+
+@itemize @bullet
+@item
+First, set up Gnus as you would do if you were running it on a machine
+that has full connection to the net. Go ahead. I'll still be waiting
+here.
+
+@item
+Then, put the following magical incantation at the end of your
+@file{.gnus.el} file:
+
+@lisp
+(gnus-agentize)
+@end lisp
+@end itemize
+
+That's it. Gnus is now an ``offline'' newsreader.
+
+Of course, to use it as such, you have to learn a few new commands.
+
+@menu
+* Agent Basics:: How it all is supposed to work.
+* Agent Categories:: How to tell the Gnus Agent what to download.
+* Agent Commands:: New commands for all the buffers.
+* Agent Expiry:: How to make old articles go away.
+* Outgoing Messages:: What happens when you post/mail something?
+* Agent Variables:: Customizing is fun.
+* Example Setup:: An example @file{.gnus.el} file for offline people.
+* Batching Agents:: How to fetch news from a @code{cron} job.
+@end menu
+
+
+@node Agent Basics
+@subsection Agent Basics
+
+First, let's get some terminology out of the way.
+
+The Gnus Agent is said to be @dfn{unplugged} when you have severed the
+connection to the net (and notified the Agent that this is the case).
+When the connection to the net is up again (and Gnus knows this), the
+Agent is @dfn{plugged}.
+
+The @dfn{local} machine is the one you're running on, and which isn't
+connected to the net continuously.
+
+@dfn{Downloading} means fetching things from the net to your local
+machine. @dfn{Uploading} is doing the opposite.
+
+Let's take a typical Gnus session using the Agent.
+
+@itemize @bullet
+
+@item
+You start Gnus with @code{gnus-unplugged}. This brings up the Gnus
+Agent in a disconnected state. You can read all the news that you have
+already fetched while in this mode.
+
+@item
+You then decide to see whether any new news has arrived. You connect
+your machine to the net (using PPP or whatever), and then hit @kbd{J j}
+to make Gnus become @dfn{plugged}.
+
+@item
+You can then read the new news immediately, or you can download the news
+onto your local machine. If you want to do the latter, you press @kbd{J
+s} to fetch all the eligible articles in all the groups. (To let Gnus
+know which articles you want to download, @pxref{Agent Categories}.)
+
+@item
+After fetching the articles, you press @kbd{J j} to make Gnus become
+unplugged again, and you shut down the PPP thing (or whatever). And
+then you read the news offline.
+
+@item
+And then you go to step 2.
+@end itemize
+
+Here are some things you should do the first time (or so) that you use
+the Agent.
+
+@itemize @bullet
+
+@item
+Decide which servers should be covered by the Agent. If you have a mail
+backend, it would probably be nonsensical to have it covered by the
+Agent. Go to the server buffer (@kbd{^} in the group buffer) and press
+@kbd{J a} the server (or servers) that you wish to have covered by the
+Agent (@pxref{Server Agent Commands}). This will typically be only the
+primary select method, which is listed on the bottom in the buffer.
+
+@item
+Decide on download policy. @xref{Agent Categories}.
+
+@item
+Uhm... that's it.
+@end itemize
+
+
+@node Agent Categories
+@subsection Agent Categories
+
+One of the main reasons to integrate the news transport layer into the
+newsreader is to allow greater control over what articles to download.
+There's not much point in downloading huge amounts of articles, just to
+find out that you're not interested in reading any of them. It's better
+to be somewhat more conservative in choosing what to download, and then
+mark the articles for downloading manually if it should turn out that
+you're interested in the articles anyway.
+
+The main way to control what is to be downloaded is to create a
+@dfn{category} and then assign some (or all) groups to this category.
+Gnus has its own buffer for creating and managing categories.
+
+@menu
+* Category Syntax:: What a category looks like.
+* The Category Buffer:: A buffer for maintaining categories.
+* Category Variables:: Customize'r'Us.
+@end menu
+
+
+@node Category Syntax
+@subsubsection Category Syntax
+
+A category consists of two things.
+
+@enumerate
+@item
+A predicate which (generally) gives a rough outline of which articles
+are eligible for downloading; and
+
+@item
+a score rule which (generally) gives you a finer granularity when
+deciding what articles to download. (Note that this @dfn{download
+score} is wholly unrelated to normal scores.)
+@end enumerate
+
+A predicate consists of predicates with logical operators sprinkled in
+between.
+
+Perhaps some examples are in order.
+
+Here's a simple predicate. (It's the default predicate, in fact, used
+for all groups that don't belong to any other category.)
+
+@lisp
+short
+@end lisp
+
+Quite simple, eh? This predicate is true if and only if the article is
+short (for some value of ``short'').
+
+Here's a more complex predicate:
+
+@lisp
+(or high
+ (and
+ (not low)
+ (not long)))
+@end lisp
+
+This means that an article should be downloaded if it has a high score,
+or if the score is not low and the article is not long. You get the
+drift.
+
+The available logical operators are @code{or}, @code{and} and
+@code{not}. (If you prefer, you can use the more ``C''-ish operators
+@samp{|}, @code{&} and @code{!} instead.)
+
+The following predicates are pre-defined, but if none of these fit what
+you want to do, you can write your own.
+
+@table @code
+@item short
+True iff the article is shorter than @code{gnus-agent-short-article}
+lines; default 100.
+
+@item long
+True iff the article is longer than @code{gnus-agent-long-article}
+lines; default 200.
+
+@item low
+True iff the article has a download score less than
+@code{gnus-agent-low-score}; default 0.
+
+@item high
+True iff the article has a download score greater than
+@code{gnus-agent-high-score}; default 0.
+
+@item spam
+True iff the Gnus Agent guesses that the article is spam. The
+heuristics may change over time, but at present it just computes a
+checksum and sees whether articles match.
+
+@item true
+Always true.
+
+@item false
+Always false.
+@end table
+
+If you want to create your own predicate function, here's what you have
+to know: The functions are called with no parameters, but the
+@code{gnus-headers} and @code{gnus-score} dynamic variables are bound to
+useful values.
+
+Now, the syntax of the download score is the same as the syntax of
+normal score files, except that all elements that require actually
+seeing the article itself are verboten. This means that only the
+following headers can be scored on: @code{From}, @code{Subject},
+@code{Date}, @code{Xref}, @code{Lines}, @code{Chars}, @code{Message-ID},
+and @code{References}.
+
+
+@node The Category Buffer
+@subsubsection The Category Buffer
+
+You'd normally do all category maintenance from the category buffer.
+When you enter it for the first time (with the @kbd{J c} command from
+the group buffer), you'll only see the @code{default} category.
+
+The following commands are available in this buffer:
+
+@table @kbd
+@item q
+@kindex q (Category)
+@findex gnus-category-exit
+Return to the group buffer (@code{gnus-category-exit}).
+
+@item k
+@kindex k (Category)
+@findex gnus-category-kill
+Kill the current category (@code{gnus-category-kill}).
+
+@item c
+@kindex c (Category)
+@findex gnus-category-copy
+Copy the current category (@code{gnus-category-copy}).
+
+@item a
+@kindex a (Category)
+@findex gnus-category-add
+Add a new category (@code{gnus-category-add}).
+
+@item p
+@kindex p (Category)
+@findex gnus-category-edit-predicate
+Edit the predicate of the current category
+(@code{gnus-category-edit-predicate}).
+
+@item g
+@kindex g (Category)
+@findex gnus-category-edit-groups
+Edit the list of groups belonging to the current category
+(@code{gnus-category-edit-groups}).
+
+@item s
+@kindex s (Category)
+@findex gnus-category-edit-score
+Edit the download score rule of the current category
+(@code{gnus-category-edit-score}).
+
+@item l
+@kindex l (Category)
+@findex gnus-category-list
+List all the categories (@code{gnus-category-list}).
+@end table
+
+
+@node Category Variables
+@subsubsection Category Variables
+
+@table @code
+@item gnus-category-mode-hook
+@vindex gnus-category-mode-hook
+Hook run in category buffers.
+
+@item gnus-category-line-format
+@vindex gnus-category-line-format
+Format of the lines in the category buffer (@pxref{Formatting
+Variables}). Valid elements are:
+
+@table @samp
+@item c
+The name of the category.
+
+@item g
+The number of groups in the category.
+@end table
+
+@item gnus-category-mode-line-format
+@vindex gnus-category-mode-line-format
+Format of the category mode line (@pxref{Mode Line Formatting}).
+
+@item gnus-agent-short-article
+@vindex gnus-agent-short-article
+Articles that have fewer lines than this are short. Default 100.
+
+@item gnus-agent-long-article
+@vindex gnus-agent-long-article
+Articles that have more lines than this are long. Default 200.
+
+@item gnus-agent-low-score
+@vindex gnus-agent-low-score
+Articles that have a score lower than this have a low score. Default
+0.
+
+@item gnus-agent-high-score
+@vindex gnus-agent-high-score
+Articles that have a score higher than this have a high score. Default
+0.
+
+@end table
+
+
+@node Agent Commands
+@subsection Agent Commands
+
+All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j}
+(@code{gnus-agent-toggle-plugged} command works in all modes, and
+toggles the plugged/unplugged state of the Gnus Agent.
+
+
+@menu
+* Group Agent Commands::
+* Summary Agent Commands::
+* Server Agent Commands::
+@end menu
+
+You can run a complete batch fetch from the command line with the
+following incantation:
+
+@cindex gnus-agent-batch-fetch
+@example
+$ emacs -batch -l ~/.gnus.el -f gnus-agent-batch-fetch
+@end example
+
+
+
+@node Group Agent Commands
+@subsubsection Group Agent Commands
+
+@table @kbd
+@item J u
+@kindex J u (Agent Group)
+@findex gnus-agent-fetch-groups
+Fetch all eligible articles in the current group
+(@code{gnus-agent-fetch-groups}).
+
+@item J c
+@kindex J c (Agent Group)
+@findex gnus-enter-category-buffer
+Enter the Agent category buffer (@code{gnus-enter-category-buffer}).
+
+@item J s
+@kindex J s (Agent Group)
+@findex gnus-agent-fetch-session
+Fetch all eligible articles in all groups
+(@code{gnus-agent-fetch-session}).
+
+@item J S
+@kindex J S (Agent Group)
+@findex gnus-group-send-drafts
+Send all sendable messages in the draft group
+(@code{gnus-agent-fetch-session}). @xref{Drafts}.
+
+@item J a
+@kindex J a (Agent Group)
+@findex gnus-agent-add-group
+Add the current group to an Agent category
+(@code{gnus-agent-add-group}).
+
+@end table
+
+
+@node Summary Agent Commands
+@subsubsection Summary Agent Commands
+
+@table @kbd
+@item J #
+@kindex J # (Agent Summary)
+@findex gnus-agent-mark-article
+Mark the article for downloading (@code{gnus-agent-mark-article}).
+
+@item J M-#
+@kindex J M-# (Agent Summary)
+@findex gnus-agent-unmark-article
+Remove the downloading mark from the article
+(@code{gnus-agent-unmark-article}).
+
+@item @@
+@kindex @@ (Agent Summary)
+@findex gnus-agent-toggle-mark
+Toggle whether to download the article (@code{gnus-agent-toggle-mark}).
+
+@item J c
+@kindex J c (Agent Summary)
+@findex gnus-agent-catchup
+Mark all undownloaded articles as read (@code{gnus-agent-catchup}).
+
+@end table
+
+
+@node Server Agent Commands
+@subsubsection Server Agent Commands
+
+@table @kbd
+@item J a
+@kindex J a (Agent Server)
+@findex gnus-agent-add-server
+Add the current server to the list of servers covered by the Gnus Agent
+(@code{gnus-agent-add-server}).
+
+@item J r
+@kindex J r (Agent Server)
+@findex gnus-agent-remove-server
+Remove the current server from the list of servers covered by the Gnus
+Agent (@code{gnus-agent-remove-server}).
+
+@end table
+
+
+@node Agent Expiry
+@subsection Agent Expiry
+
+@vindex gnus-agent-expire-days
+@findex gnus-agent-expire
+@kindex M-x gnus-agent-expire
+@cindex Agent expire
+@cindex Gnus Agent expire
+@cindex expiry
+
+@code{nnagent} doesn't handle expiry. Instead, there's a special
+@code{gnus-agent-expire} command that will expire all read articles that
+are older than @code{gnus-agent-expire-days} days. It can be run
+whenever you feel that you're running out of space. It's not
+particularly fast or efficient, and it's not a particularly good idea to
+interrupt it (with @kbd{C-g} or anything else) once you've started it.
+
+@vindex gnus-agent-expire-all
+if @code{gnus-agent-expire-all} is non-@code{nil}, this command will
+expire all articles---unread, read, ticked and dormant. If @code{nil}
+(which is the default), only read articles are eligible for expiry, and
+unread, ticked and dormant articles will be kept indefinitely.
+
+
+@node Outgoing Messages
+@subsection Outgoing Messages
+
+When Gnus is unplugged, all outgoing messages (both mail and news) are
+stored in the draft groups (@pxref{Drafts}). You can view them there
+after posting, and edit them at will.
+
+When Gnus is plugged again, you can send the messages either from the
+draft group with the special commands available there, or you can use
+the @kbd{J S} command in the group buffer to send all the sendable
+messages in the draft group.
+
+
+
+@node Agent Variables
+@subsection Agent Variables
+
+@table @code
+@item gnus-agent-directory
+@vindex gnus-agent-directory
+Where the Gnus Agent will store its files. The default is
+@file{~/News/agent/}.
+
+@item gnus-agent-handle-level
+@vindex gnus-agent-handle-level
+Groups on levels (@pxref{Group Levels}) higher than this variable will
+be ignored by the Agent. The default is @code{gnus-level-subscribed},
+which means that only subscribed group will be considered by the Agent
+by default.
+
+@item gnus-agent-plugged-hook
+@vindex gnus-agent-plugged-hook
+Hook run when connecting to the network.
+
+@item gnus-agent-unplugged-hook
+@vindex gnus-agent-unplugged-hook
+Hook run when disconnecting from the network.
+
+@end table
+
+
+@node Example Setup
+@subsection Example Setup
+
+If you don't want to read this manual, and you have a fairly standard
+setup, you may be able to use something like the following as your
+@file{.gnus.el} file to get started.
+
+@lisp
+;;; Define how Gnus is to fetch news. We do this over NNTP
+;;; from your ISP's server.
+(setq gnus-select-method '(nntp "nntp.your-isp.com"))
+
+;;; Define how Gnus is to read your mail. We read mail from
+;;; your ISP's POP server.
+(setenv "MAILHOST" "pop.your-isp.com")
+(setq nnmail-spool-file "po:username")
+
+;;; Say how Gnus is to store the mail. We use nnml groups.
+(setq gnus-secondary-select-methods '((nnml "")))
+
+;;; Make Gnus into an offline newsreader.
+(gnus-agentize)
+@end lisp
+
+That should be it, basically. Put that in your @file{~/.gnus.el} file,
+edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x
+gnus}.
+
+If this is the first time you've run Gnus, you will be subscribed
+automatically to a few default newsgroups. You'll probably want to
+subscribe to more groups, and to do that, you have to query the
+@sc{nntp} server for a complete list of groups with the @kbd{A A}
+command. This usually takes quite a while, but you only have to do it
+once.
+
+After reading and parsing a while, you'll be presented with a list of
+groups. Subscribe to the ones you want to read with the @kbd{u}
+command. @kbd{l} to make all the killed groups disappear after you've
+subscribe to all the groups you want to read. (@kbd{A k} will bring
+back all the killed groups.)
+
+You can now read the groups at once, or you can download the articles
+with the @kbd{J s} command. And then read the rest of this manual to
+find out which of the other gazillion things you want to customize.
+
+
+@node Batching Agents
+@subsection Batching Agents
+
+Having the Gnus Agent fetch articles (and post whatever messages you've
+written) is quite easy once you've gotten things set up properly. The
+following shell script will do everything that is necessary:
+
+@example
+#!/bin/sh
+emacs -batch -l ~/.emacs -f gnus-agent-batch >/dev/null
+@end example
+
+
+
+@node Scoring
+@chapter Scoring
+@cindex scoring
+
+Other people use @dfn{kill files}, but we here at Gnus Towers like
+scoring better than killing, so we'd rather switch than fight. They do
+something completely different as well, so sit up straight and pay
+attention!
+
+@vindex gnus-summary-mark-below
+All articles have a default score (@code{gnus-summary-default-score}),
+which is 0 by default. This score may be raised or lowered either
+interactively or by score files. Articles that have a score lower than
+@code{gnus-summary-mark-below} are marked as read.
+
+Gnus will read any @dfn{score files} that apply to the current group
+before generating the summary buffer.
+
+There are several commands in the summary buffer that insert score
+entries based on the current article. You can, for instance, ask Gnus to
+lower or increase the score of all articles with a certain subject.
+
+There are two sorts of scoring entries: Permanent and temporary.
+Temporary score entries are self-expiring entries. Any entries that are
+temporary and have not been used for, say, a week, will be removed
+silently to help keep the sizes of the score files down.
+
+@menu
+* Summary Score Commands:: Adding score entries for the current group.
+* Group Score Commands:: General score commands.
+* Score Variables:: Customize your scoring. (My, what terminology).
+* Score File Format:: What a score file may contain.
+* Score File Editing:: You can edit score files by hand as well.
+* Adaptive Scoring:: Big Sister Gnus knows what you read.
+* Home Score File:: How to say where new score entries are to go.
+* Followups To Yourself:: Having Gnus notice when people answer you.
+* Scoring Tips:: How to score effectively.
+* Reverse Scoring:: That problem child of old is not problem.
+* Global Score Files:: Earth-spanning, ear-splitting score files.
+* Kill Files:: They are still here, but they can be ignored.
+* Converting Kill Files:: Translating kill files to score files.
+* GroupLens:: Getting predictions on what you like to read.
+* Advanced Scoring:: Using logical expressions to build score rules.
+* Score Decays:: It can be useful to let scores wither away.
+@end menu
+
+
+@node Summary Score Commands
+@section Summary Score Commands
+@cindex score commands
+
+The score commands that alter score entries do not actually modify real
+score files. That would be too inefficient. Gnus maintains a cache of
+previously loaded score files, one of which is considered the
+@dfn{current score file alist}. The score commands simply insert
+entries into this list, and upon group exit, this list is saved.
+
+The current score file is by default the group's local score file, even
+if no such score file actually exists. To insert score commands into
+some other score file (e.g. @file{all.SCORE}), you must first make this
+score file the current one.
+
+General score commands that don't actually change the score file:
+
+@table @kbd
+
+@item V s
+@kindex V s (Summary)
+@findex gnus-summary-set-score
+Set the score of the current article (@code{gnus-summary-set-score}).
+
+@item V S
+@kindex V S (Summary)
+@findex gnus-summary-current-score
+Display the score of the current article
+(@code{gnus-summary-current-score}).
+
+@item V t
+@kindex V t (Summary)
+@findex gnus-score-find-trace
+Display all score rules that have been used on the current article
+(@code{gnus-score-find-trace}).
+
+@item V R
+@kindex V R (Summary)
+@findex gnus-summary-rescore
+Run the current summary through the scoring process
+(@code{gnus-summary-rescore}). This might be useful if you're playing
+around with your score files behind Gnus' back and want to see the
+effect you're having.
+
+@item V c
+@kindex V c (Summary)
+@findex gnus-score-change-score-file
+Make a different score file the current
+(@code{gnus-score-change-score-file}).
+
+@item V e
+@kindex V e (Summary)
+@findex gnus-score-edit-current-scores
+Edit the current score file (@code{gnus-score-edit-current-scores}).
+You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score
+File Editing}).
+
+@item V f
+@kindex V f (Summary)
+@findex gnus-score-edit-file
+Edit a score file and make this score file the current one
+(@code{gnus-score-edit-file}).
+
+@item V F
+@kindex V F (Summary)
+@findex gnus-score-flush-cache
+Flush the score cache (@code{gnus-score-flush-cache}). This is useful
+after editing score files.
+
+@item V C
+@kindex V C (Summary)
+@findex gnus-score-customize
+Customize a score file in a visually pleasing manner
+(@code{gnus-score-customize}).
+
+@end table
+
+The rest of these commands modify the local score file.
+
+@table @kbd
+
+@item V m
+@kindex V m (Summary)
+@findex gnus-score-set-mark-below
+Prompt for a score, and mark all articles with a score below this as
+read (@code{gnus-score-set-mark-below}).
+
+@item V x
+@kindex V x (Summary)
+@findex gnus-score-set-expunge-below
+Prompt for a score, and add a score rule to the current score file to
+expunge all articles below this score
+(@code{gnus-score-set-expunge-below}).
+@end table
+
+The keystrokes for actually making score entries follow a very regular
+pattern, so there's no need to list all the commands. (Hundreds of
+them.)
+
+@findex gnus-summary-increase-score
+@findex gnus-summary-lower-score
+
+@enumerate
+@item
+The first key is either @kbd{I} (upper case i) for increasing the score
+or @kbd{L} for lowering the score.
+@item
+The second key says what header you want to score on. The following
+keys are available:
+@table @kbd
+
+@item a
+Score on the author name.
+
+@item s
+Score on the subject line.
+
+@item x
+Score on the Xref line---i.e., the cross-posting line.
+
+@item r
+Score on the References line.
+
+@item d
+Score on the date.
+
+@item l
+Score on the number of lines.
+
+@item i
+Score on the Message-ID.
+
+@item f
+Score on followups.
+
+@item b
+Score on the body.
+
+@item h
+Score on the head.
+
+@item t
+Score on thead.
+
+@end table
+
+@item
+The third key is the match type. Which match types are valid depends on
+what headers you are scoring on.
+
+@table @code
+
+@item strings
+
+@table @kbd
+
+@item e
+Exact matching.
+
+@item s
+Substring matching.
+
+@item f
+Fuzzy matching (@pxref{Fuzzy Matching}).
+
+@item r
+Regexp matching
+@end table
+
+@item date
+@table @kbd
+
+@item b
+Before date.
+
+@item a
+After date.
+
+@item n
+This date.
+@end table
+
+@item number
+@table @kbd
+
+@item <
+Less than number.
+
+@item =
+Equal to number.
+
+@item >
+Greater than number.
+@end table
+@end table
+
+@item
+The fourth and final key says whether this is a temporary (i.e., expiring)
+score entry, or a permanent (i.e., non-expiring) score entry, or whether
+it is to be done immediately, without adding to the score file.
+@table @kbd
+
+@item t
+Temporary score entry.
+
+@item p
+Permanent score entry.
+
+@item i
+Immediately scoring.
+@end table
+
+@end enumerate
+
+So, let's say you want to increase the score on the current author with
+exact matching permanently: @kbd{I a e p}. If you want to lower the
+score based on the subject line, using substring matching, and make a
+temporary score entry: @kbd{L s s t}. Pretty easy.
+
+To make things a bit more complicated, there are shortcuts. If you use
+a capital letter on either the second or third keys, Gnus will use
+defaults for the remaining one or two keystrokes. The defaults are
+``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s
+t}, and @kbd{I a R} is the same as @kbd{I a r t}.
+
+These functions take both the numerical prefix and the symbolic prefix
+(@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower
+(or increase) the score of the article. A symbolic prefix of @code{a}
+says to use the @file{all.SCORE} file for the command instead of the
+current score file.
+
+@vindex gnus-score-mimic-keymap
+The @code{gnus-score-mimic-keymap} says whether these commands will
+pretend they are keymaps or not.
+
+
+@node Group Score Commands
+@section Group Score Commands
+@cindex group score commands
+
+There aren't many of these as yet, I'm afraid.
+
+@table @kbd
+
+@item W f
+@kindex W f (Group)
+@findex gnus-score-flush-cache
+Gnus maintains a cache of score alists to avoid having to reload them
+all the time. This command will flush the cache
+(@code{gnus-score-flush-cache}).
+
+@end table
+
+You can do scoring from the command line by saying something like:
+
+@findex gnus-batch-score
+@cindex batch scoring
+@example
+$ emacs -batch -l ~/.emacs -l gnus -f gnus-batch-score
+@end example
+
+
+@node Score Variables
+@section Score Variables
+@cindex score variables
+
+@table @code
+
+@item gnus-use-scoring
+@vindex gnus-use-scoring
+If @code{nil}, Gnus will not check for score files, and will not, in
+general, do any score-related work. This is @code{t} by default.
+
+@item gnus-kill-killed
+@vindex gnus-kill-killed
+If this variable is @code{nil}, Gnus will never apply score files to
+articles that have already been through the kill process. While this
+may save you lots of time, it also means that if you apply a kill file
+to a group, and then change the kill file and want to run it over you
+group again to kill more articles, it won't work. You have to set this
+variable to @code{t} to do that. (It is @code{t} by default.)
+
+@item gnus-kill-files-directory
+@vindex gnus-kill-files-directory
+All kill and score files will be stored in this directory, which is
+initialized from the @code{SAVEDIR} environment variable by default.
+This is @file{~/News/} by default.
+
+@item gnus-score-file-suffix
+@vindex gnus-score-file-suffix
+Suffix to add to the group name to arrive at the score file name
+(@samp{SCORE} by default.)
+
+@item gnus-score-uncacheable-files
+@vindex gnus-score-uncacheable-files
+@cindex score cache
+All score files are normally cached to avoid excessive re-loading of
+score files. However, if this might make you Emacs grow big and
+bloated, so this regexp can be used to weed out score files unlikely to be needed again. It would be a bad idea to deny caching of
+@file{all.SCORE}, while it might be a good idea to not cache
+@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
+variable is @samp{ADAPT$} by default, so no adaptive score files will
+be cached.
+
+@item gnus-save-score
+@vindex gnus-save-score
+If you have really complicated score files, and do lots of batch
+scoring, then you might set this variable to @code{t}. This will make
+Gnus save the scores into the @file{.newsrc.eld} file.
+
+@item gnus-score-interactive-default-score
+@vindex gnus-score-interactive-default-score
+Score used by all the interactive raise/lower commands to raise/lower
+score with. Default is 1000, which may seem excessive, but this is to
+ensure that the adaptive scoring scheme gets enough room to play with.
+We don't want the small changes from the adaptive scoring to overwrite
+manually entered data.
+
+@item gnus-summary-default-score
+@vindex gnus-summary-default-score
+Default score of an article, which is 0 by default.
+
+@item gnus-summary-expunge-below
+@vindex gnus-summary-expunge-below
+Don't display the summary lines of articles that have scores lower than
+this variable. This is @code{nil} by default, which means that no
+articles will be hidden. This variable is local to the summary buffers,
+and has to be set from @code{gnus-summary-mode-hook}.
+
+@item gnus-score-over-mark
+@vindex gnus-score-over-mark
+Mark (in the third column) used for articles with a score over the
+default. Default is @samp{+}.
+
+@item gnus-score-below-mark
+@vindex gnus-score-below-mark
+Mark (in the third column) used for articles with a score below the
+default. Default is @samp{-}.
+
+@item gnus-score-find-score-files-function
+@vindex gnus-score-find-score-files-function
+Function used to find score files for the current group. This function
+is called with the name of the group as the argument.
+
+Predefined functions available are:
+@table @code
+
+@item gnus-score-find-single
+@findex gnus-score-find-single
+Only apply the group's own score file.
+
+@item gnus-score-find-bnews
+@findex gnus-score-find-bnews
+Apply all score files that match, using bnews syntax. This is the
+default. If the current group is @samp{gnu.emacs.gnus}, for instance,
+@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and
+@file{gnu.all.SCORE} would all apply. In short, the instances of
+@samp{all} in the score file names are translated into @samp{.*}, and
+then a regexp match is done.
+
+This means that if you have some score entries that you want to apply to
+all groups, then you put those entries in the @file{all.SCORE} file.
+
+The score files are applied in a semi-random order, although Gnus will
+try to apply the more general score files before the more specific score
+files. It does this by looking at the number of elements in the score
+file names---discarding the @samp{all} elements.
+
+@item gnus-score-find-hierarchical
+@findex gnus-score-find-hierarchical
+Apply all score files from all the parent groups. This means that you
+can't have score files like @file{all.SCORE}, but you can have
+@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE}.
+
+@end table
+This variable can also be a list of functions. In that case, all these
+functions will be called, and all the returned lists of score files will
+be applied. These functions can also return lists of score alists
+directly. In that case, the functions that return these non-file score
+alists should probably be placed before the ``real'' score file
+functions, to ensure that the last score file returned is the local
+score file. Phu.
+
+@item gnus-score-expiry-days
+@vindex gnus-score-expiry-days
+This variable says how many days should pass before an unused score file
+entry is expired. If this variable is @code{nil}, no score file entries
+are expired. It's 7 by default.
+
+@item gnus-update-score-entry-dates
+@vindex gnus-update-score-entry-dates
+If this variable is non-@code{nil}, matching score entries will have
+their dates updated. (This is how Gnus controls expiry---all
+non-matching entries will become too old while matching entries will
+stay fresh and young.) However, if you set this variable to @code{nil},
+even matching entries will grow old and will have to face that oh-so
+grim reaper.
+
+@item gnus-score-after-write-file-function
+@vindex gnus-score-after-write-file-function
+Function called with the name of the score file just written.
+
+@item gnus-score-thread-simplify
+@vindex gnus-score-thread-simplify
+If this variable is non-@code{nil}, article subjects will be simplified
+for subject scoring purposes in the same manner as with
+threading---according to the current value of
+gnus-simplify-subject-functions. If the scoring entry uses
+@code{substring} or @code{exact} matching, the match will also be
+simplified in this manner.
+
+@end table
+
+
+@node Score File Format
+@section Score File Format
+@cindex score file format
+
+A score file is an @code{emacs-lisp} file that normally contains just a
+single form. Casual users are not expected to edit these files;
+everything can be changed from the summary buffer.
+
+Anyway, if you'd like to dig into it yourself, here's an example:
+
+@lisp
+(("from"
+ ("Lars Ingebrigtsen" -10000)
+ ("Per Abrahamsen")
+ ("larsi\\|lmi" -50000 nil R))
+ ("subject"
+ ("Ding is Badd" nil 728373))
+ ("xref"
+ ("alt.politics" -1000 728372 s))
+ ("lines"
+ (2 -100 nil <))
+ (mark 0)
+ (expunge -1000)
+ (mark-and-expunge -10)
+ (read-only nil)
+ (orphan -10)
+ (adapt t)
+ (files "/hom/larsi/News/gnu.SCORE")
+ (exclude-files "all.SCORE")
+ (local (gnus-newsgroup-auto-expire t)
+ (gnus-summary-make-false-root empty))
+ (eval (ding)))
+@end lisp
+
+This example demonstrates most score file elements. For a different
+approach, see @pxref{Advanced Scoring}.
+
+Even though this looks much like lisp code, nothing here is actually
+@code{eval}ed. The lisp reader is used to read this form, though, so it
+has to be valid syntactically, if not semantically.
+
+Six keys are supported by this alist:
+
+@table @code
+
+@item STRING
+If the key is a string, it is the name of the header to perform the
+match on. Scoring can only be performed on these eight headers:
+@code{From}, @code{Subject}, @code{References}, @code{Message-ID},
+@code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to
+these headers, there are three strings to tell Gnus to fetch the entire
+article and do the match on larger parts of the article: @code{Body}
+will perform the match on the body of the article, @code{Head} will
+perform the match on the head of the article, and @code{All} will
+perform the match on the entire article. Note that using any of these
+last three keys will slow down group entry @emph{considerably}. The
+final ``header'' you can score on is @code{Followup}. These score
+entries will result in new score entries being added for all follow-ups
+to articles that matches these score entries.
+
+Following this key is a arbitrary number of score entries, where each
+score entry has one to four elements.
+@enumerate
+
+@item
+The first element is the @dfn{match element}. On most headers this will
+be a string, but on the Lines and Chars headers, this must be an
+integer.
+
+@item
+If the second element is present, it should be a number---the @dfn{score
+element}. This number should be an integer in the neginf to posinf
+interval. This number is added to the score of the article if the match
+is successful. If this element is not present, the
+@code{gnus-score-interactive-default-score} number will be used
+instead. This is 1000 by default.
+
+@item
+If the third element is present, it should be a number---the @dfn{date
+element}. This date says when the last time this score entry matched,
+which provides a mechanism for expiring the score entries. It this
+element is not present, the score entry is permanent. The date is
+represented by the number of days since December 31, 1 BCE.
+
+@item
+If the fourth element is present, it should be a symbol---the @dfn{type
+element}. This element specifies what function should be used to see
+whether this score entry matches the article. What match types that can
+be used depends on what header you wish to perform the match on.
+@table @dfn
+
+@item From, Subject, References, Xref, Message-ID
+For most header types, there are the @code{r} and @code{R} (regexp), as
+well as @code{s} and @code{S} (substring) types, and @code{e} and
+@code{E} (exact match), and @code{w} (word match) types. If this
+element is not present, Gnus will assume that substring matching should
+be used. @code{R}, @code{S}, and @code{E} differ from the others in
+that the matches will be done in a case-sensitive manner. All these
+one-letter types are really just abbreviations for the @code{regexp},
+@code{string}, @code{exact}, and @code{word} types, which you can use
+instead, if you feel like.
+
+@item Lines, Chars
+These two headers use different match types: @code{<}, @code{>},
+@code{=}, @code{>=} and @code{<=}.
+
+These predicates are true if
+
+@example
+(PREDICATE HEADER MATCH)
+@end example
+
+evaluates to non-@code{nil}. For instance, the advanced match
+@code{("lines" 4 <)} (@pxref{Advanced Scoring}) will result in the
+following form:
+
+@lisp
+(< header-value 4)
+@end lisp
+
+Or to put it another way: When using @code{<} on @code{Lines} with 4 as
+the match, we get the score added if the article has less than 4 lines.
+(It's easy to get confused and think it's the other way around. But
+it's not. I think.)
+
+When matching on @code{Lines}, be careful because some backends (like
+@code{nndir}) do not generate @code{Lines} header, so every article ends
+up being marked as having 0 lines. This can lead to strange results if
+you happen to lower score of the articles with few lines.
+
+@item Date
+For the Date header we have three kinda silly match types:
+@code{before}, @code{at} and @code{after}. I can't really imagine this
+ever being useful, but, like, it would feel kinda silly not to provide
+this function. Just in case. You never know. Better safe than sorry.
+Once burnt, twice shy. Don't judge a book by its cover. Never not have
+sex on a first date. (I have been told that at least one person, and I
+quote, ``found this function indispensable'', however.)
+
+@cindex ISO8601
+@cindex date
+A more useful match type is @code{regexp}. With it, you can match the
+date string using a regular expression. The date is normalized to
+ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If
+you want to match all articles that have been posted on April 1st in
+every year, you could use @samp{....0401.........} as a match string,
+for instance. (Note that the date is kept in its original time zone, so
+this will match articles that were posted when it was April 1st where
+the article was posted from. Time zones are such wholesome fun for the
+whole family, eh?)
+
+@item Head, Body, All
+These three match keys use the same match types as the @code{From} (etc)
+header uses.
+
+@item Followup
+This match key is somewhat special, in that it will match the
+@code{From} header, and affect the score of not only the matching
+articles, but also all followups to the matching articles. This allows
+you e.g. increase the score of followups to your own articles, or
+decrease the score of followups to the articles of some known
+trouble-maker. Uses the same match types as the @code{From} header
+uses. (Using this match key will lead to creation of @file{ADAPT}
+files.)
+
+@item Thread
+This match key works along the same lines as the @code{Followup} match
+key. If you say that you want to score on a (sub-)thread started by an article with a @code{Message-ID} @var{X}, then you add a
+@samp{thread} match. This will add a new @samp{thread} match for each
+article that has @var{X} in its @code{References} header. (These new
+@samp{thread} matches will use the @code{Message-ID}s of these matching
+articles.) This will ensure that you can raise/lower the score of an
+entire thread, even though some articles in the thread may not have
+complete @code{References} headers. Note that using this may lead to
+undeterministic scores of the articles in the thread. (Using this match
+key will lead to creation of @file{ADAPT} files.)
+@end table
+@end enumerate
+
+@cindex Score File Atoms
+@item mark
+The value of this entry should be a number. Any articles with a score
+lower than this number will be marked as read.
+
+@item expunge
+The value of this entry should be a number. Any articles with a score
+lower than this number will be removed from the summary buffer.
+
+@item mark-and-expunge
+The value of this entry should be a number. Any articles with a score
+lower than this number will be marked as read and removed from the
+summary buffer.
+
+@item thread-mark-and-expunge
+The value of this entry should be a number. All articles that belong to
+a thread that has a total score below this number will be marked as read
+and removed from the summary buffer. @code{gnus-thread-score-function}
+says how to compute the total score for a thread.
+
+@item files
+The value of this entry should be any number of file names. These files
+are assumed to be score files as well, and will be loaded the same way
+this one was.
+
+@item exclude-files
+The clue of this entry should be any number of files. These files will
+not be loaded, even though they would normally be so, for some reason or
+other.
+
+@item eval
+The value of this entry will be @code{eval}el. This element will be
+ignored when handling global score files.
+
+@item read-only
+Read-only score files will not be updated or saved. Global score files
+should feature this atom (@pxref{Global Score Files}). (Note:
+@dfn{Global} here really means @dfn{global}; not your personal
+apply-to-all-groups score files.)
+
+@item orphan
+The value of this entry should be a number. Articles that do not have
+parents will get this number added to their scores. Imagine you follow
+some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you
+will only follow a few of the threads, also want to see any new threads.
+
+You can do this with the following two score file entries:
+
+@example
+ (orphan -500)
+ (mark-and-expunge -100)
+@end example
+
+When you enter the group the first time, you will only see the new
+threads. You then raise the score of the threads that you find
+interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the
+rest. Next time you enter the group, you will see new articles in the
+interesting threads, plus any new threads.
+
+I.e.---the orphan score atom is for high-volume groups where there
+exist a few interesting threads which can't be found automatically by
+ordinary scoring rules.
+
+@item adapt
+This entry controls the adaptive scoring. If it is @code{t}, the
+default adaptive scoring rules will be used. If it is @code{ignore}, no
+adaptive scoring will be performed on this group. If it is a list, this
+list will be used as the adaptive scoring rules. If it isn't present,
+or is something other than @code{t} or @code{ignore}, the default
+adaptive scoring rules will be used. If you want to use adaptive
+scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to
+@code{t}, and insert an @code{(adapt ignore)} in the groups where you do
+not want adaptive scoring. If you only want adaptive scoring in a few
+groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and
+insert @code{(adapt t)} in the score files of the groups where you want
+it.
+
+@item adapt-file
+All adaptive score entries will go to the file named by this entry. It
+will also be applied when entering the group. This atom might be handy
+if you want to adapt on several groups at once, using the same adaptive
+file for a number of groups.
+
+@item local
+@cindex local variables
+The value of this entry should be a list of @code{(VAR VALUE)} pairs.
+Each @var{var} will be made buffer-local to the current summary buffer,
+and set to the value specified. This is a convenient, if somewhat
+strange, way of setting variables in some groups if you don't like hooks
+much. Note that the @var{value} won't be evaluated.
+@end table
+
+
+@node Score File Editing
+@section Score File Editing
+
+You normally enter all scoring commands from the summary buffer, but you
+might feel the urge to edit them by hand as well, so we've supplied you
+with a mode for that.
+
+It's simply a slightly customized @code{emacs-lisp} mode, with these
+additional commands:
+
+@table @kbd
+
+@item C-c C-c
+@kindex C-c C-c (Score)
+@findex gnus-score-edit-done
+Save the changes you have made and return to the summary buffer
+(@code{gnus-score-edit-done}).
+
+@item C-c C-d
+@kindex C-c C-d (Score)
+@findex gnus-score-edit-insert-date
+Insert the current date in numerical format
+(@code{gnus-score-edit-insert-date}). This is really the day number, if
+you were wondering.
+
+@item C-c C-p
+@kindex C-c C-p (Score)
+@findex gnus-score-pretty-print
+The adaptive score files are saved in an unformatted fashion. If you
+intend to read one of these files, you want to @dfn{pretty print} it
+first. This command (@code{gnus-score-pretty-print}) does that for
+you.
+
+@end table
+
+Type @kbd{M-x gnus-score-mode} to use this mode.
+
+@vindex gnus-score-mode-hook
+@code{gnus-score-menu-hook} is run in score mode buffers.
+
+In the summary buffer you can use commands like @kbd{V f} and @kbd{V
+e} to begin editing score files.
+
+
+@node Adaptive Scoring
+@section Adaptive Scoring
+@cindex adaptive scoring
+
+If all this scoring is getting you down, Gnus has a way of making it all
+happen automatically---as if by magic. Or rather, as if by artificial
+stupidity, to be precise.
+
+@vindex gnus-use-adaptive-scoring
+When you read an article, or mark an article as read, or kill an
+article, you leave marks behind. On exit from the group, Gnus can sniff
+these marks and add score elements depending on what marks it finds.
+You turn on this ability by setting @code{gnus-use-adaptive-scoring} to
+@code{t} or @code{(line)}. If you want score adaptively on separate
+words appearing in the subjects, you should set this variable to
+@code{(word)}. If you want to use both adaptive methods, set this
+variable to @code{(word line)}.
+
+@vindex gnus-default-adaptive-score-alist
+To give you complete control over the scoring process, you can customize
+the @code{gnus-default-adaptive-score-alist} variable. For instance, it
+might look something like this:
+
+@lisp
+(defvar gnus-default-adaptive-score-alist
+ '((gnus-unread-mark)
+ (gnus-ticked-mark (from 4))
+ (gnus-dormant-mark (from 5))
+ (gnus-del-mark (from -4) (subject -1))
+ (gnus-read-mark (from 4) (subject 2))
+ (gnus-expirable-mark (from -1) (subject -1))
+ (gnus-killed-mark (from -1) (subject -3))
+ (gnus-kill-file-mark)
+ (gnus-ancient-mark)
+ (gnus-low-score-mark)
+ (gnus-catchup-mark (from -1) (subject -1))))
+@end lisp
+
+As you see, each element in this alist has a mark as a key (either a
+variable name or a ``real'' mark---a character). Following this key is
+a arbitrary number of header/score pairs. If there are no header/score
+pairs following the key, no adaptive scoring will be done on articles
+that have that key as the article mark. For instance, articles with
+@code{gnus-unread-mark} in the example above will not get adaptive score
+entries.
+
+Each article can have only one mark, so just a single of these rules
+will be applied to each article.
+
+To take @code{gnus-del-mark} as an example---this alist says that all
+articles that have that mark (i.e., are marked with @samp{D}) will have a
+score entry added to lower based on the @code{From} header by -4, and
+lowered by @code{Subject} by -1. Change this to fit your prejudices.
+
+If you have marked 10 articles with the same subject with
+@code{gnus-del-mark}, the rule for that mark will be applied ten times.
+That means that that subject will get a score of ten times -1, which
+should be, unless I'm much mistaken, -10.
+
+If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all
+the read articles will be marked with the @samp{E} mark. This'll
+probably make adaptive scoring slightly impossible, so auto-expiring and
+adaptive scoring doesn't really mix very well.
+
+The headers you can score on are @code{from}, @code{subject},
+@code{message-id}, @code{references}, @code{xref}, @code{lines},
+@code{chars} and @code{date}. In addition, you can score on
+@code{followup}, which will create an adaptive score entry that matches
+on the @code{References} header using the @code{Message-ID} of the
+current article, thereby matching the following thread.
+
+You can also score on @code{thread}, which will try to score all
+articles that appear in a thread. @code{thread} matches uses a
+@code{Message-ID} to match on the @code{References} header of the
+article. If the match is made, the @code{Message-ID} of the article is
+added to the @code{thread} rule. (Think about it. I'd recommend two
+aspirins afterwards.)
+
+If you use this scheme, you should set the score file atom @code{mark}
+to something small---like -300, perhaps, to avoid having small random
+changes result in articles getting marked as read.
+
+After using adaptive scoring for a week or so, Gnus should start to
+become properly trained and enhance the authors you like best, and kill
+the authors you like least, without you having to say so explicitly.
+
+You can control what groups the adaptive scoring is to be performed on
+by using the score files (@pxref{Score File Format}). This will also
+let you use different rules in different groups.
+
+@vindex gnus-adaptive-file-suffix
+The adaptive score entries will be put into a file where the name is the
+group name with @code{gnus-adaptive-file-suffix} appended. The default
+is @samp{ADAPT}.
+
+@vindex gnus-score-exact-adapt-limit
+When doing adaptive scoring, substring or fuzzy matching would probably
+give you the best results in most cases. However, if the header one
+matches is short, the possibility for false positives is great, so if
+the length of the match is less than
+@code{gnus-score-exact-adapt-limit}, exact matching will be used. If
+this variable is @code{nil}, exact matching will always be used to avoid
+this problem.
+
+@vindex gnus-default-adaptive-word-score-alist
+As mentioned above, you can adapt either on individual words or entire
+headers. If you adapt on words, the
+@code{gnus-default-adaptive-word-score-alist} variable says what score
+each instance of a word should add given a mark.
+
+@lisp
+(setq gnus-default-adaptive-word-score-alist
+ `((,gnus-read-mark . 30)
+ (,gnus-catchup-mark . -10)
+ (,gnus-killed-mark . -20)
+ (,gnus-del-mark . -15)))
+@end lisp
+
+This is the default value. If you have adaption on words enabled, every
+word that appears in subjects of articles marked with
+@code{gnus-read-mark} will result in a score rule that increase the
+score with 30 points.
+
+@vindex gnus-default-ignored-adaptive-words
+@vindex gnus-ignored-adaptive-words
+Words that appear in the @code{gnus-default-ignored-adaptive-words} list
+will be ignored. If you wish to add more words to be ignored, use the
+@code{gnus-ignored-adaptive-words} list instead.
+
+@vindex gnus-adaptive-word-syntax-table
+When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the
+syntax table in effect. It is similar to the standard syntax table, but
+it considers numbers to be non-word-constituent characters.
+
+@vindex gnus-adaptive-word-minimum
+If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive
+word scoring process will never bring down the score of an article to
+below this number. The default is @code{nil}.
+
+After using this scheme for a while, it might be nice to write a
+@code{gnus-psychoanalyze-user} command to go through the rules and see
+what words you like and what words you don't like. Or perhaps not.
+
+Note that the adaptive word scoring thing is highly experimental and is
+likely to change in the future. Initial impressions seem to indicate
+that it's totally useless as it stands. Some more work (involving more
+rigorous statistical methods) will have to be done to make this useful.
+
+
+@node Home Score File
+@section Home Score File
+
+The score file where new score file entries will go is called the
+@dfn{home score file}. This is normally (and by default) the score file
+for the group itself. For instance, the home score file for
+@samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}.
+
+However, this may not be what you want. It is often convenient to share
+a common home score file among many groups---all @samp{emacs} groups
+could perhaps use the same home score file.
+
+@vindex gnus-home-score-file
+The variable that controls this is @code{gnus-home-score-file}. It can
+be:
+
+@enumerate
+@item
+A string. Then this file will be used as the home score file for all
+groups.
+
+@item
+A function. The result of this function will be used as the home score
+file. The function will be called with the name of the group as the
+parameter.
+
+@item
+A list. The elements in this list can be:
+
+@enumerate
+@item
+@var{(regexp file-name)}. If the @var{regexp} matches the group name,
+the @var{file-name} will will be used as the home score file.
+
+@item
+A function. If the function returns non-nil, the result will be used as
+the home score file.
+
+@item
+A string. Use the string as the home score file.
+@end enumerate
+
+The list will be traversed from the beginning towards the end looking
+for matches.
+
+@end enumerate
+
+So, if you want to use just a single score file, you could say:
+
+@lisp
+(setq gnus-home-score-file
+ "my-total-score-file.SCORE")
+@end lisp
+
+If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and
+@file{rec.SCORE} for all @samp{rec} groups (and so on), you can say:
+
+@findex gnus-hierarchial-home-score-file
+@lisp
+(setq gnus-home-score-file
+ 'gnus-hierarchial-home-score-file)
+@end lisp
+
+This is a ready-made function provided for your convenience.
+Other functions include
+
+@table @code
+@item gnus-current-home-score-file
+@findex gnus-current-home-score-file
+Return the ``current'' regular score file. This will make scoring
+commands add entry to the ``innermost'' matching score file.
+
+@end table
+
+If you want to have one score file for the @samp{emacs} groups and
+another for the @samp{comp} groups, while letting all other groups use
+their own home score files:
+
+@lisp
+(setq gnus-home-score-file
+ ;; All groups that match the regexp "\\.emacs"
+ '(("\\.emacs" "emacs.SCORE")
+ ;; All the comp groups in one score file
+ ("^comp" "comp.SCORE")))
+@end lisp
+
+@vindex gnus-home-adapt-file
+@code{gnus-home-adapt-file} works exactly the same way as
+@code{gnus-home-score-file}, but says what the home adaptive score file
+is instead. All new adaptive file entries will go into the file
+specified by this variable, and the same syntax is allowed.
+
+In addition to using @code{gnus-home-score-file} and
+@code{gnus-home-adapt-file}, you can also use group parameters
+(@pxref{Group Parameters}) and topic parameters (@pxref{Topic
+Parameters}) to achieve much the same. Group and topic parameters take
+precedence over this variable.
+
+
+@node Followups To Yourself
+@section Followups To Yourself
+
+Gnus offers two commands for picking out the @code{Message-ID} header in
+the current buffer. Gnus will then add a score rule that scores using
+this @code{Message-ID} on the @code{References} header of other
+articles. This will, in effect, increase the score of all articles that
+respond to the article in the current buffer. Quite useful if you want
+to easily note when people answer what you've said.
+
+@table @code
+
+@item gnus-score-followup-article
+@findex gnus-score-followup-article
+This will add a score to articles that directly follow up your own
+article.
+
+@item gnus-score-followup-thread
+@findex gnus-score-followup-thread
+This will add a score to all articles that appear in a thread ``below''
+your own article.
+@end table
+
+@vindex message-sent-hook
+These two functions are both primarily meant to be used in hooks like
+@code{message-sent-hook}.
+
+If you look closely at your own @code{Message-ID}, you'll notice that
+the first two or three characters are always the same. Here's two of
+mine:
+
+@example
+<x6u3u47icf.fsf@@eyesore.no>
+<x6sp9o7ibw.fsf@@eyesore.no>
+@end example
+
+So ``my'' ident on this machine is @samp{x6}. This can be
+exploited---the following rule will raise the score on all followups to
+myself:
+
+@lisp
+("references"
+ ("<x6[0-9a-z]+\\.fsf\\(_-_\\)?@@.*eyesore.no>"
+ 1000 nil r))
+@end lisp
+
+Whether it's the first two or first three characters that are ``yours''
+is system-dependent.
+
+
+@node Scoring Tips
+@section Scoring Tips
+@cindex scoring tips
+
+@table @dfn
+
+@item Crossposts
+@cindex crossposts
+@cindex scoring crossposts
+If you want to lower the score of crossposts, the line to match on is
+the @code{Xref} header.
+@lisp
+("xref" (" talk.politics.misc:" -1000))
+@end lisp
+
+@item Multiple crossposts
+If you want to lower the score of articles that have been crossposted to
+more than, say, 3 groups:
+@lisp
+("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
+@end lisp
+
+@item Matching on the body
+This is generally not a very good idea---it takes a very long time.
+Gnus actually has to fetch each individual article from the server. But
+you might want to anyway, I guess. Even though there are three match
+keys (@code{Head}, @code{Body} and @code{All}), you should choose one
+and stick with it in each score file. If you use any two, each article
+will be fetched @emph{twice}. If you want to match a bit on the
+@code{Head} and a bit on the @code{Body}, just use @code{All} for all
+the matches.
+
+@item Marking as read
+You will probably want to mark articles that has a score below a certain
+number as read. This is most easily achieved by putting the following
+in your @file{all.SCORE} file:
+@lisp
+((mark -100))
+@end lisp
+You may also consider doing something similar with @code{expunge}.
+
+@item Negated character classes
+If you say stuff like @code{[^abcd]*}, you may get unexpected results.
+That will match newlines, which might lead to, well, The Unknown. Say
+@code{[^abcd\n]*} instead.
+@end table
+
+
+@node Reverse Scoring
+@section Reverse Scoring
+@cindex reverse scoring
+
+If you want to keep just articles that have @samp{Sex with Emacs} in the
+subject header, and expunge all other articles, you could put something
+like this in your score file:
+
+@lisp
+(("subject"
+ ("Sex with Emacs" 2))
+ (mark 1)
+ (expunge 1))
+@end lisp
+
+So, you raise all articles that match @samp{Sex with Emacs} and mark the
+rest as read, and expunge them to boot.
+
+
+@node Global Score Files
+@section Global Score Files
+@cindex global score files
+
+Sure, other newsreaders have ``global kill files''. These are usually
+nothing more than a single kill file that applies to all groups, stored
+in the user's home directory. Bah! Puny, weak newsreaders!
+
+What I'm talking about here are Global Score Files. Score files from
+all over the world, from users everywhere, uniting all nations in one
+big, happy score file union! Ange-score! New and untested!
+
+@vindex gnus-global-score-files
+All you have to do to use other people's score files is to set the
+@code{gnus-global-score-files} variable. One entry for each score file,
+or each score file directory. Gnus will decide by itself what score
+files are applicable to which group.
+
+Say you want to use the score file
+@file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and
+all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory:
+
+@lisp
+(setq gnus-global-score-files
+ '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE"
+ "/ftp@@ftp.some-where:/pub/score/"))
+@end lisp
+
+@findex gnus-score-search-global-directories
+Simple, eh? Directory names must end with a @samp{/}. These
+directories are typically scanned only once during each Gnus session.
+If you feel the need to manually re-scan the remote directories, you can
+use the @code{gnus-score-search-global-directories} command.
+
+Note that, at present, using this option will slow down group entry
+somewhat. (That is---a lot.)
+
+If you want to start maintaining score files for other people to use,
+just put your score file up for anonymous ftp and announce it to the
+world. Become a retro-moderator! Participate in the retro-moderator
+wars sure to ensue, where retro-moderators battle it out for the
+sympathy of the people, luring them to use their score files on false
+premises! Yay! The net is saved!
+
+Here are some tips for the would-be retro-moderator, off the top of my
+head:
+
+@itemize @bullet
+
+@item
+Articles heavily crossposted are probably junk.
+@item
+To lower a single inappropriate article, lower by @code{Message-ID}.
+@item
+Particularly brilliant authors can be raised on a permanent basis.
+@item
+Authors that repeatedly post off-charter for the group can safely be
+lowered out of existence.
+@item
+Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest
+articles completely.
+
+@item
+Use expiring score entries to keep the size of the file down. You
+should probably have a long expiry period, though, as some sites keep
+old articles for a long time.
+@end itemize
+
+... I wonder whether other newsreaders will support global score files
+in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
+Wave, xrn and 1stReader are bound to implement scoring. Should we start
+holding our breath yet?
+
+
+@node Kill Files
+@section Kill Files
+@cindex kill files
+
+Gnus still supports those pesky old kill files. In fact, the kill file
+entries can now be expiring, which is something I wrote before Daniel
+Quinlan thought of doing score files, so I've left the code in there.
+
+In short, kill processing is a lot slower (and I do mean @emph{a lot})
+than score processing, so it might be a good idea to rewrite your kill
+files into score files.
+
+Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any
+forms into this file, which means that you can use kill files as some
+sort of primitive hook function to be run on group entry, even though
+that isn't a very good idea.
+
+Normal kill files look like this:
+
+@lisp
+(gnus-kill "From" "Lars Ingebrigtsen")
+(gnus-kill "Subject" "ding")
+(gnus-expunge "X")
+@end lisp
+
+This will mark every article written by me as read, and remove the
+marked articles from the summary buffer. Very useful, you'll agree.
+
+Other programs use a totally different kill file syntax. If Gnus
+encounters what looks like a @code{rn} kill file, it will take a stab at
+interpreting it.
+
+Two summary functions for editing a GNUS kill file:
+
+@table @kbd
+
+@item M-k
+@kindex M-k (Summary)
+@findex gnus-summary-edit-local-kill
+Edit this group's kill file (@code{gnus-summary-edit-local-kill}).
+
+@item M-K
+@kindex M-K (Summary)
+@findex gnus-summary-edit-global-kill
+Edit the general kill file (@code{gnus-summary-edit-global-kill}).
+@end table
+
+Two group mode functions for editing the kill files:
+
+@table @kbd
+
+@item M-k
+@kindex M-k (Group)
+@findex gnus-group-edit-local-kill
+Edit this group's kill file (@code{gnus-group-edit-local-kill}).
+
+@item M-K
+@kindex M-K (Group)
+@findex gnus-group-edit-global-kill
+Edit the general kill file (@code{gnus-group-edit-global-kill}).
+@end table
+
+Kill file variables:
+
+@table @code
+@item gnus-kill-file-name
+@vindex gnus-kill-file-name
+A kill file for the group @samp{soc.motss} is normally called
+@file{soc.motss.KILL}. The suffix appended to the group name to get
+this file name is detailed by the @code{gnus-kill-file-name} variable.
+The ``global'' kill file (not in the score file sense of ``global'', of
+course) is just called @file{KILL}.
+
+@vindex gnus-kill-save-kill-file
+@item gnus-kill-save-kill-file
+If this variable is non-@code{nil}, Gnus will save the
+kill file after processing, which is necessary if you use expiring
+kills.
+
+@item gnus-apply-kill-hook
+@vindex gnus-apply-kill-hook
+@findex gnus-apply-kill-file-unless-scored
+@findex gnus-apply-kill-file
+A hook called to apply kill files to a group. It is
+@code{(gnus-apply-kill-file)} by default. If you want to ignore the
+kill file if you have a score file for the same group, you can set this
+hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want
+kill files to be processed, you should set this variable to @code{nil}.
+
+@item gnus-kill-file-mode-hook
+@vindex gnus-kill-file-mode-hook
+A hook called in kill-file mode buffers.
+
+@end table
+
+
+@node Converting Kill Files
+@section Converting Kill Files
+@cindex kill files
+@cindex converting kill files
+
+If you have loads of old kill files, you may want to convert them into
+score files. If they are ``regular'', you can use
+the @file{gnus-kill-to-score.el} package; if not, you'll have to do it
+by hand.
+
+The kill to score conversion package isn't included in Gnus by default.
+You can fetch it from
+@file{http://www.stud.ifi.uio.no/~larsi/ding-other/gnus-kill-to-score}.
+
+If your old kill files are very complex---if they contain more
+non-@code{gnus-kill} forms than not, you'll have to convert them by
+hand. Or just let them be as they are. Gnus will still use them as
+before.
+
+
+@node GroupLens
+@section GroupLens
+@cindex GroupLens
+
+GroupLens is a collaborative filtering system that helps you work
+together with other people to find the quality news articles out of the
+huge volume of news articles generated every day.
+
+To accomplish this the GroupLens system combines your opinions about
+articles you have already read with the opinions of others who have done
+likewise and gives you a personalized prediction for each unread news
+article. Think of GroupLens as a matchmaker. GroupLens watches how you
+rate articles, and finds other people that rate articles the same way.
+Once it has found some people you agree with it tells you, in the form
+of a prediction, what they thought of the article. You can use this
+prediction to help you decide whether or not you want to read the
+article.
+
+@menu
+* Using GroupLens:: How to make Gnus use GroupLens.
+* Rating Articles:: Letting GroupLens know how you rate articles.
+* Displaying Predictions:: Displaying predictions given by GroupLens.
+* GroupLens Variables:: Customizing GroupLens.
+@end menu
+
+
+@node Using GroupLens
+@subsection Using GroupLens
+
+To use GroupLens you must register a pseudonym with your local Better
+Bit Bureau (BBB).
+@samp{http://www.cs.umn.edu/Research/GroupLens/bbb.html} is the only
+better bit in town at the moment.
+
+Once you have registered you'll need to set a couple of variables.
+
+@table @code
+
+@item gnus-use-grouplens
+@vindex gnus-use-grouplens
+Setting this variable to a non-@code{nil} value will make Gnus hook into
+all the relevant GroupLens functions.
+
+@item grouplens-pseudonym
+@vindex grouplens-pseudonym
+This variable should be set to the pseudonym you got when registering
+with the Better Bit Bureau.
+
+@item grouplens-newsgroups
+@vindex grouplens-newsgroups
+A list of groups that you want to get GroupLens predictions for.
+
+@end table
+
+That's the minimum of what you need to get up and running with GroupLens.
+Once you've registered, GroupLens will start giving you scores for
+articles based on the average of what other people think. But, to get
+the real benefit of GroupLens you need to start rating articles
+yourself. Then the scores GroupLens gives you will be personalized for
+you, based on how the people you usually agree with have already rated.
+
+
+@node Rating Articles
+@subsection Rating Articles
+
+In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
+Where 1 means something like this article is a waste of bandwidth and 5
+means that the article was really good. The basic question to ask
+yourself is, "on a scale from 1 to 5 would I like to see more articles
+like this one?"
+
+There are four ways to enter a rating for an article in GroupLens.
+
+@table @kbd
+
+@item r
+@kindex r (GroupLens)
+@findex bbb-summary-rate-article
+This function will prompt you for a rating on a scale of one to five.
+
+@item k
+@kindex k (GroupLens)
+@findex grouplens-score-thread
+This function will prompt you for a rating, and rate all the articles in
+the thread. This is really useful for some of those long running giant
+threads in rec.humor.
+
+@end table
+
+The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be
+the score of the article you're reading.
+
+@table @kbd
+
+@item 1-5 n
+@kindex n (GroupLens)
+@findex grouplens-next-unread-article
+Rate the article and go to the next unread article.
+
+@item 1-5 ,
+@kindex , (GroupLens)
+@findex grouplens-best-unread-article
+Rate the article and go to the next unread article with the highest score.
+
+@end table
+
+If you want to give the current article a score of 4 and then go to the
+next article, just type @kbd{4 n}.
+
+
+@node Displaying Predictions
+@subsection Displaying Predictions
+
+GroupLens makes a prediction for you about how much you will like a
+news article. The predictions from GroupLens are on a scale from 1 to
+5, where 1 is the worst and 5 is the best. You can use the predictions
+from GroupLens in one of three ways controlled by the variable
+@code{gnus-grouplens-override-scoring}.
+
+@vindex gnus-grouplens-override-scoring
+There are three ways to display predictions in grouplens. You may
+choose to have the GroupLens scores contribute to, or override the
+regular gnus scoring mechanism. override is the default; however, some
+people prefer to see the Gnus scores plus the grouplens scores. To get
+the separate scoring behavior you need to set
+@code{gnus-grouplens-override-scoring} to @code{'separate}. To have the
+GroupLens predictions combined with the grouplens scores set it to
+@code{'override} and to combine the scores set
+@code{gnus-grouplens-override-scoring} to @code{'combine}. When you use
+the combine option you will also want to set the values for
+@code{grouplens-prediction-offset} and
+@code{grouplens-score-scale-factor}.
+
+@vindex grouplens-prediction-display
+In either case, GroupLens gives you a few choices for how you would like
+to see your predictions displayed. The display of predictions is
+controlled by the @code{grouplens-prediction-display} variable.
+
+The following are valid values for that variable.
+
+@table @code
+@item prediction-spot
+The higher the prediction, the further to the right an @samp{*} is
+displayed.
+
+@item confidence-interval
+A numeric confidence interval.
+
+@item prediction-bar
+The higher the prediction, the longer the bar.
+
+@item confidence-bar
+Numerical confidence.
+
+@item confidence-spot
+The spot gets bigger with more confidence.
+
+@item prediction-num
+Plain-old numeric value.
+
+@item confidence-plus-minus
+Prediction +/- confidence.
+
+@end table
+
+
+@node GroupLens Variables
+@subsection GroupLens Variables
+
+@table @code
+
+@item gnus-summary-grouplens-line-format
+The summary line format used in GroupLens-enhanced summary buffers. It
+accepts the same specs as the normal summary line format (@pxref{Summary
+Buffer Lines}). The default is @samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%)
+%s\n}.
+
+@item grouplens-bbb-host
+Host running the bbbd server. @samp{grouplens.cs.umn.edu} is the
+default.
+
+@item grouplens-bbb-port
+Port of the host running the bbbd server. The default is 9000.
+
+@item grouplens-score-offset
+Offset the prediction by this value. In other words, subtract the
+prediction value by this number to arrive at the effective score. The
+default is 0.
+
+@item grouplens-score-scale-factor
+This variable allows the user to magnify the effect of GroupLens scores.
+The scale factor is applied after the offset. The default is 1.
+
+@end table
+
+
+@node Advanced Scoring
+@section Advanced Scoring
+
+Scoring on Subjects and From headers is nice enough, but what if you're
+really interested in what a person has to say only when she's talking
+about a particular subject? Or what if you really don't want to
+read what person A has to say when she's following up to person B, but
+want to read what she says when she's following up to person C?
+
+By using advanced scoring rules you may create arbitrarily complex
+scoring patterns.
+
+@menu
+* Advanced Scoring Syntax:: A definition.
+* Advanced Scoring Examples:: What they look like.
+* Advanced Scoring Tips:: Getting the most out of it.
+@end menu
+
+
+@node Advanced Scoring Syntax
+@subsection Advanced Scoring Syntax
+
+Ordinary scoring rules have a string as the first element in the rule.
+Advanced scoring rules have a list as the first element. The second
+element is the score to be applied if the first element evaluated to a
+non-@code{nil} value.
+
+These lists may consist of three logical operators, one redirection
+operator, and various match operators.
+
+Logical operators:
+
+@table @code
+@item &
+@itemx and
+This logical operator will evaluate each of its arguments until it finds
+one that evaluates to @code{false}, and then it'll stop. If all arguments
+evaluate to @code{true} values, then this operator will return
+@code{true}.
+
+@item |
+@itemx or
+This logical operator will evaluate each of its arguments until it finds
+one that evaluates to @code{true}. If no arguments are @code{true},
+then this operator will return @code{false}.
+
+@item !
+@itemx not
+@itemx ¬
+This logical operator only takes a single argument. It returns the
+logical negation of the value of its argument.
+
+@end table
+
+There is an @dfn{indirection operator} that will make its arguments
+apply to the ancestors of the current article being scored. For
+instance, @code{1-} will make score rules apply to the parent of the
+current article. @code{2-} will make score rules apply to the
+grandparent of the current article. Alternatively, you can write
+@code{^^}, where the number of @code{^}s (carets) says how far back into
+the ancestry you want to go.
+
+Finally, we have the match operators. These are the ones that do the
+real work. Match operators are header name strings followed by a match
+and a match type. A typical match operator looks like @samp{("from"
+"Lars Ingebrigtsen" s)}. The header names are the same as when using
+simple scoring, and the match types are also the same.
+
+
+@node Advanced Scoring Examples
+@subsection Advanced Scoring Examples
+
+Let's say you want to increase the score of articles written by Lars
+when he's talking about Gnus:
+
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ ("subject" "Gnus"))
+ 1000)
+@end example
+
+Quite simple, huh?
+
+When he writes long articles, he sometimes has something nice to say:
+
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ (|
+ ("subject" "Gnus")
+ ("lines" 100 >)))
+ 1000)
+@end example
+
+However, when he responds to things written by Reig Eigil Logge, you
+really don't want to read what he's written:
+
+@example
+((&
+ ("from" "Lars Ingebrigtsen")
+ (1- ("from" "Reig Eigir Logge")))
+ -100000)
+@end example
+
+Everybody that follows up Redmondo when he writes about disappearing
+socks should have their scores raised, but only when they talk about
+white socks. However, when Lars talks about socks, it's usually not
+very interesting:
+
+@example
+((&
+ (1-
+ (&
+ ("from" "redmondo@@.*no" r)
+ ("body" "disappearing.*socks" t)))
+ (! ("from" "Lars Ingebrigtsen"))
+ ("body" "white.*socks"))
+ 1000)
+@end example
+
+The possibilities are endless.
+
+
+@node Advanced Scoring Tips
+@subsection Advanced Scoring Tips
+
+The @code{&} and @code{|} logical operators do short-circuit logic.
+That is, they stop processing their arguments when it's clear what the
+result of the operation will be. For instance, if one of the arguments
+of an @code{&} evaluates to @code{false}, there's no point in evaluating
+the rest of the arguments. This means that you should put slow matches
+(@samp{body}, @samp{header}) last and quick matches (@samp{from},
+@samp{subject}) first.
+
+The indirection arguments (@code{1-} and so on) will make their
+arguments work on previous generations of the thread. If you say
+something like:
+
+@example
+...
+(1-
+ (1-
+ ("from" "lars")))
+...
+@end example
+
+Then that means "score on the from header of the grandparent of the
+current article". An indirection is quite fast, but it's better to say:
+
+@example
+(1-
+ (&
+ ("from" "Lars")
+ ("subject" "Gnus")))
+@end example
+
+than it is to say:
+
+@example
+(&
+ (1- ("from" "Lars"))
+ (1- ("subject" "Gnus")))
+@end example
+
+
+@node Score Decays
+@section Score Decays
+@cindex score decays
+@cindex decays
+
+You may find that your scores have a tendency to grow without
+bounds, especially if you're using adaptive scoring. If scores get too
+big, they lose all meaning---they simply max out and it's difficult to
+use them in any sensible way.
+
+@vindex gnus-decay-scores
+@findex gnus-decay-score
+@vindex gnus-decay-score-function
+Gnus provides a mechanism for decaying scores to help with this problem.
+When score files are loaded and @code{gnus-decay-scores} is
+non-@code{nil}, Gnus will run the score files through the decaying
+mechanism thereby lowering the scores of all non-permanent score rules.
+The decay itself if performed by the @code{gnus-decay-score-function}
+function, which is @code{gnus-decay-score} by default. Here's the
+definition of that function:
+
+@lisp
+(defun gnus-decay-score (score)
+ "Decay SCORE.
+This is done according to `gnus-score-decay-constant'
+and `gnus-score-decay-scale'."
+ (floor
+ (- score
+ (* (if (< score 0) 1 -1)
+ (min (abs score)
+ (max gnus-score-decay-constant
+ (* (abs score)
+ gnus-score-decay-scale)))))))
+@end lisp
+
+@vindex gnus-score-decay-scale
+@vindex gnus-score-decay-constant
+@code{gnus-score-decay-constant} is 3 by default and
+@code{gnus-score-decay-scale} is 0.05. This should cause the following:
+
+@enumerate
+@item
+Scores between -3 and 3 will be set to 0 when this function is called.
+
+@item
+Scores with magnitudes between 3 and 60 will be shrunk by 3.
+
+@item
+Scores with magnitudes greater than 60 will be shrunk by 5% of the
+score.
+@end enumerate
+
+If you don't like this decay function, write your own. It is called
+with the score to be decayed as its only parameter, and it should return
+the new score, which should be an integer.
+
+Gnus will try to decay scores once a day. If you haven't run Gnus for
+four days, Gnus will decay the scores four times, for instance.
+
+
+@node Various
+@chapter Various
+
+@menu
+* Process/Prefix:: A convention used by many treatment commands.
+* Interactive:: Making Gnus ask you many questions.
+* Symbolic Prefixes:: How to supply some Gnus functions with options.
+* Formatting Variables:: You can specify what buffers should look like.
+* Windows Configuration:: Configuring the Gnus buffer windows.
+* Faces and Fonts:: How to change how faces look.
+* Compilation:: How to speed Gnus up.
+* Mode Lines:: Displaying information in the mode lines.
+* Highlighting and Menus:: Making buffers look all nice and cozy.
+* Buttons:: Get tendonitis in ten easy steps!
+* Daemons:: Gnus can do things behind your back.
+* NoCeM:: How to avoid spam and other fatty foods.
+* Undo:: Some actions can be undone.
+* Moderation:: What to do if you're a moderator.
+* XEmacs Enhancements:: There are more pictures and stuff under XEmacs.
+* Fuzzy Matching:: What's the big fuzz?
+* Thwarting Email Spam:: A how-to on avoiding unsolicited commercial email.
+* Various Various:: Things that are really various.
+@end menu
+
+
+@node Process/Prefix
+@section Process/Prefix
+@cindex process/prefix convention
+
+Many functions, among them functions for moving, decoding and saving
+articles, use what is known as the @dfn{Process/Prefix convention}.
+
+This is a method for figuring out what articles the user wants the
+command to be performed on.
+
+It goes like this:
+
+If the numeric prefix is N, perform the operation on the next N
+articles, starting with the current one. If the numeric prefix is
+negative, perform the operation on the previous N articles, starting
+with the current one.
+
+@vindex transient-mark-mode
+If @code{transient-mark-mode} in non-@code{nil} and the region is
+active, all articles in the region will be worked upon.
+
+If there is no numeric prefix, but some articles are marked with the
+process mark, perform the operation on the articles marked with
+the process mark.
+
+If there is neither a numeric prefix nor any articles marked with the
+process mark, just perform the operation on the current article.
+
+Quite simple, really, but it needs to be made clear so that surprises
+are avoided.
+
+Commands that react to the process mark will push the current list of
+process marked articles onto a stack and will then clear all process
+marked articles. You can restore the previous configuration with the
+@kbd{M P y} command (@pxref{Setting Process Marks}).
+
+@vindex gnus-summary-goto-unread
+One thing that seems to shock & horrify lots of people is that, for
+instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}.
+Since each @kbd{d} (which marks the current article as read) by default
+goes to the next unread article after marking, this means that @kbd{3 d}
+will mark the next three unread articles as read, no matter what the
+summary buffer looks like. Set @code{gnus-summary-goto-unread} to
+@code{nil} for a more straightforward action.
+
+
+@node Interactive
+@section Interactive
+@cindex interaction
+
+@table @code
+
+@item gnus-novice-user
+@vindex gnus-novice-user
+If this variable is non-@code{nil}, you are either a newcomer to the
+World of Usenet, or you are very cautious, which is a nice thing to be,
+really. You will be given questions of the type ``Are you sure you want
+to do this?'' before doing anything dangerous. This is @code{t} by
+default.
+
+@item gnus-expert-user
+@vindex gnus-expert-user
+If this variable is non-@code{nil}, you will seldom be asked any
+questions by Gnus. It will simply assume you know what you're doing, no
+matter how strange.
+
+@item gnus-interactive-catchup
+@vindex gnus-interactive-catchup
+Require confirmation before catching up a group if non-@code{nil}. It
+is @code{t} by default.
+
+@item gnus-interactive-exit
+@vindex gnus-interactive-exit
+Require confirmation before exiting Gnus. This variable is @code{t} by
+default.
+@end table
+
+
+@node Symbolic Prefixes
+@section Symbolic Prefixes
+@cindex symbolic prefixes
+
+Quite a lot of Emacs commands react to the (numeric) prefix. For
+instance, @kbd{C-u 4 C-f} moves point four characters forward, and
+@kbd{C-u 9 0 0 I s s p} adds a permanent @code{Subject} substring score
+rule of 900 to the current article.
+
+This is all nice and well, but what if you want to give a command some
+additional information? Well, what most commands do is interpret the
+``raw'' prefix in some special way. @kbd{C-u 0 C-x C-s} means that one
+doesn't want a backup file to be created when saving the current buffer,
+for instance. But what if you want to save without making a backup
+file, and you want Emacs to flash lights and play a nice tune at the
+same time? You can't, and you're probably perfectly happy that way.
+
+@kindex M-i (Summary)
+@findex gnus-symbolic-argument
+I'm not, so I've added a second prefix---the @dfn{symbolic prefix}. The
+prefix key is @kbd{M-i} (@code{gnus-symbolic-argument}), and the next
+character typed in is the value. You can stack as many @kbd{M-i}
+prefixes as you want. @kbd{M-i a M-C-u} means ``feed the @kbd{M-C-u}
+command the symbolic prefix @code{a}''. @kbd{M-i a M-i b M-C-u} means
+``feed the @kbd{M-C-u} command the symbolic prefixes @code{a} and
+@code{b}''. You get the drift.
+
+Typing in symbolic prefixes to commands that don't accept them doesn't
+hurt, but it doesn't do any good either. Currently not many Gnus
+functions make use of the symbolic prefix.
+
+If you're interested in how Gnus implements this, @pxref{Extended
+Interactive}.
+
+
+@node Formatting Variables
+@section Formatting Variables
+@cindex formatting variables
+
+Throughout this manual you've probably noticed lots of variables called
+things like @code{gnus-group-line-format} and
+@code{gnus-summary-mode-line-format}. These control how Gnus is to
+output lines in the various buffers. There's quite a lot of them.
+Fortunately, they all use the same syntax, so there's not that much to
+be annoyed by.
+
+Here's an example format spec (from the group buffer): @samp{%M%S%5y:
+%(%g%)\n}. We see that it is indeed extremely ugly, and that there are
+lots of percentages everywhere.
+
+@menu
+* Formatting Basics:: A formatting variable is basically a format string.
+* Mode Line Formatting:: Some rules about mode line formatting variables.
+* Advanced Formatting:: Modifying output in various ways.
+* User-Defined Specs:: Having Gnus call your own functions.
+* Formatting Fonts:: Making the formatting look colorful and nice.
+@end menu
+
+Currently Gnus uses the following formatting variables:
+@code{gnus-group-line-format}, @code{gnus-summary-line-format},
+@code{gnus-server-line-format}, @code{gnus-topic-line-format},
+@code{gnus-group-mode-line-format},
+@code{gnus-summary-mode-line-format},
+@code{gnus-article-mode-line-format},
+@code{gnus-server-mode-line-format}, and
+@code{gnus-summary-pick-line-format}.
+
+All these format variables can also be arbitrary elisp forms. In that
+case, they will be @code{eval}ed to insert the required lines.
+
+@kindex M-x gnus-update-format
+@findex gnus-update-format
+Gnus includes a command to help you while creating your own format
+specs. @kbd{M-x gnus-update-format} will @code{eval} the current form,
+update the spec in question and pop you to a buffer where you can
+examine the resulting lisp code to be run to generate the line.
+
+
+
+@node Formatting Basics
+@subsection Formatting Basics
+
+Each @samp{%} element will be replaced by some string or other when the
+buffer in question is generated. @samp{%5y} means ``insert the @samp{y}
+spec, and pad with spaces to get a 5-character field''.
+
+As with normal C and Emacs Lisp formatting strings, the numerical
+modifier between the @samp{%} and the formatting type character will
+@dfn{pad} the output so that it is always at least that long.
+@samp{%5y} will make the field always (at least) five characters wide by
+padding with spaces to the left. If you say @samp{%-5y}, it will pad to
+the right instead.
+
+You may also wish to limit the length of the field to protect against
+particularly wide values. For that you can say @samp{%4,6y}, which
+means that the field will never be more than 6 characters wide and never
+less than 4 characters wide.
+
+
+@node Mode Line Formatting
+@subsection Mode Line Formatting
+
+Mode line formatting variables (e.g.,
+@code{gnus-summary-mode-line-format}) follow the same rules as other,
+buffer line oriented formatting variables (@pxref{Formatting Basics})
+with the following two differences:
+
+@enumerate
+
+@item
+There must be no newline (@samp{\n}) at the end.
+
+@item
+The special @samp{%%b} spec can be used to display the buffer name.
+Well, it's no spec at all, really---@samp{%%} is just a way to quote
+@samp{%} to allow it to pass through the formatting machinery unmangled,
+so that Emacs receives @samp{%b}, which is something the Emacs mode line
+display interprets to mean ``show the buffer name''. For a full list of
+mode line specs Emacs understands, see the documentation of the
+@code{mode-line-format} variable.
+
+@end enumerate
+
+
+@node Advanced Formatting
+@subsection Advanced Formatting
+
+It is frequently useful to post-process the fields in some way.
+Padding, limiting, cutting off parts and suppressing certain values can
+be achieved by using @dfn{tilde modifiers}. A typical tilde spec might
+look like @samp{%~(cut 3)~(ignore "0")y}.
+
+These are the valid modifiers:
+
+@table @code
+@item pad
+@itemx pad-left
+Pad the field to the left with spaces until it reaches the required
+length.
+
+@item pad-right
+Pad the field to the right with spaces until it reaches the required
+length.
+
+@item max
+@itemx max-left
+Cut off characters from the left until it reaches the specified length.
+
+@item max-right
+Cut off characters from the right until it reaches the specified
+length.
+
+@item cut
+@itemx cut-left
+Cut off the specified number of characters from the left.
+
+@item cut-right
+Cut off the specified number of characters from the right.
+
+@item ignore
+Return an empty string if the field is equal to the specified value.
+
+@item form
+Use the specified form as the field value when the @samp{@@} spec is
+used.
+@end table
+
+Let's take an example. The @samp{%o} spec in the summary mode lines
+will return a date in compact ISO8601 format---@samp{19960809T230410}.
+This is quite a mouthful, so we want to shave off the century number and
+the time, leaving us with a six-character date. That would be
+@samp{%~(cut-left 2)~(max-right 6)~(pad 6)o}. (Cutting is done before
+maxing, and we need the padding to ensure that the date is never less
+than 6 characters to make it look nice in columns.)
+
+Ignoring is done first; then cutting; then maxing; and then as the very
+last operation, padding.
+
+If you use lots of these advanced thingies, you'll find that Gnus gets
+quite slow. This can be helped enormously by running @kbd{M-x
+gnus-compile} when you are satisfied with the look of your lines.
+@xref{Compilation}.
+
+
+@node User-Defined Specs
+@subsection User-Defined Specs
+
+All the specs allow for inserting user defined specifiers---@samp{u}.
+The next character in the format string should be a letter. Gnus
+will call the function @code{gnus-user-format-function-}@samp{X}, where
+@samp{X} is the letter following @samp{%u}. The function will be passed
+a single parameter---what the parameter means depends on what buffer
+it's being called from. The function should return a string, which will
+be inserted into the buffer just like information from any other
+specifier. This function may also be called with dummy values, so it
+should protect against that.
+
+You can also use tilde modifiers (@pxref{Advanced Formatting} to achieve
+much the same without defining new functions. Here's an example:
+@samp{%~(form (count-lines (point-min) (point)))@@}. The form
+given here will be evaluated to yield the current line number, and then
+inserted.
+
+
+@node Formatting Fonts
+@subsection Formatting Fonts
+
+There are specs for highlighting, and these are shared by all the format
+variables. Text inside the @samp{%(} and @samp{%)} specifiers will get
+the special @code{mouse-face} property set, which means that it will be
+highlighted (with @code{gnus-mouse-face}) when you put the mouse pointer
+over it.
+
+Text inside the @samp{%@{} and @samp{%@}} specifiers will have their
+normal faces set using @code{gnus-face-0}, which is @code{bold} by
+default. If you say @samp{%1@{}, you'll get @code{gnus-face-1} instead,
+and so on. Create as many faces as you wish. The same goes for the
+@code{mouse-face} specs---you can say @samp{%3(hello%)} to have
+@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
+
+Here's an alternative recipe for the group buffer:
+
+@lisp
+;; Create three face types.
+(setq gnus-face-1 'bold)
+(setq gnus-face-3 'italic)
+
+;; We want the article count to be in
+;; a bold and green face. So we create
+;; a new face called `my-green-bold'.
+(copy-face 'bold 'my-green-bold)
+;; Set the color.
+(set-face-foreground 'my-green-bold "ForestGreen")
+(setq gnus-face-2 'my-green-bold)
+
+;; Set the new & fancy format.
+(setq gnus-group-line-format
+ "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n")
+@end lisp
+
+I'm sure you'll be able to use this scheme to create totally unreadable
+and extremely vulgar displays. Have fun!
+
+Note that the @samp{%(} specs (and friends) do not make any sense on the
+mode-line variables.
+
+
+@node Windows Configuration
+@section Windows Configuration
+@cindex windows configuration
+
+No, there's nothing here about X, so be quiet.
+
+@vindex gnus-use-full-window
+If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all
+other windows and occupy the entire Emacs screen by itself. It is
+@code{t} by default.
+
+@vindex gnus-buffer-configuration
+@code{gnus-buffer-configuration} describes how much space each Gnus
+buffer should be given. Here's an excerpt of this variable:
+
+@lisp
+((group (vertical 1.0 (group 1.0 point)
+ (if gnus-carpal (group-carpal 4))))
+ (article (vertical 1.0 (summary 0.25 point)
+ (article 1.0))))
+@end lisp
+
+This is an alist. The @dfn{key} is a symbol that names some action or
+other. For instance, when displaying the group buffer, the window
+configuration function will use @code{group} as the key. A full list of
+possible names is listed below.
+
+The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer
+should occupy. To take the @code{article} split as an example -
+
+@lisp
+(article (vertical 1.0 (summary 0.25 point)
+ (article 1.0)))
+@end lisp
+
+This @dfn{split} says that the summary buffer should occupy 25% of upper
+half of the screen, and that it is placed over the article buffer. As
+you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all
+reaching for that calculator there). However, the special number
+@code{1.0} is used to signal that this buffer should soak up all the
+rest of the space available after the rest of the buffers have taken
+whatever they need. There should be only one buffer with the @code{1.0}
+size spec per split.
+
+Point will be put in the buffer that has the optional third element
+@code{point}. In a @code{frame} split, the last subsplit having a leaf
+split where the tag @code{frame-focus} is a member (i.e. is the third or
+fourth element in the list, depending on whether the @code{point} tag is
+present) gets focus.
+
+Here's a more complicated example:
+
+@lisp
+(article (vertical 1.0 (group 4)
+ (summary 0.25 point)
+ (if gnus-carpal (summary-carpal 4))
+ (article 1.0)))
+@end lisp
+
+If the size spec is an integer instead of a floating point number,
+then that number will be used to say how many lines a buffer should
+occupy, not a percentage.
+
+If the @dfn{split} looks like something that can be @code{eval}ed (to be
+precise---if the @code{car} of the split is a function or a subr), this
+split will be @code{eval}ed. If the result is non-@code{nil}, it will
+be used as a split. This means that there will be three buffers if
+@code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal}
+is non-@code{nil}.
+
+Not complicated enough for you? Well, try this on for size:
+
+@lisp
+(article (horizontal 1.0
+ (vertical 0.5
+ (group 1.0)
+ (gnus-carpal 4))
+ (vertical 1.0
+ (summary 0.25 point)
+ (summary-carpal 4)
+ (article 1.0))))
+@end lisp
+
+Whoops. Two buffers with the mystery 100% tag. And what's that
+@code{horizontal} thingie?
+
+If the first element in one of the split is @code{horizontal}, Gnus will
+split the window horizontally, giving you two windows side-by-side.
+Inside each of these strips you may carry on all you like in the normal
+fashion. The number following @code{horizontal} says what percentage of
+the screen is to be given to this strip.
+
+For each split, there @emph{must} be one element that has the 100% tag.
+The splitting is never accurate, and this buffer will eat any leftover
+lines from the splits.
+
+To be slightly more formal, here's a definition of what a valid split
+may look like:
+
+@example
+split = frame | horizontal | vertical | buffer | form
+frame = "(frame " size *split ")"
+horizontal = "(horizontal " size *split ")"
+vertical = "(vertical " size *split ")"
+buffer = "(" buffer-name " " size *[ "point" ] *[ "frame-focus"] ")"
+size = number | frame-params
+buffer-name = group | article | summary ...
+@end example
+
+The limitations are that the @code{frame} split can only appear as the
+top-level split. @var{form} should be an Emacs Lisp form that should
+return a valid split. We see that each split is fully recursive, and
+may contain any number of @code{vertical} and @code{horizontal} splits.
+
+@vindex gnus-window-min-width
+@vindex gnus-window-min-height
+@cindex window height
+@cindex window width
+Finding the right sizes can be a bit complicated. No window may be less
+than @code{gnus-window-min-height} (default 1) characters high, and all
+windows must be at least @code{gnus-window-min-width} (default 1)
+characters wide. Gnus will try to enforce this before applying the
+splits. If you want to use the normal Emacs window width/height limit,
+you can just set these two variables to @code{nil}.
+
+If you're not familiar with Emacs terminology, @code{horizontal} and
+@code{vertical} splits may work the opposite way of what you'd expect.
+Windows inside a @code{horizontal} split are shown side-by-side, and
+windows within a @code{vertical} split are shown above each other.
+
+@findex gnus-configure-frame
+If you want to experiment with window placement, a good tip is to call
+@code{gnus-configure-frame} directly with a split. This is the function
+that does all the real work when splitting buffers. Below is a pretty
+nonsensical configuration with 5 windows; two for the group buffer and
+three for the article buffer. (I said it was nonsensical.) If you
+@code{eval} the statement below, you can get an idea of how that would
+look straight away, without going through the normal Gnus channels.
+Play with it until you're satisfied, and then use
+@code{gnus-add-configuration} to add your new creation to the buffer
+configuration list.
+
+@lisp
+(gnus-configure-frame
+ '(horizontal 1.0
+ (vertical 10
+ (group 1.0)
+ (article 0.3 point))
+ (vertical 1.0
+ (article 1.0)
+ (horizontal 4
+ (group 1.0)
+ (article 10)))))
+@end lisp
+
+You might want to have several frames as well. No prob---just use the
+@code{frame} split:
+
+@lisp
+(gnus-configure-frame
+ '(frame 1.0
+ (vertical 1.0
+ (summary 0.25 point frame-focus)
+ (article 1.0))
+ (vertical ((height . 5) (width . 15)
+ (user-position . t)
+ (left . -1) (top . 1))
+ (picon 1.0))))
+
+@end lisp
+
+This split will result in the familiar summary/article window
+configuration in the first (or ``main'') frame, while a small additional
+frame will be created where picons will be shown. As you can see,
+instead of the normal @code{1.0} top-level spec, each additional split
+should have a frame parameter alist as the size spec.
+@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp
+Reference Manual}. Under XEmacs, a frame property list will be
+accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)}
+is such a plist.
+
+Here's a list of all possible keys for
+@code{gnus-buffer-configuration}:
+
+@code{group}, @code{summary}, @code{article}, @code{server},
+@code{browse}, @code{message}, @code{pick}, @code{info},
+@code{summary-faq}, @code{edit-group}, @code{edit-server},
+@code{edit-score}, @code{post}, @code{reply}, @code{forward},
+@code{reply-yank}, @code{mail-bounce}, @code{draft}, @code{pipe},
+@code{bug}, @code{compose-bounce}, and @code{score-trace}.
+
+Note that the @code{message} key is used for both
+@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If
+it is desirable to distinguish between the two, something like this
+might be used:
+
+@lisp
+(message (horizontal 1.0
+ (vertical 1.0 (message 1.0 point))
+ (vertical 0.24
+ (if (buffer-live-p gnus-summary-buffer)
+ '(summary 0.5))
+ (group 1.0)))))
+@end lisp
+
+@findex gnus-add-configuration
+Since the @code{gnus-buffer-configuration} variable is so long and
+complicated, there's a function you can use to ease changing the config
+of a single setting: @code{gnus-add-configuration}. If, for instance,
+you want to change the @code{article} setting, you could say:
+
+@lisp
+(gnus-add-configuration
+ '(article (vertical 1.0
+ (group 4)
+ (summary .25 point)
+ (article 1.0))))
+@end lisp
+
+You'd typically stick these @code{gnus-add-configuration} calls in your
+@file{.gnus.el} file or in some startup hook---they should be run after
+Gnus has been loaded.
+
+@vindex gnus-always-force-window-configuration
+If all windows mentioned in the configuration are already visible, Gnus
+won't change the window configuration. If you always want to force the
+``right'' window configuration, you can set
+@code{gnus-always-force-window-configuration} to non-@code{nil}.
+
+
+@node Faces and Fonts
+@section Faces and Fonts
+@cindex faces
+@cindex fonts
+@cindex colors
+
+Fiddling with fonts and faces used to be very difficult, but these days
+it is very simple. You simply say @kbd{M-x customize-face}, pick out
+the face you want to alter, and alter it via the standard Customize
+interface.
+
+
+@node Compilation
+@section Compilation
+@cindex compilation
+@cindex byte-compilation
+
+@findex gnus-compile
+
+Remember all those line format specification variables?
+@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so
+on. Now, Gnus will of course heed whatever these variables are, but,
+unfortunately, changing them will mean a quite significant slow-down.
+(The default values of these variables have byte-compiled functions
+associated with them, while the user-generated versions do not, of
+course.)
+
+To help with this, you can run @kbd{M-x gnus-compile} after you've
+fiddled around with the variables and feel that you're (kind of)
+satisfied. This will result in the new specs being byte-compiled, and
+you'll get top speed again. Gnus will save these compiled specs in the
+@file{.newsrc.eld} file. (User-defined functions aren't compiled by
+this function, though---you should compile them yourself by sticking
+them into the @code{.gnus.el} file and byte-compiling that file.)
+
+
+@node Mode Lines
+@section Mode Lines
+@cindex mode lines
+
+@vindex gnus-updated-mode-lines
+@code{gnus-updated-mode-lines} says what buffers should keep their mode
+lines updated. It is a list of symbols. Supported symbols include
+@code{group}, @code{article}, @code{summary}, @code{server},
+@code{browse}, and @code{tree}. If the corresponding symbol is present,
+Gnus will keep that mode line updated with information that may be
+pertinent. If this variable is @code{nil}, screen refresh may be
+quicker.
+
+@cindex display-time
+
+@vindex gnus-mode-non-string-length
+By default, Gnus displays information on the current article in the mode
+lines of the summary and article buffers. The information Gnus wishes
+to display (e.g. the subject of the article) is often longer than the
+mode lines, and therefore have to be cut off at some point. The
+@code{gnus-mode-non-string-length} variable says how long the other
+elements on the line is (i.e., the non-info part). If you put
+additional elements on the mode line (e.g. a clock), you should modify
+this variable:
+
+@c Hook written by Francesco Potorti` <pot@cnuce.cnr.it>
+@lisp
+(add-hook 'display-time-hook
+ (lambda () (setq gnus-mode-non-string-length
+ (+ 21
+ (if line-number-mode 5 0)
+ (if column-number-mode 4 0)
+ (length display-time-string)))))
+@end lisp
+
+If this variable is @code{nil} (which is the default), the mode line
+strings won't be chopped off, and they won't be padded either. Note
+that the default is unlikely to be desirable, as even the percentage
+complete in the buffer may be crowded off the mode line; the user should
+configure this variable appropriately for her configuration.
+
+
+@node Highlighting and Menus
+@section Highlighting and Menus
+@cindex visual
+@cindex highlighting
+@cindex menus
+
+@vindex gnus-visual
+The @code{gnus-visual} variable controls most of the Gnus-prettifying
+aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy
+colors or fonts. This will also inhibit loading the @file{gnus-vis.el}
+file.
+
+This variable can be a list of visual properties that are enabled. The
+following elements are valid, and are all included by default:
+
+@table @code
+@item group-highlight
+Do highlights in the group buffer.
+@item summary-highlight
+Do highlights in the summary buffer.
+@item article-highlight
+Do highlights in the article buffer.
+@item highlight
+Turn on highlighting in all buffers.
+@item group-menu
+Create menus in the group buffer.
+@item summary-menu
+Create menus in the summary buffers.
+@item article-menu
+Create menus in the article buffer.
+@item browse-menu
+Create menus in the browse buffer.
+@item server-menu
+Create menus in the server buffer.
+@item score-menu
+Create menus in the score buffers.
+@item menu
+Create menus in all buffers.
+@end table
+
+So if you only want highlighting in the article buffer and menus in all
+buffers, you could say something like:
+
+@lisp
+(setq gnus-visual '(article-highlight menu))
+@end lisp
+
+If you want highlighting only and no menus whatsoever, you'd say:
+
+@lisp
+(setq gnus-visual '(highlight))
+@end lisp
+
+If @code{gnus-visual} is @code{t}, highlighting and menus will be used
+in all Gnus buffers.
+
+Other general variables that influence the look of all buffers include:
+
+@table @code
+@item gnus-mouse-face
+@vindex gnus-mouse-face
+This is the face (i.e., font) used for mouse highlighting in Gnus. No
+mouse highlights will be done if @code{gnus-visual} is @code{nil}.
+
+@end table
+
+There are hooks associated with the creation of all the different menus:
+
+@table @code
+
+@item gnus-article-menu-hook
+@vindex gnus-article-menu-hook
+Hook called after creating the article mode menu.
+
+@item gnus-group-menu-hook
+@vindex gnus-group-menu-hook
+Hook called after creating the group mode menu.
+
+@item gnus-summary-menu-hook
+@vindex gnus-summary-menu-hook
+Hook called after creating the summary mode menu.
+
+@item gnus-server-menu-hook
+@vindex gnus-server-menu-hook
+Hook called after creating the server mode menu.
+
+@item gnus-browse-menu-hook
+@vindex gnus-browse-menu-hook
+Hook called after creating the browse mode menu.
+
+@item gnus-score-menu-hook
+@vindex gnus-score-menu-hook
+Hook called after creating the score mode menu.
+
+@end table
+
+
+@node Buttons
+@section Buttons
+@cindex buttons
+@cindex mouse
+@cindex click
+
+Those new-fangled @dfn{mouse} contraptions is very popular with the
+young, hep kids who don't want to learn the proper way to do things
+these days. Why, I remember way back in the summer of '89, when I was
+using Emacs on a Tops 20 system. Three hundred users on one single
+machine, and every user was running Simula compilers. Bah!
+
+Right.
+
+@vindex gnus-carpal
+Well, you can make Gnus display bufferfuls of buttons you can click to
+do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple,
+really. Tell the chiropractor I sent you.
+
+
+@table @code
+
+@item gnus-carpal-mode-hook
+@vindex gnus-carpal-mode-hook
+Hook run in all carpal mode buffers.
+
+@item gnus-carpal-button-face
+@vindex gnus-carpal-button-face
+Face used on buttons.
+
+@item gnus-carpal-header-face
+@vindex gnus-carpal-header-face
+Face used on carpal buffer headers.
+
+@item gnus-carpal-group-buffer-buttons
+@vindex gnus-carpal-group-buffer-buttons
+Buttons in the group buffer.
+
+@item gnus-carpal-summary-buffer-buttons
+@vindex gnus-carpal-summary-buffer-buttons
+Buttons in the summary buffer.
+
+@item gnus-carpal-server-buffer-buttons
+@vindex gnus-carpal-server-buffer-buttons
+Buttons in the server buffer.
+
+@item gnus-carpal-browse-buffer-buttons
+@vindex gnus-carpal-browse-buffer-buttons
+Buttons in the browse buffer.
+@end table
+
+All the @code{buttons} variables are lists. The elements in these list
+are either cons cells where the @code{car} contains a text to be displayed and
+the @code{cdr} contains a function symbol, or a simple string.
+
+
+@node Daemons
+@section Daemons
+@cindex demons
+@cindex daemons
+
+Gnus, being larger than any program ever written (allegedly), does lots
+of strange stuff that you may wish to have done while you're not
+present. For instance, you may want it to check for new mail once in a
+while. Or you may want it to close down all connections to all servers
+when you leave Emacs idle. And stuff like that.
+
+Gnus will let you do stuff like that by defining various
+@dfn{handlers}. Each handler consists of three elements: A
+@var{function}, a @var{time}, and an @var{idle} parameter.
+
+Here's an example of a handler that closes connections when Emacs has
+been idle for thirty minutes:
+
+@lisp
+(gnus-demon-close-connections nil 30)
+@end lisp
+
+Here's a handler that scans for PGP headers every hour when Emacs is
+idle:
+
+@lisp
+(gnus-demon-scan-pgp 60 t)
+@end lisp
+
+This @var{time} parameter and than @var{idle} parameter work together
+in a strange, but wonderful fashion. Basically, if @var{idle} is
+@code{nil}, then the function will be called every @var{time} minutes.
+
+If @var{idle} is @code{t}, then the function will be called after
+@var{time} minutes only if Emacs is idle. So if Emacs is never idle,
+the function will never be called. But once Emacs goes idle, the
+function will be called every @var{time} minutes.
+
+If @var{idle} is a number and @var{time} is a number, the function will
+be called every @var{time} minutes only when Emacs has been idle for
+@var{idle} minutes.
+
+If @var{idle} is a number and @var{time} is @code{nil}, the function
+will be called once every time Emacs has been idle for @var{idle}
+minutes.
+
+And if @var{time} is a string, it should look like @samp{07:31}, and
+the function will then be called once every day somewhere near that
+time. Modified by the @var{idle} parameter, of course.
+
+@vindex gnus-demon-timestep
+(When I say ``minute'' here, I really mean @code{gnus-demon-timestep}
+seconds. This is 60 by default. If you change that variable,
+all the timings in the handlers will be affected.)
+
+@vindex gnus-use-demon
+To set the whole thing in motion, though, you have to set
+@code{gnus-use-demon} to @code{t}.
+
+So, if you want to add a handler, you could put something like this in
+your @file{.gnus} file:
+
+@findex gnus-demon-add-handler
+@lisp
+(gnus-demon-add-handler 'gnus-demon-close-connections 30 t)
+@end lisp
+
+@findex gnus-demon-add-nocem
+@findex gnus-demon-add-scanmail
+@findex gnus-demon-add-rescan
+@findex gnus-demon-add-scan-timestamps
+@findex gnus-demon-add-disconnection
+Some ready-made functions to do this have been created:
+@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection},
+@code{gnus-demon-add-nntp-close-connection},
+@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and
+@code{gnus-demon-add-scanmail}. Just put those functions in your
+@file{.gnus} if you want those abilities.
+
+@findex gnus-demon-init
+@findex gnus-demon-cancel
+@vindex gnus-demon-handlers
+If you add handlers to @code{gnus-demon-handlers} directly, you should
+run @code{gnus-demon-init} to make the changes take hold. To cancel all
+daemons, you can use the @code{gnus-demon-cancel} function.
+
+Note that adding daemons can be pretty naughty if you over do it. Adding
+functions that scan all news and mail from all servers every two seconds
+is a sure-fire way of getting booted off any respectable system. So
+behave.
+
+
+@node NoCeM
+@section NoCeM
+@cindex nocem
+@cindex spam
+
+@dfn{Spamming} is posting the same article lots and lots of times.
+Spamming is bad. Spamming is evil.
+
+Spamming is usually canceled within a day or so by various anti-spamming
+agencies. These agencies usually also send out @dfn{NoCeM} messages.
+NoCeM is pronounced ``no see-'em'', and means what the name
+implies---these are messages that make the offending articles, like, go
+away.
+
+What use are these NoCeM messages if the articles are canceled anyway?
+Some sites do not honor cancel messages and some sites just honor cancels
+from a select few people. Then you may wish to make use of the NoCeM
+messages, which are distributed in the @samp{alt.nocem.misc} newsgroup.
+
+Gnus can read and parse the messages in this group automatically, and
+this will make spam disappear.
+
+There are some variables to customize, of course:
+
+@table @code
+@item gnus-use-nocem
+@vindex gnus-use-nocem
+Set this variable to @code{t} to set the ball rolling. It is @code{nil}
+by default.
+
+@item gnus-nocem-groups
+@vindex gnus-nocem-groups
+Gnus will look for NoCeM messages in the groups in this list. The
+default is @code{("news.lists.filters" "news.admin.net-abuse.bulletins"
+"alt.nocem.misc" "news.admin.net-abuse.announce")}.
+
+@item gnus-nocem-issuers
+@vindex gnus-nocem-issuers
+There are many people issuing NoCeM messages. This list says what
+people you want to listen to. The default is @code{("Automoose-1"
+"rbraver@@ohww.norman.ok.us" "clewis@@ferret.ocunix.on.ca"
+"jem@@xpat.com" "snowhare@@xmission.com" "red@@redpoll.mrfs.oh.us
+(Richard E. Depew)")}; fine, upstanding citizens all of them.
+
+Known despammers that you can put in this list include:
+
+@table @samp
+@item clewis@@ferret.ocunix.on.ca;
+@cindex Chris Lewis
+Chris Lewis---Major Canadian despammer who has probably canceled more
+usenet abuse than anybody else.
+
+@item Automoose-1
+@cindex CancelMoose[tm]
+The CancelMoose[tm] on autopilot. The CancelMoose[tm] is reputed to be
+Norwegian, and was the person(s) who invented NoCeM.
+
+@item jem@@xpat.com;
+@cindex Jem
+John Milburn---despammer located in Korea who is getting very busy these
+days.
+
+@item red@@redpoll.mrfs.oh.us (Richard E. Depew)
+Richard E. Depew---lone American despammer. He mostly cancels binary
+postings to non-binary groups and removes spews (regurgitated articles).
+@end table
+
+You do not have to heed NoCeM messages from all these people---just the
+ones you want to listen to. You also don't have to accept all NoCeM
+messages from the people you like. Each NoCeM message has a @dfn{type}
+header that gives the message a (more or less, usually less) rigorous
+definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf},
+@samp{binary}, and @samp{troll}. To specify this, you have to use
+@var{(issuer conditions ...)} elements in the list. Each condition is
+either a string (which is a regexp that matches types you want to use)
+or a list on the form @code{(not STRING)}, where @var{string} is a
+regexp that matches types you don't want to use.
+
+For instance, if you want all NoCeM messages from Chris Lewis except his
+@samp{troll} messages, you'd say:
+
+@lisp
+("clewis@@ferret.ocunix.on.ca" ".*" (not "troll"))
+@end lisp
+
+On the other hand, if you just want nothing but his @samp{spam} and
+@samp{spew} messages, you'd say:
+
+@lisp
+("clewis@@ferret.ocunix.on.ca" (not ".*") "spew" "spam")
+@end lisp
+
+The specs are applied left-to-right.
+
+
+@item gnus-nocem-verifyer
+@vindex gnus-nocem-verifyer
+@findex mc-verify
+This should be a function for verifying that the NoCeM issuer is who she
+says she is. The default is @code{mc-verify}, which is a Mailcrypt
+function. If this is too slow and you don't care for verification
+(which may be dangerous), you can set this variable to @code{nil}.
+
+If you want signed NoCeM messages to be verified and unsigned messages
+not to be verified (but used anyway), you could do something like:
+
+@lisp
+(setq gnus-nocem-verifyer 'my-gnus-mc-verify)
+
+(defun my-gnus-mc-verify ()
+ (not (eq 'forged
+ (ignore-errors
+ (if (mc-verify)
+ t
+ 'forged)))))
+@end lisp
+
+This might be dangerous, though.
+
+@item gnus-nocem-directory
+@vindex gnus-nocem-directory
+This is where Gnus will store its NoCeM cache files. The default is
+@file{~/News/NoCeM/}.
+
+@item gnus-nocem-expiry-wait
+@vindex gnus-nocem-expiry-wait
+The number of days before removing old NoCeM entries from the cache.
+The default is 15. If you make it shorter Gnus will be faster, but you
+might then see old spam.
+
+@end table
+
+Using NoCeM could potentially be a memory hog. If you have many living
+(i. e., subscribed or unsubscribed groups), your Emacs process will grow
+big. If this is a problem, you should kill off all (or most) of your
+unsubscribed groups (@pxref{Subscription Commands}).
+
+
+@node Undo
+@section Undo
+@cindex undo
+
+It is very useful to be able to undo actions one has done. In normal
+Emacs buffers, it's easy enough---you just push the @code{undo} button.
+In Gnus buffers, however, it isn't that simple.
+
+The things Gnus displays in its buffer is of no value whatsoever to
+Gnus---it's all just data designed to look nice to the user.
+Killing a group in the group buffer with @kbd{C-k} makes the line
+disappear, but that's just a side-effect of the real action---the
+removal of the group in question from the internal Gnus structures.
+Undoing something like that can't be done by the normal Emacs
+@code{undo} function.
+
+Gnus tries to remedy this somewhat by keeping track of what the user
+does and coming up with actions that would reverse the actions the user
+takes. When the user then presses the @code{undo} key, Gnus will run
+the code to reverse the previous action, or the previous actions.
+However, not all actions are easily reversible, so Gnus currently offers
+a few key functions to be undoable. These include killing groups,
+yanking groups, and changing the list of read articles of groups.
+That's it, really. More functions may be added in the future, but each
+added function means an increase in data to be stored, so Gnus will
+never be totally undoable.
+
+@findex gnus-undo-mode
+@vindex gnus-use-undo
+@findex gnus-undo
+The undoability is provided by the @code{gnus-undo-mode} minor mode. It
+is used if @code{gnus-use-undo} is non-@code{nil}, which is the
+default. The @kbd{M-C-_} key performs the @code{gnus-undo} command
+command, which should feel kinda like the normal Emacs @code{undo}
+command.
+
+
+@node Moderation
+@section Moderation
+@cindex moderation
+
+If you are a moderator, you can use the @file{gnus-mdrtn.el} package.
+It is not included in the standard Gnus package. Write a mail to
+@samp{larsi@@gnus.org} and state what group you moderate, and you'll
+get a copy.
+
+The moderation package is implemented as a minor mode for summary
+buffers. Put
+
+@lisp
+(add-hook 'gnus-summary-mode-hook 'gnus-moderate)
+@end lisp
+
+in your @file{.gnus.el} file.
+
+If you are the moderator of @samp{rec.zoofle}, this is how it's
+supposed to work:
+
+@enumerate
+@item
+You split your incoming mail by matching on
+@samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted
+articles in some mail group---for instance, @samp{nnml:rec.zoofle}.
+
+@item
+You enter that group once in a while and post articles using the @kbd{e}
+(edit-and-post) or @kbd{s} (just send unedited) commands.
+
+@item
+If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some
+articles that weren't approved by you, you can cancel them with the
+@kbd{c} command.
+@end enumerate
+
+To use moderation mode in these two groups, say:
+
+@lisp
+(setq gnus-moderated-list
+ "^nnml:rec.zoofle$\\|^rec.zoofle$")
+@end lisp
+
+
+@node XEmacs Enhancements
+@section XEmacs Enhancements
+@cindex XEmacs
+
+XEmacs is able to display pictures and stuff, so Gnus has taken
+advantage of that.
+
+@menu
+* Picons:: How to display pictures of what your reading.
+* Smileys:: Show all those happy faces the way they were meant to be shown.
+* Toolbar:: Click'n'drool.
+* XVarious:: Other XEmacsy Gnusey variables.
+@end menu
+
+
+@node Picons
+@subsection Picons
+
+So... You want to slow down your news reader even more! This is a
+good way to do so. Its also a great way to impress people staring
+over your shoulder as you read news.
+
+@menu
+* Picon Basics:: What are picons and How do I get them.
+* Picon Requirements:: Don't go further if you aren't using XEmacs.
+* Easy Picons:: Displaying Picons---the easy way.
+* Hard Picons:: The way you should do it. You'll learn something.
+* Picon Useless Configuration:: Other variables you can trash/tweak/munge/play with.
+@end menu
+
+
+@node Picon Basics
+@subsubsection Picon Basics
+
+What are Picons? To quote directly from the Picons Web site:
+
+@quotation
+@dfn{Picons} is short for ``personal icons''. They're small,
+constrained images used to represent users and domains on the net,
+organized into databases so that the appropriate image for a given
+e-mail address can be found. Besides users and domains, there are picon
+databases for Usenet newsgroups and weather forecasts. The picons are
+in either monochrome @code{XBM} format or color @code{XPM} and
+@code{GIF} formats.
+@end quotation
+
+@vindex gnus-picons-piconsearch-url
+If you have a permanent connection to the Internet you can use Steve
+Kinzler's Picons Search engine by setting
+@code{gnus-picons-piconsearch-url} to the string @*
+@file{http://www.cs.indiana.edu/picons/search.html}.
+
+@vindex gnus-picons-database
+Otherwise you need a local copy of his database. For instructions on
+obtaining and installing the picons databases, point your Web browser at @*
+@file{http://www.cs.indiana.edu/picons/ftp/index.html}. Gnus expects
+picons to be installed into a location pointed to by
+@code{gnus-picons-database}.
+
+
+@node Picon Requirements
+@subsubsection Picon Requirements
+
+To have Gnus display Picons for you, you must be running XEmacs
+19.13 or greater since all other versions of Emacs aren't yet able to
+display images.
+
+Additionally, you must have @code{x} support compiled into XEmacs. To
+display color picons which are much nicer than the black & white one,
+you also need one of @code{xpm} or @code{gif} compiled into XEmacs.
+
+@vindex gnus-picons-convert-x-face
+If you want to display faces from @code{X-Face} headers, you should have
+the @code{xface} support compiled into XEmacs. Otherwise you must have
+the @code{netpbm} utilities installed, or munge the
+@code{gnus-picons-convert-x-face} variable to use something else.
+
+
+@node Easy Picons
+@subsubsection Easy Picons
+
+To enable displaying picons, simply put the following line in your
+@file{~/.gnus} file and start Gnus.
+
+@lisp
+(setq gnus-use-picons t)
+(add-hook 'gnus-article-display-hook
+ 'gnus-article-display-picons t)
+(add-hook 'gnus-article-display-hook
+ 'gnus-picons-article-display-x-face)
+@end lisp
+
+and make sure @code{gnus-picons-database} points to the directory
+containing the Picons databases.
+
+Alternatively if you want to use the web piconsearch engine add this:
+
+@lisp
+(setq gnus-picons-piconsearch-url
+ "http://www.cs.indiana.edu:800/piconsearch")
+@end lisp
+
+
+@node Hard Picons
+@subsubsection Hard Picons
+
+Gnus can display picons for you as you enter and leave groups and
+articles. It knows how to interact with three sections of the picons
+database. Namely, it can display the picons newsgroup pictures,
+author's face picture(s), and the authors domain. To enable this
+feature, you need to select where to get the picons from, and where to
+display them.
+
+@table @code
+
+@item gnus-picons-database
+@vindex gnus-picons-database
+The location of the picons database. Should point to a directory
+containing the @file{news}, @file{domains}, @file{users} (and so on)
+subdirectories. This is only useful if
+@code{gnus-picons-piconsearch-url} is @code{nil}. Defaults to
+@file{/usr/local/faces/}.
+
+@item gnus-picons-piconsearch-url
+@vindex gnus-picons-piconsearch-url
+The URL for the web picons search engine. The only currently known
+engine is @file{http://www.cs.indiana.edu:800/piconsearch}. To
+workaround network delays, icons will be fetched in the background. If
+this is @code{nil} 'the default), then picons are fetched from local
+database indicated by @code{gnus-picons-database}.
+
+@item gnus-picons-display-where
+@vindex gnus-picons-display-where
+Where the picon images should be displayed. It is @code{picons} by
+default (which by default maps to the buffer @samp{*Picons*}). Other
+valid places could be @code{article}, @code{summary}, or
+@samp{*scratch*} for all I care. Just make sure that you've made the
+buffer visible using the standard Gnus window configuration
+routines---@pxref{Windows Configuration}.
+
+@item gnus-picons-group-excluded-groups
+@vindex gnus-picons-group-excluded-groups
+Groups that are matched by this regexp won't have their group icons
+displayed.
+
+@end table
+
+Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your
+window configuration for you to include the @code{picons} buffer.
+
+Now that you've made those decision, you need to add the following
+functions to the appropriate hooks so these pictures will get displayed
+at the right time.
+
+@vindex gnus-article-display-hook
+@vindex gnus-picons-display-where
+@table @code
+@item gnus-article-display-picons
+@findex gnus-article-display-picons
+Looks up and displays the picons for the author and the author's domain
+in the @code{gnus-picons-display-where} buffer. Should be added to the
+@code{gnus-article-display-hook}.
+
+@item gnus-picons-article-display-x-face
+@findex gnus-article-display-picons
+Decodes and displays the X-Face header if present. This function
+should be added to @code{gnus-article-display-hook}.
+
+@end table
+
+Note: You must append them to the hook, so make sure to specify 't'
+for the append flag of @code{add-hook}:
+
+@lisp
+(add-hook 'gnus-article-display-hook 'gnus-article-display-picons t)
+@end lisp
+
+
+@node Picon Useless Configuration
+@subsubsection Picon Useless Configuration
+
+The following variables offer further control over how things are
+done, where things are located, and other useless stuff you really
+don't need to worry about.
+
+@table @code
+
+@item gnus-picons-news-directories
+@vindex gnus-picons-news-directories
+List of subdirectories to search in @code{gnus-picons-database} for
+newsgroups faces. @code{("news")} is the default.
+
+@item gnus-picons-user-directories
+@vindex gnus-picons-user-directories
+List of subdirectories to search in @code{gnus-picons-database} for user
+faces. @code{("local" "users" "usenix" "misc")} is the default.
+
+@item gnus-picons-domain-directories
+@vindex gnus-picons-domain-directories
+List of subdirectories to search in @code{gnus-picons-database} for
+domain name faces. Defaults to @code{("domains")}. Some people may
+want to add @samp{"unknown"} to this list.
+
+@item gnus-picons-convert-x-face
+@vindex gnus-picons-convert-x-face
+If you don't have @code{xface} support builtin XEmacs, this is the
+command to use to convert the @code{X-Face} header to an X bitmap
+(@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48,
+Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s"
+gnus-picons-x-face-file-name)}
+
+@item gnus-picons-x-face-file-name
+@vindex gnus-picons-x-face-file-name
+Names a temporary file to store the @code{X-Face} bitmap in. Defaults
+to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}.
+
+@item gnus-picons-has-modeline-p
+@vindex gnus-picons-has-modeline-p
+If you have set @code{gnus-picons-display-where} to @code{picons}, your
+XEmacs frame will become really cluttered. To alleviate this a bit you
+can set @code{gnus-picons-has-modeline-p} to @code{nil}; this will
+remove the mode line from the Picons buffer. This is only useful if
+@code{gnus-picons-display-where} is @code{picons}.
+
+@item gnus-picons-refresh-before-display
+@vindex gnus-picons-refresh-before-display
+If non-nil, display the article buffer before computing the picons.
+Defaults to @code{nil}.
+
+@item gnus-picons-display-as-address
+@vindex gnus-picons-display-as-address
+If @code{t} display textual email addresses along with pictures.
+Defaults to @code{t}.
+
+@item gnus-picons-file-suffixes
+@vindex gnus-picons-file-suffixes
+Ordered list of suffixes on picon file names to try. Defaults to
+@code{("xpm" "gif" "xbm")} minus those not builtin your XEmacs.
+
+@item gnus-picons-display-article-move-p
+@vindex gnus-picons-display-article-move-p
+Whether to move point to first empty line when displaying picons. This
+has only an effect if `gnus-picons-display-where' has value `article'.
+
+@item gnus-picons-clear-cache-on-shutdown
+@vindex gnus-picons-clear-cache-on-shutdown
+Whether to clear the picons cache when exiting gnus. Gnus caches every
+picons it finds while it is running. This saves some time in the search
+process but eats some memory. If this variable is set to @code{nil},
+Gnus will never clear the cache itself; you will have to manually call
+@code{gnus-picons-clear-cache} to clear it. Otherwise the cache will be
+cleared every time you exit Gnus. Defaults to @code{t}.
+
+@end table
+
+@node Smileys
+@subsection Smileys
+@cindex smileys
+
+@dfn{Smiley} is a package separate from Gnus, but since Gnus is
+currently the only package that uses Smiley, it is documented here.
+
+In short---to use Smiley in Gnus, put the following in your
+@file{.gnus.el} file:
+
+@lisp
+(add-hook 'gnus-article-display-hook 'gnus-smiley-display t)
+@end lisp
+
+Smiley maps text smiley faces---@samp{:-)}, @samp{:-=}, @samp{:-(} and
+the like---to pictures and displays those instead of the text smiley
+faces. The conversion is controlled by a list of regexps that matches
+text and maps that to file names.
+
+@vindex smiley-nosey-regexp-alist
+@vindex smiley-deformed-regexp-alist
+Smiley supplies two example conversion alists by default:
+@code{smiley-deformed-regexp-alist} (which matches @samp{:)}, @samp{:(}
+and so on), and @code{smiley-nosey-regexp-alist} (which matches
+@samp{:-)}, @samp{:-(} and so on).
+
+The alist used is specified by the @code{smiley-regexp-alist} variable,
+which defaults to the value of @code{smiley-deformed-regexp-alist}.
+
+The first item in each element is the regexp to be matched; the second
+element is the regexp match group that is to be replaced by the picture;
+and the third element is the name of the file to be displayed.
+
+The following variables customize where Smiley will look for these
+files, as well as the color to be used and stuff:
+
+@table @code
+
+@item smiley-data-directory
+@vindex smiley-data-directory
+Where Smiley will look for smiley faces files.
+
+@item smiley-flesh-color
+@vindex smiley-flesh-color
+Skin color. The default is @samp{yellow}, which is really racist.
+
+@item smiley-features-color
+@vindex smiley-features-color
+Color of the features of the face. The default is @samp{black}.
+
+@item smiley-tongue-color
+@vindex smiley-tongue-color
+Color of the tongue. The default is @samp{red}.
+
+@item smiley-circle-color
+@vindex smiley-circle-color
+Color of the circle around the face. The default is @samp{black}.
+
+@item smiley-mouse-face
+@vindex smiley-mouse-face
+Face used for mouse highlighting over the smiley face.
+
+@end table
+
+
+@node Toolbar
+@subsection Toolbar
+
+@table @code
+
+@item gnus-use-toolbar
+@vindex gnus-use-toolbar
+If @code{nil}, don't display toolbars. If non-@code{nil}, it should be
+one of @code{default-toolbar}, @code{top-toolbar}, @code{bottom-toolbar},
+@code{right-toolbar}, or @code{left-toolbar}.
+
+@item gnus-group-toolbar
+@vindex gnus-group-toolbar
+The toolbar in the group buffer.
+
+@item gnus-summary-toolbar
+@vindex gnus-summary-toolbar
+The toolbar in the summary buffer.
+
+@item gnus-summary-mail-toolbar
+@vindex gnus-summary-mail-toolbar
+The toolbar in the summary buffer of mail groups.
+
+@end table
+
+
+@node XVarious
+@subsection Various XEmacs Variables
+
+@table @code
+@item gnus-xmas-glyph-directory
+@vindex gnus-xmas-glyph-directory
+This is where Gnus will look for pictures. Gnus will normally
+auto-detect this directory, but you may set it manually if you have an
+unusual directory structure.
+
+@item gnus-xmas-logo-color-alist
+@vindex gnus-xmas-logo-color-alist
+This is an alist where the key is a type symbol and the values are the
+foreground and background color of the splash page glyph.
+
+@item gnus-xmas-logo-color-style
+@vindex gnus-xmas-logo-color-style
+This is the key used to look up the color in the alist described above.
+Valid values include @code{flame}, @code{pine}, @code{moss},
+@code{irish}, @code{sky}, @code{tin}, @code{velvet}, @code{grape},
+@code{labia}, @code{berry}, @code{neutral}, and @code{september}.
+
+@item gnus-xmas-modeline-glyph
+@vindex gnus-xmas-modeline-glyph
+A glyph displayed in all Gnus mode lines. It is a tiny gnu head by
+default.
+
+@end table
+
+
+
+
+@node Fuzzy Matching
+@section Fuzzy Matching
+@cindex fuzzy matching
+
+Gnus provides @dfn{fuzzy matching} of @code{Subject} lines when doing
+things like scoring, thread gathering and thread comparison.
+
+As opposed to regular expression matching, fuzzy matching is very fuzzy.
+It's so fuzzy that there's not even a definition of what @dfn{fuzziness}
+means, and the implementation has changed over time.
+
+Basically, it tries to remove all noise from lines before comparing.
+@samp{Re: }, parenthetical remarks, white space, and so on, are filtered
+out of the strings before comparing the results. This often leads to
+adequate results---even when faced with strings generated by text
+manglers masquerading as newsreaders.
+
+
+@node Thwarting Email Spam
+@section Thwarting Email Spam
+@cindex email spam
+@cindex spam
+@cindex UCE
+@cindex unsolicited commercial email
+
+In these last days of the Usenet, commercial vultures are hanging about
+and grepping through news like crazy to find email addresses they can
+foist off their scams and products to. As a reaction to this, many
+people have started putting nonsense addresses into their @code{From}
+lines. I think this is counterproductive---it makes it difficult for
+people to send you legitimate mail in response to things you write, as
+well as making it difficult to see who wrote what. This rewriting may
+perhaps be a bigger menace than the unsolicited commercial email itself
+in the end.
+
+The biggest problem I have with email spam is that it comes in under
+false pretenses. I press @kbd{g} and Gnus merrily informs me that I
+have 10 new emails. I say ``Golly gee! Happy is me!'' and select the
+mail group, only to find two pyramid schemes, seven advertisements
+(``New! Miracle tonic for growing full, lustrous hair on your toes!'')
+and one mail asking me to repent and find some god.
+
+This is annoying.
+
+The way to deal with this is having Gnus split out all spam into a
+@samp{spam} mail group (@pxref{Splitting Mail}).
+
+First, pick one (1) valid mail address that you can be reached at, and
+put it in your @code{From} header of all your news articles. (I've
+chosen @samp{larsi@@trym.ifi.uio.no}, but for many addresses on the form
+@samp{larsi+usenet@@ifi.uio.no} will be a better choice. Ask your
+sysadm whether your sendmail installation accepts keywords in the local
+part of the mail address.)
+
+@lisp
+(setq message-default-news-headers
+ "From: Lars Magne Ingebrigtsen <larsi@@trym.ifi.uio.no>\n")
+@end lisp
+
+Then put the following split rule in @code{nnmail-split-fancy}
+(@pxref{Fancy Mail Splitting}):
+
+@lisp
+(
+ ...
+ (to "larsi@@trym.ifi.uio.no"
+ (| ("subject" "re:.*" "misc")
+ ("references" ".*@@.*" "misc")
+ "spam"))
+ ...
+)
+@end lisp
+
+This says that all mail to this address is suspect, but if it has a
+@code{Subject} that starts with a @samp{Re:} or has a @code{References}
+header, it's probably ok. All the rest goes to the @samp{spam} group.
+(This idea probably comes from Tim Pierce.)
+
+In addition, many mail spammers talk directly to your @code{smtp} server
+and do not include your email address explicitly in the @code{To}
+header. Why they do this is unknown---perhaps it's to thwart this
+thwarting scheme? In any case, this is trivial to deal with---you just
+put anything not addressed to you in the @samp{spam} group by ending
+your fancy split rule in this way:
+
+@lisp
+(
+ ...
+ (to "larsi" "misc")
+ "spam")
+@end lisp
+
+In my experience, this will sort virtually everything into the right
+group. You still have to check the @samp{spam} group from time to time to
+check for legitimate mail, though. If you feel like being a good net
+citizen, you can even send off complaints to the proper authorities on
+each unsolicited commercial email---at your leisure.
+
+If you are also a lazy net citizen, you will probably prefer complaining
+automatically with the @file{gnus-junk.el} package, available FOR FREE
+at @* @file{<URL:http://stud2.tuwien.ac.at/~e9426626/gnus-junk.html>}.
+Since most e-mail spam is sent automatically, this may reconcile the
+cosmic balance somewhat.
+
+This works for me. It allows people an easy way to contact me (they can
+just press @kbd{r} in the usual way), and I'm not bothered at all with
+spam. It's a win-win situation. Forging @code{From} headers to point
+to non-existent domains is yucky, in my opinion.
+
+
+@node Various Various
+@section Various Various
+@cindex mode lines
+@cindex highlights
+
+@table @code
+
+@item gnus-home-directory
+All Gnus path variables will be initialized from this variable, which
+defaults to @file{~/}.
+
+@item gnus-directory
+@vindex gnus-directory
+Most Gnus storage path variables will be initialized from this variable,
+which defaults to the @samp{SAVEDIR} environment variable, or
+@file{~/News/} if that variable isn't set.
+
+Note that Gnus is mostly loaded when the @file{.gnus.el} file is read.
+This means that other directory variables that are initialized from this
+variable won't be set properly if you set this variable in
+@file{.gnus.el}. Set this variable in @file{.emacs} instead.
+
+@item gnus-default-directory
+@vindex gnus-default-directory
+Not related to the above variable at all---this variable says what the
+default directory of all Gnus buffers should be. If you issue commands
+like @kbd{C-x C-f}, the prompt you'll get starts in the current buffer's
+default directory. If this variable is @code{nil} (which is the
+default), the default directory will be the default directory of the
+buffer you were in when you started Gnus.
+
+@item gnus-verbose
+@vindex gnus-verbose
+This variable is an integer between zero and ten. The higher the value,
+the more messages will be displayed. If this variable is zero, Gnus
+will never flash any messages, if it is seven (which is the default),
+most important messages will be shown, and if it is ten, Gnus won't ever
+shut up, but will flash so many messages it will make your head swim.
+
+@item gnus-verbose-backends
+@vindex gnus-verbose-backends
+This variable works the same way as @code{gnus-verbose}, but it applies
+to the Gnus backends instead of Gnus proper.
+
+@item nnheader-max-head-length
+@vindex nnheader-max-head-length
+When the backends read straight heads of articles, they all try to read
+as little as possible. This variable (default 4096) specifies
+the absolute max length the backends will try to read before giving up
+on finding a separator line between the head and the body. If this
+variable is @code{nil}, there is no upper read bound. If it is
+@code{t}, the backends won't try to read the articles piece by piece,
+but read the entire articles. This makes sense with some versions of
+@code{ange-ftp} or @code{efs}.
+
+@item nnheader-head-chop-length
+@vindex nnheader-head-chop-length
+This variable (default 2048) says how big a piece of each article to
+read when doing the operation described above.
+
+@item nnheader-file-name-translation-alist
+@vindex nnheader-file-name-translation-alist
+@cindex file names
+@cindex invalid characters in file names
+@cindex characters in file names
+This is an alist that says how to translate characters in file names.
+For instance, if @samp{:} is invalid as a file character in file names
+on your system (you OS/2 user you), you could say something like:
+
+@lisp
+(setq nnheader-file-name-translation-alist
+ '((?: . ?_)))
+@end lisp
+
+In fact, this is the default value for this variable on OS/2 and MS
+Windows (phooey) systems.
+
+@item gnus-hidden-properties
+@vindex gnus-hidden-properties
+This is a list of properties to use to hide ``invisible'' text. It is
+@code{(invisible t intangible t)} by default on most systems, which
+makes invisible text invisible and intangible.
+
+@item gnus-parse-headers-hook
+@vindex gnus-parse-headers-hook
+A hook called before parsing headers. It can be used, for instance, to
+gather statistics on the headers fetched, or perhaps you'd like to prune
+some headers. I don't see why you'd want that, though.
+
+@item gnus-shell-command-separator
+@vindex gnus-shell-command-separator
+String used to separate two shell commands. The default is @samp{;}.
+
+
+@end table
+
+
+@node The End
+@chapter The End
+
+Well, that's the manual---you can get on with your life now. Keep in
+touch. Say hello to your cats from me.
+
+My @strong{ghod}---I just can't stand goodbyes. Sniffle.
+
+Ol' Charles Reznikoff said it pretty well, so I leave the floor to him:
+
+@quotation
+@strong{Te Deum}
+
+@sp 1
+Not because of victories @*
+I sing,@*
+having none,@*
+but for the common sunshine,@*
+the breeze,@*
+the largess of the spring.
+
+@sp 1
+Not for victory@*
+but for the day's work done@*
+as well as I was able;@*
+not for a seat upon the dais@*
+but at the common table.@*
+@end quotation
+
+
+@node Appendices
+@chapter Appendices
+
+@menu
+* History:: How Gnus got where it is today.
+* Terminology:: We use really difficult, like, words here.
+* Customization:: Tailoring Gnus to your needs.
+* Troubleshooting:: What you might try if things do not work.
+* A Programmers Guide to Gnus:: Rilly, rilly technical stuff.
+* Emacs for Heathens:: A short introduction to Emacsian terms.
+* Frequently Asked Questions:: A question-and-answer session.
+@end menu
+
+
+@node History
+@section History
+
+@cindex history
+@sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in
+'94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus.
+
+If you want to investigate the person responsible for this outrage, you
+can point your (feh!) web browser to
+@file{http://www.stud.ifi.uio.no/~larsi/}. This is also the primary
+distribution point for the new and spiffy versions of Gnus, and is known
+as The Site That Destroys Newsrcs And Drives People Mad.
+
+During the first extended alpha period of development, the new Gnus was
+called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for
+@dfn{ding is not Gnus}, which is a total and utter lie, but who cares?
+(Besides, the ``Gnus'' in this abbreviation should probably be
+pronounced ``news'' as @sc{Umeda} intended, which makes it a more
+appropriate name, don't you think?)
+
+In any case, after spending all that energy on coming up with a new and
+spunky name, we decided that the name was @emph{too} spunky, so we
+renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs.
+``@sc{gnus}''. New vs. old.
+
+The first ``proper'' release of Gnus 5 was done in November 1995 when it
+was included in the Emacs 19.30 distribution (132 (ding) Gnus releases
+plus 15 Gnus 5.0 releases).
+
+In May 1996 the next Gnus generation (aka. ``September Gnus'' (after 99
+releases)) was released under the name ``Gnus 5.2'' (40 releases).
+
+On July 28th 1996 work on Red Gnus was begun, and it was released on
+January 25th 1997 (after 84 releases) as ``Gnus 5.4'' (67 releases).
+
+On September 13th 1997, Quassia Gnus was started and lasted 37
+releases. If was released as ``Gnus 5.6 on March 8th 1998.
+
+If you happen upon a version of Gnus that has a prefixed name --
+``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'' --
+don't panic. Don't let it know that you're frightened. Back away.
+Slowly. Whatever you do, don't run. Walk away, calmly, until you're
+out of its reach. Find a proper released version of Gnus and snuggle up
+to that instead.
+
+@menu
+* Why?:: What's the point of Gnus?
+* Compatibility:: Just how compatible is Gnus with @sc{gnus}?
+* Conformity:: Gnus tries to conform to all standards.
+* Emacsen:: Gnus can be run on a few modern Emacsen.
+* Contributors:: Oodles of people.
+* New Features:: Pointers to some of the new stuff in Gnus.
+* Newest Features:: Features so new that they haven't been written yet.
+@end menu
+
+
+@node Why?
+@subsection Why?
+
+What's the point of Gnus?
+
+I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep''
+newsreader, that lets you do anything you can think of. That was my
+original motivation, but while working on Gnus, it has become clear to
+me that this generation of newsreaders really belong in the stone age.
+Newsreaders haven't developed much since the infancy of the net. If the
+volume continues to rise with the current rate of increase, all current
+newsreaders will be pretty much useless. How do you deal with
+newsgroups that have thousands of new articles each day? How do you
+keep track of millions of people who post?
+
+Gnus offers no real solutions to these questions, but I would very much
+like to see Gnus being used as a testing ground for new methods of
+reading and fetching news. Expanding on @sc{Umeda}-san's wise decision
+to separate the newsreader from the backends, Gnus now offers a simple
+interface for anybody who wants to write new backends for fetching mail
+and news from different sources. I have added hooks for customizations
+everywhere I could imagine it being useful. By doing so, I'm inviting
+every one of you to explore and invent.
+
+May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and
+@kbd{C-u 100 M-x all-hail-xemacs}.
+
+
+@node Compatibility
+@subsection Compatibility
+
+@cindex compatibility
+Gnus was designed to be fully compatible with @sc{gnus}. Almost all key
+bindings have been kept. More key bindings have been added, of course,
+but only in one or two obscure cases have old bindings been changed.
+
+Our motto is:
+@quotation
+@cartouche
+@center In a cloud bones of steel.
+@end cartouche
+@end quotation
+
+All commands have kept their names. Some internal functions have changed
+their names.
+
+The @code{gnus-uu} package has changed drastically. @xref{Decoding
+Articles}.
+
+One major compatibility question is the presence of several summary
+buffers. All variables relevant while reading a group are
+buffer-local to the summary buffer they belong in. Although many
+important variables have their values copied into their global
+counterparts whenever a command is executed in the summary buffer, this
+change might lead to incorrect values being used unless you are careful.
+
+All code that relies on knowledge of @sc{gnus} internals will probably
+fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or
+changing it in any way, as a matter of fact) is strictly verboten. Gnus
+maintains a hash table that points to the entries in this alist (which
+speeds up many functions), and changing the alist directly will lead to
+peculiar results.
+
+@cindex hilit19
+@cindex highlighting
+Old hilit19 code does not work at all. In fact, you should probably
+remove all hilit code from all Gnus hooks
+(@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}).
+Gnus provides various integrated functions for highlighting. These are
+faster and more accurate. To make life easier for everybody, Gnus will
+by default remove all hilit calls from all hilit hooks. Uncleanliness!
+Away!
+
+Packages like @code{expire-kill} will no longer work. As a matter of
+fact, you should probably remove all old @sc{gnus} packages (and other
+code) when you start using Gnus. More likely than not, Gnus already
+does what you have written code to make @sc{gnus} do. (Snicker.)
+
+Even though old methods of doing things are still supported, only the
+new methods are documented in this manual. If you detect a new method of
+doing something while reading this manual, that does not mean you have
+to stop doing it the old way.
+
+Gnus understands all @sc{gnus} startup files.
+
+@kindex M-x gnus-bug
+@findex gnus-bug
+@cindex reporting bugs
+@cindex bugs
+Overall, a casual user who hasn't written much code that depends on
+@sc{gnus} internals should suffer no problems. If problems occur,
+please let me know by issuing that magic command @kbd{M-x gnus-bug}.
+
+@vindex gnus-bug-create-help-buffer
+If you are in the habit of sending bug reports @emph{very} often, you
+may find the helpful help buffer annoying after a while. If so, set
+@code{gnus-bug-create-help-buffer} to @code{nil} to avoid having it pop
+up at you.
+
+
+@node Conformity
+@subsection Conformity
+
+No rebels without a clue here, ma'am. We conform to all standards known
+to (wo)man. Except for those standards and/or conventions we disagree
+with, of course.
+
+@table @strong
+
+@item RFC 822
+@cindex RFC 822
+There are no known breaches of this standard.
+
+@item RFC 1036
+@cindex RFC 1036
+There are no known breaches of this standard, either.
+
+@item Son-of-RFC 1036
+@cindex Son-of-RFC 1036
+We do have some breaches to this one.
+
+@table @emph
+
+@item MIME
+Gnus does no MIME handling, and this standard-to-be seems to think that
+MIME is the bees' knees, so we have major breakage here.
+
+@item X-Newsreader
+This is considered to be a ``vanity header'', while I consider it to be
+consumer information. After seeing so many badly formatted articles
+coming from @code{tin} and @code{Netscape} I know not to use either of
+those for posting articles. I would not have known that if it wasn't
+for the @code{X-Newsreader} header.
+@end table
+
+@end table
+
+If you ever notice Gnus acting non-compliant with regards to the texts
+mentioned above, don't hesitate to drop a note to Gnus Towers and let us
+know.
+
+
+@node Emacsen
+@subsection Emacsen
+@cindex Emacsen
+@cindex XEmacs
+@cindex Mule
+@cindex Emacs
+
+Gnus should work on :
+
+@itemize @bullet
+
+@item
+Emacs 19.32 and up.
+
+@item
+XEmacs 19.14 and up.
+
+@item
+Mule versions based on Emacs 19.32 and up.
+
+@end itemize
+
+Gnus will absolutely not work on any Emacsen older than that. Not
+reliably, at least.
+
+There are some vague differences between Gnus on the various
+platforms---XEmacs features more graphics (a logo and a toolbar)---but
+other than that, things should look pretty much the same under all
+Emacsen.
+
+
+@node Contributors
+@subsection Contributors
+@cindex contributors
+
+The new Gnus version couldn't have been done without the help of all the
+people on the (ding) mailing list. Every day for over a year I have
+gotten billions of nice bug reports from them, filling me with joy,
+every single one of them. Smooches. The people on the list have been
+tried beyond endurance, what with my ``oh, that's a neat idea <type
+type>, yup, I'll release it right away <ship off> no wait, that doesn't
+work at all <type type>, yup, I'll ship that one off right away <ship
+off> no, wait, that absolutely does not work'' policy for releases.
+Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that
+``worser''? ``much worser''? ``worsest''?)
+
+I would like to take this opportunity to thank the Academy for... oops,
+wrong show.
+
+@itemize @bullet
+
+@item
+Masanobu @sc{Umeda}---the writer of the original @sc{gnus}.
+
+@item
+Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as
+well as numerous other things).
+
+@item
+Luis Fernandes---design and graphics.
+
+@item
+Erik Naggum---help, ideas, support, code and stuff.
+
+@item
+Wes Hardaker---@file{gnus-picon.el} and the manual section on
+@dfn{picons} (@pxref{Picons}).
+
+@item
+Kim-Minh Kaplan---further work on the picon code.
+
+@item
+Brad Miller---@file{gnus-gl.el} and the GroupLens manual section
+(@pxref{GroupLens}).
+
+@item
+Sudish Joseph---innumerable bug fixes.
+
+@item
+Ilja Weis---@file{gnus-topic.el}.
+
+@item
+Steven L. Baur---lots and lots and lots of bugs detections and fixes.
+
+@item
+Vladimir Alexiev---the refcard and reference booklets.
+
+@item
+Felix Lee & Jamie Zawinski---I stole some pieces from the XGnus
+distribution by Felix Lee and JWZ.
+
+@item
+Scott Byer---@file{nnfolder.el} enhancements & rewrite.
+
+@item
+Peter Mutsaers---orphan article scoring code.
+
+@item
+Ken Raeburn---POP mail support.
+
+@item
+Hallvard B Furuseth---various bits and pieces, especially dealing with
+.newsrc files.
+
+@item
+Brian Edmonds---@file{gnus-bbdb.el}.
+
+@item
+David Moore---rewrite of @file{nnvirtual.el} and many other things.
+
+@item
+Kevin Davidson---came up with the name @dfn{ding}, so blame him.
+
+@item
+François Pinard---many, many interesting and thorough bug reports, as
+well as autoconf support.
+
+@end itemize
+
+This manual was proof-read by Adrian Aichner, with Ricardo Nassif, Mark
+Borges, and Jost Krieger proof-reading parts of the manual.
+
+The following people have contributed many patches and suggestions:
+
+Christopher Davis,
+Andrew Eskilsson,
+Kai Grossjohann,
+David Kågedal,
+Richard Pieri,
+Fabrice Popineau,
+Daniel Quinlan,
+Jason L. Tibbitts, III,
+and
+Jack Vinson.
+
+Also thanks to the following for patches and stuff:
+
+Jari Aalto,
+Adrian Aichner,
+Vladimir Alexiev,
+Russ Allbery,
+Peter Arius,
+Matt Armstrong,
+Marc Auslander,
+Frank Bennett,
+Robert Bihlmeyer,
+Chris Bone,
+Mark Borges,
+Mark Boyns,
+Lance A. Brown,
+Kees de Bruin,
+Martin Buchholz,
+Joe Buehler,
+Kevin Buhr,
+Alastair Burt,
+Joao Cachopo,
+Zlatko Calusic,
+Massimo Campostrini,
+Castor,
+David Charlap,
+Dan Christensen,
+Kevin Christian,
+Michael R. Cook,
+Glenn Coombs,
+Frank D. Cringle,
+Geoffrey T. Dairiki,
+Andre Deparade,
+Ulrik Dickow,
+Dave Disser,
+Rui-Tao Dong, @c ?
+Joev Dubach,
+Michael Welsh Duggan,
+Dave Edmondson,
+Paul Eggert,
+Enami Tsugutomo, @c Enami
+Michael Ernst,
+Luc Van Eycken,
+Sam Falkner,
+Nelson Jose dos Santos Ferreira,
+Sigbjorn Finne,
+Decklin Foster,
+Gary D. Foster,
+Paul Franklin,
+Guy Geens,
+Arne Georg Gleditsch,
+David S. Goldberg,
+Michelangelo Grigni,
+D. Hall,
+Magnus Hammerin,
+Kenichi Handa, @c Handa
+Raja R. Harinath,
+Yoshiki Hayashi, @c ?
+P. E. Jareth Hein,
+Hisashige Kenji, @c Hisashige
+Marc Horowitz,
+Gunnar Horrigmo,
+Richard Hoskins,
+Brad Howes,
+François Felix Ingrand,
+Ishikawa Ichiro, @c Ishikawa
+Lee Iverson,
+Iwamuro Motonori, @c Iwamuro
+Rajappa Iyer,
+Andreas Jaeger,
+Randell Jesup,
+Fred Johansen,
+Gareth Jones,
+Simon Josefsson,
+Greg Klanderman,
+Karl Kleinpaste,
+Peter Skov Knudsen,
+Shuhei Kobayashi, @c Kobayashi
+Koseki Yoshinori, @c Koseki
+Thor Kristoffersen,
+Jens Lautenbacher,
+Martin Larose,
+Seokchan Lee, @c Lee
+Carsten Leonhardt,
+James LewisMoss,
+Christian Limpach,
+Markus Linnala,
+Dave Love,
+Mike McEwan,
+Tonny Madsen,
+Shlomo Mahlab,
+Nat Makarevitch,
+Istvan Marko,
+David Martin,
+Jason R. Mastaler,
+Gordon Matzigkeit,
+Timo Metzemakers,
+Richard Mlynarik,
+Lantz Moore,
+Morioka Tomohiko, @c Morioka
+Erik Toubro Nielsen,
+Hrvoje Niksic,
+Andy Norman,
+Fred Oberhauser,
+C. R. Oldham,
+Alexandre Oliva,
+Ken Olstad,
+Masaharu Onishi, @c Onishi
+Hideki Ono, @c Ono
+William Perry,
+Stephen Peters,
+Jens-Ulrik Holger Petersen,
+Ulrich Pfeifer,
+Matt Pharr,
+John McClary Prevost,
+Bill Pringlemeir,
+Mike Pullen,
+Jim Radford,
+Colin Rafferty,
+Lasse Rasinen,
+Lars Balker Rasmussen,
+Joe Reiss,
+Renaud Rioboo,
+Roland B. Roberts,
+Bart Robinson,
+Christian von Roques,
+Jason Rumney,
+Wolfgang Rupprecht,
+Jay Sachs,
+Dewey M. Sasser,
+Loren Schall,
+Dan Schmidt,
+Ralph Schleicher,
+Philippe Schnoebelen,
+Andreas Schwab,
+Randal L. Schwartz,
+Justin Sheehy,
+Danny Siu,
+Matt Simmons,
+Paul D. Smith,
+Jeff Sparkes,
+Toby Speight,
+Michael Sperber,
+Darren Stalder,
+Richard Stallman,
+Greg Stark,
+Sam Steingold,
+Paul Stodghill,
+Kurt Swanson,
+Samuel Tardieu,
+Teddy,
+Chuck Thompson,
+Philippe Troin,
+James Troup,
+Trung Tran-Duc,
+Aaron M. Ucko,
+Aki Vehtari,
+Didier Verna,
+Jan Vroonhof,
+Stefan Waldherr,
+Pete Ware,
+Barry A. Warsaw,
+Christoph Wedler,
+Joe Wells,
+Katsumi Yamaoka, @c Yamaoka
+and
+Shenghuo Zhu. @c Zhu
+
+For a full overview of what each person has done, the ChangeLogs
+included in the Gnus alpha distributions should give ample reading
+(550kB and counting).
+
+Apologies to everybody that I've forgotten, of which there are many, I'm
+sure.
+
+Gee, that's quite a list of people. I guess that must mean that there
+actually are people who are using Gnus. Who'd'a thunk it!
+
+
+@node New Features
+@subsection New Features
+@cindex new features
+
+@menu
+* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus.
+* September Gnus:: The Thing Formally Known As Gnus 5.3/5.3.
+* Red Gnus:: Third time best---Gnus 5.4/5.5.
+* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7.
+@end menu
+
+These lists are, of course, just @emph{short} overviews of the
+@emph{most} important new features. No, really. There are tons more.
+Yes, we have feeping creaturism in full effect.
+
+
+@node ding Gnus
+@subsubsection (ding) Gnus
+
+New features in Gnus 5.0/5.1:
+
+@itemize @bullet
+
+@item
+The look of all buffers can be changed by setting format-like variables
+(@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}).
+
+@item
+Local spool and several @sc{nntp} servers can be used at once
+(@pxref{Select Methods}).
+
+@item
+You can combine groups into virtual groups (@pxref{Virtual Groups}).
+
+@item
+You can read a number of different mail formats (@pxref{Getting Mail}).
+All the mail backends implement a convenient mail expiry scheme
+(@pxref{Expiring Mail}).
+
+@item
+Gnus can use various strategies for gathering threads that have lost
+their roots (thereby gathering loose sub-threads into one thread) or it
+can go back and retrieve enough headers to build a complete thread
+(@pxref{Customizing Threading}).
+
+@item
+Killed groups can be displayed in the group buffer, and you can read
+them as well (@pxref{Listing Groups}).
+
+@item
+Gnus can do partial group updates---you do not have to retrieve the
+entire active file just to check for new articles in a few groups
+(@pxref{The Active File}).
+
+@item
+Gnus implements a sliding scale of subscribedness to groups
+(@pxref{Group Levels}).
+
+@item
+You can score articles according to any number of criteria
+(@pxref{Scoring}). You can even get Gnus to find out how to score
+articles for you (@pxref{Adaptive Scoring}).
+
+@item
+Gnus maintains a dribble buffer that is auto-saved the normal Emacs
+manner, so it should be difficult to lose much data on what you have
+read if your machine should go down (@pxref{Auto Save}).
+
+@item
+Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up
+the @file{.emacs} file.
+
+@item
+You can set the process mark on both groups and articles and perform
+operations on all the marked items (@pxref{Process/Prefix}).
+
+@item
+You can grep through a subset of groups and create a group from the
+results (@pxref{Kibozed Groups}).
+
+@item
+You can list subsets of groups according to, well, anything
+(@pxref{Listing Groups}).
+
+@item
+You can browse foreign servers and subscribe to groups from those
+servers (@pxref{Browse Foreign Server}).
+
+@item
+Gnus can fetch articles, asynchronously, on a second connection to the
+server (@pxref{Asynchronous Fetching}).
+
+@item
+You can cache articles locally (@pxref{Article Caching}).
+
+@item
+The uudecode functions have been expanded and generalized
+(@pxref{Decoding Articles}).
+
+@item
+You can still post uuencoded articles, which was a little-known feature
+of @sc{gnus}' past (@pxref{Uuencoding and Posting}).
+
+@item
+Fetching parents (and other articles) now actually works without
+glitches (@pxref{Finding the Parent}).
+
+@item
+Gnus can fetch FAQs and group descriptions (@pxref{Group Information}).
+
+@item
+Digests (and other files) can be used as the basis for groups
+(@pxref{Document Groups}).
+
+@item
+Articles can be highlighted and customized (@pxref{Customizing
+Articles}).
+
+@item
+URLs and other external references can be buttonized (@pxref{Article
+Buttons}).
+
+@item
+You can do lots of strange stuff with the Gnus window & frame
+configuration (@pxref{Windows Configuration}).
+
+@item
+You can click on buttons instead of using the keyboard
+(@pxref{Buttons}).
+
+@end itemize
+
+
+@node September Gnus
+@subsubsection September Gnus
+
+New features in Gnus 5.2/5.3:
+
+@itemize @bullet
+
+@item
+A new message composition mode is used. All old customization variables
+for @code{mail-mode}, @code{rnews-reply-mode} and @code{gnus-msg} are
+now obsolete.
+
+@item
+Gnus is now able to generate @dfn{sparse} threads---threads where
+missing articles are represented by empty nodes (@pxref{Customizing
+Threading}).
+
+@lisp
+(setq gnus-build-sparse-threads 'some)
+@end lisp
+
+@item
+Outgoing articles are stored on a special archive server
+(@pxref{Archived Messages}).
+
+@item
+Partial thread regeneration now happens when articles are
+referred.
+
+@item
+Gnus can make use of GroupLens predictions (@pxref{GroupLens}).
+
+@item
+Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}).
+
+@item
+A @code{trn}-like tree buffer can be displayed (@pxref{Tree Display}).
+
+@lisp
+(setq gnus-use-trees t)
+@end lisp
+
+@item
+An @code{nn}-like pick-and-read minor mode is available for the summary
+buffers (@pxref{Pick and Read}).
+
+@lisp
+(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode)
+@end lisp
+
+@item
+In binary groups you can use a special binary minor mode (@pxref{Binary
+Groups}).
+
+@item
+Groups can be grouped in a folding topic hierarchy (@pxref{Group
+Topics}).
+
+@lisp
+(add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
+@end lisp
+
+@item
+Gnus can re-send and bounce mail (@pxref{Summary Mail Commands}).
+
+@item
+Groups can now have a score, and bubbling based on entry frequency
+is possible (@pxref{Group Score}).
+
+@lisp
+(add-hook 'gnus-summary-exit-hook 'gnus-summary-bubble-group)
+@end lisp
+
+@item
+Groups can be process-marked, and commands can be performed on
+groups of groups (@pxref{Marking Groups}).
+
+@item
+Caching is possible in virtual groups.
+
+@item
+@code{nndoc} now understands all kinds of digests, mail boxes, rnews
+news batches, ClariNet briefs collections, and just about everything
+else (@pxref{Document Groups}).
+
+@item
+Gnus has a new backend (@code{nnsoup}) to create/read SOUP packets
+(@pxref{SOUP}).
+
+@item
+The Gnus cache is much faster.
+
+@item
+Groups can be sorted according to many criteria (@pxref{Sorting
+Groups}).
+
+@item
+New group parameters have been introduced to set list-addresses and
+expiry times (@pxref{Group Parameters}).
+
+@item
+All formatting specs allow specifying faces to be used
+(@pxref{Formatting Fonts}).
+
+@item
+There are several more commands for setting/removing/acting on process
+marked articles on the @kbd{M P} submap (@pxref{Setting Process Marks}).
+
+@item
+The summary buffer can be limited to show parts of the available
+articles based on a wide range of criteria. These commands have been
+bound to keys on the @kbd{/} submap (@pxref{Limiting}).
+
+@item
+Articles can be made persistent with the @kbd{*} command
+(@pxref{Persistent Articles}).
+
+@item
+All functions for hiding article elements are now toggles.
+
+@item
+Article headers can be buttonized (@pxref{Article Washing}).
+
+@lisp
+(add-hook 'gnus-article-display-hook
+ 'gnus-article-add-buttons-to-head)
+@end lisp
+
+@item
+All mail backends support fetching articles by @code{Message-ID}.
+
+@item
+Duplicate mail can now be treated properly (@pxref{Duplicates}).
+
+@item
+All summary mode commands are available directly from the article
+buffer (@pxref{Article Keymap}).
+
+@item
+Frames can be part of @code{gnus-buffer-configuration} (@pxref{Windows
+Configuration}).
+
+@item
+Mail can be re-scanned by a daemonic process (@pxref{Daemons}).
+
+@item
+Gnus can make use of NoCeM files to weed out spam (@pxref{NoCeM}).
+
+@lisp
+(setq gnus-use-nocem t)
+@end lisp
+
+@item
+Groups can be made permanently visible (@pxref{Listing Groups}).
+
+@lisp
+(setq gnus-permanently-visible-groups "^nnml:")
+@end lisp
+
+@item
+Many new hooks have been introduced to make customizing easier.
+
+@item
+Gnus respects the @code{Mail-Copies-To} header.
+
+@item
+Threads can be gathered by looking at the @code{References} header
+(@pxref{Customizing Threading}).
+
+@lisp
+(setq gnus-summary-thread-gathering-function
+ 'gnus-gather-threads-by-references)
+@end lisp
+
+@item
+Read articles can be stored in a special backlog buffer to avoid
+refetching (@pxref{Article Backlog}).
+
+@lisp
+(setq gnus-keep-backlog 50)
+@end lisp
+
+@item
+A clean copy of the current article is always stored in a separate
+buffer to allow easier treatment.
+
+@item
+Gnus can suggest where to save articles (@pxref{Saving Articles}).
+
+@item
+Gnus doesn't have to do as much prompting when saving (@pxref{Saving
+Articles}).
+
+@lisp
+(setq gnus-prompt-before-saving t)
+@end lisp
+
+@item
+@code{gnus-uu} can view decoded files asynchronously while fetching
+articles (@pxref{Other Decode Variables}).
+
+@lisp
+(setq gnus-uu-grabbed-file-functions 'gnus-uu-grab-view)
+@end lisp
+
+@item
+Filling in the article buffer now works properly on cited text
+(@pxref{Article Washing}).
+
+@item
+Hiding cited text adds buttons to toggle hiding, and how much
+cited text to hide is now customizable (@pxref{Article Hiding}).
+
+@lisp
+(setq gnus-cited-lines-visible 2)
+@end lisp
+
+@item
+Boring headers can be hidden (@pxref{Article Hiding}).
+
+@lisp
+(add-hook 'gnus-article-display-hook
+ 'gnus-article-hide-boring-headers t)
+@end lisp
+
+@item
+Default scoring values can now be set from the menu bar.
+
+@item
+Further syntax checking of outgoing articles have been added.
+
+@end itemize
+
+
+@node Red Gnus
+@subsubsection Red Gnus
+
+New features in Gnus 5.4/5.5:
+
+@itemize @bullet
+
+@item
+@file{nntp.el} has been totally rewritten in an asynchronous fashion.
+
+@item
+Article prefetching functionality has been moved up into
+Gnus (@pxref{Asynchronous Fetching}).
+
+@item
+Scoring can now be performed with logical operators like @code{and},
+@code{or}, @code{not}, and parent redirection (@pxref{Advanced
+Scoring}).
+
+@item
+Article washing status can be displayed in the
+article mode line (@pxref{Misc Article}).
+
+@item
+@file{gnus.el} has been split into many smaller files.
+
+@item
+Suppression of duplicate articles based on Message-ID can be done
+(@pxref{Duplicate Suppression}).
+
+@lisp
+(setq gnus-suppress-duplicates t)
+@end lisp
+
+@item
+New variables for specifying what score and adapt files are to be
+considered home score and adapt files (@pxref{Home Score File}) have
+been added.
+
+@item
+@code{nndoc} was rewritten to be easily extendable (@pxref{Document
+Server Internals}).
+
+@item
+Groups can inherit group parameters from parent topics (@pxref{Topic
+Parameters}).
+
+@item
+Article editing has been revamped and is now actually usable.
+
+@item
+Signatures can be recognized in more intelligent fashions
+(@pxref{Article Signature}).
+
+@item
+Summary pick mode has been made to look more @code{nn}-like. Line
+numbers are displayed and the @kbd{.} command can be used to pick
+articles (@code{Pick and Read}).
+
+@item
+Commands for moving the @file{.newsrc.eld} from one server to
+another have been added (@pxref{Changing Servers}).
+
+@item
+There's a way now to specify that ``uninteresting'' fields be suppressed
+when generating lines in buffers (@pxref{Advanced Formatting}).
+
+@item
+Several commands in the group buffer can be undone with @kbd{M-C-_}
+(@pxref{Undo}).
+
+@item
+Scoring can be done on words using the new score type @code{w}
+(@pxref{Score File Format}).
+
+@item
+Adaptive scoring can be done on a Subject word-by-word basis
+(@pxref{Adaptive Scoring}).
+
+@lisp
+(setq gnus-use-adaptive-scoring '(word))
+@end lisp
+
+@item
+Scores can be decayed (@pxref{Score Decays}).
+
+@lisp
+(setq gnus-decay-scores t)
+@end lisp
+
+@item
+Scoring can be performed using a regexp on the Date header. The Date is
+normalized to compact ISO 8601 format first (@pxref{Score File Format}).
+
+@item
+A new command has been added to remove all data on articles from
+the native server (@pxref{Changing Servers}).
+
+@item
+A new command for reading collections of documents
+(@code{nndoc} with @code{nnvirtual} on top) has been added---@kbd{M-C-d}
+(@pxref{Really Various Summary Commands}).
+
+@item
+Process mark sets can be pushed and popped (@pxref{Setting Process
+Marks}).
+
+@item
+A new mail-to-news backend makes it possible to post even when the NNTP
+server doesn't allow posting (@pxref{Mail-To-News Gateways}).
+
+@item
+A new backend for reading searches from Web search engines
+(@dfn{DejaNews}, @dfn{Alta Vista}, @dfn{InReference}) has been added
+(@pxref{Web Searches}).
+
+@item
+Groups inside topics can now be sorted using the standard sorting
+functions, and each topic can be sorted independently (@pxref{Topic
+Sorting}).
+
+@item
+Subsets of the groups can be sorted independently (@code{Sorting
+Groups}).
+
+@item
+Cached articles can be pulled into the groups (@pxref{Summary Generation
+Commands}).
+
+@item
+Score files are now applied in a more reliable order (@pxref{Score
+Variables}).
+
+@item
+Reports on where mail messages end up can be generated (@pxref{Splitting
+Mail}).
+
+@item
+More hooks and functions have been added to remove junk from incoming
+mail before saving the mail (@pxref{Washing Mail}).
+
+@item
+Emphasized text can be properly fontisized:
+
+@lisp
+(add-hook 'gnus-article-display-hook
+ 'gnus-article-emphasize)
+@end lisp
+
+@end itemize
+
+
+@node Quassia Gnus
+@subsubsection Quassia Gnus
+
+New features in Gnus 5.6:
+
+@itemize @bullet
+
+@item
+New functionality for using Gnus as an offline newsreader has been
+added. A plethora of new commands and modes have been added. See
+@pxref{Gnus Unplugged} for the full story.
+
+@item
+ The @code{nndraft} backend has returned, but works differently than
+before. All Message buffers are now also articles in the @code{nndraft}
+group, which is created automatically.
+
+@item
+@code{gnus-alter-header-function} can now be used to alter header
+values.
+
+@item
+ @code{gnus-summary-goto-article} now accept Message-ID's.
+
+@item
+ A new Message command for deleting text in the body of a message
+outside the region: @kbd{C-c C-v}.
+
+@item
+ You can now post to component group in @code{nnvirtual} groups with
+@kbd{C-u C-c C-c}.
+
+@item
+ @code{nntp-rlogin-program}---new variable to ease customization.
+
+@item
+ @code{C-u C-c C-c} in @code{gnus-article-edit-mode} will now inhibit
+re-highlighting of the article buffer.
+
+@item
+ New element in @code{gnus-boring-article-headers}---@code{long-to}.
+
+@item
+ @kbd{M-i} symbolic prefix command. See the section "Symbolic
+Prefixes" in the Gnus manual for details.
+
+@item
+ @kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix
+@kbd{a} to add the score rule to the "all.SCORE" file.
+
+@item
+ @code{gnus-simplify-subject-functions} variable to allow greater
+control over simplification.
+
+@item
+ @kbd{A T}---new command for fetching the current thread.
+
+@item
+ @kbd{/ T}---new command for including the current thread in the
+limit.
+
+@item
+ @kbd{M-RET} is a new Message command for breaking cited text.
+
+@item
+ @samp{\\1}-expressions are now valid in @code{nnmail-split-methods}.
+
+@item
+ The @code{custom-face-lookup} function has been removed.
+If you used this function in your initialization files, you must
+rewrite them to use @code{face-spec-set} instead.
+
+@item
+ Canceling now uses the current select method. Symbolic prefix
+@kbd{a} forces normal posting method.
+
+@item
+ New command to translate M******** sm*rtq**t*s into proper
+text---@kbd{W d}.
+
+@item
+ For easier debugging of @code{nntp}, you can set
+@code{nntp-record-commands} to a non-@code{nil} value.
+
+@item
+ @code{nntp} now uses @file{~/.authinfo}, a @file{.netrc}-like file, for
+controlling where and how to send @sc{authinfo} to @sc{nntp} servers.
+
+@item
+ A command for editing group parameters from the summary buffer
+has been added.
+
+@item
+ A history of where mails have been split is available.
+
+@item
+ A new article date command has been added---@code{article-date-iso8601}.
+
+@item
+ Subjects can be simplified when threading by setting
+@code{gnus-score-thread-simplify}.
+
+@item
+ A new function for citing in Message has been
+added---@code{message-cite-original-without-signature}.
+
+@item
+ @code{article-strip-all-blank-lines}---new article command.
+
+@item
+ A new Message command to kill to the end of the article has
+been added.
+
+@item
+ A minimum adaptive score can be specified by using the
+@code{gnus-adaptive-word-minimum} variable.
+
+@item
+ The "lapsed date" article header can be kept continually
+updated by the @code{gnus-start-date-timer} command.
+
+@item
+ Web listserv archives can be read with the @code{nnlistserv} backend.
+
+@item
+ Old dejanews archives can now be read by @code{nnweb}.
+
+@end itemize
+
+
+@node Newest Features
+@subsection Newest Features
+@cindex todo
+
+Also known as the @dfn{todo list}. Sure to be implemented before the
+next millennium.
+
+Be afraid. Be very afraid.
+
+(That a feature appears in this list doesn't necessarily mean that I've
+decided to actually implement it. It just means that I think it sounds
+interesting.)
+
+(Yes, this is the actual, up-to-the-second todo list.)
+
+@itemize @bullet
+
+@item
+Native @sc{mime} support is something that should be done.
+
+@item
+Really do unbinhexing.
+
+@item
+ I would like the zombie-page to contain an URL to the source of the
+latest version of gnus or some explanation on where to find it.
+
+@item
+ A way to continue editing the latest Message composition.
+
+@item
+ http://www.sonicnet.com/feature/ari3/
+
+@item
+ facep is not declared.
+
+@item
+ Include a section in the manual on why the number of articles
+isn't the same in the group buffer and on the SPC prompt.
+
+@item
+ Interacting with rmail fcc isn't easy.
+
+@item
+@example
+ Hypermail:
+<URL:http://www.falch.no/people/pepper/DSSSL-Lite/archives/>
+<URL:http://www.eit.com/software/hypermail/hypermail.html>
+<URL:http://homer.ncm.com/>
+<URL:http://www.yahoo.com/Computers_and_Internet/Internet/World_Wide_Web/HTML_Converters/>
+http://www.uwsg.indiana.edu/hypermail/linux/kernel/9610/index.html
+<URL:http://union.ncsa.uiuc.edu/HyperNews/get/www/html/converters.html>
+http://www.miranova.com/gnus-list/
+
+@end example
+
+@item
+@samp{^-- } is made into - in LaTeX.
+
+@item
+ gnus-kill is much slower than it was in GNUS 4.1.3.
+
+@item
+ when expunging articles on low score, the sparse nodes keep hanging on?
+@item
+ starting the first time seems to hang Gnus on some systems. Does
+NEWGROUPS answer too fast?
+@item
+ nndir doesn't read gzipped files.
+@item
+ FAQ doesn't have an up node?
+@item
+ when moving mail from a procmail spool to the crash-box,
+the crash-box is only appropriate to one specific group.
+@item
+ `t' `t' makes X-Faces disappear.
+@item
+ nnmh-be-safe means that crossposted articles will
+be marked as unread.
+@item
+ Orphan score entries don't show on "V t" score trace
+@item
+ when clearing out data, the cache data should also be reset.
+@item
+ rewrite gnus-summary-limit-children to be non-recursive
+to avoid exceeding lisp nesting on huge groups.
+@item
+ expunged articles are counted when computing scores.
+@item
+ implement gnus-batch-brew-soup
+@item
+ ticked articles aren't easy to read in pick mode -- `n' and
+stuff just skips past them. Read articles are the same.
+@item
+ topics that contain just groups with ticked
+articles aren't displayed.
+@item
+ nndoc should always allocate unique Message-IDs.
+@item
+ If there are mail groups the first time you use Gnus, Gnus'll
+make the mail groups killed.
+@item
+ no "no news is good news" when using topics.
+@item
+ when doing crosspost marking, the cache has to be consulted
+and articles have to be removed.
+@item
+ nnweb should fetch complete articles when they are split into several
+parts.
+@item
+ scoring on head immediate doesn't work.
+@item
+ finding short score file names takes forever.
+@item
+ canceling articles in foreign groups.
+@item
+ nntp-open-rlogin no longer works.
+@item
+ C-u C-x C-s (Summary) switches to the group buffer.
+@item
+ move nnmail-split-history out to the backends.
+@item
+ nnweb doesn't work properly.
+@item
+ using a virtual server name as `gnus-select-method' doesn't work?
+@item
+ when killing/yanking a group from one topic to another in a slave, the
+master will yank it first to one topic and then add it to another.
+Perhaps.
+
+@item
+ warn user about `=' redirection of a group in the active file?
+@item
+ really unbinhex binhex files.
+@item
+ take over the XEmacs menubar and offer a toggle between the XEmacs
+bar and the Gnus bar.
+@item
+@example
+ push active file and NOV file parsing down into C code.
+`(canonize-message-id id)'
+`(mail-parent-message-id references n)'
+`(parse-news-nov-line &optional dependency-hashtb)'
+`(parse-news-nov-region beg end &optional dependency-hashtb fullp)'
+`(parse-news-active-region beg end hashtb)'
+
+@end example
+
+@item
+ nnml .overview directory with splits.
+@item
+ asynchronous cache
+@item
+ postponed commands.
+@item
+ the selected article show have its Subject displayed in its summary line.
+@item
+ when entering groups, get the real number of unread articles from
+the server?
+@item
+ sort after gathering threads -- make false roots have the
+headers of the oldest orphan with a 0 article number?
+@item
+ nndoc groups should inherit the score files of their parents? Also
+inherit copy prompts and save files.
+@item
+ command to start up Gnus (if not running) and enter a mail mode buffer.
+@item
+ allow editing the group description from the group buffer
+for backends that support that.
+@item
+gnus-hide,show-all-topics
+@item
+ groups and sub-topics should be allowed to mingle inside each topic,
+and not just list all subtopics at the end.
+@item
+ a command to remove all read articles that are not needed to connect
+threads -- `gnus-summary-limit-to-sparse-unread'?
+@item
+ a variable to turn off limiting/cutting of threads in the tree buffer.
+@item
+ a variable to limit how many files are uudecoded.
+@item
+ add zombie groups to a special "New Groups" topic.
+@item
+ server mode command: close/open all connections
+@item
+ put a file date in gnus-score-alist and check whether the file
+has been changed before using it.
+@item
+ on exit from a digest group, go to the next article in the parent group.
+@item
+ hide (sub)threads with low score.
+@item
+ when expiring, remove all marks from expired articles.
+@item
+ gnus-summary-limit-to-body
+@item
+ a regexp alist that says what level groups are to be subscribed
+on. Eg. -- `(("nnml:" . 1))'.
+@item
+ easier interface to nnkiboze to create ephemeral groups that
+contain groups that match a regexp.
+@item
+ allow newlines in <URL:> urls, but remove them before using
+the URL.
+@item
+ If there is no From line, the mail backends should fudge one from the
+"From " line.
+@item
+ fuzzy simplifying should strip all non-alpha-numerical info
+from subject lines.
+@item
+ gnus-soup-brew-soup-with-high-scores.
+@item
+ nntp-ping-before-connect
+@item
+ command to check whether NOV is evil. "list overview.fmt".
+@item
+ when entering a group, Gnus should look through the score
+files very early for `local' atoms and set those local variables.
+@item
+ message annotations.
+@item
+ topics are always yanked before groups, and that's not good.
+@item
+ (set-extent-property extent 'help-echo "String to display in minibuf")
+to display help in the minibuffer on buttons under XEmacs.
+@item
+ allow group line format spec to say how many articles there
+are in the cache.
+@item
+ AUTHINFO GENERIC
+@item
+ support qmail maildir spools
+@item
+ `run-with-idle-timer' in gnus-demon.
+@item
+ stop using invisible text properties and start using overlays instead
+@item
+ C-c C-f C-e to add an Expires header.
+@item
+ go from one group to the next; everything is expunged; go to the
+next group instead of going to the group buffer.
+@item
+ gnus-renumber-cache -- to renumber the cache using "low" numbers.
+@item
+ record topic changes in the dribble buffer.
+@item
+ `nnfolder-generate-active-file' should look at the folders it
+finds and generate proper active ranges.
+@item
+ nneething-look-in-files-for-article-heads variable to control
+whether nneething should sniff all files in the directories.
+@item
+ gnus-fetch-article -- start Gnus, enter group, display article
+@item
+ gnus-dont-move-articles-to-same-group variable when respooling.
+@item
+ when messages are crossposted between several auto-expirable groups,
+articles aren't properly marked as expirable.
+@item
+ nneething should allow deletion/moving.
+@item
+ TAB on the last button should go to the first button.
+@item
+ if the car of an element in `mail-split-methods' is a function,
+and the function returns non-nil, use that as the name of the group(s) to
+save mail in.
+@item
+ command for listing all score files that have been applied.
+@item
+ a command in the article buffer to return to `summary' config.
+@item
+ `gnus-always-post-using-current-server' -- variable to override
+`C-c C-c' when posting.
+@item
+ nnmail-group-spool-alist -- says where each group should use
+as a spool file.
+@item
+ when an article is crossposted to an auto-expirable group, the article
+should be marker as expirable.
+@item
+ article mode command/menu for "send region as URL to browser".
+@item
+ on errors, jump to info nodes that explain the error. For instance,
+on invalid From headers, or on error messages from the nntp server.
+@item
+ when gathering threads, make the article that has no "Re: " the parent.
+Also consult Date headers.
+@item
+ a token in splits to call shrink-window-if-larger-than-buffer
+@item
+ `1 0 A M' to do matches on the active hashtb.
+@item
+ duplicates -- command to remove Gnus-Warning header, use the read
+Message-ID, delete the "original".
+@item
+ when replying to several messages at once, put the "other" message-ids
+into a See-Also header.
+@item
+ support setext: URL:http://www.bsdi.com/setext/
+@item
+ support ProleText: <URL:http://proletext.clari.net/prole/proletext.html>
+@item
+ when browsing a foreign server, the groups that are already subscribed
+should be listed as such and not as "K".
+@item
+ generate font names dynamically.
+@item
+ score file mode auto-alist.
+@item
+ allow nndoc to change/add/delete things from documents. Implement
+methods for each format for adding an article to the document.
+@item
+ `gnus-fetch-old-headers' `all' value to incorporate
+absolutely all headers there is.
+@item
+ function like `|', but concatenate all marked articles
+and pipe them to the process.
+@item
+ cache the list of killed (or active) groups in a separate file. Update
+the file whenever we read the active file or the list
+of killed groups in the .eld file reaches a certain length.
+@item
+ function for starting to edit a file to put into
+the current mail group.
+@item
+ score-find-trace should display the total score of the article.
+@item
+ "ghettozie" -- score on Xref header and nix it out after using it
+to avoid marking as read in other groups it has been crossposted to.
+@item
+ look at procmail splitting. The backends should create
+the groups automatically if a spool file exists for that group.
+@item
+ function for backends to register themselves with Gnus.
+@item
+ when replying to several process-marked articles,
+have all the From end up in Cc headers? Variable to toggle.
+@item
+ command to delete a crossposted mail article from all
+groups it has been mailed to.
+@item
+ `B c' and `B m' should be crosspost aware.
+@item
+ hide-pgp should also hide PGP public key blocks.
+@item
+ Command in the group buffer to respool process-marked groups.
+@item
+ `gnus-summary-find-matching' should accept
+pseudo-"headers" like "body", "head" and "all"
+@item
+ When buttifying <URL: > things, all white space (including
+newlines) should be ignored.
+@item
+ Process-marking all groups in a topic should process-mark
+groups in subtopics as well.
+@item
+ Add non-native groups to the list of killed groups when killing them.
+@item
+ nntp-suggest-kewl-config to probe the nntp server and suggest
+variable settings.
+@item
+ add edit and forward secondary marks.
+@item
+ nnml shouldn't visit its .overview files.
+@item
+ allow customizing sorting within gathered threads.
+@item
+ `B q' shouldn't select the current article.
+@item
+ nnmbox should support a newsgroups file for descriptions.
+@item
+ allow fetching mail from several pop servers.
+@item
+ Be able to specify whether the saving commands save the original
+or the formatted article.
+@item
+ a command to reparent with the child process-marked (cf. `T ^'.).
+@item
+ I think the possibility to send a password with nntp-open-rlogin
+should be a feature in Red Gnus.
+@item
+ The `Z n' command should be possible to execute from a mouse click.
+@item
+ more limiting functions -- date, etc.
+@item
+ be able to limit on a random header; on body; using reverse matches.
+@item
+ a group parameter (`absofucking-total-expiry') that will make Gnus expire
+even unread articles.
+@item
+ a command to print the article buffer as postscript.
+@item
+ variable to disable password fetching when opening by nntp-open-telnet.
+@item
+ manual: more example servers -- nntp with rlogin, telnet
+@item
+ checking for bogus groups should clean topic alists as well.
+@item
+ canceling articles in foreign groups.
+@item
+ article number in folded topics isn't properly updated by
+Xref handling.
+@item
+ Movement in the group buffer to the next unread group should go to the
+next closed topic with unread messages if no group can be found.
+@item
+ Extensive info pages generated on the fly with help everywhere --
+in the "*Gnus edit*" buffers, for instance.
+@item
+ Topic movement commands -- like thread movement. Up, down, forward, next.
+@item
+ a way to tick/mark as read Gcc'd articles.
+@item
+ a way to say that all groups within a specific topic comes
+from a particular server? Hm.
+@item
+ `gnus-article-fill-if-long-lines' -- a function to fill
+the article buffer if there are any looong lines there.
+@item
+ `T h' should jump to the parent topic and fold it.
+@item
+ a command to create an ephemeral nndoc group out of a file,
+and then splitting it/moving it to some other group/backend.
+@item
+ a group parameter for nnkiboze groups that says that
+all kibozed articles should be entered into the cache.
+@item
+ It should also probably be possible to delimit what
+`gnus-jog-cache' does -- for instance, work on just some groups, or on
+some levels, and entering just articles that have a score higher than
+a certain number.
+@item
+ nnfolder should append to the folder instead of re-writing
+the entire folder to disk when accepting new messages.
+@item
+ allow all backends to do the proper thing with .gz files.
+@item
+ a backend for reading collections of babyl files nnbabylfolder?
+@item
+ a command for making the native groups into foreign groups.
+@item
+ server mode command for clearing read marks from all groups
+from a server.
+@item
+ when following up multiple articles, include all To, Cc, etc headers
+from all articles.
+@item
+ a command for deciding what the total score of the current
+thread is. Also a way to highlight based on this.
+@item
+ command to show and edit group scores
+@item
+ a gnus-tree-minimize-horizontal to minimize tree buffers
+horizontally.
+@item
+ command to generate nnml overview file for one group.
+@item
+ `C-u C-u a' -- prompt for many crossposted groups.
+@item
+ keep track of which mail groups have received new articles (in this session).
+Be able to generate a report and perhaps do some marking in the group
+buffer.
+@item
+ gnus-build-sparse-threads to a number -- build only sparse threads
+that are of that length.
+@item
+ have nnmh respect mh's unseen sequence in .mh_profile.
+@item
+ cache the newsgroups descriptions locally.
+@item
+ asynchronous posting under nntp.
+@item
+ be able to control word adaptive scoring from the score files.
+@item
+ a variable to make `C-c C-c' post using the "current" select method.
+@item
+ `limit-exclude-low-scored-articles'.
+@item
+ if `gnus-summary-show-thread' is a number, hide threads that have
+a score lower than this number.
+@item
+ split newsgroup subscription variable up into "order" and "method".
+@item
+ buttonize ange-ftp file names.
+@item
+ a command to make a duplicate copy of the current article
+so that each copy can be edited separately.
+@item
+ nnweb should allow fetching from the local nntp server.
+@item
+ record the sorting done in the summary buffer so that
+it can be repeated when limiting/regenerating the buffer.
+@item
+ nnml-generate-nov-databses should generate for
+all nnml servers.
+@item
+ when the user does commands in the group buffer, check
+the modification time of the .newsrc.eld file and use
+ask-user-about-supersession-threat. Also warn when trying
+to save .newsrc.eld and it has changed.
+@item
+ M-g on a topic will display all groups with 0 articles in
+the topic.
+@item
+ command to remove all topic stuff.
+@item
+ allow exploding incoming digests when reading incoming mail
+and splitting the resulting digests.
+@item
+ nnsoup shouldn't set the `message-' variables.
+@item
+ command to nix out all nnoo state information.
+@item
+ nnmail-process-alist that calls functions if group names
+matches an alist -- before saving.
+@item
+ use buffer-invisibility-spec everywhere for hiding text.
+@item
+ variable to activate each group before entering them
+to get the (new) number of articles. `gnus-activate-before-entering'.
+@item
+ command to fetch a Message-ID from any buffer, even
+starting Gnus first if necessary.
+@item
+ when posting and checking whether a group exists or not, just
+ask the nntp server instead of relying on the active hashtb.
+@item
+ buttonize the output of `C-c C-a' in an apropos-like way.
+@item
+ `G p' should understand process/prefix, and allow editing
+of several groups at once.
+@item
+ command to create an ephemeral nnvirtual group that
+matches some regexp(s).
+@item
+ nndoc should understand "Content-Type: message/rfc822" forwarded messages.
+@item
+ it should be possible to score "thread" on the From header.
+@item
+ hitting RET on a "gnus-uu-archive" pseudo article should unpack it.
+@item
+ `B i' should display the article at once in the summary buffer.
+@item
+ remove the "*" mark at once when unticking an article.
+@item
+ `M-s' should highlight the matching text.
+@item
+ when checking for duplicated mails, use Resent-Message-ID if present.
+@item
+ killing and yanking groups in topics should be better. If killing one copy
+of a group that exists in multiple topics, only that copy should
+be removed. Yanking should insert the copy, and yanking topics
+should be possible to be interspersed with the other yankings.
+@item
+ command for enter a group just to read the cached articles. A way to say
+"ignore the nntp connection; just read from the cache."
+@item
+ `X u' should decode base64 articles.
+@item
+ a way to hide all "inner" cited text, leaving just the most
+recently cited text.
+@item
+ nnvirtual should be asynchronous.
+@item
+ after editing an article, gnus-original-article-buffer should
+be invalidated.
+@item
+ there should probably be a way to make Gnus not connect to the
+server and just read the articles in the server
+@item
+ allow a `set-default' (or something) to change the default
+value of nnoo variables.
+@item
+ a command to import group infos from a .newsrc.eld file.
+@item
+ groups from secondary servers have the entire select method
+listed in each group info.
+@item
+ a command for just switching from the summary buffer to the group
+buffer.
+@item
+ a way to specify that some incoming mail washing functions
+should only be applied to some groups.
+@item
+ Message `C-f C-t' should ask the user whether to heed
+mail-copies-to: never.
+@item
+ new group parameter -- `post-to-server' that says to post
+using the current server. Also a variable to do the same.
+@item
+ the slave dribble files should autosave to the slave file names.
+@item
+ a group parameter that says what articles to display on group entry, based
+on article marks.
+@item
+ a way to visually distinguish slave Gnusae from masters. (Whip instead
+of normal logo?)
+@item
+ Use DJ Bernstein "From " quoting/dequoting, where applicable.
+@item
+ Why is hide-citation-maybe and hide-citation different? Also
+clear up info.
+@item
+ group user-defined meta-parameters.
+
+
+
+From: John Griffith <griffith@@sfs.nphil.uni-tuebingen.de>
+@item
+ I like the option for trying to retrieve the FAQ for a group and I was
+thinking it would be great if for those newsgroups that had archives
+you could also try to read the archive for that group. Part of the
+problem is that archives are spread all over the net, unlike FAQs.
+What would be best I suppose is to find the one closest to your site.
+
+In any case, there is a list of general news group archives at @*
+ftp://ftp.neosoft.com/pub/users/claird/news.lists/newsgroup_archives.html
+
+
+
+
+@item
+@example
+From: Jason L Tibbitts III <tibbs@@hpc.uh.edu>
+(add-hook 'gnus-select-group-hook
+ (lambda ()
+ (gnus-group-add-parameter group
+ (cons 'gnus-group-date-last-entered (list (current-time-string))))))
+
+(defun gnus-user-format-function-d (headers)
+ "Return the date the group was last read."
+ (cond ((car (gnus-group-get-parameter gnus-tmp-group 'gnus-group-date-last-entered)))
+ (t "")))
+@end example
+
+@item
+ tanken var at når du bruker `gnus-startup-file' som prefix (FOO) til å lete
+opp en fil FOO-SERVER, FOO-SERVER.el, FOO-SERVER.eld, kan du la den være en
+liste hvor du bruker hvert element i listen som FOO, istedet. da kunne man
+hatt forskjellige serveres startup-filer forskjellige steder.
+
+
+@item
+LMI> Well, nnbabyl could alter the group info to heed labels like
+LMI> answered and read, I guess.
+
+It could also keep them updated (the same for the Status: header of
+unix mbox files).
+
+They could be used like this:
+
+
+@example
+`M l <name> RET' add label <name> to current message.
+`M u <name> RET' remove label <name> from current message.
+`/ l <expr> RET' limit summary buffer according to <expr>.
+
+<expr> would be a boolean expression on the labels, e.g.
+
+`/ l bug & !fixed RET'
+@end example
+
+would show all the messages which are labeled `bug' but not labeled
+`fixed'.
+
+One could also imagine the labels being used for highlighting, or
+affect the summary line format.
+
+
+@item
+Sender: abraham@@dina.kvl.dk
+
+I'd like a gnus-find-file which work like find file, except that it
+would recognize things that looks like messages or folders:
+
+- If it is a directory containing numbered files, create an nndir
+summary buffer.
+
+- For other directories, create a nneething summary buffer.
+
+- For files matching "\\`From ", create a nndoc/mbox summary.
+
+- For files matching "\\`BABYL OPTIONS:", create a nndoc/baby summary.
+
+- For files matching "\\`[^ \t\n]+:", create an *Article* buffer.
+
+- For other files, just find them normally.
+
+I'd like `nneething' to use this function, so it would work on a
+directory potentially containing mboxes or babyl files.
+
+@item
+Please send a mail to bwarsaw@@cnri.reston.va.us (Barry A. Warsaw) and
+tell him what you are doing.
+
+@item
+Currently, I get prompted:
+
+decend into sci?
+- type y
+decend into sci.something ?
+- type n
+decend into ucd?
+
+The problem above is that since there is really only one subsection of
+science, shouldn't it prompt you for only descending sci.something? If
+there was a sci.somethingelse group or section, then it should prompt
+for sci? first the sci.something? then sci.somethingelse?...
+
+@item
+Ja, det burde være en måte å si slikt. Kanskje en ny variabel?
+`gnus-use-few-score-files'? Så kunne score-regler legges til den
+"mest" lokale score-fila. F. eks. ville no-gruppene betjenes av
+"no.all.SCORE", osv.
+
+@item
+What i want is for Gnus to treat any sequence or combination of the following
+as a single spoiler warning and hide it all, replacing it with a "Next Page"
+button:
+
+
+^L's
+
+more than n blank lines
+
+more than m identical lines
+(which should be replaced with button to show them)
+
+any whitespace surrounding any of the above
+
+
+@item
+Well, we could allow a new value to `gnus-thread-ignore-subject' --
+`spaces', or something. (We could even default to that.) And then
+subjects that differ in white space only could be considered the
+"same" subject for threading purposes.
+
+@item
+Modes to preprocess the contents (e.g. jka-compr) use the second form
+"(REGEXP FUNCTION NON-NIL)" while ordinary modes (e.g. tex) use the first
+form "(REGEXP . FUNCTION)", so you could use it to distinguish between
+those two types of modes. (auto-modes-alist, insert-file-contents-literally.)
+
+@item
+ Under XEmacs -- do funny article marks:
+tick - thumb tack
+killed - skull
+soup - bowl of soup
+score below - dim light bulb
+score over - bright light bulb
+
+@item
+Yes. I think the algorithm is as follows:
+
+@example
+Group-mode
+
+ show-list-of-articles-in-group
+ if (key-pressed == SPACE)
+ if (no-more-articles-in-group-to-select)
+ if (articles-selected)
+ start-reading-selected-articles;
+ junk-unread-articles;
+ next-group;
+ else
+ show-next-page;
+
+ else if (key-pressed = '.')
+ if (consolidated-menus) # same as hide-thread in Gnus
+ select-thread-under-cursor;
+ else
+ select-article-under-cursor;
+
+
+Article-mode
+ if (key-pressed == SPACE)
+ if (more-pages-in-article)
+ next-page;
+ else if (more-selected-articles-to-read)
+ next-article;
+ else
+ next-group;
+@end example
+
+@item
+My precise need here would have been to limit files to Incoming*.
+One could think of some `nneething-only-files' variable, but I guess
+it would have been unacceptable if one was using many unrelated such
+nneething groups.
+
+A more useful approach would be to, in response to the `G D' prompt, be
+allowed to say something like: `~/.mail/Incoming*', somewhat limiting
+the top-level directory only (in case directories would be matched by
+the wildcard expression).
+
+@item
+It would be nice if it also handled
+
+ <URL:news://sunsite.auc.dk/>
+
+which should correspond to `B nntp RET sunsite.auc.dk' in *Group*.
+
+
+@item
+
+ Take a look at w3-menu.el in the Emacs-W3 distribution - this works out
+really well. Each menu is 'named' by a symbol that would be on a
+gnus-*-menus (where * would be whatever, but at least group, summary, and
+article versions) variable.
+
+ So for gnus-summary-menus, I would set to '(sort mark dispose ...)
+
+ A value of '1' would just put _all_ the menus in a single 'GNUS' menu in
+the main menubar. This approach works really well for Emacs-W3 and VM.
+
+
+@item
+ nndoc should take care to create unique Message-IDs for all its
+articles.
+@item
+ gnus-score-followup-article only works when you have a summary buffer
+active. Make it work when posting from the group buffer as well.
+(message-sent-hook).
+@item
+ rewrite gnus-demon to use run-with-idle-timers.
+
+@item
+ * Enhancements to Gnus:
+
+ Add two commands:
+
+ * gnus-servers (gnus-start-server-buffer?)--enters Gnus and goes
+ straight to the server buffer, without opening any connections to
+ servers first.
+
+ * gnus-server-read-server-newsrc--produces a buffer very similar to
+ the group buffer, but with only groups from that server listed;
+ quitting this buffer returns to the server buffer.
+
+@item
+ add a command to check the integrity of an nnfolder folder --
+go through the article numbers and see that there are no duplicates,
+and stuff.
+
+@item
+ `unsmileyfy-buffer' to undo smileification.
+
+@item
+ a command to give all relevant info on an article, including all
+secondary marks.
+
+@item
+ when doing `-request-accept-article', the backends should do
+the nnmail duplicate checking.
+
+@item
+ allow `message-signature-file' to be a function to return the
+value of the signature file.
+
+@item
+ In addition, I would love it if I could configure message-tab so that it
+could call `bbdb-complete-name' in other headers. So, some sort of
+interface like
+
+(setq message-tab-alist
+ '((message-header-regexp message-expand-group)
+ ("^\\(To\\|[cC]c\\|[bB]cc\\)" bbdb-complete-name)))
+
+then you could run the relevant function to complete the information in
+the header
+
+@item
+ cache the newsgroups file locally to avoid reloading it all the time.
+
+@item
+ a command to import a buffer into a group.
+
+@item
+ nnweb should allow fetching by Message-ID from servers.
+
+@item
+ point in the article buffer doesn't always go to the
+beginning of the buffer when selecting new articles.
+
+@item
+ a command to process mark all unread articles.
+
+@item
+ `gnus-gather-threads-by-references-and-subject' -- first
+do gathering by references, and then go through the dummy roots and
+do more gathering by subject.
+
+@item
+ gnus-uu-mark-in-numerical-order -- process mark articles in
+article numerical order.
+
+@item
+ (gnus-thread-total-score
+ (gnus-id-to-thread (mail-header-id (gnus-summary-article-header))))
+bind to a key.
+
+@item
+ sorting by score is wrong when using sparse threads.
+
+@item
+ a command to fetch an arbitrary article -- without having to be
+in the summary buffer.
+
+@item
+ a new nncvs backend. Each group would show an article, using
+version branches as threading, checkin date as the date, etc.
+
+@item
+ http://www.dejanews.com/forms/dnsetfilter_exp.html ?
+This filter allows one to construct advance queries on the Dejanews
+database such as specifying start and end dates, subject, author,
+and/or newsgroup name.
+
+@item
+ new Date header scoring type -- older, newer
+
+@item
+ use the summary toolbar in the article buffer.
+
+@item
+ a command to fetch all articles that are less than X days old.
+
+@item
+ in pick mode, `q' should save the list of selected articles in the
+group info. The next time the group is selected, these articles
+will automatically get the process mark.
+
+@item
+ Isn't it possible to (also?) allow M-^ to automatically try the
+default server if it fails on the current server? (controlled by a
+user variable, (nil, t, 'ask)).
+
+@item
+ make it possible to cancel articles using the select method for the
+current group.
+
+@item
+ `gnus-summary-select-article-on-entry' or something. It'll default
+to t and will select whatever article decided by `gnus-auto-select-first'.
+
+@item
+ a new variable to control which selection commands should be unselecting.
+`first', `best', `next', `prev', `next-unread', `prev-unread' are
+candidates.
+
+@item
+ be able to select groups that have no articles in them
+to be able to post in them (using the current select method).
+
+@item
+ be able to post via DejaNews.
+
+@item
+ `x' should retain any sortings that have been performed.
+
+@item
+ allow the user to specify the precedence of the secondary marks. Also
+allow them to be displayed separately.
+
+@item
+ gnus-summary-save-in-pipe should concatenate the results from
+the processes when doing a process marked pipe.
+
+@item
+ a new match type, like Followup, but which adds Thread matches on all
+articles that match a certain From header.
+
+@item
+ a function that can be read from kill-emacs-query-functions to offer
+saving living summary buffers.
+
+@item
+ a function for selecting a particular group which will contain
+the articles listed in a list of article numbers/id's.
+
+@item
+ a battery of character translation functions to translate common
+Mac, MS (etc) characters into ISO 8859-1.
+
+@example
+(defun article-fix-m$word ()
+ "Fix M$Word smartquotes in an article."
+ (interactive)
+ (save-excursion
+ (let ((buffer-read-only nil))
+ (goto-char (point-min))
+ (while (search-forward "\221" nil t)
+ (replace-match "`" t t))
+ (goto-char (point-min))
+ (while (search-forward "\222" nil t)
+ (replace-match "'" t t))
+ (goto-char (point-min))
+ (while (search-forward "\223" nil t)
+ (replace-match "\"" t t))
+ (goto-char (point-min))
+ (while (search-forward "\224" nil t)
+ (replace-match "\"" t t)))))
+@end example
+
+@item
+@example
+ (add-hook 'gnus-exit-query-functions
+'(lambda ()
+ (if (and (file-exists-p nnmail-spool-file)
+ (> (nnheader-file-size nnmail-spool-file) 0))
+ (yes-or-no-p "New mail has arrived. Quit Gnus anyways? ")
+ (y-or-n-p "Are you sure you want to quit Gnus? "))))
+@end example
+
+@item
+ allow message-default-headers to be a function.
+
+@item
+ new Date score match types -- < > = (etc) that take floating point
+numbers and match on the age of the article.
+
+@item
+@example
+> > > If so, I've got one gripe: It seems that when I fire up gnus 5.2.25
+> > > under xemacs-19.14, it's creating a new frame, but is erasing the
+> > > buffer in the frame that it was called from =:-O
+>
+> > Hm. How do you start up Gnus? From the toolbar or with
+> > `M-x gnus-other-frame'?
+>
+> I normally start it up from the toolbar; at
+> least that's the way I've caught it doing the
+> deed before.
+@end example
+
+@item
+ all commands that react to the process mark should push
+the current process mark set onto the stack.
+
+@item
+ gnus-article-hide-pgp
+Selv ville jeg nok ha valgt å slette den dersom teksten matcher
+@example
+"\\(This\s+\\)?[^ ]+ has been automatically signed by"
+@end example
+og det er maks hundre tegn mellom match-end og ----linja. Men -det-
+er min type heuristikk og langt fra alles.
+
+@item
+ `gnus-subscribe-sorted' -- insert new groups where they would have been
+sorted to if `gnus-group-sort-function' were run.
+
+@item
+ gnus-(group,summary)-highlight should respect any `face' text props set
+on the lines.
+
+@item
+ use run-with-idle-timer for gnus-demon instead of the
+home-brewed stuff for better reliability.
+
+@item
+ add a way to select which NoCeM type to apply -- spam, troll, etc.
+
+@item
+ nndraft-request-group should tally autosave files.
+
+@item
+ implement nntp-retry-on-break and nntp-command-timeout.
+
+@item
+ gnus-article-highlight-limit that says when not to highlight (long)
+articles.
+
+@item
+ (nnoo-set SERVER VARIABLE VALUE)
+
+@item
+ nn*-spool-methods
+
+@item
+ interrupitng agent fetching of articles should save articles.
+
+@item
+ command to open a digest group, and copy all the articles there to the
+current group.
+
+@item
+ a variable to disable article body highlights if there's more than
+X characters in the body.
+
+@item
+ handle 480/381 authinfo requests separately.
+
+@item
+ include the texi/dir file in the distribution.
+
+@item
+ format spec to "tab" to a position.
+
+@item
+ Move all prompting to the new `M-n' default style.
+
+@item
+ command to display all dormant articles.
+
+@item
+ gnus-auto-select-next makeover -- list of things it should do.
+
+@item
+ a score match type that adds scores matching on From if From has replied
+to something someone else has said.
+
+@item
+ Read Netscape discussion groups:
+snews://secnews.netscape.com/netscape.communicator.unix
+
+@item
+One command to edit the original version if an article, and one to edit
+the displayed version.
+
+@item
+@kbd{T v} -- make all process-marked articles the children of the
+current article.
+
+@item
+Switch from initial text to the new default text mechanism.
+
+@item
+How about making it possible to expire local articles? Will it be
+possible to make various constraints on when an article can be
+expired, e.g. (read), (age > 14 days), or the more interesting (read
+& age > 14 days)?
+
+@item
+New limit command---limit to articles that have a certain string
+in the head or body.
+
+@item
+Allow breaking lengthy NNTP commands.
+
+@item
+gnus-article-highlight-limit, to disable highlighting in big articles.
+
+@item
+Editing an article should put the article to be edited
+in a special, unique buffer.
+
+@item
+A command to send a mail to the admin-address group param.
+
+@item
+A Date scoring type that will match if the article
+is less than a certain number of days old.
+
+@item
+New spec: %~(tab 56) to put point on column 56
+
+@item
+Allow Gnus Agent scoring to use normal score files.
+
+@item
+Rething the Agent active file thing. `M-g' doesn't update the active
+file, for instance.
+
+@item
+With dummy roots, `^' and then selecing the first article
+in any other dummy thread will make Gnus highlight the
+dummy root instead of the first article.
+
+@item
+Propagate all group properties (marks, article numbers, etc) up to the
+topics for displaying.
+
+@item
+`n' in the group buffer with topics should go to the next group
+with unread articles, even if that group is hidden in a topic.
+
+@item
+gnus-posting-styles doesn't work in drafts.
+
+@item
+gnus-summary-limit-include-cached is slow when there are
+many articles in the cache, since it regenerates big parts of the
+summary buffer for each article.
+
+@item
+Implement gnus-batch-brew-soup.
+
+@item
+Group parameters and summary commands for un/subscribing to mailing
+lists.
+
+@item
+Introduce nnmail-home-directory.
+
+@item
+gnus-fetch-group and friends should exit Gnus when the user
+exits the group.
+
+@item
+Solve the halting problem.
+
+@c TODO
+@end itemize
+
+@iftex
+
+@page
+@node The Manual
+@section The Manual
+@cindex colophon
+@cindex manual
+
+This manual was generated from a TeXinfo file and then run through
+either @code{texi2dvi}
+to get what you hold in your hands now.
+
+The following conventions have been used:
+
+@enumerate
+
+@item
+This is a @samp{string}
+
+@item
+This is a @kbd{keystroke}
+
+@item
+This is a @file{file}
+
+@item
+This is a @code{symbol}
+
+@end enumerate
+
+So if I were to say ``set @code{flargnoze} to @samp{yes}'', that would
+mean:
+
+@lisp
+(setq flargnoze "yes")
+@end lisp
+
+If I say ``set @code{flumphel} to @code{yes}'', that would mean:
+
+@lisp
+(setq flumphel 'yes)
+@end lisp
+
+@samp{yes} and @code{yes} are two @emph{very} different things---don't
+ever get them confused.
+
+
+@end iftex
+
+
+@page
+@node Terminology
+@section Terminology
+
+@cindex terminology
+@table @dfn
+
+@item news
+@cindex news
+This is what you are supposed to use this thing for---reading news.
+News is generally fetched from a nearby @sc{nntp} server, and is
+generally publicly available to everybody. If you post news, the entire
+world is likely to read just what you have written, and they'll all
+snigger mischievously. Behind your back.
+
+@item mail
+@cindex mail
+Everything that's delivered to you personally is mail. Some news/mail
+readers (like Gnus) blur the distinction between mail and news, but
+there is a difference. Mail is private. News is public. Mailing is
+not posting, and replying is not following up.
+
+@item reply
+@cindex reply
+Send a mail to the person who has written what you are reading.
+
+@item follow up
+@cindex follow up
+Post an article to the current newsgroup responding to the article you
+are reading.
+
+@item backend
+@cindex backend
+Gnus gets fed articles from a number of backends, both news and mail
+backends. Gnus does not handle the underlying media, so to speak---this
+is all done by the backends.
+
+@item native
+@cindex native
+Gnus will always use one method (and backend) as the @dfn{native}, or
+default, way of getting news.
+
+@item foreign
+@cindex foreign
+You can also have any number of foreign groups active at the same time.
+These are groups that use non-native non-secondary backends for getting
+news.
+
+@item secondary
+@cindex secondary
+Secondary backends are somewhere half-way between being native and being
+foreign, but they mostly act like they are native.
+
+@item article
+@cindex article
+A message that has been posted as news.
+
+@item mail message
+@cindex mail message
+A message that has been mailed.
+
+@item message
+@cindex message
+A mail message or news article
+
+@item head
+@cindex head
+The top part of a message, where administrative information (etc.) is
+put.
+
+@item body
+@cindex body
+The rest of an article. Everything not in the head is in the
+body.
+
+@item header
+@cindex header
+A line from the head of an article.
+
+@item headers
+@cindex headers
+A collection of such lines, or a collection of heads. Or even a
+collection of @sc{nov} lines.
+
+@item @sc{nov}
+@cindex nov
+When Gnus enters a group, it asks the backend for the headers of all
+unread articles in the group. Most servers support the News OverView
+format, which is more compact and much faster to read and parse than the
+normal @sc{head} format.
+
+@item level
+@cindex levels
+Each group is subscribed at some @dfn{level} or other (1-9). The ones
+that have a lower level are ``more'' subscribed than the groups with a
+higher level. In fact, groups on levels 1-5 are considered
+@dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9
+are @dfn{killed}. Commands for listing groups and scanning for new
+articles will all use the numeric prefix as @dfn{working level}.
+
+@item killed groups
+@cindex killed groups
+No information on killed groups is stored or updated, which makes killed
+groups much easier to handle than subscribed groups.
+
+@item zombie groups
+@cindex zombie groups
+Just like killed groups, only slightly less dead.
+
+@item active file
+@cindex active file
+The news server has to keep track of what articles it carries, and what
+groups exist. All this information in stored in the active file, which
+is rather large, as you might surmise.
+
+@item bogus groups
+@cindex bogus groups
+A group that exists in the @file{.newsrc} file, but isn't known to the
+server (i.e., it isn't in the active file), is a @emph{bogus group}.
+This means that the group probably doesn't exist (any more).
+
+@item activating
+@cindex activating groups
+The act of asking the server for info on a group and computing the
+number of unread articles is called @dfn{activating the group}.
+Un-activated groups are listed with @samp{*} in the group buffer.
+
+@item server
+@cindex server
+A machine one can connect to and get news (or mail) from.
+
+@item select method
+@cindex select method
+A structure that specifies the backend, the server and the virtual
+server settings.
+
+@item virtual server
+@cindex virtual server
+A named select method. Since a select method defines all there is to
+know about connecting to a (physical) server, taking the thing as a
+whole is a virtual server.
+
+@item washing
+@cindex washing
+Taking a buffer and running it through a filter of some sort. The
+result will (more often than not) be cleaner and more pleasing than the
+original.
+
+@item ephemeral groups
+@cindex ephemeral groups
+Most groups store data on what articles you have read. @dfn{Ephemeral}
+groups are groups that will have no data stored---when you exit the
+group, it'll disappear into the aether.
+
+@item solid groups
+@cindex solid groups
+This is the opposite of ephemeral groups. All groups listed in the
+group buffer are solid groups.
+
+@item sparse articles
+@cindex sparse articles
+These are article placeholders shown in the summary buffer when
+@code{gnus-build-sparse-threads} has been switched on.
+
+@item threading
+@cindex threading
+To put responses to articles directly after the articles they respond
+to---in a hierarchical fashion.
+
+@item root
+@cindex root
+@cindex thread root
+The first article in a thread is the root. It is the ancestor of all
+articles in the thread.
+
+@item parent
+@cindex parent
+An article that has responses.
+
+@item child
+@cindex child
+An article that responds to a different article---its parent.
+
+@item digest
+@cindex digest
+A collection of messages in one file. The most common digest format is
+specified by RFC1153.
+
+@end table
+
+
+@page
+@node Customization
+@section Customization
+@cindex general customization
+
+All variables are properly documented elsewhere in this manual. This
+section is designed to give general pointers on how to customize Gnus
+for some quite common situations.
+
+@menu
+* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
+* Slow Terminal Connection:: You run a remote Emacs.
+* Little Disk Space:: You feel that having large setup files is icky.
+* Slow Machine:: You feel like buying a faster machine.
+@end menu
+
+
+@node Slow/Expensive Connection
+@subsection Slow/Expensive @sc{nntp} Connection
+
+If you run Emacs on a machine locally, and get your news from a machine
+over some very thin strings, you want to cut down on the amount of data
+Gnus has to get from the @sc{nntp} server.
+
+@table @code
+
+@item gnus-read-active-file
+Set this to @code{nil}, which will inhibit Gnus from requesting the
+entire active file from the server. This file is often v. large. You
+also have to set @code{gnus-check-new-newsgroups} and
+@code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus
+doesn't suddenly decide to fetch the active file anyway.
+
+@item gnus-nov-is-evil
+This one has to be @code{nil}. If not, grabbing article headers from
+the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers
+support @sc{xover}; Gnus will detect this by itself.
+@end table
+
+
+@node Slow Terminal Connection
+@subsection Slow Terminal Connection
+
+Let's say you use your home computer for dialing up the system that runs
+Emacs and Gnus. If your modem is slow, you want to reduce (as much as
+possible) the amount of data sent over the wires.
+
+@table @code
+
+@item gnus-auto-center-summary
+Set this to @code{nil} to inhibit Gnus from re-centering the summary
+buffer all the time. If it is @code{vertical}, do only vertical
+re-centering. If it is neither @code{nil} nor @code{vertical}, do both
+horizontal and vertical recentering.
+
+@item gnus-visible-headers
+Cut down on the headers included in the articles to the
+minimum. You can, in fact, make do without them altogether---most of the
+useful data is in the summary buffer, anyway. Set this variable to
+@samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need.
+
+@item gnus-article-display-hook
+Set this hook to all the available hiding commands:
+@lisp
+(setq gnus-article-display-hook
+ '(gnus-article-hide-headers
+ gnus-article-hide-signature
+ gnus-article-hide-citation))
+@end lisp
+
+@item gnus-use-full-window
+By setting this to @code{nil}, you can make all the windows smaller.
+While this doesn't really cut down much generally, it means that you
+have to see smaller portions of articles before deciding that you didn't
+want to read them anyway.
+
+@item gnus-thread-hide-subtree
+If this is non-@code{nil}, all threads in the summary buffer will be
+hidden initially.
+
+@item gnus-updated-mode-lines
+If this is @code{nil}, Gnus will not put information in the buffer mode
+lines, which might save some time.
+@end table
+
+
+@node Little Disk Space
+@subsection Little Disk Space
+@cindex disk space
+
+The startup files can get rather large, so you may want to cut their
+sizes a bit if you are running out of space.
+
+@table @code
+
+@item gnus-save-newsrc-file
+If this is @code{nil}, Gnus will never save @file{.newsrc}---it will
+only save @file{.newsrc.eld}. This means that you will not be able to
+use any other newsreaders than Gnus. This variable is @code{t} by
+default.
+
+@item gnus-save-killed-list
+If this is @code{nil}, Gnus will not save the list of dead groups. You
+should also set @code{gnus-check-new-newsgroups} to @code{ask-server}
+and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this
+variable to @code{nil}. This variable is @code{t} by default.
+
+@end table
+
+
+@node Slow Machine
+@subsection Slow Machine
+@cindex slow machine
+
+If you have a slow machine, or are just really impatient, there are a
+few things you can do to make Gnus run faster.
+
+Set @code{gnus-check-new-newsgroups} and
+@code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
+
+Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
+@code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
+summary buffer faster.
+
+Set @code{gnus-article-display-hook} to @code{nil} to make article
+processing a bit faster.
+
+
+@page
+@node Troubleshooting
+@section Troubleshooting
+@cindex troubleshooting
+
+Gnus works @emph{so} well straight out of the box---I can't imagine any
+problems, really.
+
+Ahem.
+
+@enumerate
+
+@item
+Make sure your computer is switched on.
+
+@item
+Make sure that you really load the current Gnus version. If you have
+been running @sc{gnus}, you need to exit Emacs and start it up again before
+Gnus will work.
+
+@item
+Try doing an @kbd{M-x gnus-version}. If you get something that looks
+like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
+on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
+flee}, you have some old @file{.el} files lying around. Delete these.
+
+@item
+Read the help group (@kbd{G h} in the group buffer) for a FAQ and a
+how-to.
+
+@item
+@vindex max-lisp-eval-depth
+Gnus works on many recursive structures, and in some extreme (and very
+rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at
+you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or
+something like that.
+@end enumerate
+
+If all else fails, report the problem as a bug.
+
+@cindex bugs
+@cindex reporting bugs
+
+@kindex M-x gnus-bug
+@findex gnus-bug
+If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug}
+command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send
+me the backtrace. I will fix bugs, but I can only fix them if you send
+me a precise description as to how to reproduce the bug.
+
+You really can never be too detailed in a bug report. Always use the
+@kbd{M-x gnus-bug} command when you make bug reports, even if it creates
+a 10Kb mail each time you use it, and even if you have sent me your
+environment 500 times before. I don't care. I want the full info each
+time.
+
+It is also important to remember that I have no memory whatsoever. If
+you send a bug report, and I send you a reply, and then you just send
+back ``No, it's not! Moron!'', I will have no idea what you are
+insulting me about. Always over-explain everything. It's much easier
+for all of us---if I don't have all the information I need, I will just
+mail you and ask for more info, and everything takes more time.
+
+If the problem you're seeing is very visual, and you can't quite explain
+it, copy the Emacs window to a file (with @code{xwd}, for instance), put
+it somewhere it can be reached, and include the URL of the picture in
+the bug report.
+
+If you just need help, you are better off asking on
+@samp{gnu.emacs.gnus}. I'm not very helpful.
+
+@cindex gnu.emacs.gnus
+@cindex ding mailing list
+You can also ask on the ding mailing list---@samp{ding@@gnus.org}.
+Write to @samp{ding-request@@gnus.org} to subscribe.
+
+
+@page
+@node A Programmers Guide to Gnus
+@section A Programmer@'s Guide to Gnus
+
+It is my hope that other people will figure out smart stuff that Gnus
+can do, and that other people will write those smart things as well. To
+facilitate that I thought it would be a good idea to describe the inner
+workings of Gnus. And some of the not-so-inner workings, while I'm at
+it.
+
+You can never expect the internals of a program not to change, but I
+will be defining (in some details) the interface between Gnus and its
+backends (this is written in stone), the format of the score files
+(ditto), data structures (some are less likely to change than others)
+and general methods of operation.
+
+@menu
+* Gnus Utility Functions:: Common functions and variable to use.
+* Backend Interface:: How Gnus communicates with the servers.
+* Score File Syntax:: A BNF definition of the score file standard.
+* Headers:: How Gnus stores headers internally.
+* Ranges:: A handy format for storing mucho numbers.
+* Group Info:: The group info format.
+* Extended Interactive:: Symbolic prefixes and stuff.
+* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen.
+* Various File Formats:: Formats of files that Gnus use.
+@end menu
+
+
+@node Gnus Utility Functions
+@subsection Gnus Utility Functions
+@cindex Gnus utility functions
+@cindex utility functions
+@cindex functions
+@cindex internal variables
+
+When writing small functions to be run from hooks (and stuff), it's
+vital to have access to the Gnus internal functions and variables.
+Below is a list of the most common ones.
+
+@table @code
+
+@item gnus-newsgroup-name
+@vindex gnus-newsgroup-name
+This variable holds the name of the current newsgroup.
+
+@item gnus-find-method-for-group
+@findex gnus-find-method-for-group
+A function that returns the select method for @var{group}.
+
+@item gnus-group-real-name
+@findex gnus-group-real-name
+Takes a full (prefixed) Gnus group name, and returns the unprefixed
+name.
+
+@item gnus-group-prefixed-name
+@findex gnus-group-prefixed-name
+Takes an unprefixed group name and a select method, and returns the full
+(prefixed) Gnus group name.
+
+@item gnus-get-info
+@findex gnus-get-info
+Returns the group info list for @var{group}.
+
+@item gnus-group-unread
+@findex gnus-group-unread
+The number of unread articles in @var{group}, or @code{t} if that is
+unknown.
+
+@item gnus-active
+@findex gnus-active
+The active entry for @var{group}.
+
+@item gnus-set-active
+@findex gnus-set-active
+Set the active entry for @var{group}.
+
+@item gnus-add-current-to-buffer-list
+@findex gnus-add-current-to-buffer-list
+Adds the current buffer to the list of buffers to be killed on Gnus
+exit.
+
+@item gnus-continuum-version
+@findex gnus-continuum-version
+Takes a Gnus version string as a parameter and returns a floating point
+number. Earlier versions will always get a lower number than later
+versions.
+
+@item gnus-group-read-only-p
+@findex gnus-group-read-only-p
+Says whether @var{group} is read-only or not.
+
+@item gnus-news-group-p
+@findex gnus-news-group-p
+Says whether @var{group} came from a news backend.
+
+@item gnus-ephemeral-group-p
+@findex gnus-ephemeral-group-p
+Says whether @var{group} is ephemeral or not.
+
+@item gnus-server-to-method
+@findex gnus-server-to-method
+Returns the select method corresponding to @var{server}.
+
+@item gnus-server-equal
+@findex gnus-server-equal
+Says whether two virtual servers are equal.
+
+@item gnus-group-native-p
+@findex gnus-group-native-p
+Says whether @var{group} is native or not.
+
+@item gnus-group-secondary-p
+@findex gnus-group-secondary-p
+Says whether @var{group} is secondary or not.
+
+@item gnus-group-foreign-p
+@findex gnus-group-foreign-p
+Says whether @var{group} is foreign or not.
+
+@item group-group-find-parameter
+@findex group-group-find-parameter
+Returns the parameter list of @var{group}. If given a second parameter,
+returns the value of that parameter for @var{group}.
+
+@item gnus-group-set-parameter
+@findex gnus-group-set-parameter
+Takes three parameters; @var{group}, @var{parameter} and @var{value}.
+
+@item gnus-narrow-to-body
+@findex gnus-narrow-to-body
+Narrows the current buffer to the body of the article.
+
+@item gnus-check-backend-function
+@findex gnus-check-backend-function
+Takes two parameters, @var{function} and @var{group}. If the backend
+@var{group} comes from supports @var{function}, return non-@code{nil}.
+
+@lisp
+(gnus-check-backend-function "request-scan" "nnml:misc")
+=> t
+@end lisp
+
+@item gnus-read-method
+@findex gnus-read-method
+Prompts the user for a select method.
+
+@end table
+
+
+@node Backend Interface
+@subsection Backend Interface
+
+Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual
+groups. It only knows how to talk to @dfn{virtual servers}. A virtual
+server is a @dfn{backend} and some @dfn{backend variables}. As examples
+of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As
+examples of the latter we have @code{nntp-port-number} and
+@code{nnmbox-directory}.
+
+When Gnus asks for information from a backend---say @code{nntp}---on
+something, it will normally include a virtual server name in the
+function parameters. (If not, the backend should use the ``current''
+virtual server.) For instance, @code{nntp-request-list} takes a virtual
+server as its only (optional) parameter. If this virtual server hasn't
+been opened, the function should fail.
+
+Note that a virtual server name has no relation to some physical server
+name. Take this example:
+
+@lisp
+(nntp "odd-one"
+ (nntp-address "ifi.uio.no")
+ (nntp-port-number 4324))
+@end lisp
+
+Here the virtual server name is @samp{odd-one} while the name of
+the physical server is @samp{ifi.uio.no}.
+
+The backends should be able to switch between several virtual servers.
+The standard backends implement this by keeping an alist of virtual
+server environments that they pull down/push up when needed.
+
+There are two groups of interface functions: @dfn{required functions},
+which must be present, and @dfn{optional functions}, which Gnus will
+always check for presence before attempting to call 'em.
+
+All these functions are expected to return data in the buffer
+@code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat
+unfortunately named, but we'll have to live with it. When I talk about
+@dfn{resulting data}, I always refer to the data in that buffer. When I
+talk about @dfn{return value}, I talk about the function value returned by
+the function call. Functions that fail should return @code{nil} as the
+return value.
+
+Some backends could be said to be @dfn{server-forming} backends, and
+some might be said not to be. The latter are backends that generally
+only operate on one group at a time, and have no concept of ``server''
+-- they have a group, and they deliver info on that group and nothing
+more.
+
+In the examples and definitions I will refer to the imaginary backend
+@code{nnchoke}.
+
+@cindex @code{nnchoke}
+
+@menu
+* Required Backend Functions:: Functions that must be implemented.
+* Optional Backend Functions:: Functions that need not be implemented.
+* Error Messaging:: How to get messages and report errors.
+* Writing New Backends:: Extending old backends.
+* Hooking New Backends Into Gnus:: What has to be done on the Gnus end.
+* Mail-like Backends:: Some tips on mail backends.
+@end menu
+
+
+@node Required Backend Functions
+@subsubsection Required Backend Functions
+
+@table @code
+
+@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
+
+@var{articles} is either a range of article numbers or a list of
+@code{Message-ID}s. Current backends do not fully support either---only
+sequences (lists) of article numbers, and most backends do not support
+retrieval of @code{Message-ID}s. But they should try for both.
+
+The result data should either be HEADs or NOV lines, and the result
+value should either be @code{headers} or @code{nov} to reflect this.
+This might later be expanded to @code{various}, which will be a mixture
+of HEADs and NOV lines, but this is currently not supported by Gnus.
+
+If @var{fetch-old} is non-@code{nil} it says to try fetching "extra
+headers", in some meaning of the word. This is generally done by
+fetching (at most) @var{fetch-old} extra headers less than the smallest
+article number in @code{articles}, and filling the gaps as well. The
+presence of this parameter can be ignored if the backend finds it
+cumbersome to follow the request. If this is non-@code{nil} and not a
+number, do maximum fetches.
+
+Here's an example HEAD:
+
+@example
+221 1056 Article retrieved.
+Path: ifi.uio.no!sturles
+From: sturles@@ifi.uio.no (Sturle Sunde)
+Newsgroups: ifi.discussion
+Subject: Re: Something very droll
+Date: 27 Oct 1994 14:02:57 +0100
+Organization: Dept. of Informatics, University of Oslo, Norway
+Lines: 26
+Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no>
+References: <38jdmq$4qu@@visbur.ifi.uio.no>
+NNTP-Posting-Host: holmenkollen.ifi.uio.no
+.
+@end example
+
+So a @code{headers} return value would imply that there's a number of
+these in the data buffer.
+
+Here's a BNF definition of such a buffer:
+
+@example
+headers = *head
+head = error / valid-head
+error-message = [ "4" / "5" ] 2number " " <error message> eol
+valid-head = valid-message *header "." eol
+valid-message = "221 " <number> " Article retrieved." eol
+header = <text> eol
+@end example
+
+If the return value is @code{nov}, the data buffer should contain
+@dfn{network overview database} lines. These are basically fields
+separated by tabs.
+
+@example
+nov-buffer = *nov-line
+nov-line = 8*9 [ field <TAB> ] eol
+field = <text except TAB>
+@end example
+
+For a closer look at what should be in those fields,
+@pxref{Headers}.
+
+
+@item (nnchoke-open-server SERVER &optional DEFINITIONS)
+
+@var{server} is here the virtual server name. @var{definitions} is a
+list of @code{(VARIABLE VALUE)} pairs that define this virtual server.
+
+If the server can't be opened, no error should be signaled. The backend
+may then choose to refuse further attempts at connecting to this
+server. In fact, it should do so.
+
+If the server is opened already, this function should return a
+non-@code{nil} value. There should be no data returned.
+
+
+@item (nnchoke-close-server &optional SERVER)
+
+Close connection to @var{server} and free all resources connected
+to it. Return @code{nil} if the server couldn't be closed for some
+reason.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-close)
+
+Close connection to all servers and free all resources that the backend
+have reserved. All buffers that have been created by that backend
+should be killed. (Not the @code{nntp-server-buffer}, though.) This
+function is generally only called when Gnus is shutting down.
+
+There should be no data returned.
+
+
+@item (nnchoke-server-opened &optional SERVER)
+
+If @var{server} is the current virtual server, and the connection to the
+physical server is alive, then this function should return a
+non-@code{nil} vlue. This function should under no circumstances
+attempt to reconnect to a server we have lost connection to.
+
+There should be no data returned.
+
+
+@item (nnchoke-status-message &optional SERVER)
+
+This function should return the last error message from @var{server}.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
+
+The result data from this function should be the article specified by
+@var{article}. This might either be a @code{Message-ID} or a number.
+It is optional whether to implement retrieval by @code{Message-ID}, but
+it would be nice if that were possible.
+
+If @var{to-buffer} is non-@code{nil}, the result data should be returned
+in this buffer instead of the normal data buffer. This is to make it
+possible to avoid copying large amounts of data from one buffer to
+another, while Gnus mainly requests articles to be inserted directly
+into its article buffer.
+
+If it is at all possible, this function should return a cons cell where
+the @code{car} is the group name the article was fetched from, and the @code{cdr} is
+the article number. This will enable Gnus to find out what the real
+group and article numbers are when fetching articles by
+@code{Message-ID}. If this isn't possible, @code{t} should be returned
+on successful article retrieval.
+
+
+@item (nnchoke-request-group GROUP &optional SERVER FAST)
+
+Get data on @var{group}. This function also has the side effect of
+making @var{group} the current group.
+
+If @var{FAST}, don't bother to return useful data, just make @var{group}
+the current group.
+
+Here's an example of some result data and a definition of the same:
+
+@example
+211 56 1000 1059 ifi.discussion
+@end example
+
+The first number is the status, which should be 211. Next is the
+total number of articles in the group, the lowest article number, the
+highest article number, and finally the group name. Note that the total
+number of articles may be less than one might think while just
+considering the highest and lowest article numbers, but some articles
+may have been canceled. Gnus just discards the total-number, so
+whether one should take the bother to generate it properly (if that is a
+problem) is left as an exercise to the reader.
+
+@example
+group-status = [ error / info ] eol
+error = [ "4" / "5" ] 2<number> " " <Error message>
+info = "211 " 3* [ <number> " " ] <string>
+@end example
+
+
+@item (nnchoke-close-group GROUP &optional SERVER)
+
+Close @var{group} and free any resources connected to it. This will be
+a no-op on most backends.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-list &optional SERVER)
+
+Return a list of all groups available on @var{server}. And that means
+@emph{all}.
+
+Here's an example from a server that only carries two groups:
+
+@example
+ifi.test 0000002200 0000002000 y
+ifi.discussion 3324 3300 n
+@end example
+
+On each line we have a group name, then the highest article number in
+that group, the lowest article number, and finally a flag.
+
+@example
+active-file = *active-line
+active-line = name " " <number> " " <number> " " flags eol
+name = <string>
+flags = "n" / "y" / "m" / "x" / "j" / "=" name
+@end example
+
+The flag says whether the group is read-only (@samp{n}), is moderated
+(@samp{m}), is dead (@samp{x}), is aliased to some other group
+(@samp{=other-group}) or none of the above (@samp{y}).
+
+
+@item (nnchoke-request-post &optional SERVER)
+
+This function should post the current buffer. It might return whether
+the posting was successful or not, but that's not required. If, for
+instance, the posting is done asynchronously, it has generally not been
+completed by the time this function concludes. In that case, this
+function should set up some kind of sentinel to beep the user loud and
+clear if the posting could not be completed.
+
+There should be no result data from this function.
+
+@end table
+
+
+@node Optional Backend Functions
+@subsubsection Optional Backend Functions
+
+@table @code
+
+@item (nnchoke-retrieve-groups GROUPS &optional SERVER)
+
+@var{groups} is a list of groups, and this function should request data
+on all those groups. How it does it is of no concern to Gnus, but it
+should attempt to do this in a speedy fashion.
+
+The return value of this function can be either @code{active} or
+@code{group}, which says what the format of the result data is. The
+former is in the same format as the data from
+@code{nnchoke-request-list}, while the latter is a buffer full of lines
+in the same format as @code{nnchoke-request-group} gives.
+
+@example
+group-buffer = *active-line / *group-status
+@end example
+
+
+@item (nnchoke-request-update-info GROUP INFO &optional SERVER)
+
+A Gnus group info (@pxref{Group Info}) is handed to the backend for
+alterations. This comes in handy if the backend really carries all the
+information (as is the case with virtual and imap groups). This
+function should destructively alter the info to suit its needs, and
+should return the (altered) group info.
+
+There should be no result data from this function.
+
+
+@item (nnchoke-request-type GROUP &optional ARTICLE)
+
+When the user issues commands for ``sending news'' (@kbd{F} in the
+summary buffer, for instance), Gnus has to know whether the article the
+user is following up on is news or mail. This function should return
+@code{news} if @var{article} in @var{group} is news, @code{mail} if it
+is mail and @code{unknown} if the type can't be decided. (The
+@var{article} parameter is necessary in @code{nnvirtual} groups which
+might very well combine mail groups and news groups.) Both @var{group}
+and @var{article} may be @code{nil}.
+
+There should be no result data from this function.
+
+
+@item (nnchoke-request-update-mark GROUP ARTICLE MARK)
+
+If the user tries to set a mark that the backend doesn't like, this
+function may change the mark. Gnus will use whatever this function
+returns as the mark for @var{article} instead of the original
+@var{mark}. If the backend doesn't care, it must return the original
+@var{mark}, and not @code{nil} or any other type of garbage.
+
+The only use for this I can see is what @code{nnvirtual} does with
+it---if a component group is auto-expirable, marking an article as read
+in the virtual group should result in the article being marked as
+expirable.
+
+There should be no result data from this function.
+
+
+@item (nnchoke-request-scan &optional GROUP SERVER)
+
+This function may be called at any time (by Gnus or anything else) to
+request that the backend check for incoming articles, in one way or
+another. A mail backend will typically read the spool file or query the
+POP server when this function is invoked. The @var{group} doesn't have
+to be heeded---if the backend decides that it is too much work just
+scanning for a single group, it may do a total scan of all groups. It
+would be nice, however, to keep things local if that's practical.
+
+There should be no result data from this function.
+
+
+@item (nnchoke-request-group-description GROUP &optional SERVER)
+
+The result data from this function should be a description of
+@var{group}.
+
+@example
+description-line = name <TAB> description eol
+name = <string>
+description = <text>
+@end example
+
+@item (nnchoke-request-list-newsgroups &optional SERVER)
+
+The result data from this function should be the description of all
+groups available on the server.
+
+@example
+description-buffer = *description-line
+@end example
+
+
+@item (nnchoke-request-newgroups DATE &optional SERVER)
+
+The result data from this function should be all groups that were
+created after @samp{date}, which is in normal human-readable date
+format. The data should be in the active buffer format.
+
+
+@item (nnchoke-request-create-group GROUP &optional SERVER)
+
+This function should create an empty group with name @var{group}.
+
+There should be no return data.
+
+
+@item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
+
+This function should run the expiry process on all articles in the
+@var{articles} range (which is currently a simple list of article
+numbers.) It is left up to the backend to decide how old articles
+should be before they are removed by this function. If @var{force} is
+non-@code{nil}, all @var{articles} should be deleted, no matter how new
+they are.
+
+This function should return a list of articles that it did not/was not
+able to delete.
+
+There should be no result data returned.
+
+
+@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
+&optional LAST)
+
+This function should move @var{article} (which is a number) from
+@var{group} by calling @var{accept-form}.
+
+This function should ready the article in question for moving by
+removing any header lines it has added to the article, and generally
+should ``tidy up'' the article. Then it should @code{eval}
+@var{accept-form} in the buffer where the ``tidy'' article is. This
+will do the actual copying. If this @code{eval} returns a
+non-@code{nil} value, the article should be removed.
+
+If @var{last} is @code{nil}, that means that there is a high likelihood
+that there will be more requests issued shortly, so that allows some
+optimizations.
+
+The function should return a cons where the @code{car} is the group name and
+the @code{cdr} is the article number that the article was entered as.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-accept-article GROUP &optional SERVER LAST)
+
+This function takes the current buffer and inserts it into @var{group}.
+If @var{last} in @code{nil}, that means that there will be more calls to
+this function in short order.
+
+The function should return a cons where the @code{car} is the group name and
+the @code{cdr} is the article number that the article was entered as.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
+
+This function should remove @var{article} (which is a number) from
+@var{group} and insert @var{buffer} there instead.
+
+There should be no data returned.
+
+
+@item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
+
+This function should delete @var{group}. If @var{force}, it should
+really delete all the articles in the group, and then delete the group
+itself. (If there is such a thing as ``the group itself''.)
+
+There should be no data returned.
+
+
+@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
+
+This function should rename @var{group} into @var{new-name}. All
+articles in @var{group} should move to @var{new-name}.
+
+There should be no data returned.
+
+@end table
+
+
+@node Error Messaging
+@subsubsection Error Messaging
+
+@findex nnheader-report
+@findex nnheader-get-report
+The backends should use the function @code{nnheader-report} to report
+error conditions---they should not raise errors when they aren't able to
+perform a request. The first argument to this function is the backend
+symbol, and the rest are interpreted as arguments to @code{format} if
+there are multiple of them, or just a string if there is one of them.
+This function must always returns @code{nil}.
+
+@lisp
+(nnheader-report 'nnchoke "You did something totally bogus")
+
+(nnheader-report 'nnchoke "Could not request group %s" group)
+@end lisp
+
+Gnus, in turn, will call @code{nnheader-get-report} when it gets a
+@code{nil} back from a server, and this function returns the most
+recently reported message for the backend in question. This function
+takes one argument---the server symbol.
+
+Internally, these functions access @var{backend}@code{-status-string},
+so the @code{nnchoke} backend will have its error message stored in
+@code{nnchoke-status-string}.
+
+
+@node Writing New Backends
+@subsubsection Writing New Backends
+
+Many backends are quite similar. @code{nnml} is just like
+@code{nnspool}, but it allows you to edit the articles on the server.
+@code{nnmh} is just like @code{nnml}, but it doesn't use an active file,
+and it doesn't maintain overview databases. @code{nndir} is just like
+@code{nnml}, but it has no concept of ``groups'', and it doesn't allow
+editing articles.
+
+It would make sense if it were possible to ``inherit'' functions from
+backends when writing new backends. And, indeed, you can do that if you
+want to. (You don't have to if you don't want to, of course.)
+
+All the backends declare their public variables and functions by using a
+package called @code{nnoo}.
+
+To inherit functions from other backends (and allow other backends to
+inherit functions from the current backend), you should use the
+following macros:
+
+@table @code
+
+@item nnoo-declare
+This macro declares the first parameter to be a child of the subsequent
+parameters. For instance:
+
+@lisp
+(nnoo-declare nndir
+ nnml nnmh)
+@end lisp
+
+@code{nndir} has declared here that it intends to inherit functions from
+both @code{nnml} and @code{nnmh}.
+
+@item defvoo
+This macro is equivalent to @code{defvar}, but registers the variable as
+a public server variable. Most state-oriented variables should be
+declared with @code{defvoo} instead of @code{defvar}.
+
+In addition to the normal @code{defvar} parameters, it takes a list of
+variables in the parent backends to map the variable to when executing
+a function in those backends.
+
+@lisp
+(defvoo nndir-directory nil
+ "Where nndir will look for groups."
+ nnml-current-directory nnmh-current-directory)
+@end lisp
+
+This means that @code{nnml-current-directory} will be set to
+@code{nndir-directory} when an @code{nnml} function is called on behalf
+of @code{nndir}. (The same with @code{nnmh}.)
+
+@item nnoo-define-basics
+This macro defines some common functions that almost all backends should
+have.
+
+@example
+(nnoo-define-basics nndir)
+@end example
+
+@item deffoo
+This macro is just like @code{defun} and takes the same parameters. In
+addition to doing the normal @code{defun} things, it registers the
+function as being public so that other backends can inherit it.
+
+@item nnoo-map-functions
+This macro allows mapping of functions from the current backend to
+functions from the parent backends.
+
+@example
+(nnoo-map-functions nndir
+ (nnml-retrieve-headers 0 nndir-current-group 0 0)
+ (nnmh-request-article 0 nndir-current-group 0 0))
+@end example
+
+This means that when @code{nndir-retrieve-headers} is called, the first,
+third, and fourth parameters will be passed on to
+@code{nnml-retrieve-headers}, while the second parameter is set to the
+value of @code{nndir-current-group}.
+
+@item nnoo-import
+This macro allows importing functions from backends. It should be the
+last thing in the source file, since it will only define functions that
+haven't already been defined.
+
+@example
+(nnoo-import nndir
+ (nnmh
+ nnmh-request-list
+ nnmh-request-newgroups)
+ (nnml))
+@end example
+
+This means that calls to @code{nndir-request-list} should just be passed
+on to @code{nnmh-request-list}, while all public functions from
+@code{nnml} that haven't been defined in @code{nndir} yet should be
+defined now.
+
+@end table
+
+Below is a slightly shortened version of the @code{nndir} backend.
+
+@lisp
+;;; nndir.el --- single directory newsgroup access for Gnus
+;; Copyright (C) 1995,96 Free Software Foundation, Inc.
+
+;;; Code:
+
+(require 'nnheader)
+(require 'nnmh)
+(require 'nnml)
+(require 'nnoo)
+(eval-when-compile (require 'cl))
+
+(nnoo-declare nndir
+ nnml nnmh)
+
+(defvoo nndir-directory nil
+ "Where nndir will look for groups."
+ nnml-current-directory nnmh-current-directory)
+
+(defvoo nndir-nov-is-evil nil
+ "*Non-nil means that nndir will never retrieve NOV headers."
+ nnml-nov-is-evil)
+
+(defvoo nndir-current-group "" nil nnml-current-group nnmh-current-group)
+(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
+(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)
+
+(defvoo nndir-status-string "" nil nnmh-status-string)
+(defconst nndir-version "nndir 1.0")
+
+;;; Interface functions.
+
+(nnoo-define-basics nndir)
+
+(deffoo nndir-open-server (server &optional defs)
+ (setq nndir-directory
+ (or (cadr (assq 'nndir-directory defs))
+ server))
+ (unless (assq 'nndir-directory defs)
+ (push `(nndir-directory ,server) defs))
+ (push `(nndir-current-group
+ ,(file-name-nondirectory (directory-file-name nndir-directory)))
+ defs)
+ (push `(nndir-top-directory
+ ,(file-name-directory (directory-file-name nndir-directory)))
+ defs)
+ (nnoo-change-server 'nndir server defs))
+
+(nnoo-map-functions nndir
+ (nnml-retrieve-headers 0 nndir-current-group 0 0)
+ (nnmh-request-article 0 nndir-current-group 0 0)
+ (nnmh-request-group nndir-current-group 0 0)
+ (nnmh-close-group nndir-current-group 0))
+
+(nnoo-import nndir
+ (nnmh
+ nnmh-status-message
+ nnmh-request-list
+ nnmh-request-newgroups))
+
+(provide 'nndir)
+@end lisp
+
+
+@node Hooking New Backends Into Gnus
+@subsubsection Hooking New Backends Into Gnus
+
+@vindex gnus-valid-select-methods
+Having Gnus start using your new backend is rather easy---you just
+declare it with the @code{gnus-declare-backend} functions. This will
+enter the backend into the @code{gnus-valid-select-methods} variable.
+
+@code{gnus-declare-backend} takes two parameters---the backend name and
+an arbitrary number of @dfn{abilities}.
+
+Here's an example:
+
+@lisp
+(gnus-declare-backend "nnchoke" 'mail 'respool 'address)
+@end lisp
+
+The abilities can be:
+
+@table @code
+@item mail
+This is a mailish backend---followups should (probably) go via mail.
+@item post
+This is a newsish backend---followups should (probably) go via news.
+@item post-mail
+This backend supports both mail and news.
+@item none
+This is neither a post nor mail backend---it's something completely
+different.
+@item respool
+It supports respooling---or rather, it is able to modify its source
+articles and groups.
+@item address
+The name of the server should be in the virtual server name. This is
+true for almost all backends.
+@item prompt-address
+The user should be prompted for an address when doing commands like
+@kbd{B} in the group buffer. This is true for backends like
+@code{nntp}, but not @code{nnmbox}, for instance.
+@end table
+
+
+@node Mail-like Backends
+@subsubsection Mail-like Backends
+
+One of the things that separate the mail backends from the rest of the
+backends is the heavy dependence by the mail backends on common
+functions in @file{nnmail.el}. For instance, here's the definition of
+@code{nnml-request-scan}:
+
+@lisp
+(deffoo nnml-request-scan (&optional group server)
+ (setq nnml-article-file-alist nil)
+ (nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group))
+@end lisp
+
+It simply calls @code{nnmail-get-new-mail} with a few parameters,
+and @code{nnmail} takes care of all the moving and splitting of the
+mail.
+
+This function takes four parameters.
+
+@table @var
+@item method
+This should be a symbol to designate which backend is responsible for
+the call.
+
+@item exit-function
+This function should be called after the splitting has been performed.
+
+@item temp-directory
+Where the temporary files should be stored.
+
+@item group
+This optional argument should be a group name if the splitting is to be
+performed for one group only.
+@end table
+
+@code{nnmail-get-new-mail} will call @var{backend}@code{-save-mail} to
+save each article. @var{backend}@code{-active-number} will be called to
+find the article number assigned to this article.
+
+The function also uses the following variables:
+@var{backend}@code{-get-new-mail} (to see whether to get new mail for
+this backend); and @var{backend}@code{-group-alist} and
+@var{backend}@code{-active-file} to generate the new active file.
+@var{backend}@code{-group-alist} should be a group-active alist, like
+this:
+
+@example
+(("a-group" (1 . 10))
+ ("some-group" (34 . 39)))
+@end example
+
+
+@node Score File Syntax
+@subsection Score File Syntax
+
+Score files are meant to be easily parseable, but yet extremely
+mallable. It was decided that something that had the same read syntax
+as an Emacs Lisp list would fit that spec.
+
+Here's a typical score file:
+
+@lisp
+(("summary"
+ ("win95" -10000 nil s)
+ ("Gnus"))
+ ("from"
+ ("Lars" -1000))
+ (mark -100))
+@end lisp
+
+BNF definition of a score file:
+
+@example
+score-file = "" / "(" *element ")"
+element = rule / atom
+rule = string-rule / number-rule / date-rule
+string-rule = "(" quote string-header quote space *string-match ")"
+number-rule = "(" quote number-header quote space *number-match ")"
+date-rule = "(" quote date-header quote space *date-match ")"
+quote = <ascii 34>
+string-header = "subject" / "from" / "references" / "message-id" /
+ "xref" / "body" / "head" / "all" / "followup"
+number-header = "lines" / "chars"
+date-header = "date"
+string-match = "(" quote <string> quote [ "" / [ space score [ "" /
+ space date [ "" / [ space string-match-t ] ] ] ] ] ")"
+score = "nil" / <integer>
+date = "nil" / <natural number>
+string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
+ "r" / "regex" / "R" / "Regex" /
+ "e" / "exact" / "E" / "Exact" /
+ "f" / "fuzzy" / "F" / "Fuzzy"
+number-match = "(" <integer> [ "" / [ space score [ "" /
+ space date [ "" / [ space number-match-t ] ] ] ] ] ")"
+number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
+date-match = "(" quote <string> quote [ "" / [ space score [ "" /
+ space date [ "" / [ space date-match-t ] ] ] ] ")"
+date-match-t = "nil" / "at" / "before" / "after"
+atom = "(" [ required-atom / optional-atom ] ")"
+required-atom = mark / expunge / mark-and-expunge / files /
+ exclude-files / read-only / touched
+optional-atom = adapt / local / eval
+mark = "mark" space nil-or-number
+nil-or-number = "nil" / <integer>
+expunge = "expunge" space nil-or-number
+mark-and-expunge = "mark-and-expunge" space nil-or-number
+files = "files" *[ space <string> ]
+exclude-files = "exclude-files" *[ space <string> ]
+read-only = "read-only" [ space "nil" / space "t" ]
+adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ]
+adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
+local = "local" *[ space "(" <string> space <form> ")" ]
+eval = "eval" space <form>
+space = *[ " " / <TAB> / <NEWLINE> ]
+@end example
+
+Any unrecognized elements in a score file should be ignored, but not
+discarded.
+
+As you can see, white space is needed, but the type and amount of white
+space is irrelevant. This means that formatting of the score file is
+left up to the programmer---if it's simpler to just spew it all out on
+one looong line, then that's ok.
+
+The meaning of the various atoms are explained elsewhere in this
+manual (@pxref{Score File Format}).
+
+
+@node Headers
+@subsection Headers
+
+Internally Gnus uses a format for storing article headers that
+corresponds to the @sc{nov} format in a mysterious fashion. One could
+almost suspect that the author looked at the @sc{nov} specification and
+just shamelessly @emph{stole} the entire thing, and one would be right.
+
+@dfn{Header} is a severely overloaded term. ``Header'' is used in
+RFC1036 to talk about lines in the head of an article (e.g.,
+@code{From}). It is used by many people as a synonym for
+``head''---``the header and the body''. (That should be avoided, in my
+opinion.) And Gnus uses a format internally that it calls ``header'',
+which is what I'm talking about here. This is a 9-element vector,
+basically, with each header (ouch) having one slot.
+
+These slots are, in order: @code{number}, @code{subject}, @code{from},
+@code{date}, @code{id}, @code{references}, @code{chars}, @code{lines},
+@code{xref}. There are macros for accessing and setting these
+slots---they all have predictable names beginning with
+@code{mail-header-} and @code{mail-header-set-}, respectively.
+
+The @code{xref} slot is really a @code{misc} slot. Any extra info will
+be put in there.
+
+
+@node Ranges
+@subsection Ranges
+
+@sc{gnus} introduced a concept that I found so useful that I've started
+using it a lot and have elaborated on it greatly.
+
+The question is simple: If you have a large amount of objects that are
+identified by numbers (say, articles, to take a @emph{wild} example)
+that you want to qualify as being ``included'', a normal sequence isn't
+very useful. (A 200,000 length sequence is a bit long-winded.)
+
+The solution is as simple as the question: You just collapse the
+sequence.
+
+@example
+(1 2 3 4 5 6 10 11 12)
+@end example
+
+is transformed into
+
+@example
+((1 . 6) (10 . 12))
+@end example
+
+To avoid having those nasty @samp{(13 . 13)} elements to denote a
+lonesome object, a @samp{13} is a valid element:
+
+@example
+((1 . 6) 7 (10 . 12))
+@end example
+
+This means that comparing two ranges to find out whether they are equal
+is slightly tricky:
+
+@example
+((1 . 5) 7 8 (10 . 12))
+@end example
+
+and
+
+@example
+((1 . 5) (7 . 8) (10 . 12))
+@end example
+
+are equal. In fact, any non-descending list is a range:
+
+@example
+(1 2 3 4 5)
+@end example
+
+is a perfectly valid range, although a pretty long-winded one. This is
+also valid:
+
+@example
+(1 . 5)
+@end example
+
+and is equal to the previous range.
+
+Here's a BNF definition of ranges. Of course, one must remember the
+semantic requirement that the numbers are non-descending. (Any number
+of repetition of the same number is allowed, but apt to disappear in
+range handling.)
+
+@example
+range = simple-range / normal-range
+simple-range = "(" number " . " number ")"
+normal-range = "(" start-contents ")"
+contents = "" / simple-range *[ " " contents ] /
+ number *[ " " contents ]
+@end example
+
+Gnus currently uses ranges to keep track of read articles and article
+marks. I plan on implementing a number of range operators in C if The
+Powers That Be are willing to let me. (I haven't asked yet, because I
+need to do some more thinking on what operators I need to make life
+totally range-based without ever having to convert back to normal
+sequences.)
+
+
+@node Group Info
+@subsection Group Info
+
+Gnus stores all permanent info on groups in a @dfn{group info} list.
+This list is from three to six elements (or more) long and exhaustively
+describes the group.
+
+Here are two example group infos; one is a very simple group while the
+second is a more complex one:
+
+@example
+("no.group" 5 (1 . 54324))
+
+("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
+ ((tick (15 . 19)) (replied 3 6 (19 . 3)))
+ (nnml "")
+ ((auto-expire . t) (to-address . "ding@@gnus.org")))
+@end example
+
+The first element is the @dfn{group name}---as Gnus knows the group,
+anyway. The second element is the @dfn{subscription level}, which
+normally is a small integer. (It can also be the @dfn{rank}, which is a
+cons cell where the @code{car} is the level and the @code{cdr} is the
+score.) The third element is a list of ranges of read articles. The
+fourth element is a list of lists of article marks of various kinds.
+The fifth element is the select method (or virtual server, if you like).
+The sixth element is a list of @dfn{group parameters}, which is what
+this section is about.
+
+Any of the last three elements may be missing if they are not required.
+In fact, the vast majority of groups will normally only have the first
+three elements, which saves quite a lot of cons cells.
+
+Here's a BNF definition of the group info format:
+
+@example
+info = "(" group space ralevel space read
+ [ "" / [ space marks-list [ "" / [ space method [ "" /
+ space parameters ] ] ] ] ] ")"
+group = quote <string> quote
+ralevel = rank / level
+level = <integer in the range of 1 to inf>
+rank = "(" level "." score ")"
+score = <integer in the range of 1 to inf>
+read = range
+marks-lists = nil / "(" *marks ")"
+marks = "(" <string> range ")"
+method = "(" <string> *elisp-forms ")"
+parameters = "(" *elisp-forms ")"
+@end example
+
+Actually that @samp{marks} rule is a fib. A @samp{marks} is a
+@samp{<string>} consed on to a @samp{range}, but that's a bitch to say
+in pseudo-BNF.
+
+If you have a Gnus info and want to access the elements, Gnus offers a
+series of macros for getting/setting these elements.
+
+@table @code
+@item gnus-info-group
+@itemx gnus-info-set-group
+@findex gnus-info-group
+@findex gnus-info-set-group
+Get/set the group name.
+
+@item gnus-info-rank
+@itemx gnus-info-set-rank
+@findex gnus-info-rank
+@findex gnus-info-set-rank
+Get/set the group rank (@pxref{Group Score}).
+
+@item gnus-info-level
+@itemx gnus-info-set-level
+@findex gnus-info-level
+@findex gnus-info-set-level
+Get/set the group level.
+
+@item gnus-info-score
+@itemx gnus-info-set-score
+@findex gnus-info-score
+@findex gnus-info-set-score
+Get/set the group score (@pxref{Group Score}).
+
+@item gnus-info-read
+@itemx gnus-info-set-read
+@findex gnus-info-read
+@findex gnus-info-set-read
+Get/set the ranges of read articles.
+
+@item gnus-info-marks
+@itemx gnus-info-set-marks
+@findex gnus-info-marks
+@findex gnus-info-set-marks
+Get/set the lists of ranges of marked articles.
+
+@item gnus-info-method
+@itemx gnus-info-set-method
+@findex gnus-info-method
+@findex gnus-info-set-method
+Get/set the group select method.
+
+@item gnus-info-params
+@itemx gnus-info-set-params
+@findex gnus-info-params
+@findex gnus-info-set-params
+Get/set the group parameters.
+@end table
+
+All the getter functions take one parameter---the info list. The setter
+functions take two parameters---the info list and the new value.
+
+The last three elements in the group info aren't mandatory, so it may be
+necessary to extend the group info before setting the element. If this
+is necessary, you can just pass on a non-@code{nil} third parameter to
+the three final setter functions to have this happen automatically.
+
+
+@node Extended Interactive
+@subsection Extended Interactive
+@cindex interactive
+@findex gnus-interactive
+
+Gnus extends the standard Emacs @code{interactive} specification
+slightly to allow easy use of the symbolic prefix (@pxref{Symbolic
+Prefixes}). Here's an example of how this is used:
+
+@lisp
+(defun gnus-summary-increase-score (&optional score symp)
+ (interactive (gnus-interactive "P\ny"))
+ ...
+ )
+@end lisp
+
+The best thing to do would have been to implement
+@code{gnus-interactive} as a macro which would have returned an
+@code{interactive} form, but this isn't possible since Emacs checks
+whether a function is interactive or not by simply doing an @code{assq}
+on the lambda form. So, instead we have @code{gnus-interactive}
+function that takes a string and returns values that are usable to
+@code{interactive}.
+
+This function accepts (almost) all normal @code{interactive} specs, but
+adds a few more.
+
+@table @samp
+@item y
+@vindex gnus-current-prefix-symbol
+The current symbolic prefix---the @code{gnus-current-prefix-symbol}
+variable.
+
+@item Y
+@vindex gnus-current-prefix-symbols
+A list of the current symbolic prefixes---the
+@code{gnus-current-prefix-symbol} variable.
+
+@item A
+The current article number---the @code{gnus-summary-article-number}
+function.
+
+@item H
+The current article header---the @code{gnus-summary-article-header}
+function.
+
+@item g
+The current group name---the @code{gnus-group-group-name}
+function.
+
+@end table
+
+
+@node Emacs/XEmacs Code
+@subsection Emacs/XEmacs Code
+@cindex XEmacs
+@cindex Emacsen
+
+While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the
+platforms must be the primary one. I chose Emacs. Not because I don't
+like XEmacs or Mule, but because it comes first alphabetically.
+
+This means that Gnus will byte-compile under Emacs with nary a warning,
+while XEmacs will pump out gigabytes of warnings while byte-compiling.
+As I use byte-compilation warnings to help me root out trivial errors in
+Gnus, that's very useful.
+
+I've also consistently used Emacs function interfaces, but have used
+Gnusey aliases for the functions. To take an example: Emacs defines a
+@code{run-at-time} function while XEmacs defines a @code{start-itimer}
+function. I then define a function called @code{gnus-run-at-time} that
+takes the same parameters as the Emacs @code{run-at-time}. When running
+Gnus under Emacs, the former function is just an alias for the latter.
+However, when running under XEmacs, the former is an alias for the
+following function:
+
+@lisp
+(defun gnus-xmas-run-at-time (time repeat function &rest args)
+ (start-itimer
+ "gnus-run-at-time"
+ `(lambda ()
+ (,function ,@@args))
+ time repeat))
+@end lisp
+
+This sort of thing has been done for bunches of functions. Gnus does
+not redefine any native Emacs functions while running under XEmacs---it
+does this @code{defalias} thing with Gnus equivalents instead. Cleaner
+all over.
+
+In the cases where the XEmacs function interface was obviously cleaner,
+I used it instead. For example @code{gnus-region-active-p} is an alias
+for @code{region-active-p} in XEmacs, whereas in Emacs it is a function.
+
+Of course, I could have chosen XEmacs as my native platform and done
+mapping functions the other way around. But I didn't. The performance
+hit these indirections impose on Gnus under XEmacs should be slight.
+
+
+@node Various File Formats
+@subsection Various File Formats
+
+@menu
+* Active File Format:: Information on articles and groups available.
+* Newsgroups File Format:: Group descriptions.
+@end menu
+
+
+@node Active File Format
+@subsubsection Active File Format
+
+The active file lists all groups available on the server in
+question. It also lists the highest and lowest current article numbers
+in each group.
+
+Here's an excerpt from a typical active file:
+
+@example
+soc.motss 296030 293865 y
+alt.binaries.pictures.fractals 3922 3913 n
+comp.sources.unix 1605 1593 m
+comp.binaries.ibm.pc 5097 5089 y
+no.general 1000 900 y
+@end example
+
+Here's a pseudo-BNF definition of this file:
+
+@example
+active = *group-line
+group-line = group space high-number space low-number space flag <NEWLINE>
+group = <non-white-space string>
+space = " "
+high-number = <non-negative integer>
+low-number = <positive integer>
+flag = "y" / "n" / "m" / "j" / "x" / "=" group
+@end example
+
+For a full description of this file, see the manual pages for
+@samp{innd}, in particular @samp{active(5)}.
+
+
+@node Newsgroups File Format
+@subsubsection Newsgroups File Format
+
+The newsgroups file lists groups along with their descriptions. Not all
+groups on the server have to be listed, and not all groups in the file
+have to exist on the server. The file is meant purely as information to
+the user.
+
+The format is quite simple; a group name, a tab, and the description.
+Here's the definition:
+
+@example
+newsgroups = *line
+line = group tab description <NEWLINE>
+group = <non-white-space string>
+tab = <TAB>
+description = <string>
+@end example
+
+
+@page
+@node Emacs for Heathens
+@section Emacs for Heathens
+
+Believe it or not, but some people who use Gnus haven't really used
+Emacs much before they embarked on their journey on the Gnus Love Boat.
+If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the
+region'', and ``set @code{gnus-flargblossen} to an alist where the key
+is a regexp that is used for matching on the group name'' are magical
+phrases with little or no meaning, then this appendix is for you. If
+you are already familiar with Emacs, just ignore this and go fondle your
+cat instead.
+
+@menu
+* Keystrokes:: Entering text and executing commands.
+* Emacs Lisp:: The built-in Emacs programming language.
+@end menu
+
+
+@node Keystrokes
+@subsection Keystrokes
+
+@itemize @bullet
+@item
+Q: What is an experienced Emacs user?
+
+@item
+A: A person who wishes that the terminal had pedals.
+@end itemize
+
+Yes, when you use Emacs, you are apt to use the control key, the shift
+key and the meta key a lot. This is very annoying to some people
+(notably @code{vi}le users), and the rest of us just love the hell out
+of it. Just give up and submit. Emacs really does stand for
+``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you
+may have heard from other disreputable sources (like the Emacs author).
+
+The shift keys are normally located near your pinky fingers, and are
+normally used to get capital letters and stuff. You probably use it all
+the time. The control key is normally marked ``CTRL'' or something like
+that. The meta key is, funnily enough, never marked as such on any
+keyboard. The one I'm currently at has a key that's marked ``Alt'',
+which is the meta key on this keyboard. It's usually located somewhere
+to the left hand side of the keyboard, usually on the bottom row.
+
+Now, us Emacs people don't say ``press the meta-control-m key'',
+because that's just too inconvenient. We say ``press the @kbd{M-C-m}
+key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the
+prefix that means ``control''. So ``press @kbd{C-k}'' means ``press
+down the control key, and hold it down while you press @kbd{k}''.
+``Press @kbd{M-C-k}'' means ``press down and hold down the meta key and
+the control key and then press @kbd{k}''. Simple, ay?
+
+This is somewhat complicated by the fact that not all keyboards have a
+meta key. In that case you can use the ``escape'' key. Then @kbd{M-k}
+means ``press escape, release escape, press @kbd{k}''. That's much more
+work than if you have a meta key, so if that's the case, I respectfully
+suggest you get a real keyboard with a meta key. You can't live without
+it.
+
+
+
+@node Emacs Lisp
+@subsection Emacs Lisp
+
+Emacs is the King of Editors because it's really a Lisp interpreter.
+Each and every key you tap runs some Emacs Lisp code snippet, and since
+Emacs Lisp is an interpreted language, that means that you can configure
+any key to run any arbitrary code. You just, like, do it.
+
+Gnus is written in Emacs Lisp, and is run as a bunch of interpreted
+functions. (These are byte-compiled for speed, but it's still
+interpreted.) If you decide that you don't like the way Gnus does
+certain things, it's trivial to have it do something a different way.
+(Well, at least if you know how to write Lisp code.) However, that's
+beyond the scope of this manual, so we are simply going to talk about
+some common constructs that you normally use in your @file{.emacs} file
+to customize Gnus.
+
+If you want to set the variable @code{gnus-florgbnize} to four (4), you
+write the following:
+
+@lisp
+(setq gnus-florgbnize 4)
+@end lisp
+
+This function (really ``special form'') @code{setq} is the one that can
+set a variable to some value. This is really all you need to know. Now
+you can go and fill your @code{.emacs} file with lots of these to change
+how Gnus works.
+
+If you have put that thing in your @code{.emacs} file, it will be read
+and @code{eval}ed (which is lisp-ese for ``run'') the next time you
+start Emacs. If you want to change the variable right away, simply say
+@kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the
+previous ``form'', which is a simple @code{setq} statement here.
+
+Go ahead---just try it, if you're located at your Emacs. After you
+@kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which
+is the return value of the form you @code{eval}ed.
+
+Some pitfalls:
+
+If the manual says ``set @code{gnus-read-active-file} to @code{some}'',
+that means:
+
+@lisp
+(setq gnus-read-active-file 'some)
+@end lisp
+
+On the other hand, if the manual says ``set @code{gnus-nntp-server} to
+@samp{nntp.ifi.uio.no}'', that means:
+
+@lisp
+(setq gnus-nntp-server "nntp.ifi.uio.no")
+@end lisp
+
+So be careful not to mix up strings (the latter) with symbols (the
+former). The manual is unambiguous, but it can be confusing.
+
+@page
+@include gnus-faq.texi
+
+@node Index
+@chapter Index
+@printindex cp
+
+@node Key Index
+@chapter Key Index
+@printindex ky
+
+@summarycontents
+@contents
+@bye
+
+
+@c End:
+
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Help, Mark, M-x, Top
+@chapter Help
+@kindex Help
+@cindex help
+@cindex self-documentation
+@findex help-command
+@kindex C-h
+@kindex F1
+
+ Emacs provides extensive help features accessible through a single
+character, @kbd{C-h}. @kbd{C-h} is a prefix key that is used only for
+documentation-printing commands. The characters that you can type after
+@kbd{C-h} are called @dfn{help options}. One help option is @kbd{C-h};
+that is how you ask for help about using @kbd{C-h}. To cancel, type
+@kbd{C-g}. The function key @key{F1} is equivalent to @kbd{C-h}.
+
+@kindex C-h C-h
+@findex help-for-help
+ @kbd{C-h C-h} (@code{help-for-help}) displays a list of the possible
+help options, each with a brief description. Before you type a help
+option, you can use @key{SPC} or @key{DEL} to scroll through the list.
+
+ @kbd{C-h} or @key{F1} means ``help'' in various other contexts as
+well. For example, in the middle of @code{query-replace}, it describes
+the options available for how to operate on the current match. After a
+prefix key, it displays a list of the alternatives that can follow the
+prefix key. (A few prefix keys don't support @kbd{C-h}, because they
+define other meanings for it, but they all support @key{F1}.)
+
+ Most help buffers use a special major mode, Help mode, which lets you
+scroll conveniently with @key{SPC} and @key{DEL}.
+
+@menu
+* Help Summary:: Brief list of all Help commands.
+* Key Help:: Asking what a key does in Emacs.
+* Name Help:: Asking about a command, variable or function name.
+* Apropos:: Asking what pertains to a given topic.
+* Library Keywords:: Finding Lisp libraries by keywords (topics).
+* Language Help:: Help relating to international language support.
+* Help Mode:: Special features of Help mode and Help buffers.
+* Misc Help:: Other help commands.
+@end menu
+
+@iftex
+@node Help Summary
+@end iftex
+@ifinfo
+@node Help Summary
+@section Help Summary
+@end ifinfo
+
+ Here is a summary of the defined help commands.
+
+@table @kbd
+@item C-h a @var{regexp} @key{RET}
+Display a list of commands whose names match @var{regexp}
+(@code{apropos-command}).
+@item C-h b
+Display a table of all key bindings in effect now, in this order: minor
+mode bindings, major mode bindings, and global bindings
+(@code{describe-bindings}).
+@item C-h c @var{key}
+Print the name of the command that @var{key} runs
+(@code{describe-key-briefly}). Here @kbd{c} stands for `character'. For more
+extensive information on @var{key}, use @kbd{C-h k}.
+@item C-h f @var{function} @key{RET}
+Display documentation on the Lisp function named @var{function}
+(@code{describe-function}). Since commands are Lisp functions,
+a command name may be used.
+@item C-h h
+Display the @file{hello} file, which shows examples of various character
+sets.
+@item C-h i
+Run Info, the program for browsing documentation files (@code{info}).
+The complete Emacs manual is available on-line in Info.
+@item C-h k @var{key}
+Display the name and documentation of the command that @var{key} runs
+(@code{describe-key}).
+@item C-h l
+Display a description of the last 100 characters you typed
+(@code{view-lossage}).
+@item C-h m
+Display documentation of the current major mode (@code{describe-mode}).
+@item C-h n
+Display documentation of Emacs changes, most recent first
+(@code{view-emacs-news}).
+@item C-h p
+Find packages by topic keyword (@code{finder-by-keyword}).
+@item C-h s
+Display current contents of the syntax table, plus an explanation of
+what they mean (@code{describe-syntax}). @xref{Syntax}.
+@item C-h t
+Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
+@item C-h v @var{var} @key{RET}
+Display the documentation of the Lisp variable @var{var}
+(@code{describe-variable}).
+@item C-h w @var{command} @key{RET}
+Print which keys run the command named @var{command} (@code{where-is}).
+@item C-h C @var{coding} @key{RET}
+Describe coding system @var{coding}
+(@code{describe-coding-system}).
+@item C-h C @key{RET}
+Describe the coding systems currently in use.
+@item C-h I @var{method} @key{RET}
+Describe an input method (@code{describe-input-method}).
+@item C-h L @var{language-env} @key{RET}
+Describe information on the character sets, coding systems and input
+methods used for language environment @var{language-env}
+(@code{describe-language-environment}).
+@item C-h C-c
+Display the copying conditions for GNU Emacs.
+@item C-h C-d
+Display information about getting new versions of GNU Emacs.
+@item C-h C-f @var{function} @key{RET}
+Enter Info and go to the node documenting the Emacs function @var{function}
+(@code{Info-goto-emacs-command-node}).
+@item C-h C-k @var{key}
+Enter Info and go to the node where the key sequence @var{key} is
+documented (@code{Info-goto-emacs-key-command-node}).
+@item C-h C-p
+Display information about the GNU Project.
+@item C-h @key{TAB} @var{symbol} @key{RET}
+Display the Info documentation on symbol @var{symbol} according to the
+programming language you are editing (@code{info-lookup-symbol}).
+@end table
+
+@node Key Help
+@section Documentation for a Key
+
+@kindex C-h c
+@findex describe-key-briefly
+ The most basic @kbd{C-h} options are @kbd{C-h c}
+(@code{describe-key-briefly}) and @w{@kbd{C-h k}} (@code{describe-key}).
+@kbd{C-h c @var{key}} prints in the echo area the name of the command
+that @var{key} is bound to. For example, @kbd{C-h c C-f} prints
+@samp{forward-char}. Since command names are chosen to describe what
+the commands do, this is a good way to get a very brief description of
+what @var{key} does.
+
+@kindex C-h k
+@findex describe-key
+ @kbd{C-h k @var{key}} is similar but gives more information: it
+displays the documentation string of the command as well as its name.
+This is too big for the echo area, so a window is used for the display.
+
+ @kbd{C-h c} and @kbd{C-h k} work for any sort of key sequences,
+including function keys and mouse events.
+
+@node Name Help
+@section Help by Command or Variable Name
+
+@kindex C-h f
+@findex describe-function
+ @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function
+using the minibuffer, then displays that function's documentation string
+in a window. Since commands are Lisp functions, you can use this to get
+the documentation of a command that you know by name. For example,
+
+@example
+C-h f auto-fill-mode @key{RET}
+@end example
+
+@noindent
+displays the documentation of @code{auto-fill-mode}. This is the only
+way to get the documentation of a command that is not bound to any key
+(one which you would normally run using @kbd{M-x}).
+
+ @kbd{C-h f} is also useful for Lisp functions that you are planning to
+use in a Lisp program. For example, if you have just written the
+expression @code{(make-vector len)} and want to check that you are using
+@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}.
+Because @kbd{C-h f} allows all function names, not just command names,
+you may find that some of your favorite abbreviations that work in
+@kbd{M-x} don't work in @kbd{C-h f}. An abbreviation may be unique
+among command names yet fail to be unique when other function names are
+allowed.
+
+ The function name for @kbd{C-h f} to describe has a default which is
+used if you type @key{RET} leaving the minibuffer empty. The default is
+the function called by the innermost Lisp expression in the buffer around
+point, @emph{provided} that is a valid, defined Lisp function name. For
+example, if point is located following the text @samp{(make-vector (car
+x)}, the innermost list containing point is the one that starts with
+@samp{(make-vector}, so the default is to describe the function
+@code{make-vector}.
+
+ @kbd{C-h f} is often useful just to verify that you have the right
+spelling for the function name. If @kbd{C-h f} mentions a name from the
+buffer as the default, that name must be defined as a Lisp function. If
+that is all you want to know, just type @kbd{C-g} to cancel the @kbd{C-h
+f} command, then go on editing.
+
+@kindex C-h w
+@findex where-is
+ @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to
+@var{command}. It prints a list of the keys in the echo area. If it
+says the command is not on any key, you must use @kbd{M-x} to run it.
+@kbd{C-h w} runs the command @code{where-is}.
+
+ @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes
+Lisp variables instead of Lisp functions. Its default is the Lisp symbol
+around or before point, but only if that is the name of a known Lisp
+variable. @xref{Variables}.@refill
+
+@node Apropos
+@section Apropos
+
+@kindex C-h a
+@findex apropos-command
+@cindex apropos
+ A more sophisticated sort of question to ask is, ``What are the
+commands for working with files?'' To ask this question, type @kbd{C-h
+a file @key{RET}}, which displays a list of all command names that
+contain @samp{file}, including @code{copy-file}, @code{find-file}, and
+so on. With each command name appears a brief description of how to use
+the command, and what keys you can currently invoke it with. For
+example, it would say that you can invoke @code{find-file} by typing
+@kbd{C-x C-f}. The @kbd{a} in @kbd{C-h a} stands for `Apropos';
+@kbd{C-h a} runs the command @code{apropos-command}. This command
+normally checks only commands (interactive functions); if you specify a
+prefix argument, it checks noninteractive functions as well.
+
+ Because @kbd{C-h a} looks only for functions whose names contain the
+string you specify, you must use ingenuity in choosing the
+string. If you are looking for commands for killing backwards and
+@kbd{C-h a kill-backwards @key{RET}} doesn't reveal any, don't give up.
+Try just @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}. Be
+persistent. Also note that you can use a regular expression as the
+argument, for more flexibility (@pxref{Regexps}).
+
+ Here is a set of arguments to give to @kbd{C-h a} that covers many
+classes of Emacs commands, since there are strong conventions for naming
+the standard Emacs commands. By giving you a feel for the naming
+conventions, this set should also serve to aid you in developing a
+technique for picking @code{apropos} strings.
+
+@quotation
+char, line, word, sentence, paragraph, region, page, sexp, list, defun,
+rect, buffer, frame, window, face, file, dir, register, mode, beginning, end,
+forward, backward, next, previous, up, down, search, goto, kill, delete,
+mark, insert, yank, fill, indent, case, change, set, what, list, find,
+view, describe, default.
+@end quotation
+
+@findex apropos-variable
+ To list all user variables that match a regexp, use the command
+@kbd{M-x apropos-variable}. This command shows only user variables and
+customization options by default; if you specify a prefix argument, it
+checks all variables.
+
+@findex apropos
+ To list all Lisp symbols that contain a match for a regexp, not just
+the ones that are defined as commands, use the command @kbd{M-x apropos}
+instead of @kbd{C-h a}. This command does not check key bindings by
+default; specify a numeric argument if you want it to check them.
+
+@findex apropos-documentation
+ The @code{apropos-documentation} command is like @code{apropos} except
+that it searches documentation strings as well as symbol names for
+matches for the specified regular expression.
+
+@findex apropos-value
+ The @code{apropos-value} command is like @code{apropos} except that it
+searches symbols' values for matches for the specified regular
+expression. This command does not check function definitions or
+property lists by default; specify a numeric argument if you want it to
+check them.
+
+@vindex apropos-do-all
+ If the variable @code{apropos-do-all} is non-@code{nil}, the commands
+above all behave as if they had been given a prefix argument.
+
+ If you want more information about a function definition, variable or
+symbol property listed in the Apropos buffer, you can click on it with
+@kbd{Mouse-2} or move there and type @key{RET}.
+
+@node Library Keywords
+@section Keyword Search for Lisp Libraries
+
+@kindex C-h p
+@findex finder-by-keyword
+The @kbd{C-h p} command lets you search the standard Emacs Lisp
+libraries by topic keywords. Here is a partial list of keywords you can
+use:
+
+@display
+abbrev --- abbreviation handling, typing shortcuts, macros.
+bib --- support for the bibliography processor @code{bib}.
+c --- C and C++ language support.
+calendar --- calendar and time management support.
+comm --- communications, networking, remote access to files.
+data --- support for editing files of data.
+docs --- support for Emacs documentation.
+emulations --- emulations of other editors.
+extensions --- Emacs Lisp language extensions.
+faces --- support for using faces (fonts and colors; @pxref{Faces}).
+frames --- support for Emacs frames and window systems.
+games --- games, jokes and amusements.
+hardware --- support for interfacing with exotic hardware.
+help --- support for on-line help systems.
+hypermedia --- support for links within text, or other media types.
+i18n --- internationalization and alternate character-set support.
+internal --- code for Emacs internals, build process, defaults.
+languages --- specialized modes for editing programming languages.
+lisp --- support for using Lisp (including Emacs Lisp).
+local --- libraries local to your site.
+maint --- maintenance aids for the Emacs development group.
+mail --- modes for electronic-mail handling.
+matching --- searching and matching.
+news --- support for netnews reading and posting.
+non-text --- support for editing files that are not ordinary text.
+oop --- support for object-oriented programming.
+outlines --- hierarchical outlining.
+processes --- process, subshell, compilation, and job control support.
+terminals --- support for terminal types.
+tex --- support for the @TeX{} formatter.
+tools --- programming tools.
+unix --- front-ends/assistants for, or emulators of, Unix features.
+vms --- support code for VMS.
+wp --- word processing.
+@end display
+
+@node Language Help
+@section Help for International Language Support
+
+ You can use the command @kbd{C-h L}
+(@code{describe-language-environment}) to find out the support for a
+specific language environment. @xref{Language Environments}. This
+tells you which languages this language environment is useful for, and
+lists the character sets, coding systems, and input methods that go with
+it. It also shows some sample text to illustrate scripts.
+
+ The command @kbd{C-h h} (@code{view-hello-file}) displays the file
+@file{etc/HELLO}, which shows how to say ``hello'' in many languages.
+
+ The command @kbd{C-h I} (@code{describe-input-method}) describes
+information about input methods---either a specified input method, or by
+default the input method in use. @xref{Input Methods}.
+
+ The command @kbd{C-h C} (@code{describe-coding-system}) describes
+information about coding systems---either a specified coding system, or
+the ones currently in use. @xref{Coding Systems}.
+
+@node Help Mode
+@section Help Mode Commands
+
+ Help buffers provide the commands of View mode (@pxref{Misc File
+Ops}), plus a few special commands of their own.
+
+@table @kbd
+@item @key{SPC}
+Scroll forward.
+@item @key{DEL}
+Scroll backward.
+@item @key{RET}
+Follow a cross reference at point.
+@item @key{TAB}
+Move point forward to the next cross reference.
+@item S-@key{TAB}
+Move point back to the previous cross reference.
+@item Mouse-2
+Follow a cross reference that you click on.
+@end table
+
+ When a command name (@pxref{M-x,, Running Commands by Name}) or
+variable name (@pxref{Variables}) appears in the documentation, it
+normally appears inside paired single-quotes. You can click on the name
+with @kbd{Mouse-2}, or move point there and type @key{RET}, to view the
+documentation of that command or variable. Use @kbd{C-c C-b} to retrace
+your steps.
+
+@kindex @key{TAB} @r{(Help mode)}
+@findex help-next-ref
+@kindex S-@key{TAB} @r{(Help mode)}
+@findex help-previous-ref
+ There are convenient commands for moving point to cross references in
+the help text. @key{TAB} (@code{help-next-ref}) moves point down to the
+next cross reference. Use @kbd{S-@key{TAB}} to move point up to the
+previous cross reference (@code{help-previous-ref}).
+
+@node Misc Help
+@section Other Help Commands
+
+@kindex C-h i
+@findex info
+@cindex Info
+@cindex manuals, on-line
+@cindex on-line manuals
+ @kbd{C-h i} (@code{info}) runs the Info program, which is used for
+browsing through structured documentation files. The entire Emacs manual
+is available within Info. Eventually all the documentation of the GNU
+system will be available. Type @kbd{h} after entering Info to run
+a tutorial on using Info.
+
+ If you specify a numeric argument, @kbd{C-h i} prompts for the name of
+a documentation file. This way, you can browse a file which doesn't
+have an entry in the top-level Info menu. It is also handy when you
+need to get to the documentation quickly, and you know the exact name of
+the file.
+
+@kindex C-h C-f
+@kindex C-h C-k
+@findex Info-goto-emacs-key-command-node
+@findex Info-goto-emacs-command-node
+ There are two special help commands for accessing Emacs documentation
+through Info. @kbd{C-h C-f @var{function} @key{RET}} enters Info and
+goes straight to the documentation of the Emacs function
+@var{function}. @kbd{C-h C-k @var{key}} enters Info and goes straight
+to the documentation of the key @var{key}. These two keys run the
+commands @code{Info-goto-emacs-command-node} and
+@code{Info-goto-emacs-key-command-node}.
+
+ When editing a program, if you have an Info version of the manual for
+the programming language, you can use the command @kbd{C-h C-i} to refer
+to the manual documentation for a symbol (keyword, function or
+variable). The details of how this command works depend on the major
+mode.
+
+@kindex C-h l
+@findex view-lossage
+ If something surprising happens, and you are not sure what commands you
+typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} prints the last
+100 command characters you typed in. If you see commands that you don't
+know, you can use @kbd{C-h c} to find out what they do.
+
+@kindex C-h m
+@findex describe-mode
+ Emacs has numerous major modes, each of which redefines a few keys and
+makes a few other changes in how editing works. @kbd{C-h m}
+(@code{describe-mode}) prints documentation on the current major mode,
+which normally describes all the commands that are changed in this
+mode.
+
+@kindex C-h b
+@findex describe-bindings
+ @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
+(@code{describe-syntax}) present other information about the current
+Emacs mode. @kbd{C-h b} displays a list of all the key bindings now in
+effect; the local bindings defined by the current minor modes first,
+then the local bindings defined by the current major mode, and finally
+the global bindings (@pxref{Key Bindings}). @kbd{C-h s} displays the
+contents of the syntax table, with explanations of each character's
+syntax (@pxref{Syntax}).
+
+ You can get a similar list for a particular prefix key by typing
+@kbd{C-h} after the prefix key. (There are a few prefix keys for which
+this does not work---those that provide their own bindings for
+@kbd{C-h}. One of these is @key{ESC}, because @kbd{@key{ESC} C-h} is
+actually @kbd{C-M-h}, which marks a defun.)
+
+@kindex C-h F
+@findex view-emacs-FAQ
+@kindex C-h n
+@findex view-emacs-news
+@kindex C-h C-c
+@findex describe-copying
+@kindex C-h C-d
+@findex describe-distribution
+@kindex C-h C-w
+@findex describe-no-warranty
+@kindex C-h C-p
+@findex describe-project
+ The other @kbd{C-h} options display various files of useful
+information. @kbd{C-h C-w} displays the full details on the complete
+absence of warranty for GNU Emacs. @kbd{C-h n} (@code{view-emacs-news})
+displays the file @file{emacs/etc/NEWS}, which contains documentation on
+Emacs changes arranged chronologically. @kbd{C-h F}
+(@code{view-emacs-FAQ}) displays the Emacs frequently-answered-questions
+list. @kbd{C-h t} (@code{help-with-tutorial}) displays the
+learn-by-doing Emacs tutorial. @kbd{C-h C-c} (@code{describe-copying})
+displays the file @file{emacs/etc/COPYING}, which tells you the
+conditions you must obey in distributing copies of Emacs. @kbd{C-h C-d}
+(@code{describe-distribution}) displays the file
+@file{emacs/etc/DISTRIB}, which tells you how you can order a copy of
+the latest version of Emacs. @kbd{C-h C-p} (@code{describe-project})
+displays general information about the GNU Project.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Indentation, Text, Major Modes, Top
+@chapter Indentation
+@cindex indentation
+@cindex columns (indentation)
+
+ This chapter describes the Emacs commands that add, remove, or
+adjust indentation.
+
+@c WideCommands
+@table @kbd
+@item @key{TAB}
+Indent current line ``appropriately'' in a mode-dependent fashion.
+@item @kbd{C-j}
+Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
+@item M-^
+Merge two lines (@code{delete-indentation}). This would cancel out
+the effect of @kbd{C-j}.
+@item C-M-o
+Split line at point; text on the line after point becomes a new line
+indented to the same column that it now starts in (@code{split-line}).
+@item M-m
+Move (forward or back) to the first nonblank character on the current
+line (@code{back-to-indentation}).
+@item C-M-\
+Indent several lines to same column (@code{indent-region}).
+@item C-x @key{TAB}
+Shift block of lines rigidly right or left (@code{indent-rigidly}).
+@item M-i
+Indent from point to the next prespecified tab stop column
+(@code{tab-to-tab-stop}).
+@item M-x indent-relative
+Indent from point to under an indentation point in the previous line.
+@end table
+
+ Most programming languages have some indentation convention. For Lisp
+code, lines are indented according to their nesting in parentheses. The
+same general idea is used for C code, though many details are different.
+
+@kindex TAB
+ Whatever the language, to indent a line, use the @key{TAB} command. Each
+major mode defines this command to perform the sort of indentation
+appropriate for the particular language. In Lisp mode, @key{TAB} aligns
+the line according to its depth in parentheses. No matter where in the
+line you are when you type @key{TAB}, it aligns the line as a whole. In C
+mode, @key{TAB} implements a subtle and sophisticated indentation style that
+knows about many aspects of C syntax.
+
+ In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
+indents to the next tab stop column. You can set the tab stops with
+@kbd{M-x edit-tab-stops}.
+
+@menu
+* Indentation Commands:: Various commands and techniques for indentation.
+* Tab Stops:: You can set arbitrary "tab stops" and then
+ indent to the next tab stop when you want to.
+* Just Spaces:: You can request indentation using just spaces.
+@end menu
+
+@node Indentation Commands, Tab Stops, Indentation, Indentation
+@section Indentation Commands and Techniques
+
+@kindex M-m
+@findex back-to-indentation
+ To move over the indentation on a line, do @kbd{M-m}
+(@code{back-to-indentation}). This command, given anywhere on a line,
+positions point at the first nonblank character on the line.
+
+ To insert an indented line before the current line, do @kbd{C-a C-o
+@key{TAB}}. To make an indented line after the current line, use
+@kbd{C-e C-j}.
+
+ If you just want to insert a tab character in the buffer, you can type
+@kbd{C-q @key{TAB}}.
+
+@kindex C-M-o
+@findex split-line
+ @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
+the line vertically down, so that the current line becomes two lines.
+@kbd{C-M-o} first moves point forward over any spaces and tabs. Then it
+inserts after point a newline and enough indentation to reach the same
+column point is on. Point remains before the inserted newline; in this
+regard, @kbd{C-M-o} resembles @kbd{C-o}.
+
+@kindex M-^
+@findex delete-indentation
+ To join two lines cleanly, use the @kbd{M-^}
+(@code{delete-indentation}) command. It deletes the indentation at the
+front of the current line, and the line boundary as well, replacing them
+with a single space. As a special case (useful for Lisp code) the
+single space is omitted if the characters to be joined are consecutive
+open parentheses or closing parentheses, or if the junction follows
+another newline. To delete just the indentation of a line, go to the
+beginning of the line and use @kbd{M-\}
+(@code{delete-horizontal-space}), which deletes all spaces and tabs
+around the cursor.
+
+ If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it
+appears after the newline that is deleted. @xref{Fill Prefix}.
+
+@kindex C-M-\
+@kindex C-x TAB
+@findex indent-region
+@findex indent-rigidly
+ There are also commands for changing the indentation of several lines
+at once. @kbd{C-M-\} (@code{indent-region}) applies to all the lines
+that begin in the region; it indents each line in the ``usual'' way, as
+if you had typed @key{TAB} at the beginning of the line. A numeric
+argument specifies the column to indent to, and each line is shifted
+left or right so that its first nonblank character appears in that
+column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of the
+lines in the region right by its argument (left, for negative
+arguments). The whole group of lines moves rigidly sideways, which is
+how the command gets its name.@refill
+
+@findex indent-relative
+ @kbd{M-x indent-relative} indents at point based on the previous line
+(actually, the last nonempty line). It inserts whitespace at point, moving
+point, until it is underneath an indentation point in the previous line.
+An indentation point is the end of a sequence of whitespace or the end of
+the line. If point is farther right than any indentation point in the
+previous line, the whitespace before point is deleted and the first
+indentation point then applicable is used. If no indentation point is
+applicable even then, @code{indent-relative} runs @code{tab-to-tab-stop}
+@ifinfo
+(@pxref{Tab Stops}).
+@end ifinfo
+@iftex
+(see next section).
+@end iftex
+
+ @code{indent-relative} is the definition of @key{TAB} in Indented Text
+mode. @xref{Text}.
+
+ @xref{Format Indentation}, for another way of specifying the
+indentation for part of your text.
+
+@node Tab Stops, Just Spaces, Indentation Commands, Indentation
+@section Tab Stops
+
+@cindex tab stops
+@cindex using tab stops in making tables
+@cindex tables, indentation for
+@kindex M-i
+@findex tab-to-tab-stop
+ For typing in tables, you can use Text mode's definition of @key{TAB},
+@code{tab-to-tab-stop}. This command inserts indentation before point,
+enough to reach the next tab stop column. If you are not in Text mode,
+this command can be found on the key @kbd{M-i}.
+
+@findex edit-tab-stops
+@findex edit-tab-stops-note-changes
+@kindex C-c C-c @r{(Edit Tab Stops)}
+@vindex tab-stop-list
+ You can specify the tab stops used by @kbd{M-i}. They are stored in a
+variable called @code{tab-stop-list}, as a list of column-numbers in
+increasing order.
+
+ The convenient way to set the tab stops is with @kbd{M-x
+edit-tab-stops}, which creates and selects a buffer containing a
+description of the tab stop settings. You can edit this buffer to
+specify different tab stops, and then type @kbd{C-c C-c} to make those
+new tab stops take effect. @code{edit-tab-stops} records which buffer
+was current when you invoked it, and stores the tab stops back in that
+buffer; normally all buffers share the same tab stops and changing them
+in one buffer affects all, but if you happen to make
+@code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in
+that buffer will edit the local settings.
+
+ Here is what the text representing the tab stops looks like for ordinary
+tab stops every eight columns.
+
+@example
+ : : : : : :
+0 1 2 3 4
+0123456789012345678901234567890123456789012345678
+To install changes, type C-c C-c
+@end example
+
+ The first line contains a colon at each tab stop. The remaining lines
+are present just to help you see where the colons are and know what to do.
+
+ Note that the tab stops that control @code{tab-to-tab-stop} have nothing
+to do with displaying tab characters in the buffer. @xref{Display Vars},
+for more information on that.
+
+@node Just Spaces,, Tab Stops, Indentation
+@section Tabs vs. Spaces
+
+@vindex indent-tabs-mode
+ Emacs normally uses both tabs and spaces to indent lines. If you prefer,
+all indentation can be made from spaces only. To request this, set
+@code{indent-tabs-mode} to @code{nil}. This is a per-buffer variable;
+altering the variable affects only the current buffer, but there is a
+default value which you can change as well. @xref{Locals}.
+
+@findex tabify
+@findex untabify
+ There are also commands to convert tabs to spaces or vice versa, always
+preserving the columns of all nonblank text. @kbd{M-x tabify} scans the
+region for sequences of spaces, and converts sequences of at least three
+spaces to tabs if that can be done without changing indentation. @kbd{M-x
+untabify} changes all tabs in the region to appropriate numbers of spaces.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@iftex
+@chapter Killing and Moving Text
+
+ @dfn{Killing} means erasing text and copying it into the @dfn{kill
+ring}, from which it can be retrieved by @dfn{yanking} it. Some systems
+use the terms ``cutting'' and ``pasting'' for these operations.
+
+ The commonest way of moving or copying text within Emacs is to kill it
+and later yank it elsewhere in one or more places. This is very safe
+because Emacs remembers several recent kills, not just the last one. It
+is versatile, because the many commands for killing syntactic units can
+also be used for moving those units. But there are other ways of
+copying text for special purposes.
+
+ Emacs has only one kill ring for all buffers, so you can kill text in
+one buffer and yank it in another buffer.
+
+@end iftex
+
+@node Killing, Yanking, Mark, Top
+@section Deletion and Killing
+
+@cindex killing text
+@cindex cutting text
+@cindex deletion
+ Most commands which erase text from the buffer save it in the kill
+ring so that you can move or copy it to other parts of the buffer.
+These commands are known as @dfn{kill} commands. The rest of the
+commands that erase text do not save it in the kill ring; they are known
+as @dfn{delete} commands. (This distinction is made only for erasure of
+text in the buffer.) If you do a kill or delete command by mistake, you
+can use the @kbd{C-x u} (@code{undo}) command to undo it
+(@pxref{Undo}).
+
+ The delete commands include @kbd{C-d} (@code{delete-char}) and
+@key{DEL} (@code{delete-backward-char}), which delete only one character at
+a time, and those commands that delete only spaces or newlines. Commands
+that can destroy significant amounts of nontrivial data generally kill.
+The commands' names and individual descriptions use the words @samp{kill}
+and @samp{delete} to say which they do.
+
+@menu
+* Deletion:: Commands for deleting small amounts of text and
+ blank areas.
+* Killing by Lines:: How to kill entire lines of text at one time.
+* Other Kill Commands:: Commands to kill large regions of text and
+ syntactic units such as words and sentences.
+@end menu
+
+@node Deletion
+@subsection Deletion
+@c ??? Should be backward-delete-char
+@findex delete-backward-char
+@findex delete-char
+@kindex DEL
+@kindex C-d
+
+@table @kbd
+@item C-d
+Delete next character (@code{delete-char}).
+@item @key{DEL}
+Delete previous character (@code{delete-backward-char}).
+@item M-\
+Delete spaces and tabs around point (@code{delete-horizontal-space}).
+@item M-@key{SPC}
+Delete spaces and tabs around point, leaving one space
+(@code{just-one-space}).
+@item C-x C-o
+Delete blank lines around the current line (@code{delete-blank-lines}).
+@item M-^
+Join two lines by deleting the intervening newline, along with any
+indentation following it (@code{delete-indentation}).
+@end table
+
+ The most basic delete commands are @kbd{C-d} (@code{delete-char}) and
+@key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the
+character after point, the one the cursor is ``on top of.'' This
+doesn't move point. @key{DEL} deletes the character before the cursor,
+and moves point back. You can delete newlines like any other characters
+in the buffer; deleting a newline joins two lines. Actually, @kbd{C-d}
+and @key{DEL} aren't always delete commands; when given arguments, they
+kill instead, since they can erase more than one character this way.
+
+@kindex M-\
+@findex delete-horizontal-space
+@kindex M-SPC
+@findex just-one-space
+ The other delete commands are those which delete only whitespace
+characters: spaces, tabs and newlines. @kbd{M-\}
+(@code{delete-horizontal-space}) deletes all the spaces and tab
+characters before and after point. @kbd{M-@key{SPC}}
+(@code{just-one-space}) does likewise but leaves a single space after
+point, regardless of the number of spaces that existed previously (even
+zero).
+
+ @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines
+after the current line. If the current line is blank, it deletes all
+blank lines preceding the current line as well (leaving one blank line,
+the current line).
+
+ @kbd{M-^} (@code{delete-indentation}) joins the current line and the
+previous line, by deleting a newline and all surrounding spaces, usually
+leaving a single space. @xref{Indentation,M-^}.
+
+@node Killing by Lines
+@subsection Killing by Lines
+
+@table @kbd
+@item C-k
+Kill rest of line or one or more lines (@code{kill-line}).
+@end table
+
+@kindex C-k
+@findex kill-line
+ The simplest kill command is @kbd{C-k}. If given at the beginning of
+a line, it kills all the text on the line, leaving it blank. When used
+on a blank line, it kills the whole line including its newline. To kill
+an entire non-blank line, go to the beginning and type @kbd{C-k} twice.
+
+ More generally, @kbd{C-k} kills from point up to the end of the line,
+unless it is at the end of a line. In that case it kills the newline
+following point, thus merging the next line into the current one.
+Spaces and tabs that you can't see at the end of the line are ignored
+when deciding which case applies, so if point appears to be at the end
+of the line, you can be sure @kbd{C-k} will kill the newline.
+
+ When @kbd{C-k} is given a positive argument, it kills that many lines
+and the newlines that follow them (however, text on the current line
+before point is spared). With a negative argument @minus{}@var{n}, it
+kills @var{n} lines preceding the current line (together with the text
+on the current line before point). Thus, @kbd{C-u - 2 C-k} at the front
+of a line kills the two previous lines.
+
+ @kbd{C-k} with an argument of zero kills the text before point on the
+current line.
+
+@vindex kill-whole-line
+ If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at
+the very beginning of a line kills the entire line including the
+following newline. This variable is normally @code{nil}.
+
+@node Other Kill Commands
+@subsection Other Kill Commands
+@findex kill-region
+@kindex C-w
+
+@c DoubleWideCommands
+@table @kbd
+@item C-w
+Kill region (from point to the mark) (@code{kill-region}).
+@item M-d
+Kill word (@code{kill-word}). @xref{Words}.
+@item M-@key{DEL}
+Kill word backwards (@code{backward-kill-word}).
+@item C-x @key{DEL}
+Kill back to beginning of sentence (@code{backward-kill-sentence}).
+@xref{Sentences}.
+@item M-k
+Kill to end of sentence (@code{kill-sentence}).
+@item C-M-k
+Kill sexp (@code{kill-sexp}). @xref{Lists}.
+@item M-z @var{char}
+Kill through the next occurrence of @var{char} (@code{zap-to-char}).
+@end table
+
+ A kill command which is very general is @kbd{C-w}
+(@code{kill-region}), which kills everything between point and the
+mark. With this command, you can kill any contiguous sequence of
+characters, if you first set the region around them.
+
+@kindex M-z
+@findex zap-to-char
+ A convenient way of killing is combined with searching: @kbd{M-z}
+(@code{zap-to-char}) reads a character and kills from point up to (and
+including) the next occurrence of that character in the buffer. A
+numeric argument acts as a repeat count. A negative argument means to
+search backward and kill text before point.
+
+ Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and
+@kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and
+sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k}
+(@pxref{Sentences}).@refill
+
+ You can use kill commands in read-only buffers. They don't actually
+change the buffer, and they beep to warn you of that, but they do copy
+the text you tried to kill into the kill ring, so you can yank it into
+other buffers. Most of the kill commands move point across the text
+they copy in this way, so that successive kill commands build up a
+single kill ring entry as usual.
+
+@node Yanking, Accumulating Text, Killing, Top
+@section Yanking
+@cindex moving text
+@cindex copying text
+@cindex kill ring
+@cindex yanking
+@cindex pasting
+
+ @dfn{Yanking} means reinserting text previously killed. This is what
+some systems call ``pasting.'' The usual way to move or copy text is to
+kill it and then yank it elsewhere one or more times.
+
+@table @kbd
+@item C-y
+Yank last killed text (@code{yank}).
+@item M-y
+Replace text just yanked with an earlier batch of killed text
+(@code{yank-pop}).
+@item M-w
+Save region as last killed text without actually killing it
+(@code{kill-ring-save}).
+@item C-M-w
+Append next kill to last batch of killed text (@code{append-next-kill}).
+@end table
+
+@menu
+* Kill Ring:: Where killed text is stored. Basic yanking.
+* Appending Kills:: Several kills in a row all yank together.
+* Earlier Kills:: Yanking something killed some time ago.
+@end menu
+
+@node Kill Ring
+@subsection The Kill Ring
+
+ All killed text is recorded in the @dfn{kill ring}, a list of blocks of
+text that have been killed. There is only one kill ring, shared by all
+buffers, so you can kill text in one buffer and yank it in another buffer.
+This is the usual way to move text from one file to another.
+(@xref{Accumulating Text}, for some other ways.)
+
+@kindex C-y
+@findex yank
+ The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent
+kill. It leaves the cursor at the end of the text. It sets the mark at
+the beginning of the text. @xref{Mark}.
+
+ @kbd{C-u C-y} leaves the cursor in front of the text, and sets the
+mark after it. This happens only if the argument is specified with just
+a @kbd{C-u}, precisely. Any other sort of argument, including @kbd{C-u}
+and digits, specifies an earlier kill to yank (@pxref{Earlier Kills}).
+
+@kindex M-w
+@findex kill-ring-save
+ To copy a block of text, you can use @kbd{M-w}
+(@code{kill-ring-save}), which copies the region into the kill ring
+without removing it from the buffer. This is approximately equivalent
+to @kbd{C-w} followed by @kbd{C-x u}, except that @kbd{M-w} does not
+alter the undo history and does not temporarily change the screen.
+
+@node Appending Kills
+@subsection Appending Kills
+
+@cindex appending kills in the ring
+@cindex television
+ Normally, each kill command pushes a new entry onto the kill ring.
+However, two or more kill commands in a row combine their text into a
+single entry, so that a single @kbd{C-y} yanks all the text as a unit,
+just as it was before it was killed.
+
+ Thus, if you want to yank text as a unit, you need not kill all of it
+with one command; you can keep killing line after line, or word after
+word, until you have killed it all, and you can still get it all back at
+once.
+
+ Commands that kill forward from point add onto the end of the previous
+killed text. Commands that kill backward from point add text onto the
+beginning. This way, any sequence of mixed forward and backward kill
+commands puts all the killed text into one entry without rearrangement.
+Numeric arguments do not break the sequence of appending kills. For
+example, suppose the buffer contains this text:
+
+@example
+This is a line @point{}of sample text.
+@end example
+
+@noindent
+with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d
+M-@key{DEL}}, killing alternately forward and backward, you end up with
+@samp{a line of sample} as one entry in the kill ring, and @samp{This
+is@ @ text.} in the buffer. (Note the double space, which you can clean
+up with @kbd{M-@key{SPC}} or @kbd{M-q}.)
+
+ Another way to kill the same text is to move back two words with
+@kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}.
+This produces exactly the same results in the buffer and in the kill
+ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going
+backward; once again, the result is the same. The text in the kill ring
+entry always has the same order that it had in the buffer before you
+killed it.
+
+@kindex C-M-w
+@findex append-next-kill
+ If a kill command is separated from the last kill command by other
+commands (not just numeric arguments), it starts a new entry on the kill
+ring. But you can force it to append by first typing the command
+@kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w}
+tells the following command, if it is a kill command, to append the text
+it kills to the last killed text, instead of starting a new entry. With
+@kbd{C-M-w}, you can kill several separated pieces of text and
+accumulate them to be yanked back in one place.@refill
+
+ A kill command following @kbd{M-w} does not append to the text that
+@kbd{M-w} copied into the kill ring.
+
+@node Earlier Kills
+@subsection Yanking Earlier Kills
+
+@cindex yanking previous kills
+@kindex M-y
+@findex yank-pop
+ To recover killed text that is no longer the most recent kill, use the
+@kbd{M-y} command (@code{yank-pop}). It takes the text previously
+yanked and replaces it with the text from an earlier kill. So, to
+recover the text of the next-to-the-last kill, first use @kbd{C-y} to
+yank the last kill, and then use @kbd{M-y} to replace it with the
+previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another
+@kbd{M-y}.
+
+ You can understand @kbd{M-y} in terms of a ``last yank'' pointer which
+points at an entry in the kill ring. Each time you kill, the ``last
+yank'' pointer moves to the newly made entry at the front of the ring.
+@kbd{C-y} yanks the entry which the ``last yank'' pointer points to.
+@kbd{M-y} moves the ``last yank'' pointer to a different entry, and the
+text in the buffer changes to match. Enough @kbd{M-y} commands can move
+the pointer to any entry in the ring, so you can get any entry into the
+buffer. Eventually the pointer reaches the end of the ring; the next
+@kbd{M-y} moves it to the first entry again.
+
+ @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does
+not change the order of the entries in the ring, which always runs from
+the most recent kill at the front to the oldest one still remembered.
+
+ @kbd{M-y} can take a numeric argument, which tells it how many entries
+to advance the ``last yank'' pointer by. A negative argument moves the
+pointer toward the front of the ring; from the front of the ring, it
+moves ``around'' to the last entry and continues forward from there.
+
+ Once the text you are looking for is brought into the buffer, you can
+stop doing @kbd{M-y} commands and it will stay there. It's just a copy
+of the kill ring entry, so editing it in the buffer does not change
+what's in the ring. As long as no new killing is done, the ``last
+yank'' pointer remains at the same place in the kill ring, so repeating
+@kbd{C-y} will yank another copy of the same previous kill.
+
+ If you know how many @kbd{M-y} commands it would take to find the text
+you want, you can yank that text in one step using @kbd{C-y} with a
+numeric argument. @kbd{C-y} with an argument restores the text the
+specified number of entries back in the kill ring. Thus, @kbd{C-u 2
+C-y} gets the next-to-the-last block of killed text. It is equivalent
+to @kbd{C-y M-y}. @kbd{C-y} with a numeric argument starts counting
+from the ``last yank'' pointer, and sets the ``last yank'' pointer to
+the entry that it yanks.
+
+@vindex kill-ring-max
+ The length of the kill ring is controlled by the variable
+@code{kill-ring-max}; no more than that many blocks of killed text are
+saved.
+
+@vindex kill-ring
+ The actual contents of the kill ring are stored in a variable named
+@code{kill-ring}; you can view the entire contents of the kill ring with
+the command @kbd{C-h v kill-ring}.
+
+@node Accumulating Text, Rectangles, Yanking, Top
+@section Accumulating Text
+@findex append-to-buffer
+@findex prepend-to-buffer
+@findex copy-to-buffer
+@findex append-to-file
+
+@cindex accumulating scattered text
+ Usually we copy or move text by killing it and yanking it, but there
+are other methods convenient for copying one block of text in many
+places, or for copying many scattered blocks of text into one place. To
+copy one block to many places, store it in a register
+(@pxref{Registers}). Here we describe the commands to accumulate
+scattered pieces of text into a buffer or into a file.
+
+@table @kbd
+@item M-x append-to-buffer
+Append region to contents of specified buffer.
+@item M-x prepend-to-buffer
+Prepend region to contents of specified buffer.
+@item M-x copy-to-buffer
+Copy region into specified buffer, deleting that buffer's old contents.
+@item M-x insert-buffer
+Insert contents of specified buffer into current buffer at point.
+@item M-x append-to-file
+Append region to contents of specified file, at the end.
+@end table
+
+ To accumulate text into a buffer, use @kbd{M-x append-to-buffer}.
+This reads a buffer name, then inserts a copy of the region into the
+buffer specified. If you specify a nonexistent buffer,
+@code{append-to-buffer} creates the buffer. The text is inserted
+wherever point is in that buffer. If you have been using the buffer for
+editing, the copied text goes into the middle of the text of the buffer,
+wherever point happens to be in it.
+
+ Point in that buffer is left at the end of the copied text, so
+successive uses of @code{append-to-buffer} accumulate the text in the
+specified buffer in the same order as they were copied. Strictly
+speaking, @code{append-to-buffer} does not always append to the text
+already in the buffer---it appends only if point in that buffer is at the end.
+However, if @code{append-to-buffer} is the only command you use to alter
+a buffer, then point is always at the end.
+
+ @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer}
+except that point in the other buffer is left before the copied text, so
+successive prependings add text in reverse order. @kbd{M-x
+copy-to-buffer} is similar except that any existing text in the other
+buffer is deleted, so the buffer is left containing just the text newly
+copied into it.
+
+ To retrieve the accumulated text from another buffer, use the command
+@kbd{M-x insert-buffer}; this too takes @var{buffername} as an argument.
+It inserts a copy of the text in buffer @var{buffername} into the
+selected buffer. You can alternatively select the other buffer for
+editing, then optionally move text from it by killing. @xref{Buffers},
+for background information on buffers.
+
+ Instead of accumulating text within Emacs, in a buffer, you can append
+text directly into a file with @kbd{M-x append-to-file}, which takes
+@var{filename} as an argument. It adds the text of the region to the end
+of the specified file. The file is changed immediately on disk.
+
+ You should use @code{append-to-file} only with files that are
+@emph{not} being visited in Emacs. Using it on a file that you are
+editing in Emacs would change the file behind Emacs's back, which
+can lead to losing some of your editing.
+
+@node Rectangles, Registers, Accumulating Text, Top
+@section Rectangles
+@cindex rectangle
+@cindex columns (and rectangles)
+@cindex killing rectangular areas of text
+
+ The rectangle commands operate on rectangular areas of the text: all
+the characters between a certain pair of columns, in a certain range of
+lines. Commands are provided to kill rectangles, yank killed rectangles,
+clear them out, fill them with blanks or text, or delete them. Rectangle
+commands are useful with text in multicolumn formats, and for changing
+text into or out of such formats.
+
+ When you must specify a rectangle for a command to work on, you do it
+by putting the mark at one corner and point at the opposite corner. The
+rectangle thus specified is called the @dfn{region-rectangle} because
+you control it in about the same way the region is controlled. But
+remember that a given combination of point and mark values can be
+interpreted either as a region or as a rectangle, depending on the
+command that uses them.
+
+ If point and the mark are in the same column, the rectangle they
+delimit is empty. If they are in the same line, the rectangle is one
+line high. This asymmetry between lines and columns comes about
+because point (and likewise the mark) is between two columns, but within
+a line.
+
+@table @kbd
+@item C-x r k
+Kill the text of the region-rectangle, saving its contents as the
+``last killed rectangle'' (@code{kill-rectangle}).
+@item C-x r d
+Delete the text of the region-rectangle (@code{delete-rectangle}).
+@item C-x r y
+Yank the last killed rectangle with its upper left corner at point
+(@code{yank-rectangle}).
+@item C-x r o
+Insert blank space to fill the space of the region-rectangle
+(@code{open-rectangle}). This pushes the previous contents of the
+region-rectangle rightward.
+@item M-x clear-rectangle
+Clear the region-rectangle by replacing its contents with spaces.
+@item M-x delete-whitespace-rectangle
+Delete whitespace in each of the lines on the specified rectangle,
+starting from the left edge column of the rectangle.
+@item C-x r t @key{RET} @var{string} @key{RET}
+Insert @var{string} on each line of the region-rectangle
+(@code{string-rectangle}).
+@end table
+
+ The rectangle operations fall into two classes: commands deleting and
+inserting rectangles, and commands for blank rectangles.
+
+@kindex C-x r k
+@kindex C-x r d
+@findex kill-rectangle
+@findex delete-rectangle
+ There are two ways to get rid of the text in a rectangle: you can
+discard the text (delete it) or save it as the ``last killed''
+rectangle. The commands for these two ways are @kbd{C-x r d}
+(@code{delete-rectangle}) and @kbd{C-x r k} (@code{kill-rectangle}). In
+either case, the portion of each line that falls inside the rectangle's
+boundaries is deleted, causing following text (if any) on the line to
+move left into the gap.
+
+ Note that ``killing'' a rectangle is not killing in the usual sense; the
+rectangle is not stored in the kill ring, but in a special place that
+can only record the most recent rectangle killed. This is because yanking
+a rectangle is so different from yanking linear text that different yank
+commands have to be used and yank-popping is hard to make sense of.
+
+@kindex C-x r y
+@findex yank-rectangle
+ To yank the last killed rectangle, type @kbd{C-x r y}
+(@code{yank-rectangle}). Yanking a rectangle is the opposite of killing
+one. Point specifies where to put the rectangle's upper left corner.
+The rectangle's first line is inserted there, the rectangle's second
+line is inserted at a position one line vertically down, and so on. The
+number of lines affected is determined by the height of the saved
+rectangle.
+
+ You can convert single-column lists into double-column lists using
+rectangle killing and yanking; kill the second half of the list as a
+rectangle and then yank it beside the first line of the list.
+@xref{Two-Column}, for another way to edit multi-column text.
+
+ You can also copy rectangles into and out of registers with @kbd{C-x r
+r @var{r}} and @kbd{C-x r i @var{r}}. @xref{RegRect,,Rectangle
+Registers}.
+
+@kindex C-x r o
+@findex open-rectangle
+@findex clear-rectangle
+ There are two commands you can use for making blank rectangles:
+@kbd{M-x clear-rectangle} which blanks out existing text, and @kbd{C-x r
+o} (@code{open-rectangle}) which inserts a blank rectangle. Clearing a
+rectangle is equivalent to deleting it and then inserting a blank
+rectangle of the same size.
+
+@findex delete-whitespace-rectangle
+ The command @kbd{M-x delete-whitespace-rectangle} deletes horizontal
+whitespace starting from a particular column. This applies to each of
+the lines in the rectangle, and the column is specified by the left
+edge of the rectangle. The right edge of the rectangle does not make
+any difference to this command.
+
+@kindex C-x r t
+@findex string-rectangle
+ The command @kbd{C-x r t} (@code{M-x string-rectangle}) replaces the
+rectangle with a specified string (inserted once on each line). The
+string's width need not be the same as the width of the rectangle. If
+the string's width is less, the text after the rectangle shifts left; if
+the string is wider than the rectangle, the text after the rectangle
+shifts right.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node M-x, Help, Minibuffer, Top
+@chapter Running Commands by Name
+
+ The Emacs commands that are used often or that must be quick to type are
+bound to keys---short sequences of characters---for convenient use. Other
+Emacs commands that do not need to be brief are not bound to keys; to run
+them, you must refer to them by name.
+
+ A command name is, by convention, made up of one or more words,
+separated by hyphens; for example, @code{auto-fill-mode} or
+@code{manual-entry}. The use of English words makes the command name
+easier to remember than a key made up of obscure characters, even though
+it is more characters to type.
+
+@kindex M-x
+ The way to run a command by name is to start with @kbd{M-x}, type the
+command name, and finish it with @key{RET}. @kbd{M-x} uses the
+minibuffer to read the command name. @key{RET} exits the minibuffer and
+runs the command. The string @samp{M-x} appears at the beginning of the
+minibuffer as a @dfn{prompt} to remind you to enter the name of a
+command to be run. @xref{Minibuffer}, for full information on the
+features of the minibuffer.
+
+ You can use completion to enter the command name. For example, the
+command @code{forward-char} can be invoked by name by typing
+
+@example
+M-x forward-char @key{RET}
+@end example
+
+@noindent
+or
+
+@example
+M-x forw @key{TAB} c @key{RET}
+@end example
+
+@noindent
+Note that @code{forward-char} is the same command that you invoke with
+the key @kbd{C-f}. You can run any Emacs command by name using
+@kbd{M-x}, whether or not any keys are bound to it.
+
+ If you type @kbd{C-g} while the command name is being read, you cancel
+the @kbd{M-x} command and get out of the minibuffer, ending up at top level.
+
+ To pass a numeric argument to the command you are invoking with
+@kbd{M-x}, specify the numeric argument before the @kbd{M-x}. @kbd{M-x}
+passes the argument along to the command it runs. The argument value
+appears in the prompt while the command name is being read.
+
+@vindex suggest-key-bindings
+ If the command you type has a key binding of its own, Emacs mentions
+this in the echo area, two seconds after the command finishes (if you
+don't type anything else first). For example, if you type @kbd{M-x
+forward-word}, the message says that you can run the same command more
+easily by typing @kbd{M-f}. You can turn off these messages by setting
+@code{suggest-key-bindings} to @code{nil}.
+
+ Normally, when describing in this manual a command that is run by
+name, we omit the @key{RET} that is needed to terminate the name. Thus
+we might speak of @kbd{M-x auto-fill-mode} rather than @kbd{M-x
+auto-fill-mode @key{RET}}. We mention the @key{RET} only when there is
+a need to emphasize its presence, such as when we show the command
+together with following arguments.
+
+@findex execute-extended-command
+ @kbd{M-x} works by running the command
+@code{execute-extended-command}, which is responsible for reading the
+name of another command and invoking it.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Major Modes, Indentation, International, Top
+@chapter Major Modes
+@cindex major modes
+@cindex mode, major
+@kindex TAB @r{(and major modes)}
+@kindex DEL @r{(and major modes)}
+@kindex C-j @r{(and major modes)}
+
+ Emacs provides many alternative @dfn{major modes}, each of which
+customizes Emacs for editing text of a particular sort. The major modes
+are mutually exclusive, and each buffer has one major mode at any time.
+The mode line normally shows the name of the current major mode, in
+parentheses (@pxref{Mode Line}).
+
+ The least specialized major mode is called @dfn{Fundamental mode}.
+This mode has no mode-specific redefinitions or variable settings, so
+that each Emacs command behaves in its most general manner, and each
+option is in its default state. For editing text of a specific type
+that Emacs knows about, such as Lisp code or English text, you should
+switch to the appropriate major mode, such as Lisp mode or Text mode.
+
+ Selecting a major mode changes the meanings of a few keys to become
+more specifically adapted to the language being edited. The ones that
+are changed frequently are @key{TAB}, @key{DEL}, and @kbd{C-j}. The
+prefix key @kbd{C-c} normally contains mode-specific commands. In
+addition, the commands which handle comments use the mode to determine
+how comments are to be delimited. Many major modes redefine the
+syntactical properties of characters appearing in the buffer.
+@xref{Syntax}.
+
+ The major modes fall into three major groups. Lisp mode (which has
+several variants), C mode, Fortran mode and others are for specific
+programming languages. Text mode, Nroff mode, @TeX{} mode and Outline
+mode are for editing English text. The remaining major modes are not
+intended for use on users' files; they are used in buffers created for
+specific purposes by Emacs, such as Dired mode for buffers made by Dired
+(@pxref{Dired}), Mail mode for buffers made by @kbd{C-x m}
+(@pxref{Sending Mail}), and Shell mode for buffers used for
+communicating with an inferior shell process (@pxref{Interactive
+Shell}).
+
+ Most programming-language major modes specify that only blank lines
+separate paragraphs. This is to make the paragraph commands useful.
+(@xref{Paragraphs}.) They also cause Auto Fill mode to use the
+definition of @key{TAB} to indent the new lines it creates. This is
+because most lines in a program are usually indented.
+(@xref{Indentation}.)
+
+@menu
+* Choosing Modes:: How major modes are specified or chosen.
+@end menu
+
+@node Choosing Modes,,Major Modes,Major Modes
+@section How Major Modes are Chosen
+
+@cindex choosing a major mode
+ You can select a major mode explicitly for the current buffer, but
+most of the time Emacs determines which mode to use based on the file
+name or on special text in the file.
+
+ Explicit selection of a new major mode is done with a @kbd{M-x} command.
+From the name of a major mode, add @code{-mode} to get the name of a
+command to select that mode. Thus, you can enter Lisp mode by executing
+@kbd{M-x lisp-mode}.
+
+@vindex auto-mode-alist
+ When you visit a file, Emacs usually chooses the right major mode based
+on the file's name. For example, files whose names end in @samp{.c} are
+edited in C mode. The correspondence between file names and major modes is
+controlled by the variable @code{auto-mode-alist}. Its value is a list in
+which each element has this form,
+
+@example
+(@var{regexp} . @var{mode-function})
+@end example
+
+@noindent
+or this form,
+
+@example
+(@var{regexp} @var{mode-function} @var{flag})
+@end example
+
+@noindent
+For example, one element normally found in the list has the form
+@code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C
+mode for files whose names end in @file{.c}. (Note that @samp{\\} is
+needed in Lisp syntax to include a @samp{\} in the string, which is
+needed to suppress the special meaning of @samp{.} in regexps.) If the
+element has the form @code{(@var{regexp} @var{mode-function}
+@var{flag})} and @var{flag} is non-@code{nil}, then after calling
+@var{function}, the suffix that matched @var{regexp} is discarded and
+the list is searched again for another match.
+
+ You can specify which major mode should be used for editing a certain
+file by a special sort of text in the first nonblank line of the file. The
+mode name should appear in this line both preceded and followed by
+@samp{-*-}. Other text may appear on the line as well. For example,
+
+@example
+;-*-Lisp-*-
+@end example
+
+@noindent
+tells Emacs to use Lisp mode. Such an explicit specification overrides
+any defaulting based on the file name. Note how the semicolon is used
+to make Lisp treat this line as a comment.
+
+ Another format of mode specification is
+
+@example
+-*- mode: @var{modename};-*-
+@end example
+
+@noindent
+which allows you to specify local variables as well, like this:
+
+@example
+-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
+@end example
+
+@noindent
+@xref{File Variables}, for more information about this.
+
+@vindex interpreter-mode-alist
+ When a file's contents begin with @samp{#!}, it can serve as an
+executable shell command, which works by running an interpreter named on
+the file's first line. The rest of the file is used as input to the
+interpreter.
+
+ When you visit such a file in Emacs, if the file's name does not
+specify a major mode, Emacs uses the interpreter name on the first line
+to choose a mode. If the first line is the name of a recognized
+interpreter program, such as @samp{perl} or @samp{tcl}, Emacs uses a
+mode appropriate for programs for that interpreter. The variable
+@code{interpreter-mode-alist} specifies the correspondence between
+interpreter program names and major modes.
+
+ When the first line starts with @samp{#!}, you cannot (on many
+systems) use the @samp{-*-} feature on the first line, because the
+system would get confused when running the interpreter. So Emacs looks
+for @samp{-*-} on the second line in such files as well as on the
+first line.
+
+@vindex default-major-mode
+ When you visit a file that does not specify a major mode to use, or
+when you create a new buffer with @kbd{C-x b}, the variable
+@code{default-major-mode} specifies which major mode to use. Normally
+its value is the symbol @code{fundamental-mode}, which specifies
+Fundamental mode. If @code{default-major-mode} is @code{nil}, the major
+mode is taken from the previously selected buffer.
+
+@findex normal-mode
+ If you change the major mode of a buffer, you can go back to the major
+mode Emacs would choose automatically: use the command @kbd{M-x
+normal-mode} to do this. This is the same function that
+@code{find-file} calls to choose the major mode. It also processes
+the file's local variables list if any.
+
+@vindex change-major-mode-with-file-name
+ The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to
+a new major mode if the new file name implies a mode (@pxref{Saving}).
+However, this does not happen if the buffer contents specify a major
+mode, and certain ``special'' major modes do not allow the mode to
+change. You can turn off this mode-changing feature by setting
+@code{change-major-mode-with-file-name} to @code{nil}.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Mark, Killing, Help, Top
+@chapter The Mark and the Region
+@cindex mark
+@cindex setting a mark
+@cindex region
+
+ Many Emacs commands operate on an arbitrary contiguous part of the
+current buffer. To specify the text for such a command to operate on,
+you set @dfn{the mark} at one end of it, and move point to the other
+end. The text between point and the mark is called @dfn{the region}.
+Emacs highlights the region whenever there is one, if you enable
+Transient Mark mode (@pxref{Transient Mark}).
+
+ You can move point or the mark to adjust the boundaries of the region.
+It doesn't matter which one is set first chronologically, or which one
+comes earlier in the text. Once the mark has been set, it remains where
+you put it until you set it again at another place. Each Emacs buffer
+has its own mark, so that when you return to a buffer that had been
+selected previously, it has the same mark it had before.
+
+ Many commands that insert text, such as @kbd{C-y} (@code{yank}) and
+@kbd{M-x insert-buffer}, position point and the mark at opposite ends of
+the inserted text, so that the region contains the text just inserted.
+
+ Aside from delimiting the region, the mark is also useful for
+remembering a spot that you may want to go back to. To make this
+feature more useful, each buffer remembers 16 previous locations of the
+mark in the @dfn{mark ring}.
+
+@menu
+* Setting Mark:: Commands to set the mark.
+* Transient Mark:: How to make Emacs highlight the region--
+ when there is one.
+* Using Region:: Summary of ways to operate on contents of the region.
+* Marking Objects:: Commands to put region around textual units.
+* Mark Ring:: Previous mark positions saved so you can go back there.
+* Global Mark Ring:: Previous mark positions in various buffers.
+@end menu
+
+@node Setting Mark
+@section Setting the Mark
+
+ Here are some commands for setting the mark:
+
+@c WideCommands
+@table @kbd
+@item C-@key{SPC}
+Set the mark where point is (@code{set-mark-command}).
+@item C-@@
+The same.
+@item C-x C-x
+Interchange mark and point (@code{exchange-point-and-mark}).
+@item Drag-Mouse-1
+Set point and the mark around the text you drag across.
+@item Mouse-3
+Set the mark where point is, then move point to where you click
+(@code{mouse-save-then-kill}).
+@end table
+
+ For example, suppose you wish to convert part of the buffer to
+upper case, using the @kbd{C-x C-u} (@code{upcase-region}) command,
+which operates on the text in the region. You can first go to the
+beginning of the text to be capitalized, type @kbd{C-@key{SPC}} to put
+the mark there, move to the end, and then type @kbd{C-x C-u}. Or, you
+can set the mark at the end of the text, move to the beginning, and then
+type @kbd{C-x C-u}.
+
+@kindex C-SPC
+@findex set-mark-command
+ The most common way to set the mark is with the @kbd{C-@key{SPC}} command
+(@code{set-mark-command}). This sets the mark where point is. Then you
+can move point away, leaving the mark behind.
+
+ There are two ways to set the mark with the mouse. You can drag mouse
+button one across a range of text; that puts point where you release the
+mouse button, and sets the mark at the other end of that range. Or you
+can click mouse button three, which sets the mark at point (like
+@kbd{C-@key{SPC}}) and then moves point (like @kbd{Mouse-1}). Both of
+these methods copy the region into the kill ring in addition to setting
+the mark; that gives behavior consistent with other window-driven
+applications, but if you don't want to modify the kill ring, you must
+use keyboard commands to set the mark. @xref{Mouse Commands}.
+
+@kindex C-x C-x
+@findex exchange-point-and-mark
+ Ordinary terminals have only one cursor, so there is no way for Emacs
+to show you where the mark is located. You have to remember. The usual
+solution to this problem is to set the mark and then use it soon, before
+you forget where it is. Alternatively, you can see where the mark is
+with the command @kbd{C-x C-x} (@code{exchange-point-and-mark}) which
+puts the mark where point was and point where the mark was. The extent
+of the region is unchanged, but the cursor and point are now at the
+previous position of the mark. In Transient Mark mode, this command
+reactivates the mark.
+
+ @kbd{C-x C-x} is also useful when you are satisfied with the position
+of point but want to move the other end of the region (where the mark
+is); do @kbd{C-x C-x} to put point at that end of the region, and then
+move it. A second use of @kbd{C-x C-x}, if necessary, puts the mark at
+the new position with point back at its original position.
+
+@kindex C-@@
+ There is no such character as @kbd{C-@key{SPC}} in ASCII; when you
+type @key{SPC} while holding down @key{CTRL}, what you get on most
+ordinary terminals is the character @kbd{C-@@}. This key is actually
+bound to @code{set-mark-command}. But unless you are unlucky enough to
+have a terminal where typing @kbd{C-@key{SPC}} does not produce
+@kbd{C-@@}, you might as well think of this character as
+@kbd{C-@key{SPC}}. Under X, @kbd{C-@key{SPC}} is actually a distinct
+character, but its binding is still @code{set-mark-command}.
+
+@node Transient Mark
+@section Transient Mark Mode
+@cindex mode, Transient Mark
+@cindex Transient Mark mode
+@cindex highlighting region
+@cindex region highlighting
+
+ Emacs can highlight the current region, using X Windows. But normally
+it does not. Why not?
+
+ Highlighting the region doesn't work well ordinarily in Emacs, because
+once you have set a mark, there is @emph{always} a region (in that
+buffer). And highlighting the region all the time would be a nuisance.
+
+ You can turn on region highlighting by enabling Transient Mark mode.
+This is a more rigid mode of operation in which the region ``lasts''
+only temporarily, so you must set up a region for each command that uses
+one. In Transient Mark mode, most of the time there is no region;
+therefore, highlighting the region when it exists is convenient.
+
+@findex transient-mark-mode
+ To enable Transient Mark mode, type @kbd{M-x transient-mark-mode}.
+This command toggles the mode, so you can repeat the command to turn off
+the mode.
+
+ Here are the details of Transient Mark mode:
+
+@itemize @bullet
+@item
+To set the mark, type @kbd{C-@key{SPC}} (@code{set-mark-command}).
+This makes the mark active; as you move point, you will see the region
+highlighting grow and shrink.
+
+@item
+The mouse commands for specifying the mark also make it active. So do
+keyboard commands whose purpose is to specify a region, including
+@kbd{M-@@}, @kbd{C-M-@@}, @kbd{M-h}, @kbd{C-M-h}, @kbd{C-x C-p}, and
+@kbd{C-x h}.
+
+@item
+When the mark is active, you can execute commands that operate on the
+region, such as killing, indenting, or writing to a file.
+
+@item
+Any change to the buffer, such as inserting or deleting a character,
+deactivates the mark. This means any subsequent command that operates
+on a region will get an error and refuse to operate. You can make the
+region active again by typing @kbd{C-x C-x}.
+
+@item
+Commands like @kbd{M->} and @kbd{C-s} that ``leave the mark behind'' in
+addition to some other primary purpose do not activate the new mark.
+You can activate the new region by executing @kbd{C-x C-x}
+(@code{exchange-point-and-mark}).
+
+@item
+@kbd{C-s} when the mark is active does not alter the mark.
+
+@item
+Quitting with @kbd{C-g} deactivates the mark.
+@end itemize
+
+ Highlighting of the region uses the @code{region} face; you can
+customize how the region is highlighted by changing this face.
+@xref{Face Customization}.
+
+@vindex highlight-nonselected-windows
+ When multiple windows show the same buffer, they can have different
+regions, because they can have different values of point (though they
+all share one common mark position). Ordinarily, only the selected
+window highlights its region (@pxref{Windows}). However, if the
+variable @code{highlight-nonselected-windows} is non-@code{nil}, then
+each window highlights its own region (provided that Transient Mark mode
+is enabled and the window's buffer's mark is active).
+
+ When Transient Mark mode is not enabled, every command that sets the
+mark also activates it, and nothing ever deactivates it.
+
+@vindex mark-even-if-inactive
+ If the variable @code{mark-even-if-inactive} is non-@code{nil} in
+Transient Mark mode, then commands can use the mark and the region
+even when it is inactive. Region highlighting appears and disappears
+just as it normally does in Transient Mark mode, but the mark doesn't
+really go away when the highlighting disappears.
+
+@cindex Zmacs mode
+ Transient Mark mode is also sometimes known as ``Zmacs mode''
+because the Zmacs editor on the MIT Lisp Machine handled the mark in a
+similar way.
+
+@node Using Region
+@section Operating on the Region
+
+@cindex operations on a marked region
+ Once you have a region and the mark is active, here are some of the
+ways you can operate on the region:
+
+@itemize @bullet
+@item
+Kill it with @kbd{C-w} (@pxref{Killing}).
+@item
+Save it in a register with @kbd{C-x r s} (@pxref{Registers}).
+@item
+Save it in a buffer or a file (@pxref{Accumulating Text}).
+@item
+Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}).
+@item
+Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}).
+@item
+Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}).
+@item
+Print hardcopy with @kbd{M-x print-region} (@pxref{Hardcopy}).
+@item
+Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
+@end itemize
+
+ Most commands that operate on the text in the
+region have the word @code{region} in their names.
+
+@node Marking Objects
+@section Commands to Mark Textual Objects
+
+@cindex marking sections of text
+ Here are the commands for placing point and the mark around a textual
+object such as a word, list, paragraph or page.
+
+@table @kbd
+@item M-@@
+Set mark after end of next word (@code{mark-word}). This command and
+the following one do not move point.
+@item C-M-@@
+Set mark after end of next Lisp expression (@code{mark-sexp}).
+@item M-h
+Put region around current paragraph (@code{mark-paragraph}).
+@item C-M-h
+Put region around current Lisp defun (@code{mark-defun}).
+@item C-x h
+Put region around entire buffer (@code{mark-whole-buffer}).
+@item C-x C-p
+Put region around current page (@code{mark-page}).
+@end table
+
+@kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next word,
+while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the next Lisp
+expression. These commands handle arguments just like @kbd{M-f} and
+@kbd{C-M-f}.
+
+@kindex C-x h
+@findex mark-whole-buffer
+ Other commands set both point and mark, to delimit an object in the
+buffer. For example, @kbd{M-h} (@code{mark-paragraph}) moves point to
+the beginning of the paragraph that surrounds or follows point, and puts
+the mark at the end of that paragraph (@pxref{Paragraphs}). It prepares
+the region so you can indent, case-convert, or kill a whole paragraph.
+
+ @kbd{C-M-h} (@code{mark-defun}) similarly puts point before and the
+mark after the current or following defun (@pxref{Defuns}). @kbd{C-x
+C-p} (@code{mark-page}) puts point before the current page, and mark at
+the end (@pxref{Pages}). The mark goes after the terminating page
+delimiter (to include it), while point goes after the preceding page
+delimiter (to exclude it). A numeric argument specifies a later page
+(if positive) or an earlier page (if negative) instead of the current
+page.
+
+ Finally, @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire
+buffer as the region, by putting point at the beginning and the mark at
+the end.
+
+ In Transient Mark mode, all of these commands activate the mark.
+
+@node Mark Ring
+@section The Mark Ring
+
+@kindex C-u C-SPC
+@cindex mark ring
+@kindex C-u C-@@
+ Aside from delimiting the region, the mark is also useful for
+remembering a spot that you may want to go back to. To make this
+feature more useful, each buffer remembers 16 previous locations of the
+mark, in the @dfn{mark ring}. Commands that set the mark also push the
+old mark onto this ring. To return to a marked location, use @kbd{C-u
+C-@key{SPC}} (or @kbd{C-u C-@@}); this is the command
+@code{set-mark-command} given a numeric argument. It moves point to
+where the mark was, and restores the mark from the ring of former
+marks. Thus, repeated use of this command moves point to all of the old
+marks on the ring, one by one. The mark positions you move through in
+this way are not lost; they go to the end of the ring.
+
+ Each buffer has its own mark ring. All editing commands use the current
+buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} always stays in
+the same buffer.
+
+ Many commands that can move long distances, such as @kbd{M-<}
+(@code{beginning-of-buffer}), start by setting the mark and saving the
+old mark on the mark ring. This is to make it easier for you to move
+back later. Searches set the mark if they move point. You can tell
+when a command sets the mark because it displays @samp{Mark Set} in the
+echo area.
+
+ If you want to move back to the same place over and over, the mark
+ring may not be convenient enough. If so, you can record the position
+in a register for later retrieval (@pxref{RegPos}).
+
+@vindex mark-ring-max
+ The variable @code{mark-ring-max} specifies the maximum number of
+entries to keep in the mark ring. If that many entries exist and
+another one is pushed, the last one in the list is discarded. Repeating
+@kbd{C-u C-@key{SPC}} cycles through the positions currently in the
+ring.
+
+@vindex mark-ring
+ The variable @code{mark-ring} holds the mark ring itself, as a list of
+marker objects, with the most recent first. This variable is local in
+every buffer.
+
+@node Global Mark Ring
+@section The Global Mark Ring
+@cindex global mark ring
+
+ In addition to the ordinary mark ring that belongs to each buffer,
+Emacs has a single @dfn{global mark ring}. It records a sequence of
+buffers in which you have recently set the mark, so you can go back
+to those buffers.
+
+ Setting the mark always makes an entry on the current buffer's mark
+ring. If you have switched buffers since the previous mark setting, the
+new mark position makes an entry on the global mark ring also. The
+result is that the global mark ring records a sequence of buffers that
+you have been in, and, for each buffer, a place where you set the mark.
+
+@kindex C-x C-@key{SPC}
+@findex pop-global-mark
+ The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to
+the buffer and position of the latest entry in the global ring. It also
+rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take
+you to earlier and earlier buffers.
+
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+
+@setfilename ../info/message
+@settitle Message 5.7 Manual
+@synindex fn cp
+@synindex vr cp
+@synindex pg cp
+@direntry
+* Message: (message). Mail and news composition mode that goes with Gnus.
+@end direntry
+@iftex
+@finalout
+@end iftex
+@setchapternewpage odd
+
+@ifinfo
+
+This file documents Message, the Emacs message composition mode.
+
+Copyright (C) 1996 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ifinfo
+
+@tex
+
+@titlepage
+@title Message 5.7 Manual
+
+@author by Lars Magne Ingebrigtsen
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1996 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+
+@end titlepage
+@page
+
+@end tex
+
+@node Top
+@top Message
+
+All message composition from Gnus (both mail and news) takes place in
+Message mode buffers.
+
+@menu
+* Interface:: Setting up message buffers.
+* Commands:: Commands you can execute in message mode buffers.
+* Variables:: Customizing the message buffers.
+* Compatibility:: Making Message backwards compatible.
+* Appendices:: More technical things.
+* Index:: Variable, function and concept index.
+* Key Index:: List of Message mode keys.
+@end menu
+
+This manual corresponds to Message 5.7. Message is distributed with
+the Gnus distribution bearing the same version number as this manual
+has.
+
+
+@node Interface
+@chapter Interface
+
+When a program (or a person) wants to respond to a message -- reply,
+follow up, forward, cancel -- the program (or person) should just put
+point in the buffer where the message is and call the required command.
+@code{Message} will then pop up a new @code{message} mode buffer with
+appropriate headers filled out, and the user can edit the message before
+sending it.
+
+@menu
+* New Mail Message:: Editing a brand new mail message.
+* New News Message:: Editing a brand new news message.
+* Reply:: Replying via mail.
+* Wide Reply:: Responding to all people via mail.
+* Followup:: Following up via news.
+* Canceling News:: Canceling a news article.
+* Superseding:: Superseding a message.
+* Forwarding:: Forwarding a message via news or mail.
+* Resending:: Resending a mail message.
+* Bouncing:: Bouncing a mail message.
+@end menu
+
+
+@node New Mail Message
+@section New Mail Message
+
+@findex message-mail
+The @code{message-mail} command pops up a new message buffer.
+
+Two optional parameters are accepted: The first will be used as the
+@code{To} header and the second as the @code{Subject} header. If these
+are @code{nil}, those two headers will be empty.
+
+
+@node New News Message
+@section New News Message
+
+@findex message-news
+The @code{message-news} command pops up a new message buffer.
+
+This function accepts two optional parameters. The first will be used
+as the @code{Newsgroups} header and the second as the @code{Subject}
+header. If these are @code{nil}, those two headers will be empty.
+
+
+@node Reply
+@section Reply
+
+@findex message-reply
+The @code{message-reply} function pops up a message buffer that's a
+reply to the message in the current buffer.
+
+@vindex message-reply-to-function
+Message uses the normal methods to determine where replies are to go
+(@pxref{Responses}), but you can change the behavior to suit your needs
+by fiddling with the @code{message-reply-to-function} variable.
+
+If you want the replies to go to the @code{Sender} instead of the
+@code{From}, you could do something like this:
+
+@lisp
+(setq message-reply-to-function
+ (lambda ()
+ (cond ((equal (mail-fetch-field "from") "somebody")
+ (mail-fetch-field "sender"))
+ (t
+ nil))))
+@end lisp
+
+This function will be called narrowed to the head of the article that is
+being replied to.
+
+As you can see, this function should return a string if it has an
+opinion as to what the To header should be. If it does not, it should
+just return @code{nil}, and the normal methods for determining the To
+header will be used.
+
+This function can also return a list. In that case, each list element
+should be a cons, where the car should be the name of an header
+(eg. @code{Cc}) and the cdr should be the header value
+(eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into
+the head of the outgoing mail.
+
+
+@node Wide Reply
+@section Wide Reply
+
+@findex message-wide-reply
+The @code{message-wide-reply} pops up a message buffer that's a wide
+reply to the message in the current buffer. A @dfn{wide reply} is a
+reply that goes out to all people listed in the @code{To}, @code{From}
+(or @code{Reply-to}) and @code{Cc} headers.
+
+@vindex message-wide-reply-to-function
+Message uses the normal methods to determine where wide replies are to go,
+but you can change the behavior to suit your needs by fiddling with the
+@code{message-wide-reply-to-function}. It is used in the same way as
+@code{message-reply-to-function} (@pxref{Reply}).
+
+@findex rmail-dont-reply-to-names
+Addresses that match the @code{rmail-dont-reply-to-names} regular
+expression will be removed from the @code{Cc} header.
+
+
+@node Followup
+@section Followup
+
+@findex message-followup
+The @code{message-followup} command pops up a message buffer that's a
+followup to the message in the current buffer.
+
+@vindex message-followup-to-function
+Message uses the normal methods to determine where followups are to go,
+but you can change the behavior to suit your needs by fiddling with the
+@code{message-followup-to-function}. It is used in the same way as
+@code{message-reply-to-function} (@pxref{Reply}).
+
+@vindex message-use-followup-to
+The @code{message-use-followup-to} variable says what to do about
+@code{Followup-To} headers. If it is @code{use}, always use the value.
+If it is @code{ask} (which is the default), ask whether to use the
+value. If it is @code{t}, use the value unless it is @samp{poster}. If
+it is @code{nil}, don't use the value.
+
+
+@node Canceling News
+@section Canceling News
+
+@findex message-cancel-news
+The @code{message-cancel-news} command cancels the article in the
+current buffer.
+
+
+@node Superseding
+@section Superseding
+
+@findex message-supersede
+The @code{message-supersede} command pops up a message buffer that will
+supersede the message in the current buffer.
+
+@vindex message-ignored-supersedes-headers
+Headers matching the @code{message-ignored-supersedes-headers} are
+removed before popping up the new message buffer. The default is@*
+@samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@*
+^Received:\\|^X-From-Line:\\|Return-Path:\\|^Supersedes:}.
+
+
+
+@node Forwarding
+@section Forwarding
+
+@findex message-forward
+The @code{message-forward} command pops up a message buffer to forward
+the message in the current buffer. If given a prefix, forward using
+news.
+
+@table @code
+@item message-forward-start-separator
+@vindex message-forward-start-separator
+Delimiter inserted before forwarded messages. The default is@*
+@samp{------- Start of forwarded message -------\n}.
+
+@vindex message-forward-end-separator
+@item message-forward-end-separator
+@vindex message-forward-end-separator
+Delimiter inserted after forwarded messages. The default is@*
+@samp{------- End of forwarded message -------\n}.
+
+@item message-signature-before-forwarded-message
+@vindex message-signature-before-forwarded-message
+If this variable is @code{t}, which it is by default, your personal
+signature will be inserted before the forwarded message. If not, the
+forwarded message will be inserted first in the new mail.
+
+@item message-included-forward-headers
+@vindex message-included-forward-headers
+Regexp matching header lines to be included in forwarded messages.
+
+@item message-make-forward-subject-function
+@vindex message-make-forward-subject-function
+A list of functions that are called to generate a subject header for
+forwarded messages. The subject generated by the previous function is
+passed into each successive function.
+
+The provided functions are:
+
+@table @code
+@item message-forward-subject-author-subject
+@findex message-forward-subject-author-subject
+Source of article (author or newsgroup), in brackets followed by the
+subject.
+
+@item message-forward-subject-fwd
+Subject of article with @samp{Fwd:} prepended to it.
+@end table
+
+@item message-wash-forwarded-subjects
+@vindex message-wash-forwarded-subjects
+If this variable is @code{t}, the subjects of forwarded messages have
+the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:},
+@samp{(fwd)}) removed before the new subject is
+constructed. The default value is @code{nil}.
+
+@end table
+
+
+@node Resending
+@section Resending
+
+@findex message-resend
+The @code{message-resend} command will prompt the user for an address
+and resend the message in the current buffer to that address.
+
+@vindex message-ignored-resent-headers
+Headers that match the @code{message-ignored-resent-headers} regexp will
+be removed before sending the message. The default is
+@samp{^Return-receipt}.
+
+
+@node Bouncing
+@section Bouncing
+
+@findex message-bounce
+The @code{message-bounce} command will, if the current buffer contains a
+bounced mail message, pop up a message buffer stripped of the bounce
+information. A @dfn{bounced message} is typically a mail you've sent
+out that has been returned by some @code{mailer-daemon} as
+undeliverable.
+
+@vindex message-ignored-bounced-headers
+Headers that match the @code{message-ignored-bounced-headers} regexp
+will be removed before popping up the buffer. The default is
+@samp{^\\(Received\\|Return-Path\\):}.
+
+
+@node Commands
+@chapter Commands
+
+@menu
+* Header Commands:: Commands for moving to headers.
+* Movement:: Moving around in message buffers.
+* Insertion:: Inserting things into message buffers.
+* Various Commands:: Various things.
+* Sending:: Actually sending the message.
+* Mail Aliases:: How to use mail aliases.
+@end menu
+
+
+@node Header Commands
+@section Header Commands
+
+All these commands move to the header in question. If it doesn't exist,
+it will be inserted.
+
+@table @kbd
+
+@item C-c ?
+@kindex C-c ?
+@findex message-goto-to
+Describe the message mode.
+
+@item C-c C-f C-t
+@kindex C-c C-f C-t
+@findex message-goto-to
+Go to the @code{To} header (@code{message-goto-to}).
+
+@item C-c C-f C-b
+@kindex C-c C-f C-b
+@findex message-goto-bcc
+Go to the @code{Bcc} header (@code{message-goto-bcc}).
+
+@item C-c C-f C-f
+@kindex C-c C-f C-f
+@findex message-goto-fcc
+Go to the @code{Fcc} header (@code{message-goto-fcc}).
+
+@item C-c C-f C-c
+@kindex C-c C-f C-c
+@findex message-goto-cc
+Go to the @code{Cc} header (@code{message-goto-cc}).
+
+@item C-c C-f C-s
+@kindex C-c C-f C-s
+@findex message-goto-subject
+Go to the @code{Subject} header (@code{message-goto-subject}).
+
+@item C-c C-f C-r
+@kindex C-c C-f C-r
+@findex message-goto-reply-to
+Go to the @code{Reply-To} header (@code{message-goto-reply-to}).
+
+@item C-c C-f C-n
+@kindex C-c C-f C-n
+@findex message-goto-newsgroups
+Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}).
+
+@item C-c C-f C-d
+@kindex C-c C-f C-d
+@findex message-goto-distribution
+Go to the @code{Distribution} header (@code{message-goto-distribution}).
+
+@item C-c C-f C-o
+@kindex C-c C-f C-o
+@findex message-goto-followup-to
+Go to the @code{Followup-To} header (@code{message-goto-followup-to}).
+
+@item C-c C-f C-k
+@kindex C-c C-f C-k
+@findex message-goto-keywords
+Go to the @code{Keywords} header (@code{message-goto-keywords}).
+
+@item C-c C-f C-u
+@kindex C-c C-f C-u
+@findex message-goto-summary
+Go to the @code{Summary} header (@code{message-goto-summary}).
+
+@end table
+
+
+@node Movement
+@section Movement
+
+@table @kbd
+@item C-c C-b
+@kindex C-c C-b
+@findex message-goto-body
+Move to the beginning of the body of the message
+(@code{message-goto-body}).
+
+@item C-c C-i
+@kindex C-c C-i
+@findex message-goto-signature
+Move to the signature of the message (@code{message-goto-signature}).
+
+@end table
+
+
+@node Insertion
+@section Insertion
+
+@table @kbd
+
+@item C-c C-y
+@kindex C-c C-y
+@findex message-yank-original
+Yank the message that's being replied to into the message buffer
+(@code{message-yank-original}).
+
+@item C-c C-q
+@kindex C-c C-q
+@findex message-fill-yanked-message
+Fill the yanked message (@code{message-fill-yanked-message}). Warning:
+Can severely mess up the yanked text if its quoting conventions are
+strange. You'll quickly get a feel for when it's safe, though. Anyway,
+just remember that @kbd{C-x u} (@code{undo}) is available and you'll be
+all right.
+
+
+@item C-c C-w
+@kindex C-c C-w
+@findex message-insert-signature
+Insert a signature at the end of the buffer
+(@code{message-insert-signature}).
+
+@end table
+
+@table @code
+@item message-ignored-cited-headers
+@vindex message-ignored-cited-headers
+All headers that match this regexp will be removed from yanked
+messages. The default is @samp{.}, which means that all headers will be
+removed.
+
+@item message-citation-line-function
+@vindex message-citation-line-function
+Function called to insert the citation line. The default is
+@code{message-insert-citation-line}, which will lead to citation lines
+that look like:
+
+@example
+Hallvard B Furuseth <h.b.furuseth@@usit.uio.no> writes:
+@end example
+
+Point will be at the beginning of the body of the message when this
+function is called.
+
+@item message-yank-prefix
+@vindex message-yank-prefix
+@cindex yanking
+@cindex quoting
+When you are replying to or following up an article, you normally want
+to quote the person you are answering. Inserting quoted text is done by
+@dfn{yanking}, and each quoted line you yank will have
+@code{message-yank-prefix} prepended to it. The default is @samp{> }.
+If it is @code{nil}, just indent the message.
+
+@item message-indentation-spaces
+@vindex message-indentation-spaces
+Number of spaces to indent yanked messages.
+
+@item message-cite-function
+@vindex message-cite-function
+@findex message-cite-original
+@findex sc-cite-original
+@findex message-cite-original-without-signature
+@cindex Supercite
+Function for citing an original message. The default is
+@code{message-cite-original}, which simply inserts the original message
+and prepends @samp{> } to each line.
+@code{message-cite-original-without-signature} does the same, but elides
+the signature. You can also set it to @code{sc-cite-original} to use
+Supercite.
+
+@item message-indent-citation-function
+@vindex message-indent-citation-function
+Function for modifying a citation just inserted in the mail buffer.
+This can also be a list of functions. Each function can find the
+citation between @code{(point)} and @code{(mark t)}. And each function
+should leave point and mark around the citation text as modified.
+
+@item message-signature
+@vindex message-signature
+String to be inserted at the end of the message buffer. If @code{t}
+(which is the default), the @code{message-signature-file} file will be
+inserted instead. If a function, the result from the function will be
+used instead. If a form, the result from the form will be used instead.
+If this variable is @code{nil}, no signature will be inserted at all.
+
+@item message-signature-file
+@vindex message-signature-file
+File containing the signature to be inserted at the end of the buffer.
+The default is @samp{~/.signature}.
+
+@end table
+
+Note that RFC1036bis says that a signature should be preceded by the three
+characters @samp{-- } on a line by themselves. This is to make it
+easier for the recipient to automatically recognize and process the
+signature. So don't remove those characters, even though you might feel
+that they ruin your beautiful design, like, totally.
+
+Also note that no signature should be more than four lines long.
+Including ASCII graphics is an efficient way to get everybody to believe
+that you are silly and have nothing important to say.
+
+
+
+@node Various Commands
+@section Various Commands
+
+@table @kbd
+
+@item C-c C-r
+@kindex C-c C-r
+@findex message-caesar-buffer-body
+Caesar rotate (aka. rot13) the current message
+(@code{message-caesar-buffer-body}). If narrowing is in effect, just
+rotate the visible portion of the buffer. A numerical prefix says how
+many places to rotate the text. The default is 13.
+
+@item C-c C-e
+@kindex C-c C-e
+@findex message-elide-region
+Elide the text between point and mark (@code{message-elide-region}).
+The text is killed and an ellipsis (@samp{[...]}) will be inserted in
+its place.
+
+@item C-c C-z
+@kindex C-c C-x
+@findex message-kill-to-signature
+Kill all the text up to the signature, or if that's missing, up to the
+end of the message (@code{message-kill-to-signature}).
+
+@item C-c C-v
+@kindex C-c C-v
+@findex message-delete-not-region
+Delete all text in the body of the message that is outside the region
+(@code{message-delete-not-region}).
+
+@item M-RET
+@kindex M-RET
+@kindex message-newline-and-reformat
+Insert four newlines, and then reformat if inside quoted text.
+
+Here's an example:
+
+@example
+> This is some quoted text. And here's more quoted text.
+@end example
+
+If point is before @samp{And} and you press @kbd{M-RET}, you'll get:
+
+@example
+> This is some quoted text.
+
+*
+
+> And here's more quoted text.
+@end example
+
+@samp{*} says where point will be placed.
+
+@item C-c C-t
+@kindex C-c C-t
+@findex message-insert-to
+Insert a @code{To} header that contains the @code{Reply-To} or
+@code{From} header of the message you're following up
+(@code{message-insert-to}).
+
+@item C-c C-n
+@kindex C-c C-n
+@findex message-insert-newsgroups
+Insert a @code{Newsgroups} header that reflects the @code{Followup-To}
+or @code{Newsgroups} header of the article you're replying to
+(@code{message-insert-newsgroups}).
+
+@item C-c M-r
+@kindex C-c M-r
+@findex message-rename-buffer
+Rename the buffer (@code{message-rename-buffer}). If given a prefix,
+prompt for a new buffer name.
+
+@end table
+
+
+@node Sending
+@section Sending
+
+@table @kbd
+@item C-c C-c
+@kindex C-c C-c
+@findex message-send-and-exit
+Send the message and bury the current buffer
+(@code{message-send-and-exit}).
+
+@item C-c C-s
+@kindex C-c C-s
+@findex message-send
+Send the message (@code{message-send}).
+
+@item C-c C-d
+@kindex C-c C-d
+@findex message-dont-send
+Bury the message buffer and exit (@code{message-dont-send}).
+
+@item C-c C-k
+@kindex C-c C-k
+@findex message-kill-buffer
+Kill the message buffer and exit (@code{message-kill-buffer}).
+
+@end table
+
+
+
+@node Mail Aliases
+@section Mail Aliases
+@cindex mail aliases
+@cindex aliases
+
+@vindex message-mail-alias-type
+The @code{message-mail-alias-type} variable controls what type of mail
+alias expansion to use. Currently only one form is supported---Message
+uses @code{mailabbrev} to handle mail aliases. If this variable is
+@code{nil}, no mail alias expansion will be performed.
+
+@code{mailabbrev} works by parsing the @file{/etc/mailrc} and
+@file{~/.mailrc} files. These files look like:
+
+@example
+alias lmi "Lars Magne Ingebrigtsen <larsi@@ifi.uio.no>"
+alias ding "ding@@ifi.uio.no (ding mailing list)"
+@end example
+
+After adding lines like this to your @file{~/.mailrc} file, you should
+be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so
+on) headers and press @kbd{SPC} to expand the alias.
+
+No expansion will be performed upon sending of the message---all
+expansions have to be done explicitly.
+
+
+
+@node Variables
+@chapter Variables
+
+@menu
+* Message Headers:: General message header stuff.
+* Mail Headers:: Customizing mail headers.
+* Mail Variables:: Other mail variables.
+* News Headers:: Customizing news headers.
+* News Variables:: Other news variables.
+* Various Message Variables:: Other message variables.
+* Sending Variables:: Variables for sending.
+* Message Buffers:: How Message names its buffers.
+* Message Actions:: Actions to be performed when exiting.
+@end menu
+
+
+@node Message Headers
+@section Message Headers
+
+Message is quite aggressive on the message generation front. It has to
+be -- it's a combined news and mail agent. To be able to send combined
+messages, it has to generate all headers itself (instead of letting the
+mail/news system do it) to ensure that mail and news copies of messages
+look sufficiently similar.
+
+@table @code
+
+@item message-generate-headers-first
+@vindex message-generate-headers-first
+If non-@code{nil}, generate all headers before starting to compose the
+message.
+
+@item message-from-style
+@vindex message-from-style
+Specifies how @code{From} headers should look. There are four valid
+values:
+
+@table @code
+@item nil
+Just the address -- @samp{king@@grassland.com}.
+
+@item parens
+@samp{king@@grassland.com (Elvis Parsley)}.
+
+@item angles
+@samp{Elvis Parsley <king@@grassland.com>}.
+
+@item default
+Look like @code{angles} if that doesn't require quoting, and
+@code{parens} if it does. If even @code{parens} requires quoting, use
+@code{angles} anyway.
+
+@end table
+
+@item message-deletable-headers
+@vindex message-deletable-headers
+Headers in this list that were previously generated by Message will be
+deleted before posting. Let's say you post an article. Then you decide
+to post it again to some other group, you naughty boy, so you jump back
+to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
+ship it off again. By default, this variable makes sure that the old
+generated @code{Message-ID} is deleted, and a new one generated. If
+this isn't done, the entire empire would probably crumble, anarchy would
+prevail, and cats would start walking on two legs and rule the world.
+Allegedly.
+
+@item message-default-headers
+@vindex message-default-headers
+This string is inserted at the end of the headers in all message
+buffers.
+
+@item message-subject-re-regexp
+@vindex message-subject-re-regexp
+Responses to messages have subjects that start with @samp{Re: }. This
+is @emph{not} an abbreviation of the English word ``response'', but in
+Latin, and means ``in response to''. Some illiterate nincompoops have
+failed to grasp this fact, and have ``internationalized'' their software
+to use abonimations like @samp{Aw: } (``antwort'') or @samp{Sv: }
+(``svar'') instead, which is meaningless and evil. However, you may
+have to deal with users that use these evil tools, in which case you may
+set this variable to a regexp that matches these prefixes. Myself, I
+just throw away non-compliant mail.
+
+@end table
+
+
+@node Mail Headers
+@section Mail Headers
+
+@table @code
+@item message-required-mail-headers
+@vindex message-required-mail-headers
+@xref{News Headers}, for the syntax of this variable. It is
+@code{(From Date Subject (optional . In-Reply-To) Message-ID Lines
+(optional . X-Mailer))} by default.
+
+@item message-ignored-mail-headers
+@vindex message-ignored-mail-headers
+Regexp of headers to be removed before mailing. The default is
+@samp{^[GF]cc:\\|^Resent-Fcc:}.
+
+@item message-default-mail-headers
+@vindex message-default-mail-headers
+This string is inserted at the end of the headers in all message
+buffers that are initialized as mail.
+
+@end table
+
+
+@node Mail Variables
+@section Mail Variables
+
+@table @code
+@item message-send-mail-function
+@vindex message-send-mail-function
+Function used to send the current buffer as mail. The default is
+@code{message-send-mail-with-sendmail}. If you prefer using MH
+instead, set this variable to @code{message-send-mail-with-mh}.
+
+@item message-mh-deletable-headers
+@vindex message-mh-deletable-headers
+Most versions of MH doesn't like being fed messages that contain the
+headers in this variable. If this variable is non-@code{nil} (which is
+the default), these headers will be removed before mailing when sending
+messages via MH. Set it to @code{nil} if your MH can handle these
+headers.
+
+@end table
+
+
+@node News Headers
+@section News Headers
+
+@vindex message-required-news-headers
+@code{message-required-news-headers} a list of header symbols. These
+headers will either be automatically generated, or, if that's
+impossible, they will be prompted for. The following symbols are valid:
+
+@table @code
+
+@item From
+@cindex From
+@findex user-full-name
+@findex user-mail-address
+This required header will be filled out with the result of the
+@code{message-make-from} function, which depends on the
+@code{message-from-style}, @code{user-full-name},
+@code{user-mail-address} variables.
+
+@item Subject
+@cindex Subject
+This required header will be prompted for if not present already.
+
+@item Newsgroups
+@cindex Newsgroups
+This required header says which newsgroups the article is to be posted
+to. If it isn't present already, it will be prompted for.
+
+@item Organization
+@cindex organization
+This optional header will be filled out depending on the
+@code{message-user-organization} variable.
+@code{message-user-organization-file} will be used if this variable is
+@code{t}. This variable can also be a string (in which case this string
+will be used), or it can be a function (which will be called with no
+parameters and should return a string to be used).
+
+@item Lines
+@cindex Lines
+This optional header will be computed by Message.
+
+@item Message-ID
+@cindex Message-ID
+@vindex mail-host-address
+@findex system-name
+@cindex Sun
+This required header will be generated by Message. A unique ID will be
+created based on the date, time, user name and system name. Message will
+use @code{mail-host-address} as the fully qualified domain name (FQDN)
+of the machine if that variable is defined. If not, it will use
+@code{system-name}, which doesn't report a FQDN on some machines --
+notably Suns.
+
+@item X-Newsreader
+@cindex X-Newsreader
+This optional header will be filled out according to the
+@code{message-newsreader} local variable.
+
+@item X-Mailer
+This optional header will be filled out according to the
+@code{message-mailer} local variable, unless there already is an
+@code{X-Newsreader} header present.
+
+@item In-Reply-To
+This optional header is filled out using the @code{Date} and @code{From}
+header of the article being replied to.
+
+@item Expires
+@cindex Expires
+This extremely optional header will be inserted according to the
+@code{message-expires} variable. It is highly deprecated and shouldn't
+be used unless you know what you're doing.
+
+@item Distribution
+@cindex Distribution
+This optional header is filled out according to the
+@code{message-distribution-function} variable. It is a deprecated and
+much misunderstood header.
+
+@item Path
+@cindex path
+This extremely optional header should probably never be used.
+However, some @emph{very} old servers require that this header is
+present. @code{message-user-path} further controls how this
+@code{Path} header is to look. If it is @code{nil}, use the server name
+as the leaf node. If it is a string, use the string. If it is neither
+a string nor @code{nil}, use the user name only. However, it is highly
+unlikely that you should need to fiddle with this variable at all.
+@end table
+
+@findex yow
+@cindex Mime-Version
+In addition, you can enter conses into this list. The car of this cons
+should be a symbol. This symbol's name is the name of the header, and
+the cdr can either be a string to be entered verbatim as the value of
+this header, or it can be a function to be called. This function should
+return a string to be inserted. For instance, if you want to insert
+@code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
+into the list. If you want to insert a funny quote, you could enter
+something like @code{(X-Yow . yow)} into the list. The function
+@code{yow} will then be called without any arguments.
+
+If the list contains a cons where the car of the cons is
+@code{optional}, the cdr of this cons will only be inserted if it is
+non-@code{nil}.
+
+Other variables for customizing outgoing news articles:
+
+@table @code
+
+@item message-syntax-checks
+@vindex message-syntax-checks
+Controls what syntax checks should not be performed on outgoing posts.
+To disable checking of long signatures, for instance, add
+
+@lisp
+(signature . disabled)
+@end lisp
+
+to this list.
+
+Valid checks are:
+
+@table @code
+@item subject-cmsg
+Check the subject for commands.
+@item sender
+@cindex Sender
+Insert a new @code{Sender} header if the @code{From} header looks odd.
+@item multiple-headers
+Check for the existence of multiple equal headers.
+@item sendsys
+@cindex sendsys
+Check for the existence of version and sendsys commands.
+@item message-id
+Check whether the @code{Message-ID} looks ok.
+@item from
+Check whether the @code{From} header seems nice.
+@item long-lines
+@cindex long lines
+Check for too long lines.
+@item control-chars
+Check for invalid characters.
+@item size
+Check for excessive size.
+@item new-text
+Check whether there is any new text in the messages.
+@item signature
+Check the length of the signature.
+@item approved
+@cindex approved
+Check whether the article has an @code{Approved} header, which is
+something only moderators should include.
+@item empty
+Check whether the article is empty.
+@item empty-headers
+Check whether any of the headers are empty.
+@item existing-newsgroups
+Check whether the newsgroups mentioned in the @code{Newsgroups} and
+@code{Followup-To} headers exist.
+@item valid-newsgroups
+Check whether the @code{Newsgroups} and @code{Followup-to} headers
+are valid syntactically.
+@item repeated-newsgroups
+Check whether the @code{Newsgroups} and @code{Followup-to} headers
+contains repeated group names.
+@item shorten-followup-to
+Check whether to add a @code{Followup-to} header to shorten the number
+of groups to post to.
+@end table
+
+All these conditions are checked by default.
+
+@item message-ignored-news-headers
+@vindex message-ignored-news-headers
+Regexp of headers to be removed before posting. The default is@*
+@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:}.
+
+@item message-default-news-headers
+@vindex message-default-news-headers
+This string is inserted at the end of the headers in all message
+buffers that are initialized as news.
+
+@end table
+
+
+@node News Variables
+@section News Variables
+
+@table @code
+@item message-send-news-function
+@vindex message-send-news-function
+Function used to send the current buffer as news. The default is
+@code{message-send-news}.
+
+@item message-post-method
+@vindex message-post-method
+Gnusish @dfn{select method} (see the Gnus manual for details) used for
+posting a prepared news message.
+
+@end table
+
+
+@node Various Message Variables
+@section Various Message Variables
+
+@table @code
+@item message-signature-separator
+@vindex message-signature-separator
+Regexp matching the signature separator. It is @samp{^-- *$} by
+default.
+
+@item mail-header-separator
+@vindex mail-header-separator
+String used to separate the headers from the body. It is @samp{--text
+follows this line--} by default.
+
+@item message-directory
+@vindex message-directory
+Directory used by many mailey things. The default is @file{~/Mail/}.
+
+@item message-signature-setup-hook
+@vindex message-signature-setup-hook
+Hook run when initializing the message buffer. It is run after the
+headers have been inserted but before the signature has been inserted.
+
+@item message-setup-hook
+@vindex message-setup-hook
+Hook run as the last thing when the message buffer has been initialized,
+but before yanked text is inserted.
+
+@item message-header-setup-hook
+@vindex message-header-setup-hook
+Hook called narrowed to the headers after initializing the headers.
+
+For instance, if you're running Gnus and wish to insert a
+@samp{Mail-Copies-To} header in all your news articles and all messages
+you send to mailing lists, you could do something like the following:
+
+@lisp
+(defun my-message-header-setup-hook ()
+ (let ((group (or gnus-newsgroup-name "")))
+ (when (or (message-fetch-field "newsgroups")
+ (gnus-group-find-parameter group 'to-address)
+ (gnus-group-find-parameter group 'to-list))
+ (insert "Mail-Copies-To: never\n"))))
+
+(add-hook 'message-header-setup-hook
+ 'my-message-header-setup-hook)
+@end lisp
+
+@item message-send-hook
+@vindex message-send-hook
+Hook run before sending messages.
+
+If you want to add certain headers before sending, you can use the
+@code{message-add-header} function in this hook. For instance:
+@findex message-add-header
+
+@lisp
+(add-hook 'message-send-hook 'my-message-add-content)
+(defun my-message-add-content ()
+ (message-add-header
+ "Mime-Version: 1.0"
+ "Content-Type: text/plain"
+ "Content-Transfer-Encoding: 7bit"))
+@end lisp
+
+This function won't add the header if the header is already present.
+
+@item message-send-mail-hook
+@vindex message-send-mail-hook
+Hook run before sending mail messages.
+
+@item message-send-news-hook
+@vindex message-send-news-hook
+Hook run before sending news messages.
+
+@item message-sent-hook
+@vindex message-sent-hook
+Hook run after sending messages.
+
+@item message-mode-syntax-table
+@vindex message-mode-syntax-table
+Syntax table used in message mode buffers.
+
+@item message-send-method-alist
+@vindex message-send-method-alist
+
+Alist of ways to send outgoing messages. Each element has the form
+
+@lisp
+(TYPE PREDICATE FUNCTION)
+@end lisp
+
+@table @var
+@item type
+A symbol that names the method.
+
+@item predicate
+A function called without any parameters to determine whether the
+message is a message of type @var{type}.
+
+@item function
+A function to be called if @var{predicate} returns non-@code{nil}.
+@var{function} is called with one parameter -- the prefix.
+@end table
+
+@lisp
+((news message-news-p message-send-via-news)
+ (mail message-mail-p message-send-via-mail))
+@end lisp
+
+
+
+@end table
+
+
+
+@node Sending Variables
+@section Sending Variables
+
+@table @code
+
+@item message-fcc-handler-function
+@vindex message-fcc-handler-function
+A function called to save outgoing articles. This function will be
+called with the name of the file to store the article in. The default
+function is @code{message-output} which saves in Unix mailbox format.
+
+@item message-courtesy-message
+@vindex message-courtesy-message
+When sending combined messages, this string is inserted at the start of
+the mailed copy. If the string contains the format spec @samp{%s}, the
+newsgroups the article has been posted to will be inserted there. If
+this variable is @code{nil}, no such courtesy message will be added.
+The default value is @samp{"The following message is a courtesy copy of
+an article\nthat has been posted to %s as well.\n\n"}.
+
+@end table
+
+
+@node Message Buffers
+@section Message Buffers
+
+Message will generate new buffers with unique buffer names when you
+request a message buffer. When you send the message, the buffer isn't
+normally killed off. Its name is changed and a certain number of old
+message buffers are kept alive.
+
+@table @code
+@item message-generate-new-buffers
+@vindex message-generate-new-buffers
+If non-@code{nil}, generate new buffers. The default is @code{t}. If
+this is a function, call that function with three parameters: The type,
+the to address and the group name. (Any of these may be @code{nil}.)
+The function should return the new buffer name.
+
+@item message-max-buffers
+@vindex message-max-buffers
+This variable says how many old message buffers to keep. If there are
+more message buffers than this, the oldest buffer will be killed. The
+default is 10. If this variable is @code{nil}, no old message buffers
+will ever be killed.
+
+@item message-send-rename-function
+@vindex message-send-rename-function
+After sending a message, the buffer is renamed from, for instance,
+@samp{*reply to Lars*} to @samp{*sent reply to Lars*}. If you don't
+like this, set this variable to a function that renames the buffer in a
+manner you like. If you don't want to rename the buffer at all, you can
+say:
+
+@lisp
+(setq message-send-rename-function 'ignore)
+@end lisp
+
+@item message-kill-buffer-on-exit
+@findex message-kill-buffer-on-exit
+If non-@code{nil}, kill the buffer immediately on exit.
+
+@end table
+
+
+@node Message Actions
+@section Message Actions
+
+When Message is being used from a news/mail reader, the reader is likely
+to want to perform some task after the message has been sent. Perhaps
+return to the previous window configuration or mark an article as
+replied.
+
+@vindex message-kill-actions
+@vindex message-postpone-actions
+@vindex message-exit-actions
+@vindex message-send-actions
+The user may exit from the message buffer in various ways. The most
+common is @kbd{C-c C-c}, which sends the message and exits. Other
+possibilities are @kbd{C-c C-s} which just sends the message, @kbd{C-c
+C-d} which postpones the message editing and buries the message buffer,
+and @kbd{C-c C-k} which kills the message buffer. Each of these actions
+have lists associated with them that contains actions to be executed:
+@code{message-send-actions}, @code{message-exit-actions},
+@code{message-postpone-actions}, and @code{message-kill-actions}.
+
+Message provides a function to interface with these lists:
+@code{message-add-action}. The first parameter is the action to be
+added, and the rest of the arguments are which lists to add this action
+to. Here's an example from Gnus:
+
+@lisp
+ (message-add-action
+ `(set-window-configuration ,(current-window-configuration))
+ 'exit 'postpone 'kill)
+@end lisp
+
+This restores the Gnus window configuration when the message buffer is
+killed, postponed or exited.
+
+An @dfn{action} can be either: a normal function, or a list where the
+@code{car} is a function and the @code{cdr} is the list of arguments, or
+a form to be @code{eval}ed.
+
+
+@node Compatibility
+@chapter Compatibility
+@cindex compatibility
+
+Message uses virtually only its own variables---older @code{mail-}
+variables aren't consulted. To force Message to take those variables
+into account, you can put the following in your @code{.emacs} file:
+
+@lisp
+(require 'messcompat)
+@end lisp
+
+This will initialize many Message variables from the values in the
+corresponding mail variables.
+
+
+@node Appendices
+@chapter Appendices
+
+@menu
+* Responses:: Standard rules for determining where responses go.
+@end menu
+
+
+@node Responses
+@section Responses
+
+To determine where a message is to go, the following algorithm is used
+by default.
+
+@table @dfn
+@item reply
+A @dfn{reply} is when you want to respond @emph{just} to the person who
+sent the message via mail. There will only be one recipient. To
+determine who the recipient will be, the following headers are
+consulted, in turn:
+
+@table @code
+@item Reply-To
+
+@item From
+@end table
+
+
+@item wide reply
+A @dfn{wide reply} is a mail response that includes @emph{all} entities
+mentioned in the message you are responded to. All mailboxes from the
+following headers will be concatenated to form the outgoing
+@code{To}/@code{Cc} headers:
+
+@table @code
+@item From
+(unless there's a @code{Reply-To}, in which case that is used instead).
+
+@item Cc
+
+@item To
+@end table
+
+If a @code{Mail-Copies-To} header is present, it will also be included
+in the list of mailboxes. If this header is @samp{never}, that means
+that the @code{From} (or @code{Reply-To}) mailbox will be suppressed.
+
+
+@item followup
+A @dfn{followup} is a response sent via news. The following headers
+(listed in order of precedence) determine where the response is to be
+sent:
+
+@table @code
+
+@item Followup-To
+
+@item Newsgroups
+
+@end table
+
+If a @code{Mail-Copies-To} header is present, it will be used as the
+basis of the new @code{Cc} header, except if this header is
+@samp{never}.
+
+@end table
+
+
+
+@node Index
+@chapter Index
+@printindex cp
+
+@node Key Index
+@chapter Key Index
+@printindex ky
+
+@summarycontents
+@contents
+@bye
+
+@c End:
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c $Id: mh-e.texi,v 1.17 95/08/23 07:00:16 wohler Exp $
+@c %**start of header
+@setfilename ../info/mh-e
+@settitle mh-e
+@c %**end of header
+
+@setchapternewpage odd
+
+@dircategory Editors
+@direntry
+* MH-E: (mh-e). Emacs interface to the MH mail system.
+@end direntry
+
+@c Version variables.
+@set EDITION 1.2
+@set VERSION 5.0.2
+@set UPDATED 22 August 1995
+@set UPDATE-MONTH August 1995
+
+@ifinfo
+This is Edition @value{EDITION}, last updated @value{UPDATED}, of
+@cite{mh-e, The Emacs Interface to MH}, for mh-e, Version
+@value{VERSION}.
+
+Copyright 1995 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX
+and print the results, provided the printed document
+carries a copying permission notice identical to this
+one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified
+versions of this manual under the conditions for
+verbatim copying, provided also that the section
+entitled ``Copying''
+is included exactly as in the original, and provided
+that the entire resulting derived work is distributed
+under the terms of a permission notice identical to this
+one.
+
+Permission is granted to copy and distribute
+translations of this manual into another language,
+under the above conditions for modified versions,
+except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+@end ifinfo
+
+@titlepage
+@sp 10
+@center @titlefont{mh-e}
+@sp 2
+@center The Emacs Interface to MH
+@sp 2
+@center by Bill Wohler
+@sp 2
+@center Edition @value{EDITION} for mh-e Version @value{VERSION}
+@sp 2
+@center @value{UPDATE-MONTH}
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1995 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
+Permission is granted to copy and distribute modified
+versions of this manual under the conditions for
+verbatim copying, provided also that the section
+entitled ``The GNU General Public License''
+is included exactly as in the original, and provided
+that the entire resulting derived work is distributed
+under the terms of a permission notice identical to this
+one.
+
+Permission is granted to copy and distribute
+translations of this manual into another language,
+under the above conditions for modified versions,
+except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+@end titlepage
+
+@ifinfo
+@node Top, Preface, (dir), (dir)
+@top MH and Emacs
+This is Edition @value{EDITION} of @cite{mh-e, The Emacs Interface to
+MH}, last updated @value{UPDATED} for mh-e Version @value{VERSION}.
+
+@menu
+* Preface:: Introduction to mh-e.
+* Tour Through mh-e:: Use mh-e quickly!
+* Using mh-e:: Documentation for all commands.
+* Customizing mh-e:: Documentation for all variables.
+* Odds and Ends:: Getting mh-e, reporting bugs, mailing
+ list and FAQ.
+* History:: The authors speak up!
+* Changes to mh-e:: Actual changes between Versions 3 and beyond.
+* Copying:: The GNU General Public License
+* Command Index::
+* Variable Index::
+* Concept Index::
+@end menu
+@end ifinfo
+
+@node Preface, Tour Through mh-e, Top, Top
+@unnumbered Preface
+
+@cindex Emacs
+@cindex Unix commands, Emacs
+
+These chapters introduce another interface to MH that is accessible
+through the GNU Emacs editor, namely, @emph{mh-e}. mh-e is easy to use.
+I don't assume that you know GNU Emacs or even MH at this point, since I
+didn't know either of them when I discovered mh-e. However, mh-e was
+the tip of the iceberg, and I discovered more and more niceties about
+GNU Emacs and MH@. Now I'm fully hooked on both of them.
+
+@cindex history
+
+The mh-e package is distributed with GNU Emacs, @footnote{Note that mh-e
+is supported with MH 6 and either @w{Emacs 18} or @w{Emacs 19}.
+Reportedly, large parts of it work with @w{MH 5} and also with
+Lucid/XEmacs and Epoch, but there are no guarantees. It is also
+distributed with Lucid/XEmacs, as well as with MH itself.} so you shouldn't
+have to do anything special to use it. But it's important to note a
+brief history of mh-e. @w{Version 3} was prevalent through the @w{Emacs
+18} and early @w{Emacs 19} years. Then @w{Version 4} came out (@w{Emacs
+19.23}), which introduced several new and changed commands. Finally,
+@w{Version 5.0} was released, which fixed some bugs and
+incompatibilities. This is the version covered by this manual.
+@ref{Getting Started} will help you decide which version you
+have.
+
+If you don't already use GNU Emacs but want to learn more, you can read
+an online tutorial by starting GNU Emacs and typing @kbd{C-h t}
+(@code{help-with-tutorial}). (This notation is described in
+@ref{Conventions}.) If you want to take the plunge, consult the
+@iftex
+@cite{GNU Emacs Manual},
+@end iftex
+@ifinfo
+@ref{top, , GNU Emacs Manual, emacs, The GNU Emacs Manual},
+@end ifinfo
+from the Free Software Foundation.
+
+If more information is needed, you can go to the Unix manual pages of
+the individual MH commands. When the name is not obvious, I'll guide
+you to a relevant MH manual page that describes the action more fully.
+
+I hope you enjoy these chapters! If you have any comments, or
+suggestions for this document, please let me know.
+
+@noindent
+Bill Wohler <@i{wohler@@newt.com}>@*
+8 February 1995
+
+@node Tour Through mh-e, Using mh-e, Preface, Top
+@chapter Tour Through mh-e
+
+This chapter introduces some of the terms you'll need to know and then
+takes you on a tour of mh-e. @footnote{The keys mentioned in these
+chapters refer to the default key bindings. If you've changed the
+bindings, refer to the command summaries at the beginning of each major
+section in @ref{Using mh-e}, for a mapping between default key bindings
+and function names.} When you're done, you'll be able to send, read,
+and file mail, which is all that a lot of people ever do. But if you're
+the curious type, you'll read @ref{Using mh-e} to be able to use all
+the features of mh-e. If you're the adventurous type, you'll read
+@ref{Customizing mh-e} to make mh-e do what you want. I suggest you
+read this chapter first to get the big picture, and then you can read
+the other two as you wish.
+
+@menu
+* Conventions:: GNU Emacs Terms and Conventions
+* Getting Started::
+* Sending Mail Tour::
+* Reading Mail Tour::
+* Processing Mail Tour::
+* Leaving mh-e::
+* More About mh-e::
+@end menu
+
+@node Conventions, Getting Started, Tour Through mh-e, Tour Through mh-e
+@section GNU Emacs Terms and Conventions
+
+@cindex Emacs, terms and conventions
+
+@cindex Emacs
+@cindex Unix commands, Emacs
+
+If you're an experienced Emacs user, you can skip the following
+conventions and definition of terms and go directly to @ref{Getting
+Started} below. The conventions are as follows:
+
+@table @kbd
+@item C-x
+Hold down the @key{CTRL} (Control) key and press the @kbd{x} key.
+@item M-x
+Hold down the @key{META} or @key{ALT} key and press the @kbd{x} key.
+
+Since some keyboards don't have a @key{META} key, you can generate
+@kbd{M-x}, for example, by pressing @key{ESC} (Escape), @emph{releasing
+it}, @footnote{This is emphasized because pressing ESC twice or holding
+it down a second too long so that it repeats gives you an error message.}
+and then pressing the @kbd{x} key.
+@item RET
+Press the @key{RETURN} or @key{ENTER} key. This is normally used to
+complete a command.
+@item SPC
+Press the space bar.
+@item TAB
+Press the @key{TAB} key.
+@item DEL
+Press the @key{DELETE} key. This may also be a Backspace key, depending
+on your keyboard or Emacs configuration.
+@end table
+
+@cindex Emacs, prefix argument
+@cindex prefix argument
+
+A @dfn{prefix argument} allows you to pass an argument to any Emacs
+function. To pass an argument, type @kbd{C-u} before the Emacs command
+or keystroke. Numeric arguments can be passed as well. For example, to
+insert five f's, use @kbd{C-u 5 f}. There is a default of four when
+using @kbd{C-u}, and you can use multiple prefix arguments to provide
+arguments of powers of four. To continue our example, you could insert
+four f's with @kbd{C-u f}, 16 f's with @kbd{C-u C-u f}, 64 f's with
+@kbd{C-u C-u C-u f}, and so on. Numeric and valueless negative
+arguments can also be inserted with the @key{META} key. Examples
+include @kbd{M-5} to specify an argument of 5, or @kbd{M--} which
+specifies a negative argument with no particular value.
+
+@sp 2
+@need 1000
+@center @strong{NOTE}
+
+@quotation
+The prefix @kbd{C-u} or @kbd{M-} is not necessary in mh-e's MH-Folder
+modes (@pxref{Reading Mail Tour}). In these modes, simply enter the
+numerical argument before entering the command.
+@end quotation
+
+@cindex point
+@cindex Emacs, point
+@cindex mark
+@cindex Emacs, mark
+@cindex region
+@cindex Emacs, region
+
+There are several other terms that are used in Emacs that you should
+know. The @dfn{point} is where the cursor currently is. You can save
+your current place in the file by setting a @dfn{mark}. This operation
+is useful in several ways. The mark can be later used when defining a
+@dfn{region}, which is the text between the point and mark. Many
+commands operate on regions, such as those for deleting text or filling
+paragraphs. A mark can be set with @kbd{C-@@} (or @kbd{C-SPC}).
+
+@cindex minibuffer
+@cindex Emacs, minibuffer
+@cindex file completion
+@cindex Emacs, file completion
+
+The @dfn{minibuffer} is the bottom line of the Emacs window, where all
+prompting and multiple-character input is directed. If you are prompted
+for information in the minibuffer, such as a filename, Emacs can help
+you complete your answer if you type @key{SPC} or @key{TAB}. A second
+@key{SPC} or @key{TAB} will list all possibilities at that point. The
+minibuffer is also where you enter Emacs function names after typing
+@kbd{M-x}. For example, in the first paragraph, I mentioned that you
+could obtain help with @kbd{C-h t} (@code{help-with-tutorial}). What
+this means is that you can get a tutorial by typing either @kbd{C-h t}
+or @kbd{M-x help-with-tutorial}. In the latter case, you are prompted
+for @samp{help-with-tutorial} in the minibuffer after typing @kbd{M-x}.
+
+@cindex interrupting
+@cindex Emacs, interrupting
+@cindex quitting
+@cindex Emacs, quitting
+
+@i{In case of trouble:} Emacs can be interrupted at any time with
+@kbd{C-g}. For example, if you've started a command that requests that
+you enter something in the minibuffer, but then you change your mind,
+type @kbd{C-g} and you'll be back where you started. If you want to
+exit Emacs entirely, use @kbd{C-x C-c}.
+
+@node Getting Started, Sending Mail Tour, Conventions, Tour Through mh-e
+@section Getting Started
+
+Because there are many old versions of mh-e out there, it is important to
+know which version you have. I'll be talking about @w{Version 5} which
+is similar to @w{Version 4} and vastly different from @w{Version 3}.
+
+First, enter @kbd{M-x load-library @key{RET} mh-e
+@key{RET}}. @footnote{You wouldn't ordinarily do this.} The message,
+@samp{Loading mh-e...done}, should be displayed in the minibuffer. If
+you get @samp{Cannot open load file: mh-e}, then your Emacs is very
+badly configured, or mh-e is missing. You may wish to have your system
+administrator install a new Emacs or at least the latest mh-e files.
+
+Having loaded mh-e successfully, enter @kbd{M-x mh-version @key{RET}}.
+The version of mh-e should be displayed. Hopefully it says that you're
+running @w{Version @value{VERSION}} which is the latest version as of
+this printing. If instead Emacs beeps and says @samp{[No match]}, then
+you're running an old version of mh-e.
+
+If these tests reveal a non-existent or old version of mh-e, please
+consider obtaining a new version. You can have your system
+administrator upgrade the system-wide version, or you can install your
+own personal version. It's really quite easy; instructions for getting
+and installing mh-e are in @ref{Getting mh-e}. In the meantime, see
+@ref{Changes to mh-e}, which compares the old and new names of commands,
+functions, variables, and buffers.
+
+@cindex @code{install-mh}
+@cindex MH commands, @code{install-mh}
+
+Also, older versions of mh-e assumed that you had already set up your MH
+environment. Newer versions set up a new MH environment for you by
+running @code{install-mh} and notifying you of this fact with the
+message in a temporary buffer:
+
+@example
+I'm going to create the standard MH path for you.
+@end example
+
+Therefore, if you've never run MH before and you're using an old version
+of mh-e, you need to run @code{install-mh} from the shell before you
+continue the tour. If you don't, you'll be greeted with the error
+message: @samp{Can't find MH profile}.
+
+@cindex @file{.emacs}
+@cindex files, @file{.emacs}
+
+If, during the tour described in this chapter, you see a message like:
+@samp{Searching for program: no such file or directory,
+/usr/local/bin/mhpath}, it means that the MH programs and files are kept
+in a nonstandard directory. In this case, simply add the following to
+@file{~/.emacs} and restart @code{emacs}.
+
+@vindex @code{mh-progs}, example
+@vindex @code{mh-lib}, example
+
+@c XXX Real example for really naive user?
+@example
+@group
+(setq mh-progs "@var{/path/to/MH/binary/directory/}")
+(setq mh-lib "@var{/path/to/MH/library/directory/}")
+@end group
+@end example
+
+@cindex ~
+
+The @samp{~} notation used by @file{~/.emacs} above represents your home
+directory. This is used by the @code{bash} and @code{csh} shells. If
+your shell does not support this feature, you could use the environment
+variable @samp{$HOME} (such as @file{$HOME/.emacs}) or the absolute path
+(as in @file{/home/wohler/.emacs}) instead.
+
+At this point, you should see something like the screen in the
+figure in @ref{Reading Mail Tour}. We're now ready to move on.
+
+@node Sending Mail Tour, Reading Mail Tour, Getting Started, Tour Through mh-e
+@section Sending Mail
+
+@cindex sending mail
+@findex @code{mh-smail}
+
+Let's start our tour by sending ourselves a message which we can later
+read and process. Enter @kbd{M-x mh-smail} to invoke the mh-e program
+to send messages. You will be prompted in the minibuffer by @samp{To:}.
+Enter your login name. The next prompt is @samp{cc:}. Hit @key{RET} to
+indicate that no carbon copies are to be sent. At the @samp{Subject:}
+prompt, enter @kbd{Test} or anything else that comes to mind.
+
+@cindex MH-Letter mode
+@cindex modes, MH-Letter
+@cindex mode
+
+Once you've specified the recipients and subject, your message appears
+in an Emacs buffer whose mode @footnote{A @dfn{mode} changes Emacs to
+make it easier to edit a particular type of text.} is MH-Letter.
+Enter some text in the body of the message, using normal Emacs commands.
+You should now have something like this: @footnote{If you're running Emacs
+under the X Window System, then you would also see a menubar. I've left
+out the menubar in all of the example screens.}
+
+@example
+@group
+@cartouche
+
+
+
+
+
+
+-----Emacs: *scratch* (Lisp Interaction)--All---------------------
+To: wohler
+cc:
+Subject: Test
+--------
+ This is a test message to get the wheels churning...#
+
+
+--**-@{draft@} (MH-Letter)--All----------------------------------------
+
+@end cartouche
+@i{mh-e message composition window}
+@end group
+@end example
+
+@cindex MH-Letter mode
+@cindex modes, MH-Letter
+
+Note the line of dashes that separates the header and the body of the
+message. It is essential that these dashes (or a blank line) are
+present or the body of your message will be considered to be part of
+the header.
+
+There are several commands specific to MH-Letter mode, but at
+this time we'll only use @kbd{C-c C-c} to send your message. Type
+@kbd{C-c C-c} now. That's all there is to it!
+
+@node Reading Mail Tour, Processing Mail Tour, Sending Mail Tour, Tour Through mh-e
+@section Receiving Mail
+
+@cindex reading mail
+@findex @code{mh-rmail}
+@cindex @code{inc}
+@cindex MH commands, @code{inc}
+@cindex @code{scan}
+@cindex MH commands, @code{scan}
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+
+To read the mail you've just sent yourself, enter @kbd{M-x mh-rmail}.
+This incorporates the new mail and put the output from @code{inc}
+(called @dfn{scan lines} after the MH program @code{scan} which prints a
+one-line summary of each message) into a buffer called @samp{+inbox}
+whose major mode is MH-Folder.
+
+@sp 2
+@need 1000
+@center @strong{NOTE}
+
+@quotation
+The @kbd{M-x mh-rmail} command will show you only new mail, not old
+mail. If you were to run this tour again, you would use @kbd{M-r} to
+pull all your messages into mh-e.
+@end quotation
+
+You should see the scan line for your message, and perhaps others. Use
+@kbd{n} or @kbd{p} to move the cursor to your test message and type
+@key{RET} to read your message. You should see something like:
+
+@example
+@group
+@cartouche
+ 3 24Aug root received fax files on Wed Aug 24 11:00:13 PDT 1994
+# 4+ 24Aug To:wohler Test<<This is a test message to get the wheels chu
+
+--%%-@{+inbox@} 4 msgs (1-4) (MH-Folder Show)--Bot---------------------
+To: wohler
+Subject: Test
+Date: Wed, 24 Aug 1994 13:01:13 -0700
+From: Bill Wohler <wohler@@newt.com>
+
+ This is a test message to get the wheels churning...
+
+
+
+
+
+-----@{show-+inbox@} 4 (MH-Show)--Bot----------------------------------
+
+@end cartouche
+@i{After incorporating new messages}
+@end group
+@end example
+
+If you typed a long message, you can view subsequent pages with @key{SPC}
+and previous pages with @key{DEL}.
+
+@node Processing Mail Tour, Leaving mh-e, Reading Mail Tour, Tour Through mh-e
+@section Processing Mail
+
+@cindex processing mail
+
+The first thing we want to do is reply to the message that we sent
+ourselves. Ensure that the cursor is still on the same line as your
+test message and type @kbd{r}. You are prompted in the minibuffer with
+@samp{Reply to whom:}. Here mh-e is asking whether you'd like to reply
+to the original sender only, to the sender and primary recipients, or to
+the sender and all recipients. If you simply hit @key{RET}, you'll
+reply only to the sender. Hit @key{RET} now.
+
+You'll find yourself in an Emacs buffer similar to that when you were
+sending the original message, like this:
+
+@example
+@group
+@cartouche
+To: wohler
+Subject: Re: Test
+In-reply-to: Bill Wohler's message of Wed, 24 Aug 1994 13:01:13 -0700
+ <199408242001.NAA00505@@newt.com>
+--------
+#
+
+--**-@{draft@} (MH-Letter)--All----------------------------------------
+To: wohler
+Subject: Test
+Date: Wed, 24 Aug 1994 13:01:13 -0700
+From: Bill Wohler <wohler@@newt.com>
+
+ This is a test message to get the wheels churning...
+
+-----@{show-+inbox@} 4 (MH-Show)--Bot----------------------------------
+Composing a reply...done
+@end cartouche
+@i{Composition window during reply}
+@end group
+@end example
+
+By default, MH will not add you to the address list of your replies, so
+if you find that the @samp{To:} header field is missing, don't worry.
+In this case, type @kbd{C-c C-f C-t} to create and go to the @samp{To:}
+field, where you can type your login name again. You can move around
+with the arrow keys or with @kbd{C-p} (@code{previous-line}), @kbd{C-n}
+(@code{next-line}), @kbd{C-b} (@code{backward-char}), and @kbd{C-f}
+(@code{forward-char}) and can delete the previous character with
+@key{DEL}. When you're finished editing your message, send it with
+@kbd{C-c C-c} as before.
+
+@cindex folder
+
+You'll often want to save messages that were sent to you in an organized
+fashion. This is done with @dfn{folders}. You can use folders to keep
+messages from your friends, or messages related to a particular topic.
+With your cursor in the MH-Folder buffer and positioned on the message
+you sent to yourself, type @kbd{o} to output (@code{refile} in MH
+parlance) that message to a folder. Enter @kbd{test} at the
+@samp{Destination:} prompt and type @kbd{y} (or @key{SPC}) when mh-e
+asks to create the folder @samp{+test}. Note that a @samp{^} (caret)
+appears next to the message number, which means that the message has
+been marked for refiling but has not yet been refiled. We'll talk about
+how the refile is actually carried out in a moment.
+
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+
+Your previous reply is now waiting in the system mailbox. You
+incorporate this mail into your MH-Folder buffer named @samp{+inbox}
+with the @kbd{i} command. Do this now. After the mail is incorporated,
+use @kbd{n} or @kbd{p} to move the cursor to the new message, and read
+it with @key{RET}. Let's delete this message by typing @kbd{d}. Note
+that a @samp{D} appears next to the message number. This means that the
+message is marked for deletion but is not yet deleted. To perform the
+deletion (and the refile we did previously), use the @kbd{x} command.
+
+@findex @code{mh-smail}
+
+If you want to send another message you can use @kbd{m} instead of
+@kbd{M-x mh-smail}. So go ahead, send some mail to your friends!
+
+@node Leaving mh-e, More About mh-e, Processing Mail Tour, Tour Through mh-e
+@section Leaving mh-e
+
+@cindex Emacs, quitting
+@cindex quitting
+
+You may now wish to exit @code{emacs} entirely. Use @kbd{C-x C-c} to
+exit @code{emacs}. If you exited without running @kbd{x} in the
+@samp{+inbox} buffer, Emacs will offer to save it for you. Type @kbd{y}
+or @key{SPC} to save @samp{+inbox} changes, which means to perform any refiles
+and deletes that you did there.
+
+If you don't want to leave Emacs, you can type @kbd{q} to bury (hide)
+the mh-e folder or delete them entirely with @kbd{C-x k}. You can then
+later recall them with @kbd{C-x b} or @kbd{M-x mh-rmail}.
+
+@node More About mh-e, , Leaving mh-e, Tour Through mh-e
+@section More About mh-e
+
+These are the basic commands to get you going, but there are plenty
+more. If you think that mh-e is for you, read @ref{Using mh-e} and
+@ref{Customizing mh-e} to find out how you can:
+
+@itemize @bullet
+@item
+Print your messages. (@ref{Printing} and @ref{Customizing Printing}.)
+@item
+Edit messages and include your signature. (@ref{Draft Editing}
+and @ref{Customizing Draft Editing}.)
+@item
+Forward messages. (@ref{Forwarding} and @ref{Customizing Forwarding}.)
+@item
+Read digests. (@ref{Viewing}.)
+@item
+Edit bounced messages. (@ref{Old Drafts} and @ref{Customizing Old Drafts}.)
+@item
+Send multimedia messages. (@ref{Editing MIME} and @ref{Customizing Editing MIME}.)
+@item
+Process mail that was sent with @code{shar} or @code{uuencode}.
+(@ref{Files and Pipes}.)
+@item
+Use sequences conveniently. (@ref{Sequences}.)
+@item
+Show header fields in different fonts. (@ref{Customizing Viewing}.)
+@item
+Find previously refiled messages. (@ref{Searching}.)
+@item
+Place messages in a file. (@ref{Files and Pipes}.)
+@end itemize
+
+Remember that you can also use MH commands when you're not running mh-e
+(and when you are!).
+
+@node Using mh-e, Customizing mh-e, Tour Through mh-e, Top
+@chapter Using mh-e
+
+This chapter leaves the tutorial style and goes into more detail about
+every mh-e command. The default, or "out of the box," behavior is
+documented. If this is not to your liking (for instance, you print with
+something other than @code{lpr)}, see the associated section in
+@ref{Customizing mh-e} which is organized exactly like this chapter.
+
+@cindex Emacs, functions; describe-mode
+@cindex Emacs, online help
+@cindex online help
+
+There are many commands, but don't get intimidated. There are command
+summaries at the beginning of each section. In case you have or would
+like to rebind the keys, the command summaries also list the associated
+Emacs Lisp function. Furthermore, even if you're stranded on a desert
+island with a laptop and are without your manuals, you can get a summary
+of all these commands with GNU Emacs online help: use @kbd{C-h m}
+(@code{describe-mode}) for a brief summary of commands or @kbd{C-h i} to
+read this manual via Info. The online help is quite good; try running
+@kbd{C-h C-h C-h}. This brings up a list of available help topics, one
+of which displays the documentation for a given key (like @kbd{C-h k
+C-n}). In addition, review @ref{Conventions}, if any of the GNU Emacs
+conventions are strange to you.
+
+Let's get started!
+
+@menu
+* Reading Mail::
+* Sending Mail::
+* Draft Editing::
+* Moving Mail::
+* Searching::
+* Sequences::
+* Miscellaneous::
+@end menu
+
+@node Reading Mail, Sending Mail, Using mh-e, Using mh-e
+@section Reading Your Mail
+
+@cindex reading mail
+@findex @code{mh-rmail}
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+
+The mh-e entry point for reading mail is @kbd{M-x mh-rmail}. This
+command incorporates your mail and creates a buffer called @samp{+inbox}
+in MH-Folder mode. The @kbd{M-x mh-rmail} command shows you only new
+mail, not old mail. @footnote{If you want to see your old mail as well,
+use @kbd{M-r} to pull all your messages into mh-e. Or, give a prefix
+argument to @code{mh-rmail} so it will prompt you for folder to visit
+like @kbd{M-f} (for example, @kbd{C-u M-x mh-rmail @key{RET} bob
+@key{RET}}). Both @kbd{M-r} and @kbd{M-f} are described in
+@ref{Organizing}.} The @samp{+inbox} buffer contains @dfn{scan lines},
+which are one-line summaries of each incorporated message. You can
+perform most MH commands on these messages via one-letter commands
+discussed in this chapter. See @code{scan}(1) for a description of the
+contents of the scan lines, and see the Figure in @ref{Reading Mail
+Tour}, for an example.
+
+@table @kbd
+@item RET
+Display a message (@code{mh-show}).
+
+@item SPC
+Go to next page in message (@code{mh-page-msg}).
+
+@item DEL
+Go to previous page in message (@code{mh-previous-page}).
+
+@item , (comma)
+Display a message with all header fields (@code{mh-header-display}).
+
+@item M-SPC
+Go to next message in digest (@code{mh-page-digest}).
+
+@item M-DEL
+Go to previous message in digest (@code{mh-page-digest-backwards}).
+
+@item M-b
+Break up digest into separate messages (@code{mh-burst-digest}).
+
+@item n
+Display next message (@code{mh-next-undeleted-msg}).
+
+@item p
+Display previous message (@code{mh-previous-undeleted-msg}).
+
+@item g
+Go to a message (@code{mh-goto-msg}).
+
+@item M-<
+Go to first message (@code{mh-first-msg}).
+
+@item M->
+Go to last message (@code{mh-last-msg}).
+
+@item t
+Toggle between MH-Folder and MH-Folder Show modes (@code{mh-toggle-showing}).
+@end table
+
+@menu
+* Viewing::
+* Moving Around::
+@end menu
+
+@node Viewing, Moving Around, Reading Mail, Reading Mail
+@subsection Viewing Your Mail
+
+@findex @code{mh-show}
+@findex @code{mh-page-msg}
+@findex @code{mh-previous-page}
+
+The @kbd{RET} (@code{mh-show}) command displays the message that the
+cursor is on. If the message is already displayed, it scrolls to the
+beginning of the message. Use @key{SPC} (@code{mh-page-msg}) and
+@key{DEL} (@code{mh-previous-page}) to move forwards and backwards one
+page at a time through the message. You can give either of these
+commands a prefix argument that specifies the number of lines to scroll
+(such as @kbd{10 SPC}). mh-e normally hides a lot of the
+superfluous header fields that mailers add to a message, but if you wish
+to see all of them, use the @kbd{,} (comma; @code{mh-header-display})
+command.
+
+@menu
+* Reading Digests::
+* Reading MIME::
+@end menu
+
+@node Reading Digests, Reading MIME, Viewing, Viewing
+@subsubsection Reading Digests
+
+@cindex digests
+@findex @code{mh-page-digest}
+@findex @code{mh-page-digest-backwards}
+
+A digest is a message that contains other messages. Special mh-e
+commands let you read digests conveniently. You can use @key{SPC} and
+@key{DEL} to page through the digest as if it were a normal message, but
+if you wish to skip to the next message in the digest, use @kbd{M-SPC}
+(@code{mh-page-digest}). To return to a previous message, use
+@kbd{M-DEL} (@code{mh-page-digest-backwards}).
+
+@cindex @code{burst}
+@cindex MH commands, @code{burst}
+@cindex MH-Folder Show mode
+@cindex modes, MH-Folder Show
+@findex @code{mh-burst-digest}
+
+@c There was a page break at the colon in the following paragraph which
+@c broke the transition to the example.
+@need 2000
+
+Another handy command is @kbd{M-b} (@code{mh-burst-digest}). This
+command uses the MH command @code{burst} to break out each message in
+the digest into its own message. Using this command, you can quickly
+delete unwanted messages, like this: Once the digest is split up, toggle
+out of MH-Folder Show mode with @kbd{t} (@pxref{Moving Around}) so that
+the scan lines fill the screen and messages aren't displayed. Then use
+@kbd{d} (@pxref{Deleting}) to quickly delete messages that you don't
+want to read (based on the @samp{Subject:} header field). You can also
+burst the digest to reply directly to the people who posted the messages
+in the digest. One problem you may encounter is that the @samp{From:}
+header fields are preceded with a @samp{>} so that your reply can't
+create the @samp{To:} field correctly. In this case, you must correct
+the @samp{To:} field yourself. This is described later in @ref{Editing
+Textual}.
+
+@node Reading MIME, , Reading Digests, Viewing
+@subsubsection Reading Multimedia Mail
+
+@cindex multimedia mail
+@cindex MIME
+@cindex @code{show}
+@cindex MH commands, @code{show}
+@cindex @code{mhn}
+@cindex MH commands, @code{mhn}
+
+MH has the ability to read @dfn{@sc{mime}} (Multipurpose Internet Mail
+Extensions) messages. Unfortunately, mh-e does not yet have this
+ability, so you have to use the MH commands @code{show} or @code{mhn}
+from the shell to read @sc{mime} messages. @footnote{You can call them
+directly from Emacs if you're running the X Window System: type @kbd{M-!
+xterm -e mhn @var{message-number}}. You can leave out the @code{xterm
+-e} if you use @code{mhn -list} or @code{mhn -store}.}
+
+@node Moving Around, , Viewing, Reading Mail
+@subsection Moving Around
+
+@cindex moving between messages
+@findex @code{mh-next-undeleted-msg}
+@findex @code{mh-previous-undeleted-msg}
+@findex @code{mh-goto-msg}
+@findex @code{mh-last-msg}
+@findex @code{mh-first-msg}
+
+To move on to the next message, use the @kbd{n}
+(@code{mh-next-undeleted-msg}) command; use the @kbd{p}
+(@code{mh-previous-undeleted-msg}) command to read the previous message.
+Both of these commands can be given a prefix argument to specify how
+many messages to skip (for example, @kbd{5 n}). You can also move to a
+specific message with @kbd{g} (@code{mh-goto-msg}). You can enter the
+message number either before or after typing @kbd{g}. In the latter
+case, Emacs prompts you. Finally, you can go to the first or last
+message with @kbd{M-<} (@code{mh-first-msg}) and @kbd{M->}
+(@code{mh-last-msg}) respectively.
+
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+
+You can also use the Emacs commands @kbd{C-p} (@code{previous-line}) and
+@kbd{C-n} (@code{next-line}) to move up and down the scan lines in the
+MH-Folder window. These commands can be used in conjunction with
+@kbd{RET} to look at deleted or refiled messages.
+
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+@cindex MH-Folder Show mode
+@cindex modes, MH-Folder Show
+@cindex junk mail
+@findex @code{mh-toggle-showing}
+
+The command @kbd{t} (@code{mh-toggle-showing}) switches between
+MH-Folder mode and MH-Folder Show mode. @footnote{For you Emacs
+wizards, this is implemented as an Emacs minor mode.} MH-Folder mode
+turns off the associated show buffer so that you can perform operations
+on the messages quickly without reading them. This is an excellent way
+to prune out your junk mail or to refile a group of messages to another
+folder for later examination.
+
+@node Sending Mail, Draft Editing, Reading Mail, Using mh-e
+@section Sending Mail
+
+@cindex sending mail
+@findex @code{mh-smail}
+
+You can send a mail message in several ways. You can call @kbd{M-x
+mh-smail} directly, or from the command line like this:
+
+@cindex starting from command line
+
+@example
+% @kbd{emacs -f mh-smail}
+@end example
+
+From within mh-e's MH-Folder mode, other methods of sending mail
+are available as well:
+
+@table @kbd
+@item m
+Compose a message (@code{mh-send}).
+
+@item r
+Reply to a message (@code{mh-reply}).
+
+@item f
+Forward message(s) (@code{mh-forward}).
+
+@item M-d
+Redistribute a message (@code{mh-redistribute}).
+
+@item M-e
+Edit a message that was bounced by mailer (@code{mh-extract-rejected-mail}).
+
+@item M-a
+Edit a message to send it again (@code{mh-edit-again}).
+@end table
+
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+@cindex MH-Letter mode
+@cindex modes, MH-Letter
+@findex @code{mh-send}
+
+From within a MH-Folder buffer, you can simply use the command @kbd{m}
+(@code{mh-send}). However you invoke @code{mh-send}, you are prompted
+for the @samp{To:}, @samp{cc:}, and @samp{Subject:} header fields. Once
+you've specified the recipients and subject, your message appears in an
+Emacs buffer whose mode is MH-Letter (see the Figure in @ref{Sending
+Mail} to see what the buffer looks like). MH-Letter mode allows you to
+edit your message, to check the validity of the recipients, to insert
+other messages into your message, and to send the message. We'll go
+more into depth about editing a @dfn{draft} @footnote{I highly recommend
+that you use a @dfn{draft folder} so that you can edit several drafts in
+parallel. To do so, create a folder (e.g., @file{+drafts}), and add a
+profile component called @samp{Draft-Folder:} which contains
+@file{+drafts} (see @code{mh-profile}(5)).} (a message you're composing)
+in just a moment.
+
+@findex @code{mh-smail}
+@findex @code{mh-smail-other-window}
+
+@code{mh-smail} always creates a two-window layout with the current
+buffer on top and the draft on the bottom. If you would rather preserve
+the window layout, use @kbd{M-x mh-smail-other-window}.
+
+@menu
+* Replying::
+* Forwarding::
+* Redistributing::
+* Old Drafts::
+@end menu
+
+@node Replying, Forwarding, Sending Mail, Sending Mail
+@subsection Replying to Mail
+
+@cindex replying
+@cindex @code{mhl}
+@cindex MH commands, @code{mhl}
+@cindex @file{mhl.reply}
+@cindex files, @file{mhl.reply}
+@findex @code{mh-reply}
+
+To compose a reply to a message, use the @kbd{r} (@code{mh-reply})
+command. If you supply a prefix argument (as in @kbd{C-u r}), the
+message you are replying to is inserted in your reply after having first
+been run through @code{mhl} with the format file @file{mhl.reply}. See
+@code{mhl}(1) to see how you can modify the default @file{mhl.reply}
+file.
+
+When you reply to a message, you are first prompted with @samp{Reply to
+whom?}. You have several choices here.
+
+@example
+@group
+@b{Response} @b{Reply Goes To}
+
+@kbd{from} @r{The person who sent the message. This is the default,}
+ @r{so @key{RET} is sufficient.}
+
+@kbd{to} @r{Replies to the sender, plus all recipients in the}
+ @r{@samp{To:} header field.}
+
+@kbd{all}
+@kbd{cc} @r{Forms a reply to the sender, plus all recipients.}
+@end group
+@end example
+
+@cindex @code{repl}
+@cindex MH commands, @code{repl}
+
+Depending on your answer, @code{repl} is given a different argument to
+form your reply. Specifically, a choice of @kbd{from} or none at all
+runs @code{repl -nocc all}, and a choice of @kbd{to} runs @code{repl -cc
+to}. Finally, either @kbd{cc} or @kbd{all} runs @code{repl -cc all
+-nocc me}.
+
+@cindex MH-Letter mode
+@cindex modes, MH-Letter
+
+Two windows are then created. One window contains the message to which
+you are replying. Your draft, in MH-Letter mode (described in
+@ref{Draft Editing}), is in the other window.
+
+If you wish to customize the header or other parts of the reply draft,
+please see @code{repl}(1) and @code{mh-format}(5).
+
+@node Forwarding, Redistributing, Replying, Sending Mail
+@subsection Forwarding Mail
+
+@cindex forwarding
+@cindex @code{forw}
+@cindex MH commands, @code{forw}
+@findex @code{mh-forward}
+
+To forward a message, use the @kbd{f} (@code{mh-forward}) command. You
+are given a draft to edit that looks like it would if you had run the MH
+command @code{forw}. You are given a chance to add some text (see
+@ref{Draft Editing}).
+
+You can forward several messages by using a prefix argument; in this
+case, you are prompted for the name of a @dfn{sequence}, a symbolic name
+that represents a list or range of message numbers (for example,
+@kbd{C-u f forbob @key{RET}}). All of the messages in the sequence are
+inserted into your draft. By the way, although sequences are often
+mentioned in this chapter, you don't have to worry about them for now;
+the full description of sequences in mh-e is at the end in
+@ref{Sequences}. To learn more about sequences in general, please see
+@code{mh-sequence}(5).
+
+@node Redistributing, Old Drafts, Forwarding, Sending Mail
+@subsection Redistributing Your Mail
+
+@cindex redistributing
+@findex @code{mh-redistribute}
+
+The command @kbd{M-d} (@code{mh-redistribute}) is similar in function to
+forwarding mail, but it does not allow you to edit the message, nor does
+it add your name to the @samp{From:} header field. It appears to the
+recipient as if the message had come from the original sender. For more
+information on redistributing messages, see @code{dist}(1). Also
+investigate the @kbd{M-a} (@code{mh-edit-again}) command in @ref{Old
+Drafts}, for another way to redistribute messages.
+
+@node Old Drafts, , Redistributing, Sending Mail
+@subsection Editing Old Drafts and Bounced Messages
+
+@cindex re-editing drafts
+@cindex @file{draft}
+@cindex files, @file{draft}
+@findex @code{mh-edit-again}
+
+If you don't complete a draft for one reason or another, and if the
+draft buffer is no longer available, you can pick your draft up again
+with @kbd{M-a} (@code{mh-edit-again}). If you don't use a draft folder,
+your last @file{draft} file will be used. If you use draft folders,
+you'll need to visit the draft folder with @kbd{M-f drafts @key{RET}},
+use @kbd{n} to move to the appropriate message, and then use @kbd{M-a}
+to prepare the message for editing.
+
+The @kbd{M-a} command can also be used to take messages that were sent
+to you and to send them to more people.
+
+@cindex Mailer-Daemon
+@findex @code{mh-extract-rejected-mail}
+
+Don't use @kbd{M-a} to re-edit a message from a @i{Mailer-Daemon} who
+complained that your mail wasn't posted for some reason or another. In
+this case, use @kbd{M-e} (@code{mh-extract-rejected-mail}) to prepare
+the message for editing by removing the @i{Mailer-Daemon} envelope and
+unneeded header fields. Fix whatever addressing problem you had, and
+send the message again with @kbd{C-c C-c}.
+
+@node Draft Editing, Moving Mail, Sending Mail, Using mh-e
+@section Editing a Draft
+
+@cindex editing draft
+@cindex MH-Letter mode
+@cindex modes, MH-Letter
+
+When you edit a message that you want to send (called a @dfn{draft} in
+this case), the mode used is MH-Letter. This mode provides
+several commands in addition to the normal Emacs editing commands to
+help you edit your draft.
+
+@table @kbd
+@item C-c C-y
+Insert contents of message to which you're replying (@code{mh-yank-cur-msg}).
+
+@item C-c C-i
+Insert a message from a folder (@code{mh-insert-letter}).
+
+@item C-c C-f C-t
+Move to @samp{To:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-c
+Move to @samp{cc:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-s
+Move to @samp{Subject:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-f
+Move to @samp{From:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-b
+Move to @samp{Bcc:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-f
+Move to @samp{Fcc:} header field (@code{mh-to-fcc}).
+
+@item C-c C-f C-d
+Move to @samp{Dcc:} header field (@code{mh-to-field}).
+
+@item C-c C-w
+Display expanded recipient list (@code{mh-check-whom}).
+
+@item C-c C-s
+Insert signature in message (@code{mh-insert-signature}).
+
+@item C-c C-m C-f
+Include forwarded message (@sc{mime}) (@code{mh-mhn-compose-forw}).
+
+@item C-c C-m C-e
+Include anonymous ftp reference (@sc{mime}) (@code{mh-mhn-compose-anon-ftp}).
+
+@item C-c C-m C-t
+Include anonymous ftp reference to compressed tar file (@sc{mime})
+(@code{mh-mhn-compose-external-compressed-tar}).
+
+@item C-c C-m C-i
+Include binary, image, sound, etc. (@sc{mime})
+(@code{mh-mhn-compose-insertion}).
+
+@item C-c C-e
+Run through @code{mhn} before sending (@code{mh-edit-mhn}).
+
+@item C-c C-m C-u
+Undo effects of @code{mhn} (@code{mh-revert-mhn-edit}).
+
+@item C-c C-c
+Save draft and send message (@code{mh-send-letter}).
+
+@item C-c C-q
+Quit editing and delete draft message (@code{mh-fully-kill-draft}).
+@end table
+
+@menu
+* Editing Textual::
+* Editing MIME::
+* Sending Message::
+* Killing Draft::
+@end menu
+
+@node Editing Textual, Editing MIME, Draft Editing, Draft Editing
+@subsection Editing Textual Messages
+
+The following sections show you how to edit a draft.
+The commands described here are also applicable to messages that have
+multimedia components.
+
+@menu
+* Inserting Letter::
+* Inserting Messages::
+* Header::
+* Recipients::
+* Signature::
+@end menu
+
+@node Inserting Letter, Inserting Messages, Editing Textual, Editing Textual
+@subsubsection Inserting letter to which you're replying
+
+@cindex inserting messages
+@findex @code{mh-yank-cur-msg}
+
+It is often useful to insert a snippet of text from a letter that
+someone mailed to provide some context for your reply. The command
+@kbd{C-c C-y} (@code{mh-yank-cur-msg}) does this by yanking a portion of
+text from the message to which you're replying and inserting @samp{> }
+before each line.
+
+@cindex mark
+@cindex Emacs, mark
+@cindex point
+@cindex Emacs, point
+@cindex region
+@cindex Emacs, region
+
+You can control how much text is included when you run this command. If
+you run this command right away, without entering the buffer containing
+the message to you, this command will yank the entire message, as is,
+into your reply. @footnote{If you'd rather have the header cleaned up,
+use @kbd{C-u r} instead of @kbd{r} when replying (see @ref{Replying}).}
+If you enter the buffer containing the message sent to you and move the
+cursor to a certain point and return to your reply and run @kbd{C-c
+C-y}, then the text yanked will range from that point to the end of the
+message. Finally, the most common action you'll perform is to enter the
+message sent to you, move the cursor to the beginning of a paragraph or
+phrase, set the @dfn{mark} with @kbd{C-SPC} or @kbd{C-@@}, and move the
+cursor to the end of the paragraph or phrase. The cursor position is
+called the @dfn{point}, and the space between the mark and point is
+called the @dfn{region}. Having done that, @kbd{C-c C-y} will insert
+the region you selected.
+
+@node Inserting Messages, Header, Inserting Letter, Editing Textual
+@subsubsection Inserting messages
+
+@cindex inserting messages
+@findex @code{mh-insert-letter}
+
+Messages can be inserted with @kbd{C-c C-i} (@code{mh-insert-letter}).
+This command prompts you for the folder and message number and inserts
+the message, indented by @samp{> }. Certain undesirable header fields
+are removed before insertion. If given a prefix argument (like @kbd{C-u
+C-c C-i}), the header is left intact, the message is not indented, and
+@samp{> } is not inserted before each line.
+
+@node Header, Recipients, Inserting Messages, Editing Textual
+@subsubsection Editing the header
+
+@cindex editing header
+@findex @code{mh-to-field}
+
+Because the header is part of the message, you can edit the header
+fields as you wish. However, several convenience functions exist to
+help you create and edit them. For example, the command @kbd{C-c C-f
+C-t} (@code{mh-to-field}; alternatively, @kbd{C-c C-f t}) moves the
+cursor to the @samp{To:} header field, creating it if necessary. The
+functions to move to the @samp{cc:}, @samp{Subject:}, @samp{From:},
+@samp{Bcc:}, and @samp{Dcc:} header fields are similar.
+
+@findex @code{mh-to-fcc}
+
+One function behaves differently from the others, namely, @kbd{C-c C-f
+C-f} (@code{mh-to-fcc}; alternatively, @kbd{C-c C-f f}). This function
+will prompt you for the folder name in which to file a copy of the draft.
+
+Be sure to leave a row of dashes or a blank line between the header and
+the body of the message.
+
+@node Recipients, Signature, Header, Editing Textual
+@subsubsection Checking recipients
+
+@cindex checking recipients
+@cindex @code{whom}
+@cindex MH commands, @code{whom}
+@findex @code{mh-check-whom}
+
+The @kbd{C-c C-w} (@code{mh-check-whom}) command expands aliases so you
+can check the actual address(es) in the alias. A new buffer is created
+with the output of @code{whom}.
+
+@node Signature, , Recipients, Editing Textual
+@subsubsection Inserting your signature
+
+@cindex inserting signature
+@cindex signature
+@cindex @file{.signature}
+@cindex files, @file{.signature}
+@findex @code{mh-insert-signature}
+
+You can insert your signature at the current cursor location with the
+@kbd{C-c C-s} (@code{mh-insert-signature}) command. The text of your
+signature is taken from the file @file{~/.signature}.
+
+@node Editing MIME, Sending Message, Editing Textual, Draft Editing
+@subsection Editing Multimedia Messages
+
+@cindex MIME
+@cindex multimedia mail
+@cindex @code{mhn}
+@cindex MH commands, @code{mhn}
+
+mh-e has the capability to create multimedia messages. It uses the
+@sc{mime} (Multipurpose Internet Mail Extensions) protocol. The
+@sc{mime} protocol allows you to incorporate images, sound, video,
+binary files, and even commands that fetch a file with @samp{ftp} when
+your recipient reads the message! If you were to create a multimedia
+message with plain MH commands, you would use @code{mhn}. Indeed, the
+mh-e @sc{mime} commands merely insert @code{mhn} directives which are
+later expanded by @code{mhn}.
+
+Each of the mh-e commands for editing multimedia messages or for
+incorporating multimedia objects is prefixed with @kbd{C-c C-m} .
+
+@cindex content types
+@cindex MIME, content types
+
+Several @sc{mime} objects are defined. They are called @dfn{content
+types}. The table in @ref{Customizing Draft Editing} contains a list of
+the content types that mh-e currently knows about. Several of the mh-e
+commands fill in the content type for you, whereas others require you to
+enter one. Most of the time, it should be obvious which one to use
+(e.g., use @kbd{image/jpeg} to include a @sc{jpeg} image). If not, you
+can refer to @sc{rfc} 1521,
+@c Footnotes are very fragile. Hence the duplication.
+@c The line break in the footnote was necessary since TeX wasn't creating one.
+@ifclear html
+@footnote{This @sc{rfc} (Request For Comments) is
+available via the @sc{url} @*
+@file{ftp://ds.internic.net/rfc/rfc1521.txt}.}
+@end ifclear
+@ifset html
+@footnote{This @sc{rfc} (Request For Comments) is
+available via the @sc{url} @*
+@file{<A HREF="ftp://ds.internic.net/rfc/rfc1521.txt">ftp://ds.internic.net/rfc/rfc1521.txt</A>}.}
+@end ifset
+which defines the @sc{mime} protocol, for a list of valid content types.
+
+@cindex content description
+@cindex MIME, content description
+
+You are also sometimes asked for a @dfn{content description}. This is
+simply an optional brief phrase, in your own words, that describes the
+object. If you don't care to enter a content description, just press
+return and none will be included; however, a reader may skip over
+multimedia fields unless the content description is compelling.
+
+Remember: you can always add @code{mhn} directives by hand.
+
+@menu
+* Forwarding MIME::
+* FTP::
+* Tar::
+* Other MIME Objects::
+* Sending MIME::
+@end menu
+
+@node Forwarding MIME, FTP, Editing MIME, Editing MIME
+@subsubsection Forwarding multimedia messages
+
+@findex @code{mh-mhn-compose-forw}
+
+Mail may be forwarded with @sc{mime} using the command @kbd{C-c C-m C-f}
+(@code{mh-mhn-compose-forw}). You are prompted for a content
+description, the name of the folder in which the messages to forward are
+located, and the messages' numbers.
+
+@node FTP, Tar, Forwarding MIME, Editing MIME
+@subsubsection Including an ftp reference
+
+@cindex @code{ftp}
+@cindex Unix commands, @code{ftp}
+@cindex MIME, @code{ftp}
+@findex @code{mh-mhn-compose-anon-ftp}
+
+You can even have your message initiate an @code{ftp} transfer when the
+recipient reads the message. To do this, use the @kbd{C-c C-m C-e}
+(@code{mh-mhn-compose-anon-ftp}) command. You are prompted for the
+remote host and pathname, the content type, and the content description.
+
+@node Tar, Other MIME Objects, FTP, Editing MIME
+@subsubsection Including tar files
+
+@cindex @code{tar}
+@cindex Unix commands, @code{tar}
+@cindex MIME, @code{tar}
+@cindex @code{ftp}
+@cindex Unix commands, @code{ftp}
+@cindex MIME, @code{ftp}
+@findex @code{mh-mhn-compose-external-compressed-tar}
+
+If the remote file (@pxref{FTP}) is a compressed tar file, you can use
+@kbd{C-c C-m C-t} (@code{mh-mhn-compose-external-compressed-tar}).
+Then, in addition to retrieving the file via anonymous @emph{ftp}, the
+file will also be uncompressed and untarred. You are prompted for the
+remote host and pathname and the content description. The pathname
+should contain at least one @samp{/} (slash), because the pathname is
+broken up into directory and name components.
+
+@node Other MIME Objects, Sending MIME, Tar, Editing MIME
+@subsubsection Including other multimedia objects
+
+@cindex images
+@cindex MIME, images
+@cindex sound
+@cindex MIME, sound
+@cindex video
+@cindex MIME, video
+@findex @code{mh-mhn-compose-insertion}
+
+Images, sound, and video can be inserted in your message with the
+@kbd{C-c C-m C-i} (@code{mh-mhn-compose-insertion}) command. You are
+prompted for the filename containing the object, the content type, and a
+content description of the object.
+
+@node Sending MIME, , Other MIME Objects, Editing MIME
+@subsubsection Readying multimedia messages for sending
+
+When you are finished editing a @sc{mime} message, it might look like this:
+
+@example
+@group
+@cartouche
+ 3 24Aug root received fax files on Wed Aug 24 11:00:13
+ 4+ 24Aug To:wohler Test<<This is a test message to get the wh
+
+
+
+
+
+--%%-@{+inbox@} 4 msgs (1-4) (MH-Folder Show)--Bot-------------------
+To: wohler
+cc:
+Subject: Test of MIME
+--------
+#@@application/octet-stream [Nonexistent ftp test file] \
+access-type=anon-ftp; site=berzerk.com; name=panacea.tar.gz; \
+directory="/pub/"
+#audio/basic [Test sound bite] /tmp/noise.au
+--**-@{draft@} (MH-Letter)--All--------------------------------------
+
+@end cartouche
+@i{mh-e @sc{mime} draft}
+@end group
+@end example
+
+@cindex @code{mhn}
+@cindex MH commands, @code{mhn}
+@findex @code{mh-edit-mhn}
+
+The lines added by the previous commands are @code{mhn} directives and
+need to be converted to @sc{mime} directives before sending. This is
+accomplished by the command @kbd{C-c C-e} (@code{mh-edit-mhn}), which
+runs @code{mhn} on the message. The following screen shows what those
+commands look like in full @sc{mime} format. You can see why mail user
+agents are usually built to hide these details from the user.
+
+@example
+@group
+@cartouche
+To: wohler
+cc:
+Subject: Test of MIME
+MIME-Version: 1.0
+Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
+Content-ID: <1623.777796162.0@@newt.com>
+
+------- =_aaaaaaaaaa0
+Content-Type: message/external-body; access-type="anon-ftp";
+ site="berzerk.com"; name="panacea.tar.gz"; directory="/pub/"
+
+Content-Type: application/octet-stream
+Content-ID: <1623.777796162.1@@newt.com>
+Content-Description: Nonexistent ftp test file
+
+------- =_aaaaaaaaaa0
+Content-Type: audio/basic
+Content-ID: <1623.777796162.2@@newt.com>
+Content-Description: Test sound bite
+Content-Transfer-Encoding: base64
+
+Q3JlYXRpdmUgVm9pY2UgRmlsZRoaAAoBKREBQh8AgwCAgH9/f35+fn59fX5+fn5+f39/f39/f3
+f4B/f39/f39/f39/f39/f39+f39+f39/f39/f4B/f39/fn5/f39/f3+Af39/f39/gH9/f39/fn
+-----@{draft@} (MH-Letter)--Top--------------------------------------
+
+@end cartouche
+@i{mh-e @sc{mime} draft ready to send}
+@end group
+@end example
+
+@findex @code{mh-revert-mhn-edit}
+
+This action can be undone by running @kbd{C-c C-m C-u}
+(@code{mh-revert-mhn-edit}). It does this by reverting to a backup
+file. You are prompted to confirm this action, but you can avoid the
+confirmation by adding an argument (for example, @kbd{C-u C-c C-m C-u}).
+
+@node Sending Message, Killing Draft, Editing MIME, Draft Editing
+@subsection Sending a Message
+
+@cindex sending mail
+@findex @code{mh-send-letter}
+
+When you are all through editing a message, you send it with the
+@kbd{C-c C-c} (@code{mh-send-letter}) command. You can give an argument
+(as in @kbd{C-u C-c C-c}) to monitor the first stage of the delivery.
+
+@node Killing Draft, , Sending Message, Draft Editing
+@subsection Killing the Draft
+
+@cindex killing draft
+@findex @code{mh-fully-kill-draft}
+
+If for some reason you are not happy with the draft, you can kill it
+instead with @kbd{C-c C-q} (@code{mh-fully-kill-draft}). Emacs then
+kills the draft buffer and deletes the draft message.
+
+@node Moving Mail, Searching, Draft Editing, Using mh-e
+@section Moving Your Mail Around
+
+@cindex processing mail
+
+This section covers how messages and folders can be moved about or
+manipulated. Messages may be incorporated into your @file{+inbox},
+deleted, and refiled. Messages containing @code{shar} or
+@code{uuencode} output can be stored. Folders can be visited, sorted,
+packed, or deleted. Here's a list of the available commands to do these
+things:
+
+@c Stephen thinks that ? should be documented here, since it also shows
+@c which folders a message will be refiled to.
+
+@table @kbd
+@item i
+Incorporate new mail into folder (@code{mh-inc-folder}).
+
+@item d
+Delete message (@code{mh-delete-msg}).
+
+@item C-d
+Delete message, don't move to next message (@code{mh-delete-msg-no-motion}).
+
+@item M-s
+Find messages that meet search criteria (@code{mh-search-folder}).
+
+@item o
+Output (refile) message to folder (@code{mh-refile-msg}).
+
+@item c
+Copy message to folder (@code{mh-copy-msg}).
+
+@item C-o
+Output (write) message to file (@code{mh-write-msg-to-file}).
+
+@item !
+Repeat last output command (@code{mh-refile-or-write-again}).
+
+@item l
+Print message with @code{lpr} (@code{mh-print-msg}).
+
+@item |
+Pipe message through shell command (@code{mh-pipe-msg}).
+
+@item M-n
+Unpack message created with @code{uudecode} or @code{shar}
+(@code{mh-store-msg}).
+
+@item M-l
+List all folders (@code{mh-list-folders}).
+
+@item M-f
+Visit folder (@code{mh-visit-folder}).
+
+@item M-r
+Regenerate scan lines (@code{mh-rescan-folder}).
+
+@item M-x mh-sort-folder
+Sort folder.
+
+@item M-p
+Pack folder (@code{mh-pack-folder}).
+
+@item M-k
+Remove folder (@code{mh-kill-folder}).
+
+@item x
+Execute pending refiles and deletes (@code{mh-execute-commands}).
+
+@item u
+Undo pending refile or delete (@code{mh-undo}).
+
+@item M-u
+Undo all pending refiles and deletes (@code{mh-undo-folder}).
+
+@item q
+Quit (@code{mh-quit}).
+@end table
+
+@menu
+* Incorporating::
+* Deleting::
+* Organizing::
+* Printing::
+* Files and Pipes::
+* Finishing Up::
+@end menu
+
+@node Incorporating, Deleting, Moving Mail, Moving Mail
+@subsection Incorporating Your Mail
+
+@cindex incorporating
+@findex @code{mh-inc-folder}
+
+If at any time you receive new mail, incorporate the new mail into your
+@samp{+inbox} buffer with @kbd{i} (@code{mh-inc-folder}). Note that
+@kbd{i} will display the @samp{+inbox} buffer, even if there isn't any
+new mail. You can incorporate mail from any file into the current
+folder by specifying a prefix argument; you'll be prompted for the name
+of the file to use (for example, @kbd{C-u i ~/mbox @key{RET}}).
+
+@cindex Emacs, notification of new mail
+@cindex notification of new mail
+@cindex new mail
+@cindex @file{.emacs}
+@cindex files, @file{.emacs}
+
+Emacs can notify you when you have new mail by displaying @samp{Mail} in
+the mode line. To enable this behavior, and to have a clock in the mode
+line besides, add the following to @file{~/.emacs}:
+
+@findex @code{display-time}
+
+@lisp
+(display-time)
+@end lisp
+
+@node Deleting, Organizing, Incorporating, Moving Mail
+@subsection Deleting Your Mail
+
+@cindex deleting
+@findex @code{mh-delete-msg}
+@findex @code{mh-delete-msg-no-motion}
+
+To mark a message for deletion, use the @kbd{d} (@code{mh-delete-msg})
+command. A @samp{D} is placed by the message in the scan window, and
+the next message is displayed. If the previous command had been
+@kbd{p}, then the next message displayed is the message previous to the
+message just deleted. If you specify a prefix argument, you will be
+prompted for a sequence (@pxref{Sequences}) to delete (for example,
+@kbd{C-u d frombob RET}). The @kbd{x} command actually carries out the
+deletion (@pxref{Finishing Up}). @kbd{C-d}
+(@code{mh-delete-msg-no-motion}) marks the message for deletion but
+leaves the cursor at the current message in case you wish to perform
+other operations on the message.
+
+@node Organizing, Printing, Deleting, Moving Mail
+@subsection Organizing Your Mail with Folders
+
+@cindex using folders
+@cindex @code{folder}
+@cindex MH commands, @code{folder}
+@cindex @code{refile}
+@cindex MH commands, @code{refile}
+@findex @code{mh-refile-msg}
+
+mh-e has analogies for each of the MH @code{folder} and @code{refile}
+commands. To refile a message in another folder, use the @kbd{o}
+(@code{mh-refile-msg}) (mnemonic: ``output'') command. You are prompted
+for the folder name.
+
+@findex @code{mh-refile-or-write-again}
+
+If you are refiling several messages into the same folder, you can use
+the @kbd{!} (@code{mh-refile-or-write-again}) command to repeat the last
+refile or write (see the description of @kbd{C-o} in @ref{Files and
+Pipes}). Or, place the messages into a sequence (@ref{Sequences}) and
+specify a prefix argument to @kbd{o}, in which case you'll be prompted
+for the name of the sequence (for example, @kbd{C-u o search RET}).
+
+@findex @code{mh-copy-msg}
+
+If you wish to copy a message to another folder, you can use the @kbd{c}
+(@code{mh-copy-msg}) command (see the @code{-link} argument to
+@code{refile}(1)). You are prompted for a folder, and you can specify a
+prefix argument if you want to copy a sequence into another folder. In
+this case, you are then prompted for the sequence. Note that unlike the
+@kbd{o} command, the copy takes place immediately. The original copy
+remains in the current folder.
+
+@findex @code{mh-visit-folder}
+
+When you want to read the messages that you have refiled into folders,
+use the @kbd{M-f} (@code{mh-visit-folder}) command to visit the folder.
+You are prompted for the folder name.
+
+@findex @code{mh-list-folders}
+@findex @code{mh-visit-folder}
+@findex @code{mh-sort-folder}
+@findex @code{mh-pack-folder}
+@findex @code{mh-rescan-folder}
+
+Other commands you can perform on folders include: @kbd{M-l}
+(@code{mh-list-folders}), to list all the folders in your mail
+directory; @kbd{M-k} (@code{mh-kill-folder}), to remove a folder;
+@kbd{M-x mh-sort-folder}, to sort the messages by date (see
+@code{sortm}(1) to see how to sort by other criteria); @kbd{M-p}
+(@code{mh-pack-folder}), to pack a folder, removing gaps from the
+numbering sequence; and @kbd{M-r} (@code{mh-rescan-folder}), to rescan
+the folder, which is useful to grab all messages in your @file{+inbox}
+after processing your new mail for the first time. If you don't want to
+rescan the entire folder, give @kbd{M-r} or @kbd{M-p} a prefix argument
+and you'll be prompted for a range of messages to display (for instance,
+@kbd{C-u M-r last:50 RET}).
+
+@node Printing, Files and Pipes, Organizing, Moving Mail
+@subsection Printing Your Mail
+
+@cindex printing
+@cindex @code{mhl}
+@cindex MH commands, @code{mhl}
+@cindex @code{lpr}
+@cindex Unix commands, @code{lpr}
+@findex @code{mh-print-msg}
+
+Printing mail is simple. Enter @kbd{l} (@code{mh-print-msg}) (for
+@i{l}ine printer or @i{l}pr). The message is formatted with @code{mhl}
+and printed with the @code{lpr} command. You can print all the messages
+in a sequence by specifying a prefix argument, in which case you are
+prompted for the name of the sequence (as in @kbd{C-u l frombob RET}).
+
+@node Files and Pipes, Finishing Up, Printing, Moving Mail
+@subsection Files and Pipes
+
+@cindex using files
+@cindex using pipes
+@findex @code{mh-write-msg-to-file}
+
+mh-e does offer a couple of commands that are not a part of MH@. The
+first one, @kbd{C-o} (@code{mh-write-msg-to-file}), writes a message to
+a file (think of the @kbd{o} as in "output"). You are prompted for the
+filename. If the file already exists, the message is appended to it.
+You can also write the message to the file without the header by
+specifying a prefix argument (such as @kbd{C-u C-o /tmp/foobar RET}).
+Subsequent writes to the same file can be made with the @kbd{!}
+command.
+
+@findex @code{mh-pipe-msg}
+
+You can also pipe the message through a Unix shell command with the
+@kbd{|} (@code{mh-pipe-msg}) command. You are prompted for the
+Unix command through which you wish to run your message. If you
+give an argument to this command, the message header is included in the
+text passed to the command (the contrived example @kbd{C-u | lpr}
+would be done with the @kbd{l} command instead).
+
+@cindex @code{shar}
+@cindex Unix commands, @code{shar}
+@cindex @code{uuencode}
+@cindex Unix commands, @code{uuencode}
+@findex @code{mh-store-msg}
+
+If the message is a shell archive @code{shar} or has been run through
+@code{uuencode} use @kbd{M-n} (@code{mh-store-msg}) to extract the body
+of the message. The default directory for extraction is the current
+directory, and you have a chance to specify a different extraction
+directory. The next time you use this command, the default directory is
+the last directory you used.
+
+@node Finishing Up, , Files and Pipes, Moving Mail
+@subsection Finishing Up
+
+@cindex expunging refiles and deletes
+@findex @code{mh-undo}
+@findex @code{mh-undo-folder}
+
+If you've deleted a message or refiled it, but changed your mind, you
+can cancel the action before you've executed it. Use @kbd{u}
+(@code{mh-undo}) to undo a refile on or deletion of a single message.
+You can also undo refiles and deletes for messages that belong to a
+given sequence by specifying a prefix argument. You'll be prompted for
+the name of the sequence (as in @kbd{C-u u frombob RET}).
+Alternatively, you can use @kbd{M-u} (@code{mh-undo-folder}) to undo all
+refiles or deletes in the current folder.
+
+@findex @code{mh-execute-commands}
+
+If you've marked messages to be deleted or refiled and you want to go
+ahead and delete or refile the messages, use @kbd{x}
+(@code{mh-execute-commands}). Many mh-e commands that may affect the
+numbering of the messages (such as @kbd{M-r} or @kbd{M-p}) will ask if you
+want to process refiles or deletes first and then either run @kbd{x} for
+you or undo the pending refiles and deletes, which are lost.
+
+@findex @code{mh-rmail}
+@findex @code{mh-quit}
+
+When you want to quit using mh-e and go back to editing, you can use the
+@kbd{q} (@code{mh-quit}) command. This buries the buffers of the
+current mh-e folder and restores the buffers that were present when you
+first ran @kbd{M-x mh-rmail}. You can later restore your mh-e session
+by selecting the @samp{+inbox} buffer or by running @kbd{M-x mh-rmail}
+again.
+
+@node Searching, Sequences, Moving Mail, Using mh-e
+@section Searching Through Messages
+
+@cindex searching
+@findex @code{mh-search-folder}
+
+You can search a folder for messages to or from a particular person or
+about a particular subject. In fact, you can also search for messages
+containing selected strings in any arbitrary header field or any string
+found within the messages. Use the @kbd{M-s} (@code{mh-search-folder})
+command. You are first prompted for the name of the folder to search
+and then placed in the following buffer in MH-Pick mode:
+
+@example
+@group
+@cartouche
+From: #
+To:
+Cc:
+Date:
+Subject:
+--------
+
+
+
+
+
+
+
+
+
+--**-Emacs: pick-pattern (MH-Pick)------All----------------------------
+
+@end cartouche
+@i{Pick window}
+@end group
+@end example
+
+@cindex @code{pick}
+@cindex MH commands, @code{pick}
+
+Edit this template by entering your search criteria in an appropriate
+header field that is already there, or create a new field yourself. If
+the string you're looking for could be anywhere in a message, then place
+the string underneath the row of dashes. The @kbd{M-s} command uses the
+MH command @code{pick} to do the real work, so read @code{pick}(1) to
+find out more about how to enter the criteria.
+
+There are no semantics associated with the search criteria---they are
+simply treated as strings. Case is ignored when all lowercase is used,
+and regular expressions (a la @code{ed}) are available. It is all right
+to specify several search criteria. What happens then is that a logical
+@emph{and} of the various fields is performed. If you prefer a logical
+@emph{or} operation, run @kbd{M-s} multiple times.
+
+As an example, let's say that we want to find messages from Ginnean
+about horseback riding in the Kosciusko National Park (Australia) during
+January, 1994. Normally we would start with a broad search and narrow
+it down if necessary to produce a manageable amount of data, but we'll
+cut to the chase and create a fairly restrictive set of criteria as
+follows:
+
+@example
+@group
+From: ginnean
+To:
+Cc:
+Date: Jan 1994
+Subject: horse.*kosciusko
+--------
+@end group
+@end example
+
+@findex @code{mh-to-field}
+
+As with MH-Letter mode, MH-Pick provides commands like
+@kbd{C-c C-f C-t} to help you fill in the blanks.
+
+@table @kbd
+@item C-c C-f C-t
+Move to @samp{To:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-c
+Move to @samp{cc:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-s
+Move to @samp{Subject:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-f
+Move to @samp{From:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-b
+Move to @samp{Bcc:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-f
+Move to @samp{Fcc:} header field (@code{mh-to-field}).
+
+@item C-c C-f C-d
+Move to @samp{Dcc:} header field (@code{mh-to-field}).
+
+@item C-c C-c
+Execute the search (@code{mh-do-pick-search}).
+@end table
+
+@findex @code{mh-do-pick-search}
+
+To perform the search, type @kbd{C-c C-c} (@code{mh-do-pick-search}).
+The selected messages are placed in the @i{search} sequence, which you
+can use later in forwarding (@pxref{Forwarding}), printing
+(@pxref{Printing}), or narrowing your field of view (@pxref{Sequences}).
+Subsequent searches are appended to the @i{search} sequence. If,
+however, you wish to start with a clean slate, first delete the
+@i{search} sequence (how to do this is discussed in @ref{Sequences}).
+
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+
+If you're searching in a folder that is already displayed in a
+MH-Folder buffer, only those messages contained in the buffer are
+used for the search. Therefore, if you want to search in all messages,
+first kill the folder's buffer with @kbd{C-x k} or scan the entire
+folder with @kbd{M-r}.
+
+@node Sequences, Miscellaneous, Searching, Using mh-e
+@section Using Sequences
+
+@cindex sequences
+
+For the whole scoop on MH sequences, refer to @code{mh-sequence}(5). As
+you've read, several of the mh-e commands can operate on a sequence,
+which is a shorthand for a range or group of messages. For example, you
+might want to forward several messages to a friend or colleague. Here's
+how to manipulate sequences.
+
+@table @kbd
+@item %
+Put message in a sequence (@code{mh-put-msg-in-seq}).
+
+@item ?
+Display sequences that message belongs to (@code{mh-msg-is-in-seq}).
+
+@item M-q
+List all sequences in folder (@code{mh-list-sequences}).
+
+@item M-%
+Remove message from sequence (@code{mh-delete-msg-from-seq}).
+
+@item M-#
+Delete sequence (@code{mh-delete-seq}).
+
+@item C-x n
+Restrict display to messages in sequence (@code{mh-narrow-to-seq}).
+
+@item C-x w
+Remove restriction; display all messages (@code{mh-widen}).
+
+@item M-x mh-update-sequences
+Push mh-e's state out to MH@.
+@end table
+
+@cindex @code{pick}
+@cindex MH commands, @code{pick}
+@findex @code{mh-put-msg-in-seq}
+
+To place a message in a sequence, use @kbd{%} (@code{mh-put-msg-in-seq})
+to do it manually, or use the MH command @code{pick} or the mh-e version
+of @code{pick} (@ref{Searching}) which create a sequence automatically.
+Give @kbd{%} a prefix argument and you can add all the messages in one
+sequence to another sequence (for example, @kbd{C-u % SourceSequence
+RET}).
+
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+@findex @code{mh-narrow-to-seq}
+@findex @code{mh-widen}
+
+Once you've placed some messages in a sequence, you may wish to narrow
+the field of view to just those messages in the sequence you've created.
+To do this, use @kbd{C-x n} (@code{mh-narrow-to-seq}). You are prompted
+for the name of the sequence. What this does is show only those
+messages that are in the selected sequence in the MH-Folder buffer. In
+addition, it limits further mh-e searches to just those messages. When
+you want to widen the view to all your messages again, use @kbd{C-x w}
+(@code{mh-widen}).
+
+@findex @code{mh-msg-is-in-seq}
+@findex @code{mh-list-sequences}
+
+You can see which sequences a message is in with the @kbd{?}
+(@code{mh-msg-is-in-seq}) command.
+@c Doesn't work:
+@c use a prefix argument to query a
+@c message other than the current one (as in @kbd{C-u ? 42 RET}).
+Or, you can list all sequences in a selected folder (default is current
+folder) with @kbd{M-q} (@code{mh-list-sequences}).
+
+@findex @code{mh-delete-msg-from-seq}
+@findex @code{mh-delete-seq}
+
+If you want to remove a message from a sequence, use @kbd{M-%}
+(@code{mh-delete-msg-from-seq}), and if you want to delete an entire
+sequence, use @kbd{M-#} (@code{mh-delete-seq}). In the latter case you
+are prompted for the sequence to delete. Note that this deletes only
+the sequence, not the messages in the sequence. If you want to delete
+the messages, use @kbd{C-u d} (see @ref{Deleting} above).
+
+@cindex @code{mark}
+@cindex MH commands, @code{mark}
+
+@findex @code{mh-update-sequences}
+
+Two sequences are maintained internally by mh-e and pushed out to MH
+when you type either the @kbd{x} or @kbd{q} command. They are the
+sequence specified by your @samp{Unseen-Sequence:} profile entry and
+@i{cur}. However, you can also just update MH's state with the command
+@kbd{M-x mh-update-sequences}. See @ref{Customizing Viewing} for an
+example of how this command might be used.
+
+With the exceptions of @kbd{C-x n} and @kbd{C-x w}, the underlying MH
+command dealing with sequences is @code{mark}.
+
+@node Miscellaneous, , Sequences, Using mh-e
+@section Miscellaneous Commands
+
+@findex @code{mh-version}
+
+One other command worth noting is @kbd{M-x mh-version}. Since there
+were a few changes in command letters between @w{Versions 3} and 4, use
+this command to see which version you are running. This command didn't
+exist before @w{Version 4}, so the message @samp{[No match]}
+indicates that it's time to upgrade (@pxref{Getting mh-e}). In the
+meantime, use the older commands that are listed in @ref{Changes to
+mh-e}. The output of @kbd{M-x mh-version} should also be included with
+any bug report you send (@pxref{Bug Reports}).
+
+@node Customizing mh-e, Odds and Ends, Using mh-e, Top
+@chapter Customizing mh-e
+
+Until now, we've talked about the mh-e commands as they work ``out of the
+box.'' Of course, it is also possible to reconfigure mh-e
+@c to fit the needs of even the most demanding user. ???
+beyond recognition. The following sections describe all of the
+customization variables, show the defaults, and make recommendations for
+customization. The outline of this chapter is identical to that of
+@ref{Using mh-e}, to make it easier to find the variables you'd need to
+modify to affect a particular command.
+
+However, when customizing your mail environment, first try to change
+what you want in MH, and only change mh-e if changing MH is not
+possible. That way you will get the same behavior inside and outside
+GNU Emacs. Note that mh-e does not provide hooks for customizations
+that can be done in MH; this omission is intentional.
+
+@cindex @file{.emacs}
+@cindex files, @file{.emacs}
+
+Many string or integer variables are easy enough to modify using Emacs
+Lisp. Any such modifications should be placed in a file called
+@file{.emacs} in your home directory (that is, @file{~/.emacs}). For
+example, to modify the variable that controls printing, you could add:
+
+@vindex @code{mh-lpr-command-format}, example
+
+@lisp
+(setq mh-lpr-command-format "nenscript -G -r -2 -i'%s'")
+@end lisp
+
+@ref{Customizing Printing} talks more about this variable.
+
+@cindex setting variables
+@cindex Emacs, setting variables
+
+Variables can also hold Boolean values. In Emacs Lisp, the Boolean
+values are @code{nil}, which means false, and @code{t}, which means true.
+Usually, variables are turned off by setting their value to @code{nil}, as
+in
+
+@vindex @code{mh-bury-show-buffer}, example
+
+@lisp
+(setq mh-bury-show-buffer nil)
+@end lisp
+
+which keeps the MH-Show buffer at the top of the buffer stack.
+To turn a variable on, you use
+
+@lisp
+(setq mh-bury-show-buffer t)
+@end lisp
+
+which places the MH-Show buffer at the bottom of the buffer
+stack. However, the text says to turn on a variable by setting it to a
+@emph{non-@code{nil}} value, because sometimes values other than @code{t} are
+meaningful (for example, see @code{mhl-formfile}, described in
+@ref{Customizing Viewing}). Other variables, such as hooks, involve a
+little more Emacs Lisp programming expertise.
+
+You can also ``preview'' the effects of changing variables before
+committing the changes to @file{~/.emacs}. Variables can be changed in
+the current Emacs session by using @kbd{M-x set-variable}.
+
+@c XXX Stephen says: would be easier to just call them functions, which
+@c you mostly do.
+In general, @dfn{commands} in this text refer to Emacs Lisp functions.
+Programs outside of Emacs are specifically called MH commands, shell
+commands, or Unix commands.
+
+@cindex Emacs, Emacs Lisp manual
+@cindex Emacs, online help
+@cindex online help
+@cindex Emacs, info
+@cindex info
+
+I hope I've included enough examples here to get you well on your way.
+If you want to explore Emacs Lisp further, a programming manual does
+exist,
+@c Yes, some of the stuff in the following sections is redundant, but
+@c TeX barfs if the @ifs are inside the @footnote.
+@iftex
+@footnote{The @cite{GNU Emacs Lisp Reference Manual} may be available
+online in the Info system by typing @kbd{C-h i m Emacs Lisp RET}. If
+not, you can order a printed manual, which has the desirable side-effect
+of helping to support the Free Software Foundation which made all this
+great software available. You can find an order form by running
+@kbd{C-h C-d}, or you can request an order form from
+@i{gnu@@gnu.org}.}
+@end iftex
+@ifinfo
+@footnote{Perhaps you can find the online version of @ref{Top, The GNU
+Emacs Lisp Reference Manual, , elisp, GNU Emacs Lisp Reference Manual}.
+If not, you can order a printed manual, which has the desirable
+side-effect of helping to support the Free Software Foundation which
+made all this great software available. You can find an order form by
+running @kbd{C-h C-d}, or you can request an order form from
+@i{gnu@@gnu.org}.}
+@end ifinfo
+and you can look at the code itself for examples. Look in the Emacs
+Lisp directory on your system (such as @file{/usr/local/lib/emacs/lisp})
+and find all the @file{mh-*.el} files there. When calling mh-e and
+other Emacs Lisp functions directly from Emacs Lisp code, you'll need to
+know the correct arguments. Use the online help for this. For example,
+try @kbd{C-h f mh-execute-commands RET}. If you write your own
+functions, please do not prefix your symbols (variables and functions)
+with @code{mh-}. This prefix is reserved for the mh-e package. To
+avoid conflicts with existing mh-e symbols, use a prefix like @code{my-}
+or your initials.
+
+@menu
+* Customizing Reading::
+* Customizing Sending::
+* Customizing Draft Editing::
+* Customizing Moving Mail::
+* Customizing Searching::
+@end menu
+
+@node Customizing Reading, Customizing Sending, Customizing mh-e, Customizing mh-e
+@section Reading Your Mail
+
+@cindex reading mail
+@cindex @file{.emacs}
+@cindex files, @file{.emacs}
+
+I'll start out by including a function that I use as a front end to
+mh-e. @footnote{Stephen Gildea's favorite binding is
+@kbd{(global-set-key "\C-cr" 'mh-rmail)}.} It toggles between your
+working window configuration, which may be quite involved---windows
+filled with source, compilation output, man pages, and other
+documentation---and your mh-e window configuration. Like the rest of
+the customization described in this chapter, simply add the following
+code to @file{~/.emacs}. Don't be intimidated by the size of this
+example; most customizations are only one line.
+
+@iftex
+@filbreak
+@end iftex
+
+@findex @code{mh-rmail}, example
+
+@lisp
+@group
+@i{Starting mh-e}
+
+(defvar my-mh-screen-saved nil
+ "Set to non-@code{nil} when mh-e window configuration shown.")
+(defvar my-normal-screen nil "Normal window configuration.")
+(defvar my-mh-screen nil "mh-e window configuration.")
+
+(defun my-mh-rmail (&optional arg)
+ "Toggle between mh-e and normal screen configurations.
+With non-@code{nil} or prefix argument, @i{inc} mailbox as well
+when going into mail."
+ (interactive "P") ; @r{user callable function, P=prefix arg}
+ (setq my-mh-screen-saved ; @r{save state}
+ (cond
+ ;; @r{Bring up mh-e screen if arg or normal window configuration.}
+ ;; @r{If arg or +inbox buffer doesn't exist, run mh-rmail.}
+ ((or arg (null my-mh-screen-saved))
+ (setq my-normal-screen (current-window-configuration))
+ (if (or arg (null (get-buffer "+inbox")))
+ (mh-rmail)
+ (set-window-configuration my-mh-screen))
+ t) ; @r{set my-mh-screen-saved to @code{t}}
+ ;; @r{Otherwise, save mh-e screen and restore normal screen.}
+ (t
+ (setq my-mh-screen (current-window-configuration))
+ (set-window-configuration my-normal-screen)
+ nil)))) ; @r{set my-mh-screen-saved to nil}
+
+(global-set-key "\C-x\r" 'my-mh-rmail) ;@r{ call with C-x RET}
+@end group
+@end lisp
+
+If you type an argument (@kbd{C-u}) or if @code{my-mh-screen-saved}
+is @code{nil} (meaning a non-mh-e window configuration), the current window
+configuration is saved, either +inbox is displayed or @code{mh-rmail} is
+run, and the mh-e window configuration is shown. Otherwise, the mh-e
+window configuration is saved and the original configuration is
+displayed.
+
+Now to configure mh-e. The following table lists general mh-e variables
+and variables that are used while reading mail.
+@c XXX Seth wishes the descriptions to be more parallel. That is,
+@c some are actions, and some are objects. Hmmm.
+
+@table @code
+@item mh-progs
+Directory containing MH programs (default: dynamic).
+
+@item mh-lib
+Directory containing MH support files and programs (default: dynamic).
+
+@item mh-do-not-confirm
+Don't confirm on non-reversible commands (default: @code{nil}).
+
+@item mh-summary-height
+Number of scan lines to show (includes mode line) (default: 4).
+
+@item mh-folder-mode-hook
+Functions to run in MH-Folder mode (default: @code{nil}).
+
+@item mh-clean-message-header
+Remove extraneous headers (default: @code{nil}).
+
+@item mh-invisible-headers
+Headers to hide (default: @samp{"^Received: \\| ^Message-Id: \\|
+^Remailed-\\| ^Via: \\| ^Mail-from: \\| ^Return-Path: \\| ^In-Reply-To:
+\\| ^Resent-"}).
+
+@item mh-visible-headers
+Headers to display (default: @code{nil}).
+
+@item mhl-formfile
+Format file for @code{mhl} (default: @code{nil}).
+
+@item mh-show-hook
+Functions to run when showing message (default: @code{nil}).
+
+@item mh-show-mode-hook
+Functions to run when showing message (default: @code{nil}).
+
+@item mh-bury-show-buffer
+Leave show buffer at bottom of stack (default: @code{t}).
+
+@item mh-show-buffer-mode-line-buffer-id
+Name of show buffer in mode line (default: @samp{"@{show-%s@} %d"}).
+@end table
+
+@vindex @code{mh-progs}
+@vindex @code{mh-lib}
+
+The two variables @code{mh-progs} and @code{mh-lib} are used to tell
+mh-e where the MH programs and supporting files are kept, respectively.
+mh-e does try to figure out where they are kept for itself by looking in
+common places and in the user's @samp{PATH} environment variable, but if
+it cannot find the directories, or finds the wrong ones, you should set
+these variables. The name of the directory should be placed in double
+quotes, and there should be a
+trailing slash (@samp{/}). See the example in @ref{Getting Started}.
+
+@vindex @code{mh-do-not-confirm}
+
+If you never make mistakes, and you do not like confirmations for your
+actions, you can set @code{mh-do-not-confirm} to a non-@code{nil} value to
+disable confirmation for unrecoverable commands such as @kbd{M-k}
+(@code{mh-kill-folder}) and @kbd{M-u} (@code{mh-undo-folder}). Here's
+how you set boolean values:
+
+@lisp
+(setq mh-do-not-confirm t)
+@end lisp
+
+@vindex @code{mh-summary-height}
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+
+@c Prevent page break between paragraph and example.
+@need 2000
+The variable @code{mh-summary-height} controls the number of scan lines
+displayed in the MH-Folder window, including the mode line. The
+default value of 4 means that 3 scan lines are displayed. Here's how
+you set numerical values:
+
+@lisp
+(setq mh-summary-height 2) ; @r{only show the current scan line}
+@end lisp
+
+@vindex @code{mh-bury-show-buffer}
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+
+Normally the buffer for displaying messages is buried at the bottom at
+the buffer stack. You may wish to disable this feature by setting
+@code{mh-bury-show-buffer} to @code{nil}. One advantage of not burying the
+show buffer is that one can delete the show buffer more easily in an
+electric buffer list because of its proximity to its associated
+MH-Folder buffer. Try running @kbd{M-x electric-buffer-list} to
+see what I mean.
+
+@vindex @code{mh-folder-mode-hook}
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+
+The hook @code{mh-folder-mode-hook} is called when a new folder is
+created with MH-Folder mode. This could be used to set your own
+key bindings, for example:
+
+@vindex @code{mh-folder-mode-hook}, example
+
+@lisp
+@group
+@i{Create additional key bindings via mh-folder-mode-hook}
+
+(defvar my-mh-init-done nil "Non-@code{nil} when one-time mh-e settings made.")
+
+(defun my-mh-folder-mode-hook ()
+ "Hook to set key bindings in MH-Folder mode."
+ (if (not my-mh-init-done) ; @r{only need to bind the keys once }
+ (progn
+ (local-set-key "/" 'search-msg)
+ (local-set-key "b" 'mh-burst-digest) ; @r{better use of @kbd{b}}
+ (setq my-mh-init-done t))))
+
+;;; @r{Emacs 19}
+(add-hook 'mh-folder-mode-hook 'my-mh-folder-mode-hook)
+;;; @r{Emacs 18}
+;;; @r{(setq mh-folder-mode-hook (cons 'my-mh-folder-mode-hook}
+;;; @r{mh-folder-mode-hook))}
+
+(defun search-msg ()
+ "Search for a regexp in the current message."
+ (interactive) ; @r{user function}
+ (save-window-excursion
+ (other-window 1) ; @r{go to next window}
+ (isearch-forward-regexp))) ; @r{string search; hit return (ESC}
+ ; @r{in Emacs 18) when done}
+@end group
+@end lisp
+
+@menu
+* Customizing Viewing::
+* Customizing Moving Around::
+@end menu
+
+@node Customizing Viewing, Customizing Moving Around, Customizing Reading, Customizing Reading
+@subsection Viewing Your Mail
+
+@vindex @code{mh-clean-message-header}
+@vindex @code{mh-invisible-headers}
+@vindex @code{mh-visible-headers}
+
+Several variables control what displayed messages look like. Normally
+messages are delivered with a handful of uninteresting header fields.
+You can make them go away by setting @code{mh-clean-message-header} to a
+non-@code{nil} value. The header can then be cleaned up in two ways. By
+default, the header fields in @code{mh-invisible-headers} are removed.
+On the other hand, you could set @code{mh-visible-headers} to the fields
+that you would like to see. If this variable is set,
+@code{mh-invisible-headers} is ignored. I suggest that you not set
+@code{mh-visible-headers} since if you use this variable, you might miss
+a lot of header fields that you'd rather not miss. As an example of how
+to set a string variable, @code{mh-visible-headers} can be set to show a
+minimum set of header fields (see (@ref{Regexps, , Syntax of Regular
+Expressions, emacs, The GNU Emacs Manual}, for a description of the
+special characters in this string):
+
+@lisp
+(setq mh-visible-headers "^From: \\|^Subject: \\|^Date: ")
+@end lisp
+
+@cindex @code{mhl}
+@cindex MH commands, @code{mhl}
+@vindex @code{mhl-formfile}
+
+Normally mh-e takes care of displaying messages itself (rather than
+calling an MH program to do the work). If you'd rather have @code{mhl}
+display the message (within mh-e), set the variable @code{mhl-formfile}
+to a non-@code{nil} value. You can set this variable either to @code{t}
+to use the default format file or to a filename if you have your own
+format file (@code{mhl}(1) tells you how to write one). When writing
+your own format file, use a nonzero value for @code{overflowoffset} to
+ensure the header is RFC 822 compliant and parsable by mh-e.
+@code{mhl} is always used for printing and forwarding; in this case, the
+value of @code{mhl-formfile} is consulted if it is a filename.
+
+@vindex @code{mh-show-mode-hook}
+
+Two hooks can be used to control how messages are displayed. The first
+hook, @code{mh-show-mode-hook}, is called early on in the process of
+displaying of messages. It is used to perform some actions on the
+contents of messages, such as highlighting the header fields. If you're
+running Emacs 19 under the X Window System, the following example will
+highlight the @samp{From:} and @samp{Subject:} header fields. This is a
+very nice feature indeed.
+
+@vindex @code{mh-show-mode-hook}, example
+
+@lisp
+@group
+@i{Emphasize header fields in different fonts via mh-show-mode-hook}
+
+(defvar my-mh-keywords
+ '(("^From: \\(.*\\)" 1 'bold t)
+ ("^Subject: \\(.*\\)" 1 'highlight t))
+ "mh-e additions for font-lock-keywords.")
+
+(defun my-mh-show-mode-hook ()
+ "Hook to turn on and customize fonts."
+ (require 'font-lock) ; @r{for font-lock-keywords below}
+ (make-local-variable 'font-lock-mode-hook) ; @r{don't affect other buffers}
+ (add-hook 'font-lock-mode-hook ; @r{set a hook with inline function}
+ (function ; @r{modifies font-lock-keywords when}
+ (lambda () ; @r{font-lock-mode run}
+ (setq font-lock-keywords
+ (append my-mh-keywords font-lock-keywords)))))
+ (font-lock-mode 1)) ; @r{change the typefaces}
+
+(if window-system ; @r{can't do this on @sc{ASCII} terminal}
+ (add-hook 'mh-show-mode-hook 'my-mh-show-mode-hook))
+@end group
+@end lisp
+
+@vindex @code{mh-show-hook}
+
+The second hook, @code{mh-show-hook}, is the last thing called after
+messages are displayed. It's used to affect the behavior of mh-e in
+general or when @code{mh-show-mode-hook} is too early. For example, if
+you wanted to keep mh-e in sync with MH, you could use
+@code{mh-show-hook} as follows:
+
+@vindex @code{mh-show-hook}, example
+
+@lisp
+(add-hook 'mh-show-hook 'mh-update-sequences)
+@end lisp
+
+@vindex @code{mh-show-buffer-mode-line-buffer-id}
+@cindex MH-Show mode
+@cindex modes, MH-Show
+
+The function @code{mh-update-sequences} is documented in @ref{Finishing
+Up}. For those who like to modify their mode lines, use
+@code{mh-show-buffer-mode-line-buffer-id} to modify the mode line in the
+MH-Show buffers. Place the two escape strings @samp{%s} and @samp{%d},
+which will display the folder name and the message number, respectively,
+somewhere in the string in that order. The default value of
+@samp{"@{show-%s@} %d"} yields a mode line of
+
+@example
+-----@{show-+inbox@} 4 (MH-Show)--Bot----------------------------------
+@end example
+
+@node Customizing Moving Around, , Customizing Viewing, Customizing Reading
+@subsection Moving Around
+
+@cindex moving between messages
+@cindex MH-Show mode
+@cindex modes, MH-Show
+@cindex MH-Folder mode
+@cindex modes, MH-Folder
+@vindex @code{mh-recenter-summary-p}
+
+When you use @kbd{t} (@code{mh-toggle-showing}) to toggle between show
+mode and scan mode, the MH-Show buffer is hidden and the
+MH-Folder buffer is left alone. Setting
+@code{mh-recenter-summary-p} to a non-@code{nil} value causes the toggle to
+display as many scan lines as possible, with the cursor at the middle.
+The effect of @code{mh-recenter-summary-p} is rather useful, but it can
+be annoying on a slow network connection.
+
+@node Customizing Sending, Customizing Draft Editing, Customizing Reading, Customizing mh-e
+@section Sending Mail
+
+@cindex sending mail
+
+You may wish to start off by adding the following useful key bindings to
+your @file{.emacs} file:
+
+@lisp
+(global-set-key "\C-xm" 'mh-smail)
+(global-set-key "\C-x4m" 'mh-smail-other-window)
+@end lisp
+
+In addition, several variables are useful when sending mail or replying
+to mail. They are summarized in the following table.
+
+@table @code
+@item mh-comp-formfile
+Format file for drafts (default: @samp{"components"}).
+
+@item mh-repl-formfile
+Format file for replies (default: @samp{"replcomps"}).
+
+@item mh-letter-mode-hook
+Functions to run in MH-Letter mode (default: @code{nil}).
+
+@item mh-compose-letter-function
+Functions to run when starting a new draft (default: @code{nil}).
+
+@item mh-reply-default-reply-to
+Whom reply goes to (default: @code{nil}).
+
+@item mh-forward-subject-format
+Format string for forwarded message subject (default: @samp{"%s: %s"}).
+
+@item mh-redist-full-contents
+@code{send} requires entire message (default: @code{nil}).
+
+@item mh-new-draft-cleaned-headers
+Remove these header fields from re-edited draft (default:
+@samp{"^Date:\\| ^Received:\\| ^Message-Id:\\| ^From:\\| ^Sender:\\|
+^Delivery-Date:\\| ^Return-Path:"}).
+@end table
+
+@cindex @code{comp}
+@cindex MH commands, @code{comp}
+@vindex @code{mh-comp-formfile}
+@cindex @file{components}
+@cindex files, @file{components}
+@cindex @code{repl}
+@cindex MH commands, @code{repl}
+@cindex @file{replcomps}
+@cindex files, @file{replcomps}
+@vindex @code{mh-repl-formfile}
+
+Since mh-e does not use @code{comp} to create the initial draft, you
+need to set @code{mh-comp-formfile} to the name of your components file
+if it isn't @file{components}. This is the name of the file that
+contains the form for composing messages. If it does not contain an
+absolute pathname, mh-e searches for the file first in your MH directory
+and then in the system MH library directory (such as
+@file{/usr/local/lib/mh}). Replies, on the other hand, are built using
+@code{repl}. You can change the location of the field file from the
+default of @file{replcomps} by modifying @code{mh-repl-formfile}.
+
+@vindex @code{mh-letter-mode-hook}
+@cindex @code{repl}
+@cindex MH commands, @code{repl}
+@cindex @file{components}
+@cindex files, @file{components}
+
+Two hooks are provided to run commands on your freshly created draft.
+The first hook, @code{mh-letter-mode-hook}, allows you to do some
+processing before editing a letter. For example, you may wish to modify
+the header after @code{repl} has done its work, or you may have a
+complicated @file{components} file and need to tell mh-e where the
+cursor should go. Here's an example of how you would use this hook---all
+of the other hooks are set in this fashion as well.
+
+@findex @code{mh-insert-signature}, example
+
+@lisp
+@group
+@i{Prepare draft for editing via mh-letter-mode-hook}
+
+(defvar letter-mode-init-done nil
+ "Non-@code{nil} when one-time mh-e settings have made.")
+
+(defun my-mh-letter-mode-hook ()
+ "Hook to prepare letter for editing."
+ (if (not letter-mode-init-done) ; @r{only need to bind the keys once}
+ (progn
+ (local-set-key "\C-ctb" 'add-enriched-text)
+ (local-set-key "\C-cti" 'add-enriched-text)
+ (local-set-key "\C-ctf" 'add-enriched-text)
+ (local-set-key "\C-cts" 'add-enriched-text)
+ (local-set-key "\C-ctB" 'add-enriched-text)
+ (local-set-key "\C-ctu" 'add-enriched-text)
+ (local-set-key "\C-ctc" 'add-enriched-text)
+ (setq letter-mode-init-done t)))
+ (setq fill-prefix " ") ; @r{I find indented text easier to read}
+ (save-excursion
+ (goto-char (point-max)) ; @r{go to end of message to}
+ (mh-insert-signature))) ; @r{insert signature}
+
+(add-hook 'mh-letter-mode-hook 'my-mh-letter-mode-hook)
+@end group
+@end lisp
+
+The function, @code{add-enriched-text} is defined in the example in
+@ref{Customizing Editing MIME}.
+
+@vindex @code{mh-compose-letter-function}
+
+The second hook, a function really, is
+@code{mh-compose-letter-function}. Like @code{mh-letter-mode-hook}, it
+is called just before editing a new message; however, it is the last
+function called before you edit your message. The consequence of this
+is that you can write a function to write and send the message for you.
+This function is passed three arguments: the contents of the @samp{To:},
+@samp{Subject:}, and @samp{cc:} header fields.
+
+@menu
+* Customizing Replying::
+* Customizing Forwarding::
+* Customizing Redistributing::
+* Customizing Old Drafts::
+@end menu
+
+@node Customizing Replying, Customizing Forwarding, Customizing Sending, Customizing Sending
+@subsection Replying to Mail
+
+@cindex replying
+@vindex @code{mh-reply-default-reply-to}
+
+If you find that most of the time that you specify @kbd{cc} when you
+reply to a message, set @code{mh-reply-default-reply-to} to @samp{cc}.
+This variable is normally set to @code{nil} so that you are prompted for
+the recipient of a reply. It can be set to one of @samp{from},
+@samp{to}, or @samp{cc}; you are then no longer prompted for the
+recipient(s) of your reply.
+
+@node Customizing Forwarding, Customizing Redistributing, Customizing Replying, Customizing Sending
+@subsection Forwarding Mail
+
+@cindex forwarding
+@vindex @code{mh-forward-subject-format}
+
+When forwarding a message, the format of the @samp{Subject:} header
+field can be modified by the variable @code{mh-forward-subject-format}.
+This variable is a string which includes two escapes (@samp{%s}). The
+first @samp{%s} is replaced with the sender of the original message, and
+the second one is replaced with the original @samp{Subject:}. The
+default value of @samp{"%s: %s"} takes a message with the header:
+
+@example
+@group
+To: Bill Wohler <wohler@@newt.com>
+Subject: Re: 49er football
+From: Greg DesBrisay <gd@@cellnet.com>
+@end group
+@end example
+
+and creates a subject header field of:
+
+@example
+Subject: Greg DesBrisay: Re: 49er football
+@end example
+
+@node Customizing Redistributing, Customizing Old Drafts, Customizing Forwarding, Customizing Sending
+@subsection Redistributing Your Mail
+
+@cindex redistributing
+@vindex @code{mh-redist-full-contents}
+@cindex @code{dist}
+@cindex MH commands, @code{dist}
+@cindex @code{send}
+@cindex MH commands, @code{send}
+
+The variable @code{mh-redist-full-contents} must be set to non-@code{nil} if
+@code{dist} requires the whole letter for redistribution, which is the
+case if @code{send} is compiled with the @sc{berk} @footnote{To see which
+options your copy of MH was compiled with, use @kbd{M-x mh-version}
+(@ref{Miscellaneous}).} option (which many people abhor). If you find
+that MH will not allow you to redistribute a message that has been
+redistributed before, this variable should be set to @code{nil}.
+
+@node Customizing Old Drafts, , Customizing Redistributing, Customizing Sending
+@subsection Editing Old Drafts and Bounced Messages
+
+@cindex re-editing drafts
+@vindex @code{mh-new-draft-cleaned-headers}
+
+The header fields specified by @code{mh-new-draft-cleaned-headers} are
+removed from an old draft that has been recreated with @kbd{M-e}
+(@code{mh-extract-rejected-mail}) or @kbd{M-a} (@code{mh-edit-again}).
+If when you edit an old draft with these commands you find that there
+are header fields that you don't want included, you can append them to
+this variable. For example,
+
+@vindex @code{mh-new-draft-cleaned-headers}, example
+
+@lisp
+(setq mh-new-draft-cleaned-headers
+ (concat mh-new-draft-cleaned-headers "\\|^Some-Field:"))
+@end lisp
+
+@cindex regular expressions
+
+This appends the regular expression @samp{\\|^Some-Field:} to the
+variable (@pxref{Regexps, , Syntax of Regular Expressions, emacs, The
+GNU Emacs Manual}). The @samp{\\|} means @emph{or}, and the @samp{^}
+(caret) matches the beginning of the line. This is done to be very
+specific about which fields match. The literal @samp{:} is appended for
+the same reason.
+
+@node Customizing Draft Editing, Customizing Moving Mail, Customizing Sending, Customizing mh-e
+@section Editing a Draft
+
+@cindex editing draft
+
+There are several variables used during the draft editing phase.
+Examples include changing the name of the file that holds your signature
+or telling mh-e about new multimedia types. They are:
+
+@table @code
+@item mh-yank-from-start-of-msg
+How to yank when region not set (default: @code{t}).
+
+@item mh-ins-buf-prefix
+Indent for yanked messages (default: @samp{"> "}).
+
+@item mail-citation-hook
+Functions to run on yanked messages (default: @code{nil}).
+
+@item mh-delete-yanked-msg-window
+Delete message window on yank (default: @code{nil}).
+
+@c Need the @* because otherwise TeX fills it wrong and complains
+@c about overfull hbox.
+@item mh-mime-content-types
+List of valid content types (default: @samp{'(("text/plain")@*
+("text/richtext") ("multipart/mixed") ("multipart/alternative")@*
+("multipart/digest") ("multipart/parallel") ("message/rfc822")@*
+("message/partial") ("message/external-body")@*
+("application/octet-stream") ("application/postscript")@*
+("image/jpeg") ("image/gif") ("audio/basic") ("video/mpeg"))}).
+
+@item mh-mhn-args
+Additional arguments for @code{mhn} (default: @code{nil}).
+
+@item mh-signature-file-name
+File containing signature (default: @samp{"~/.signature"}).
+
+@item mh-before-send-letter-hook
+Functions to run before sending draft (default: @code{nil}).
+
+@item mh-send-prog
+MH program used to send messages (default: @samp{"send"}).
+@end table
+
+@menu
+* Customizing Editing Textual::
+* Customizing Editing MIME::
+* Customizing Sending Message::
+@end menu
+
+@node Customizing Editing Textual, Customizing Editing MIME, Customizing Draft Editing, Customizing Draft Editing
+@subsection Editing Textual Messages
+
+The following two sections include variables that customize the way you
+edit a draft. The discussion here applies to editing multimedia
+messages as well.
+
+@menu
+* Customizing Inserting Letter::
+* Customizing Signature::
+@end menu
+
+@node Customizing Inserting Letter, Customizing Signature, Customizing Editing Textual, Customizing Editing Textual
+@subsubsection Inserting letter to which you're replying
+
+@cindex inserting messages
+@vindex @code{mh-yank-from-start-of-msg}
+@vindex @code{mh-ins-buf-prefix}
+@vindex @code{mail-citation-hook}
+@vindex @code{mh-ins-buf-prefix}
+@vindex @code{mh-delete-yanked-msg-window}
+
+To control how much of the message to which you are replying is yanked
+by @kbd{C-c C-y} (@code{mh-yank-cur-msg}) into your reply, modify
+@code{mh-yank-from-start-of-msg}. The default value of @code{t} means
+that the entire message is copied. If it is set to @code{'body} (don't
+forget the apostrophe), then only the message body is copied. If it is
+set to @code{nil}, only the part of the message following point (the
+current cursor position in the message's buffer) is copied. In any
+case, this variable is ignored if a region is set in the message you are
+replying to. The string contained in @code{mh-ins-buf-prefix} is
+inserted before each line of a message that is inserted into a draft
+with @kbd{C-c C-y} (@code{mh-yank-cur-msg}). I suggest that you not
+modify this variable. The default value of @samp{"> "} is the default
+string for many mailers and news readers: messages are far easier to
+read if several included messages have all been indented by the same
+string. The variable @code{mail-citation-hook} is @code{nil} by
+default, which means that when a message is inserted into the letter,
+each line is prefixed by @code{mh-ins-buf-prefix}. Otherwise, it can be
+set to a function that modifies an included
+@cindex Emacs, packages, supercite
+citation.
+@c Footnotes are fragile; hence the redundancy.
+@c TeX not inserting a line break; hence the @*
+@ifclear html
+@footnote{@emph{Supercite} is an example of a full-bodied, full-featured
+citation package. It is in Emacs versions 19.15 and later, and can be
+found via anonymous @code{ftp} on @samp{archive.cis.ohio-state.edu} in
+@* @file{/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z}}
+@end ifclear
+@ifset html
+@footnote{@emph{Supercite} is an example of a full-bodied,
+full-featured citation package. It is in Emacs versions 19.15 and
+later, and its @sc{url} is @*
+@file{<A HREF="ftp://archive.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z">ftp://archive.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z</A>}}
+@end ifset
+If you like to yank all the text from the message you're replying to in
+one go, set @code{mh-delete-yanked-msg-window} to non-@code{nil} to delete
+the window containing the original message after yanking it to make more
+room on your screen for your reply.
+
+@node Customizing Signature, , Customizing Inserting Letter, Customizing Editing Textual
+@subsubsection Inserting your signature
+
+@cindex inserting signature
+@cindex signature
+@vindex @code{mh-signature-file-name}
+@cindex @file{.signature}
+@cindex files, @file{.signature}
+
+You can change the name of the file inserted with @kbd{C-c C-s}
+(@code{mh-insert-signature}) by changing @code{mh-signature-file-name}
+(default: @file{"~/.signature"}).
+
+@node Customizing Editing MIME, Customizing Sending Message, Customizing Editing Textual, Customizing Draft Editing
+@subsection Editing Multimedia Messages
+
+@cindex MIME
+@cindex multimedia mail
+@vindex @code{mh-mime-content-types}
+
+The variable @code{mh-mime-content-types} contains a list of the
+currently valid content types. They are listed in the table in
+@ref{Customizing Draft Editing}. If you encounter a new content type,
+you can add it like this:
+
+@vindex @code{mh-mime-content-types}, example
+
+@lisp
+(setq mh-mime-content-types (append mh-mime-content-types
+ '(("@var{new/type}"))))
+@end lisp
+
+Emacs macros can be used to insert enriched text directives like
+@samp{<bold>}. The following code will make, for example, @kbd{C-c t
+b} insert the @samp{<bold>} directive.
+
+@lisp
+@group
+@i{Emacs macros for entering enriched text}
+
+(defvar enriched-text-types '(("b" . "bold") ("i" . "italic") ("f" . "fixed")
+ ("s" . "smaller") ("B" . "bigger")
+ ("u" . "underline") ("c" . "center"))
+ "Alist of (final-character . directive) choices for add-enriched-text.
+Additional types can be found in RFC 1563.")
+
+(defun add-enriched-text (begin end)
+ "Add enriched text directives around region.
+The directive used comes from the list enriched-text-types and is
+specified by the last keystroke of the command. When called from Lisp,
+arguments are BEGIN and END@."
+ (interactive "r")
+ ;; @r{Set type to the directive indicated by the last keystroke.}
+ (let ((type (cdr (assoc (char-to-string (logior last-input-char ?@w{`}))
+ enriched-text-types))))
+ (save-restriction ; @r{restores state from narrow-to-region}
+ (narrow-to-region begin end) ; @r{narrow view to region}
+ (goto-char (point-min)) ; @r{move to beginning of text}
+ (insert "<" type ">") ; @r{insert beginning directive}
+ (goto-char (point-max)) ; @r{move to end of text}
+ (insert "</" type ">")))) ; @r{insert terminating directive}
+@end group
+@end lisp
+
+To use the function @code{add-enriched-text}, first create keybindings
+for it (@pxref{Customizing Sending}). Then, set the mark with
+@kbd{C-@@} or @kbd{C-SPC}, type in the text to be highlighted, and type
+@kbd{C-c t b}. This adds @samp{<bold>} where you set the mark and
+adds @samp{</bold>} at the location of your cursor, giving you something
+like: @samp{You should be <bold>very</bold>}. You may also be
+interested in investigating @code{sgml-mode}.
+
+@menu
+* Customizing Sending MIME::
+@end menu
+
+@node Customizing Sending MIME, , Customizing Editing MIME, Customizing Editing MIME
+@subsubsection Readying multimedia messages for sending
+
+@vindex @code{mh-mhn-args}
+
+If you wish to pass additional arguments to @code{mhn} to affect how it
+builds your message, use the variable @code{mh-mhn-args}. For example,
+you can build a consistency check into the message by setting
+@code{mh-mhn-args} to @code{-check}. The recipient of your message can
+then run @code{mhn -check} on the message---@code{mhn} will complain if
+the message has been corrupted on the way. The @kbd{C-c C-e}
+(@code{mh-mhn-edit}) command only consults this variable when given a
+prefix argument.
+
+@node Customizing Sending Message, , Customizing Editing MIME, Customizing Draft Editing
+@subsection Sending a Message
+
+@cindex sending mail
+@cindex spell check
+@vindex @code{mh-before-send-letter-hook}
+
+If you want to check your spelling in your message before sending, use
+@code{mh-before-send-letter-hook} like this:
+
+@i{Spell-check message via mh-before-send-letter-hook}
+
+@vindex @code{mh-before-send-letter-hook}, example
+
+@lisp
+(add-hook 'mh-before-send-letter-hook 'ispell-message)
+@end lisp
+
+@cindex @code{send}
+@cindex MH commands, @code{send}
+@vindex @code{mh-send-prog}
+
+In case the MH @code{send} program is installed under a different name,
+use @code{mh-send-prog} to tell mh-e the name.
+
+@node Customizing Moving Mail, Customizing Searching, Customizing Draft Editing, Customizing mh-e
+@section Moving Your Mail Around
+
+@cindex processing mail
+
+If you change the name of some of the MH programs or have your own
+printing programs, the following variables can help you.
+They are described in detail in the subsequent sections.
+
+@table @code
+@item mh-inc-prog
+Program to incorporate mail (default: @samp{"inc"}).
+
+@item mh-inc-folder-hook
+Functions to run when incorporating mail (default: @code{nil}).
+
+@item mh-delete-msg-hook
+Functions to run when deleting messages (default: @code{nil}).
+
+@item mh-print-background
+Print in foreground or background (default: @code{nil}).
+
+@item mh-lpr-command-format
+Command used to print (default: @samp{"lpr -J '%s'"}).
+
+@item mh-default-folder-for-message-function
+Function to generate a default folder (default: @code{nil}).
+
+@item mh-auto-folder-collect
+Collect folder names in background at startup (default: @code{t}).
+
+@item mh-recursive-folders
+Collect nested folders (default: @code{nil}).
+
+@item mh-refile-msg-hook
+Functions to run when refiling message (default: @code{nil}).
+
+@item mh-store-default-directory
+Default directory for storing files created by @code{uuencode} or @code{shar}
+(default: @code{nil}).
+
+@item mh-sortm-args
+Additional arguments for @code{sortm} (default: @code{nil}).
+
+@item mh-scan-prog
+Program to scan messages (default: @samp{"scan"}).
+
+@item mh-before-quit-hook
+Functions to run before quitting (default: @code{nil}). See also
+@code{mh-quit-hook}.
+
+@item mh-quit-hook
+Functions to run after quitting (default: @code{nil}). See also
+@code{mh-before-quit-hook}.
+@end table
+
+@menu
+* Customizing Incorporating::
+* Customizing Deleting::
+* Customizing Organizing::
+* Customizing Printing::
+* Customizing Files and Pipes::
+* Customizing Finishing Up::
+@end menu
+
+@node Customizing Incorporating, Customizing Deleting, Customizing Moving Mail, Customizing Moving Mail
+@subsection Incorporating Your Mail
+
+@cindex incorporating
+@vindex @code{mh-inc-prog}
+@cindex @code{inc}
+@cindex MH commands, @code{inc}
+@vindex @code{mh-progs}
+@vindex @code{mh-scan-prog}
+@vindex @code{mh-inc-folder-hook}
+
+The name of the program that incorporates new mail is stored in
+@code{mh-inc-prog}; it is @samp{"inc"} by default. This program
+generates a one-line summary for each of the new messages. Unless it is
+an absolute pathname, the file is assumed to be in the @code{mh-progs}
+directory. You may also link a file to @code{inc} that uses a different
+format (see @code{mh-profile}(5)). You'll then need to modify several
+variables appropriately; see @code{mh-scan-prog} below. You can set the
+hook @code{mh-inc-folder-hook}, which is called after new mail is
+incorporated by the @kbd{i} (@code{mh-inc-folder}) command. A good use
+of this hook is to rescan the whole folder either after running @kbd{M-x
+mh-rmail} the first time or when you've changed the message numbers from
+outside of mh-e.
+
+@findex @code{mh-execute-commands}
+@findex @code{mh-rescan-folder}, example
+@findex @code{mh-show}, example
+@vindex @code{mh-inc-folder-hook}, example
+
+@lisp
+@group
+@i{Rescan folder after incorporating new mail via mh-inc-folder-hook}
+
+(defun my-mh-inc-folder-hook ()
+ "Hook to rescan folder after incorporating mail."
+ (if (buffer-modified-p) ; @r{if outstanding refiles and deletes,}
+ (mh-execute-commands)) ; @r{carry them out}
+ (mh-rescan-folder) ; @r{synchronize with +inbox}
+ (mh-show)) ; @r{show the current message}
+
+(add-hook 'mh-inc-folder-hook 'my-mh-inc-folder-hook)
+@end group
+@end lisp
+
+@node Customizing Deleting, Customizing Organizing, Customizing Incorporating, Customizing Moving Mail
+@subsection Deleting Your Mail
+
+@cindex deleting
+@vindex @code{mh-delete-msg-hook}
+
+The hook @code{mh-delete-msg-hook} is called after you mark a message
+for deletion. For example, the current maintainer of mh-e used this
+once when he kept statistics on his mail usage.
+
+@node Customizing Organizing, Customizing Printing, Customizing Deleting, Customizing Moving Mail
+@subsection Organizing Your Mail with Folders
+
+@cindex using folders
+@vindex @code{mh-recursive-folders}
+@vindex @code{mh-auto-folder-collect}
+
+By default, operations on folders work only one level at a time. Set
+@code{mh-recursive-folders} to non-@code{nil} to operate on all folders.
+This mostly means that you'll be able to see all your folders when you
+press @key{TAB} when prompted for a folder name. The variable
+@code{mh-auto-folder-collect} is normally turned on to generate a list
+of folder names in the background as soon as mh-e is loaded. Otherwise,
+the list is generated when you need a folder name the first time (as
+with @kbd{o} (@code{mh-refile-msg})). If you have a lot of folders and
+you have @code{mh-recursive-folders} set, this could take a while, which
+is why it's nice to do the folder collection in the background.
+
+@vindex @code{mh-default-folder-for-message-function}
+@findex @code{mh-refile-msg}
+@findex @code{mh-to-fcc}
+@cindex @file{.emacs}
+@cindex files, @file{.emacs}
+
+The function @code{mh-default-folder-for-message-function} is used by
+@kbd{o} (@code{mh-refile-msg}) and @kbd{C-c C-f C-f} (@code{mh-to-fcc})
+to generate a default folder. The generated folder name should be a
+string with a @samp{+} before it. For each of my correspondents, I use the
+same name for both an alias and a folder. So, I wrote a function that
+takes the address in the @samp{From:} header field, finds it in my alias
+file, and returns the alias, which is used as a default folder name.
+This is the most complicated example given here, and it demonstrates
+several features of Emacs Lisp programming. You should be able to drop
+this into @file{~/.emacs}, however. If you use this to store messages
+in a subfolder of your Mail directory, you can modify the line that
+starts @samp{(format +%s...} and insert your subfolder after the folder
+symbol @samp{+}.
+@c Note for me: if I insert a new version, don't forget to remove the
+@c "a/" from the folder name.
+
+@iftex
+@filbreak
+@end iftex
+
+@vindex @code{mh-default-folder-for-message-function}, example
+@vindex @code{mh-user-path}, example
+
+@lisp
+@group
+@i{Creating useful default folder for refiling via mh-default-folder-for-message-function}
+
+(defun my-mh-folder-from-address ()
+ "Determine folder name from address.
+Takes the address in the From: header field, and returns its corresponding
+alias from the user's personal aliases file. Returns @code{nil} if the address
+was not found."
+ (require 'rfc822) ; @r{for the rfc822 functions}
+ (search-forward-regexp "^From: \\(.*\\)") ; @r{grab header field contents}
+ (save-excursion ; @r{save state}
+ (let ((addr (car (rfc822-addresses ; @r{get address}
+ (buffer-substring (match-beginning 1)
+ (match-end 1)))))
+ (buffer (get-buffer-create " *temp*")) ; @r{set local variables}
+ folder)
+ (set-buffer buffer) ; @r{jump to temporary buffer}
+ (unwind-protect ; @r{run kill-buffer when done}
+ (progn ; @r{function grouping construct}
+ (insert-file-contents (expand-file-name "aliases"
+ mh-user-path))
+ (goto-char (point-min)) ; @r{grab aliases file and go to start}
+ (setq folder
+ ;; @r{Search for the given address, even commented-out}
+ ;; @r{addresses are found!}
+ ;; @r{The function search-forward-regexp sets values that are}
+ ;; @r{later used by match-beginning and match-end.}
+ (if (search-forward-regexp (format "^;*\\(.*\\):.*%s"
+ addr) nil t)
+ ;; @r{NOTE WELL: this is what the return value looks like.}
+ ;; @r{You can modify the format string to match your own}
+ ;; @r{Mail hierarchy.}
+ (format "+%s" (buffer-substring (match-beginning 1)
+ (match-end 1))))))
+ (kill-buffer buffer)) ; @r{get rid of our temporary buffer}
+ folder))) ; @r{function's return value}
+
+(setq mh-default-folder-for-message-function 'my-mh-folder-from-address)
+@end group
+@end lisp
+
+@vindex @code{mh-refile-msg-hook}
+
+The hook @code{mh-refile-msg-hook} is called after a message is marked
+to be refiled.
+
+@vindex @code{mh-sortm-args}
+@cindex @code{sortm}
+@cindex MH commands, @code{sortm}
+@findex @code{mh-sort-folder}
+@cindex MH profile components, @code{sortm}
+@cindex @file{.mh_profile}
+@cindex files, @file{.mh_profile}
+
+The variable @code{mh-sortm-args} holds extra arguments to pass on to
+the @code{sortm} command. Note: this variable is only consulted when a
+prefix argument is given to @kbd{M-x mh-sort-folder}. It is used to
+override any arguments given in a @code{sortm:} entry in your MH profile
+(@file{~/.mh_profile}).
+
+@menu
+* Customizing Scan Line Formats::
+@end menu
+
+@node Customizing Scan Line Formats, , Customizing Organizing, Customizing Organizing
+@subsubsection Scan line formatting
+
+@vindex @code{mh-scan-prog}
+@cindex @code{scan}
+@cindex MH commands, @code{scan}
+@vindex @code{mh-progs}
+
+The name of the program that generates a listing of one line per message
+is held in @code{mh-scan-prog} (default: @samp{"scan"}). Unless this
+variable contains an absolute pathname, it is assumed to be in the
+@code{mh-progs} directory. You may link another program to @code{scan}
+(see @code{mh-profile}(5)) to produce a different type of listing.
+
+If you change the format of the scan lines you'll need to tell mh-e how
+to parse the new format. As you see, quite a lot of variables are
+involved to do that. The first variable has to do with pruning out
+garbage.
+
+@table @code
+@item mh-valid-scan-line
+@vindex @code{mh-valid-scan-line}
+@cindex @code{inc}
+@cindex MH commands, @code{inc}
+@cindex @code{scan}
+@cindex MH commands, @code{scan}
+This regular expression describes a valid scan line. This is used to
+eliminate error messages that are occasionally produced by @code{inc} or
+@code{scan} (default: @samp{"^ *[0-9]"}).
+@end table
+
+Next, two variables control how the message numbers are parsed.
+
+@table @code
+
+@item mh-msg-number-regexp
+@vindex @code{mh-msg-number-regexp}
+This regular expression is used to extract the message number from a
+scan line. Note that the message number must be placed in quoted
+parentheses, (\\(...\\)), as in the default of @w{@samp{"^
+*\\([0-9]+\\)"}}.
+
+@item mh-msg-search-regexp
+@vindex @code{mh-msg-search-regexp}
+Given a message number (which is inserted in @samp{%d}), this regular
+expression will match the scan line that it represents (default:
+@samp{"^[^0-9]*%d[^0-9]"}).
+@end table
+
+Finally, there are a slew of variables that control how mh-e marks up
+the scan lines.
+
+@table @code
+@item mh-cmd-note
+@vindex @code{mh-cmd-note}
+Number of characters to skip over before inserting notation (default:
+4). Note how it relates to the following regular expressions.
+
+@item mh-deleted-msg-regexp
+@vindex @code{mh-deleted-msg-regexp}
+This regular expression describes deleted messages (default:
+@samp{"^....D"}). See also @code{mh-note-deleted}.
+
+@item mh-refiled-msg-regexp
+@vindex @code{mh-refiled-msg-regexp}
+This regular expression describes refiled messages (default:
+@samp{"^....\\^"}). See also @code{mh-note-refiled}.
+
+@item mh-cur-scan-msg-regexp
+@vindex @code{mh-cur-scan-msg-regexp}
+This regular expression matches the current message (default:
+@samp{"^....\\+"}). See also @code{mh-note-cur}.
+
+@item mh-good-msg-regexp
+@vindex @code{mh-good-msg-regexp}
+This regular expression describes which messages should be shown when
+mh-e goes to the next or previous message. Normally, deleted or refiled
+messages are skipped over (default: @samp{"^....[^D^]"}).
+
+@item mh-note-deleted
+@vindex @code{mh-note-deleted}
+Messages that have been deleted to are marked by this string (default:
+@samp{"D"}). See also @code{mh-deleted-msg-regexp}.
+
+@item mh-note-refiled
+@vindex @code{mh-note-refiled}
+Messages that have been refiled are marked by this string (default:
+@samp{"^"}). See also @code{mh-refiled-msg-regexp}.
+
+@item mh-note-copied
+@vindex @code{mh-note-copied}
+Messages that have been copied are marked by this string (default:
+@samp{"C"}).
+
+@item mh-note-cur
+@vindex @code{mh-note-cur}
+The current message (in MH, not in mh-e) is marked by this string
+(default: @samp{"+"}). See also @code{mh-cur-scan-msg-regexp}.
+
+@item mh-note-repl
+@vindex @code{mh-note-repl}
+Messages that have been replied to are marked by this string (default:
+@samp{"-"}).
+
+@item mh-note-forw
+@vindex @code{mh-note-forw}
+Messages that have been forwarded are marked by this string (default:
+@samp{"F"}).
+
+@item mh-note-dist
+@vindex @code{mh-note-dist}
+Messages that have been redistributed are marked by this string
+(default: @samp{"R"}).
+
+@item mh-note-printed
+@vindex @code{mh-note-printed}
+Messages that have been printed are marked by this string (default:
+@samp{"P"}).
+
+@item mh-note-seq
+@vindex @code{mh-note-seq}
+Messages in a sequence are marked by this string (default: @samp{"%"}).
+@end table
+
+@node Customizing Printing, Customizing Files and Pipes, Customizing Organizing, Customizing Moving Mail
+@subsection Printing Your Mail
+
+@cindex printing
+@vindex @code{mh-print-background}
+@vindex @code{mh-lpr-command-format}
+@cindex @code{lpr}
+@cindex Unix commands, @code{lpr}
+
+Normally messages are printed in the foreground. If this is slow on
+your system, you may elect to set @code{mh-print-background} to
+non-@code{nil} to print in the background. If you do this, do not delete
+the message until it is printed or else the output may be truncated.
+The variable @code{mh-lpr-command-format} controls how the printing is
+actually done. The string can contain one escape, @samp{%s}, which is
+filled with the name of the folder and the message number and is useful
+for print job names. As an example, the default is @samp{"lpr -J
+'%s'"}.
+
+@node Customizing Files and Pipes, Customizing Finishing Up, Customizing Printing, Customizing Moving Mail
+@subsection Files and Pipes
+
+@cindex using files
+@cindex using pipes
+@findex @code{mh-store-msg}
+@vindex @code{mh-store-default-directory}
+
+The initial directory for the @code{mh-store-msg} command is held in
+@code{mh-store-default-directory}. Since I almost always run
+@code{mh-store-msg} on sources, I set it to my personal source directory
+like this:
+
+@vindex @code{mh-store-default-directory}, example
+
+@lisp
+(setq mh-store-default-directory (expand-file-name "~/src/"))
+@end lisp
+
+@findex @code{mh-store-buffer}
+@cindex @code{uuencode}
+@cindex Unix commands, @code{uuencode}
+@cindex @code{shar}
+@cindex Unix commands, @code{shar}
+
+Subsequent incarnations of @code{mh-store-msg} offer the last directory
+used as the default. By the way, @code{mh-store-msg} calls the Emacs
+Lisp function @code{mh-store-buffer}. I mention this because you can use
+it directly if you're editing a buffer that contains a file that has
+been run through @code{uuencode} or @code{shar}. For example, you can
+extract the contents of the current buffer in your home directory by
+typing @kbd{M-x mh-store-buffer @key{RET} ~ @key{RET}}.
+
+@node Customizing Finishing Up, , Customizing Files and Pipes, Customizing Moving Mail
+@subsection Finishing Up
+
+@cindex quitting
+@vindex @code{mh-before-quit-hook}
+@vindex @code{mh-quit-hook}
+@findex @code{mh-execute-commands}
+
+The two variables @code{mh-before-quit-hook} and @code{mh-quit-hook} are
+called by @kbd{q} (@code{mh-quit}). The former one is called before the
+quit occurs, so you might use it to perform any mh-e operations; you
+could perform some query and abort the quit or call
+@code{mh-execute-commands}, for example. The latter is not run in an
+mh-e context, so you might use it to modify the window setup.
+
+@node Customizing Searching, , Customizing Moving Mail, Customizing mh-e
+@section Searching Through Messages
+@cindex searching
+
+@vindex @code{mh-pick-mode-hook}
+@vindex @code{mh-partial-folder-mode-line-annotation}
+
+If you find that you do the same thing over and over when editing the
+search template, you may wish to bind some shortcuts to keys. This can
+be done with the variable @code{mh-pick-mode-hook}, which is called when
+@kbd{M-s} (@code{mh-search-folder}) is run on a new pattern.
+
+The string
+@code{mh-partial-folder-mode-line-annotation} is used to annotate the
+mode line when only a portion of the folder is shown. For example, this
+will be displayed after running @kbd{M-s} (@code{mh-search-folder}) to
+list messages based on some search criteria (see @ref{Searching}). The
+default annotation of @samp{"select"} yields a mode line that looks
+like:
+
+@example
+--%%-@{+inbox/select@} 2 msgs (2-3) (MH-Folder)--All-----------------
+@end example
+
+@node Odds and Ends, History, Customizing mh-e, Top
+@appendix Odds and Ends
+
+This appendix covers a few topics that don't fit elsewhere. Here I tell
+you how to report bugs and how to get on the mh-e mailing list. I also
+point out some additional sources of information.
+
+@menu
+* Bug Reports::
+* Mailing List::
+* MH FAQ::
+* Getting mh-e::
+@end menu
+
+@node Bug Reports, Mailing List, Odds and Ends, Odds and Ends
+@appendixsec Bug Reports
+
+@cindex bugs
+@cindex Gildea, Stephen
+
+The current maintainer of mh-e is Stephen Gildea
+<@i{gildea@@lcs.mit.edu}>. Please mail bug reports directly to him, as
+well as any praise or suggestions. Please include the output of
+@kbd{M-x mh-version} (@pxref{Miscellaneous}) in any bug report you send.
+
+@node Mailing List, MH FAQ, Bug Reports, Odds and Ends
+@appendixsec mh-e Mailing List
+
+@cindex mailing list
+
+There is a mailing list, @i{mh-e@@x.org}, for discussion of mh-e and
+announcements of new versions. Send a ``subscribe'' message to
+@i{mh-e-request@@x.org} to be added. Do not report bugs on this list;
+mail them directly to the maintainer (@pxref{Bug Reports}).
+
+@node MH FAQ, Getting mh-e, Mailing List, Odds and Ends
+@appendixsec MH FAQ
+
+@cindex MH FAQ
+@cindex FAQ
+
+An FAQ appears monthly in the newsgroup @samp{comp.mail.mh}. While very
+little is there that deals with mh-e specifically, there is an
+incredible wealth of material about MH itself which you will find
+useful. The subject of the FAQ is @cite{MH Frequently Asked Questions
+(FAQ) with Answers}.
+
+The FAQ can be also obtained by anonymous @code{ftp} or via the
+World Wide Web (WWW)@. It is located at:
+
+@ifclear html
+@example
+ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/mh-faq/part1
+http://www.cis.ohio-state.edu/hypertext/faq/usenet/mail/mh-faq/part1/faq.html
+@end example
+@end ifclear
+
+@ifset html
+@example
+<A HREF="ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/mh-faq/part1">ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/mh-faq/part1</A>
+<A HREF="http://www.cis.ohio-state.edu/hypertext/faq/usenet/mail/mh-faq/part1/faq.html">http://www.cis.ohio-state.edu/hypertext/faq/usenet/mail/mh-faq/part1/faq.html</A>
+@end example
+@end ifset
+
+Otherwise, you can use mail. Send mail to @i{mail-server@@rtfm.mit.edu}
+containing the following:
+
+@example
+send usenet/news.answers/mail/mh-faq/part1
+@end example
+
+@node Getting mh-e, , MH FAQ, Odds and Ends
+@appendixsec Getting mh-e
+
+@cindex obtaining mh-e
+
+If you're running a pre-4.0 version of mh-e, please consider upgrading.
+You can either have your system administrator upgrade your Emacs, or
+just the files for mh-e.
+
+The MH distribution contains a copy of mh-e in @file{miscellany/mh-e}.
+Make sure it is at least @w{Version 4.0}.
+
+The latest version of mh-e can be obtained via anonymous @code{ftp} from
+@samp{ftp.x.org}. The file containing mh-e is currently
+@ifclear html
+@file{/misc/mh-e/mh-e-@value{VERSION}.tar.Z}.
+@end ifclear
+@ifset html
+@file{<A HREF="ftp://ftp.x.org/misc/mh-e/mh-e-@value{VERSION}.tar.Z">/misc/mh-e/mh-e-@value{VERSION}.tar.Z</A>}
+@end ifset
+I suggest that you
+extract the files from @file{mh-e-@value{VERSION}.tar.Z} in the
+following fashion:
+
+@example
+@group
+% @kbd{cd} # @r{Start in your home directory}
+% @kbd{mkdir lib lib/emacs} # @r{Create directory for mh-e}
+% @kbd{cd lib/emacs}
+% @kbd{zcat @var{path/to/}mh-e-@value{VERSION}.tar.Z | tar xvf -} # @r{Extract files}
+@end group
+@end example
+
+@cindex @file{.emacs}
+@cindex files, @file{.emacs}
+
+To use these new files, add the following to @file{~/.emacs}:
+
+@lisp
+(setq load-path (cons (expand-file-name "~/lib/emacs") load-path))
+@end lisp
+
+@cindex news
+@cindex files, @samp{MH-E-NEWS}
+
+That's it! If you're already running Emacs, please quit that session
+and start again to load in the new mh-e. Check that you're running the
+new version with the command @kbd{M-x mh-version} after running any mh-e
+command. The distribution comes with a file called @file{MH-E-NEWS} so
+you can see what's new.
+
+@node History, Changes to mh-e, Odds and Ends, Top
+@appendix History of mh-e
+
+@cindex history of mh-e
+
+mh-e was originally written by Brian Reid in 1983 and has changed hands
+twice since then. Jim Larus wanted to do something similar for GNU
+Emacs, and ended up completely rewriting it that same year. In 1989,
+Stephen Gildea picked it up and is now currently improving and
+maintaining it.
+
+@menu
+* From Brian Reid::
+* From Jim Larus::
+* From Stephen Gildea::
+@end menu
+
+@node From Brian Reid, From Jim Larus, History, History
+@appendixsec From Brian Reid
+
+@cindex Reid, Brian
+
+One day in 1983 I got the flu and had to stay home from work for three
+days with nothing to do. I used that time to write MHE@. The
+fundamental idea behind MHE was that it was a ``puppeteer'' driving the MH
+programs underneath it. MH had a model that the editor was supposed to
+run as a subprocess of the mailer, which seemed to me at the time to be
+the tail wagging the dog. So I turned it around and made the editor
+drive the MH programs. I made sure that the UCI people (who were
+maintaining MH at the time) took in my changes and made them stick.
+
+Today, I still use my own version of MHE because I don't at all like the
+way that GNU mh-e works and I've never gotten to be good enough at
+hacking Emacs Lisp to make GNU mh-e do what I want. The Gosling-emacs
+version of MHE and the GNU Emacs version of mh-e have almost nothing in
+common except similar names. They work differently, have different
+conceptual models, and have different key bindings. @footnote{After
+reading this article, I questioned Brian about his version of MHE, and
+received some great ideas for improving mh-e such as a dired-like method
+of selecting folders; and removing the prompting when sending mail,
+filling in the blanks in the draft buffer instead. I passed them on to
+Stephen Gildea, the current maintainer, and he was excited about the
+ideas as well. Perhaps one day, mh-e will again resemble MHE, although
+none of these ideas are manifest in Version 5.0.}
+
+Brian Reid, June 1994
+
+@node From Jim Larus, From Stephen Gildea, From Brian Reid, History
+@appendixsec From Jim Larus
+
+@cindex Larus, Jim
+
+Brian Reid, while at CMU or shortly after going to Stanford wrote a mail
+reading program called MHE for Gosling Emacs. It had much the same
+structure as mh-e (i.e., invoked MH programs), though it was simpler and
+the commands were slightly different. Unfortunately, I no longer have a
+copy so the differences are lost in the mists of time.
+
+In '82-83, I was working at BBN and wrote a lot of mlisp code in Gosling
+Emacs to make it look more like Tennex Emacs. One of the packages that
+I picked up and improved was Reid's mail system. In '83, I went back to
+Berkeley. About that time, Stallman's first version of GNU Emacs came
+out and people started to move to it from Gosling Emacs (as I recall,
+the transition took a year or two). I decided to port Reid's MHE and
+used the mlisp to Emacs Lisp translator that came with GNU Emacs. It
+did a lousy job and the resulting code didn't work, so I bit the bullet
+and rewrote the code by hand (it was a lot smaller and simpler then, so
+it took only a day or two).
+
+Soon after that, mh-e became part of the standard Emacs distribution and
+suggestions kept dribbling in for improvements. mh-e soon reached
+sufficient functionality to keep me happy, but I kept on improving it
+because I was a graduate student with plenty of time on my hands and it
+was more fun than my dissertation. In retrospect, the one thing that I
+regret is not writing any documentation, which seriously limited the use
+and appeal of the package.
+
+@cindex @code{xmh}, in mh-e history
+
+In '89, I came to Wisconsin as a professor and decided not to work on
+mh-e. It was stable, except for minor bugs, and had enough
+functionality, so I let it be for a few years. Stephen Gildea of BBN
+began to pester me about the bugs, but I ignored them. In 1990, he went
+off to the X Consortium, said good bye, and said that he would now be
+using @code{xmh}. A few months later, he came back and said that he
+couldn't stand @code{xmh} and could I put a few more bug fixes into
+mh-e. At that point, I had no interest in fixing mh-e, so I gave the
+responsibility of maintenance to him and he has done a fine job since
+then.
+
+Jim Larus, June 1994
+
+@node From Stephen Gildea, , From Jim Larus, History
+@appendixsec From Stephen Gildea
+
+@cindex Gildea, Stephen
+
+In 1987 I went to work for Bolt Beranek and Newman, as Jim had before
+me. In my previous job, I had been using RMAIL, but as my folders tend
+to run large, I was frustrated with the speed of RMAIL@. However, I
+stuck with it because I wanted the GNU Emacs interface. I am very
+familiar and comfortable with the Emacs interface (with just a few
+modifications of my own) and dislike having to use applications with
+embedded editors; they never live up to Emacs.
+
+MH is the mail reader of choice at BBN, so I converted to it. Since I
+didn't want to give up using an Emacs interface, I started using mh-e.
+As is my wont, I started hacking on it almost immediately. I first used
+version 3.4m. One of the first features I added was to treat the folder
+buffer as a file-visiting buffer: you could lock it, save it, and be
+warned of unsaved changes when killing it. I also worked to bring its
+functionality a little closer to RMAIL@. Jim Larus was very cooperative
+about merging in my changes, and my efforts first appeared in version
+3.6, distributed with Emacs 18.52 in 1988. Next I decided mh-e was too
+slow and optimized it a lot. Version, 3.7, distributed with Emacs 18.56
+in 1990, was noticeably faster.
+
+When I moved to the X Consortium I became the first person there to not
+use xmh. (There is now one other engineer there using mh-e.) About
+this point I took over maintenance of mh-e from Jim and was finally able
+to add some features Jim hadn't accepted, such as the backward searching
+undo. My first release was 3.8 (Emacs 18.58) in 1992.
+
+Now, in 1994, we see a flurry of releases, with both 4.0 and 5.0.
+Version 4.0 added many new features, including background folder
+collection and support for composing @sc{mime} messages. (Reading
+@sc{mime} messages remains to be done, alas.) While writing this book,
+Bill Wohler gave mh-e its closest examination ever, uncovering bugs and
+inconsistencies that required a new major version to fix, and so version
+5 was released.
+
+Stephen Gildea, June 1994
+
+@node Changes to mh-e, Copying, History, Top
+@appendix Changes to mh-e
+
+@cindex @code{mh-e}: comparison between versions
+
+mh-e had a fairly major facelift between @w{Versions 3} and 4. The
+differences between @w{Versions 4} and 5 from the user's viewpoint are
+relatively minor. The prompting order for the folder and message number
+in a couple of functions had been switched inadvertently in @w{Version
+4}. @w{Version 5} switches the order back. The @file{+inbox} folder is
+no longer hard-coded, but rather uses the @samp{Inbox} MH Profile entry.
+See the file @file{etc/MH-E-NEWS} in the Emacs distribution for more
+details on the changes.
+
+This section documents the changes between @w{Version 3} and newer
+versions so that you'll know which commands to use (or which commands
+you won't have) in case you're stuck with an old version.
+
+The following tables summarize the changes to buffer names, commands
+and variables.
+
+@unnumberedsec Buffer Mode Names
+
+@example
+@group
+@b{Version 3} @b{Version 4}
+
+mh-e folder MH-Folder
+mh-e scan MH-Folder
+mh-e show MH-Folder Show
+Fundamental MH-Show
+mh-e letter MH-Letter
+mh-e letter MH-Pick
+@end group
+@end example
+
+@page
+
+@unnumberedsec Commands
+
+@example
+@group
+ @b{Version 3} @b{Version 4}
+
+@b{Function} @b{Command} @b{Command} @b{Function}
+
+mh-first-msg < M-< mh-first-msg
+- - M-> mh-last-msg
+mh-show . RET mh-show
+- - , mh-header-display
+mh-reply a r mh-reply
+mh-redistribute r M-d mh-redistribute
+mh-unshar-msg - M-n mh-store-msg
+mh-write-msg-to-file M-o C-o mh-write-msg-to-file
+mh-delete-msg-from-seq C-u M-% M-# mh-delete-seq
+- - M-q mh-list-sequences
+mh-quit b q mh-quit
+- - C-C C-f C-r mh-to-field (@samp{From:})
+- - C-C C-f C-d mh-to-field (@samp{Dcc:})
+@end group
+@end example
+
+@unnumberedsec Variables
+
+@example
+@group
+ @b{Version 3} @b{Version 4}
+
+@b{Variable} @b{Value} @b{Value} @b{Variable}
+
+mh-show-buffer- "@{%%b@} %s/%d" "@{show-%s@} %d" mh-show-buffer-
+mode-line-buffer-id mode-line-buffer-id
+mh-unshar-default- "" nil mh-store-default-
+directory directory
+@end group
+@end example
+
+
+@unnumberedsec New Variables
+
+@example
+@group
+mail-citation-hook mh-new-draft-cleaned-headers
+mail-header-separator mh-pick-mode-hook
+mh-auto-folder-collect mh-refile-msg-hook
+mh-comp-formfile mh-scan-prog
+mh-repl-formfile mh-send-prog
+mh-delete-msg-hook mh-show-hook
+mh-forward-subject-format mh-show-mode-hook
+mh-inc-prog mh-signature-file-name
+mh-mime-content-types mh-sortm-args
+mh-default-folder-for-message-function mh-repl-formfile
+mh-mhn-args
+@end group
+@end example
+
+@node Copying, Command Index, Changes to mh-e, Top
+@appendix GNU GENERAL PUBLIC LICENSE
+@center Version 2, June 1991
+
+@display
+Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@appendixsec Preamble
+
+ The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software---to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.) You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+ We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+@iftex
+@appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end ifinfo
+
+@enumerate 0
+@item
+This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License. The ``Program'', below,
+refers to any such program or work, and a ``work based on the Program''
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language. (Hereinafter, translation is included without limitation in
+the term ``modification''.) Each licensee is addressed as ``you''.
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+@item
+You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+@item
+You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+@enumerate a
+@item
+You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+@item
+You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.
+
+@item
+If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License. (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)
+@end enumerate
+
+These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+@item
+You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+@enumerate a
+@item
+Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+@item
+Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+@item
+Accompany it with the information you received as to the offer
+to distribute corresponding source code. (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)
+@end enumerate
+
+The source code for a work means the preferred form of the work for
+making modifications to it. For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable. However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+@item
+You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Program or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+@item
+Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+@item
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+@item
+If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+@item
+The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and ``any
+later version'', you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+@item
+If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+@iftex
+@heading NO WARRANTY
+@end iftex
+@ifinfo
+@center NO WARRANTY
+@end ifinfo
+
+@item
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+@end enumerate
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+
+@page
+@appendixsec How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the ``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the program's name and an idea of what it does.}
+Copyright (C) 19@var{yy} @var{name of author}
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+@smallexample
+Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+type `show w'. This is free software, and you are welcome
+to redistribute it under certain conditions; type `show c'
+for details.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than @samp{show w} and
+@samp{show c}; they could even be mouse-clicks or menu items---whatever
+suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the program, if
+necessary. Here is a sample; alter the names:
+
+@smallexample
+@group
+Yoyodyne, Inc., hereby disclaims all copyright
+interest in the program `Gnomovision'
+(which makes passes at compilers) written
+by James Hacker.
+
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end group
+@end smallexample
+
+This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Library General
+Public License instead of this License.
+
+@node Command Index, Variable Index, Copying, Top
+@unnumbered Command Index
+
+@printindex fn
+
+@node Variable Index, Concept Index, Command Index, Top
+@unnumbered Variable Index
+
+@printindex vr
+
+@node Concept Index, , Variable Index, Top
+@unnumbered Concept Index
+
+@printindex cp
+
+@contents
+@bye
+
+@c XXX In the sections on customizing mh-e, you can add cross-references
+@c to the Emacs manual and the Emacs Lisp manual wherever they are
+@c useful. @pxref{node, , section, emacs, The GNU Emacs Manual}
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Minibuffer, M-x, Basic, Top
+@chapter The Minibuffer
+@cindex minibuffer
+
+ The @dfn{minibuffer} is the facility used by Emacs commands to read
+arguments more complicated than a single number. Minibuffer arguments
+can be file names, buffer names, Lisp function names, Emacs command
+names, Lisp expressions, and many other things, depending on the command
+reading the argument. You can use the usual Emacs editing commands in
+the minibuffer to edit the argument text.
+
+@cindex prompt
+ When the minibuffer is in use, it appears in the echo area, and the
+terminal's cursor moves there. The beginning of the minibuffer line
+displays a @dfn{prompt} which says what kind of input you should supply and
+how it will be used. Often this prompt is derived from the name of the
+command that the argument is for. The prompt normally ends with a colon.
+
+@cindex default argument
+ Sometimes a @dfn{default argument} appears in parentheses after the
+colon; it too is part of the prompt. The default will be used as the
+argument value if you enter an empty argument (for example, just type
+@key{RET}). For example, commands that read buffer names always show a
+default, which is the name of the buffer that will be used if you type
+just @key{RET}.
+
+ The simplest way to enter a minibuffer argument is to type the text
+you want, terminated by @key{RET} which exits the minibuffer. You can
+cancel the command that wants the argument, and get out of the
+minibuffer, by typing @kbd{C-g}.
+
+ Since the minibuffer uses the screen space of the echo area, it can
+conflict with other ways Emacs customarily uses the echo area. Here is how
+Emacs handles such conflicts:
+
+@itemize @bullet
+@item
+If a command gets an error while you are in the minibuffer, this does
+not cancel the minibuffer. However, the echo area is needed for the
+error message and therefore the minibuffer itself is hidden for a
+while. It comes back after a few seconds, or as soon as you type
+anything.
+
+@item
+If in the minibuffer you use a command whose purpose is to print a
+message in the echo area, such as @kbd{C-x =}, the message is printed
+normally, and the minibuffer is hidden for a while. It comes back
+after a few seconds, or as soon as you type anything.
+
+@item
+Echoing of keystrokes does not take place while the minibuffer is in
+use.
+@end itemize
+
+@menu
+* File: Minibuffer File. Entering file names with the minibuffer.
+* Edit: Minibuffer Edit. How to edit in the minibuffer.
+* Completion:: An abbreviation facility for minibuffer input.
+* Minibuffer History:: Reusing recent minibuffer arguments.
+* Repetition:: Re-executing commands that used the minibuffer.
+@end menu
+
+@node Minibuffer File
+@section Minibuffers for File Names
+
+ Sometimes the minibuffer starts out with text in it. For example, when
+you are supposed to give a file name, the minibuffer starts out containing
+the @dfn{default directory}, which ends with a slash. This is to inform
+you which directory the file will be found in if you do not specify a
+directory.
+
+@c Separate paragraph to clean up ugly pagebreak--rms
+@need 1500
+ For example, the minibuffer might start out with these contents:
+
+@example
+Find File: /u2/emacs/src/
+@end example
+
+@noindent
+where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c}
+specifies the file @file{/u2/emacs/src/buffer.c}. To find files in
+nearby directories, use @kbd{..}; thus, if you type
+@kbd{../lisp/simple.el}, you will get the file named
+@file{/u2/emacs/lisp/simple.el}. Alternatively, you can kill with
+@kbd{M-@key{DEL}} the directory names you don't want (@pxref{Words}).
+
+ If you don't want any of the default, you can kill it with @kbd{C-a
+C-k}. But you don't need to kill the default; you can simply ignore it.
+Insert an absolute file name, one starting with a slash or a tilde,
+after the default directory. For example, to specify the file
+@file{/etc/termcap}, just insert that name, giving these minibuffer
+contents:
+
+@example
+Find File: /u2/emacs/src//etc/termcap
+@end example
+
+@noindent
+@cindex // in file name
+@cindex double slash in file name
+@cindex slashes repeated in file name
+GNU Emacs gives a special meaning to a double slash (which is not
+normally a useful thing to write): it means, ``ignore everything before
+the second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored
+in the example above, and you get the file @file{/etc/termcap}.
+
+ If you set @code{insert-default-directory} to @code{nil}, the default
+directory is not inserted in the minibuffer. This way, the minibuffer
+starts out empty. But the name you type, if relative, is still
+interpreted with respect to the same default directory.
+
+@node Minibuffer Edit
+@section Editing in the Minibuffer
+
+ The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual
+Emacs commands are available for editing the text of an argument you are
+entering.
+
+ Since @key{RET} in the minibuffer is defined to exit the minibuffer,
+you can't use it to insert a newline in the minibuffer. To do that,
+type @kbd{C-o} or @kbd{C-q C-j}. (Recall that a newline is really the
+character control-J.)
+
+ The minibuffer has its own window which always has space on the screen
+but acts as if it were not there when the minibuffer is not in use. When
+the minibuffer is in use, its window is just like the others; you can
+switch to another window with @kbd{C-x o}, edit text in other windows and
+perhaps even visit more files, before returning to the minibuffer to submit
+the argument. You can kill text in another window, return to the
+minibuffer window, and then yank the text to use it in the argument.
+@xref{Windows}.
+
+@findex resize-minibuffer-mode
+@cindex Resize-Minibuffer mode
+@cindex mode, Resize-Minibuffer
+@cindex height of minibuffer
+@cindex size of minibuffer
+@cindex growing minibuffer
+ There are some restrictions on the use of the minibuffer window,
+however. You cannot switch buffers in it---the minibuffer and its
+window are permanently attached. Also, you cannot split or kill the
+minibuffer window. But you can make it taller in the normal fashion
+with @kbd{C-x ^}. If you enable Resize-Minibuffer mode, then the
+minibuffer window expands vertically as necessary to hold the text that
+you put in the minibuffer. Use @kbd{M-x resize-minibuffer-mode} to
+enable or disable this minor mode (@pxref{Minor Modes}).
+
+@vindex minibuffer-scroll-overlap
+ Scrolling works specially in the minibuffer window. When the
+minibuffer is just one line high, and it contains a long line of text
+that won't fit on the screen, scrolling automatically maintains an
+overlap of a certain number of characters from one continuation line to
+the next. The variable @code{minibuffer-scroll-overlap} specifies how
+many characters of overlap; the default is 20.
+
+ If while in the minibuffer you issue a command that displays help text
+of any sort in another window, you can use the @kbd{C-M-v} command while
+in the minibuffer to scroll the help text. This lasts until you exit
+the minibuffer. This feature is especially useful if a completing
+minibuffer gives you a list of possible completions. @xref{Other Window}.
+
+@vindex enable-recursive-minibuffers
+ Emacs normally disallows most commands that use the minibuffer while
+the minibuffer is active. This rule is to prevent recursive minibuffers
+from confusing novice users. If you want to be able to use such
+commands in the minibuffer, set the variable
+@code{enable-recursive-minibuffers} to a non-@code{nil} value.
+
+@node Completion
+@section Completion
+@cindex completion
+
+ For certain kinds of arguments, you can use @dfn{completion} to enter
+the argument value. Completion means that you type part of the
+argument, then Emacs visibly fills in the rest, or as much as
+can be determined from the part you have typed.
+
+ When completion is available, certain keys---@key{TAB}, @key{RET}, and
+@key{SPC}---are rebound to complete the text present in the minibuffer
+into a longer string that it stands for, by matching it against a set of
+@dfn{completion alternatives} provided by the command reading the
+argument. @kbd{?} is defined to display a list of possible completions
+of what you have inserted.
+
+ For example, when @kbd{M-x} uses the minibuffer to read the name of a
+command, it provides a list of all available Emacs command names to
+complete against. The completion keys match the text in the minibuffer
+against all the command names, find any additional name characters
+implied by the ones already present in the minibuffer, and add those
+characters to the ones you have given. This is what makes it possible
+to type @kbd{M-x ins @key{SPC} b @key{RET}} instead of @kbd{M-x
+insert-buffer @key{RET}} (for example).
+
+ Case is normally significant in completion, because it is significant
+in most of the names that you can complete (buffer names, file names and
+command names). Thus, @samp{fo} does not complete to @samp{Foo}.
+Completion does ignore case distinctions for certain arguments in which
+case does not matter.
+
+@menu
+* Example: Completion Example.
+* Commands: Completion Commands.
+* Strict Completion::
+* Options: Completion Options.
+@end menu
+
+@node Completion Example
+@subsection Completion Example
+
+@kindex TAB @r{(completion)}
+@findex minibuffer-complete
+ A concrete example may help here. If you type @kbd{M-x au @key{TAB}},
+the @key{TAB} looks for alternatives (in this case, command names) that
+start with @samp{au}. There are several, including
+@code{auto-fill-mode} and @code{auto-save-mode}---but they are all the
+same as far as @code{auto-}, so the @samp{au} in the minibuffer changes
+to @samp{auto-}.@refill
+
+ If you type @key{TAB} again immediately, there are multiple
+possibilities for the very next character---it could be any of
+@samp{cfilrs}---so no more characters are added; instead, @key{TAB}
+displays a list of all possible completions in another window.
+
+ If you go on to type @kbd{f @key{TAB}}, this @key{TAB} sees
+@samp{auto-f}. The only command name starting this way is
+@code{auto-fill-mode}, so completion fills in the rest of that. You now
+have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au
+@key{TAB} f @key{TAB}}. Note that @key{TAB} has this effect because in
+the minibuffer it is bound to the command @code{minibuffer-complete}
+when completion is available.
+
+@node Completion Commands
+@subsection Completion Commands
+
+ Here is a list of the completion commands defined in the minibuffer
+when completion is available.
+
+@table @kbd
+@item @key{TAB}
+Complete the text in the minibuffer as much as possible
+(@code{minibuffer-complete}).
+@item @key{SPC}
+Complete the minibuffer text, but don't go beyond one word
+(@code{minibuffer-complete-word}).
+@item @key{RET}
+Submit the text in the minibuffer as the argument, possibly completing
+first as described below (@code{minibuffer-complete-and-exit}).
+@item ?
+Print a list of all possible completions of the text in the minibuffer
+(@code{minibuffer-list-completions}).
+@end table
+
+@kindex SPC
+@findex minibuffer-complete-word
+ @key{SPC} completes much like @key{TAB}, but never goes beyond the
+next hyphen or space. If you have @samp{auto-f} in the minibuffer and
+type @key{SPC}, it finds that the completion is @samp{auto-fill-mode},
+but it stops completing after @samp{fill-}. This gives
+@samp{auto-fill-}. Another @key{SPC} at this point completes all the
+way to @samp{auto-fill-mode}. @key{SPC} in the minibuffer when
+completion is available runs the command
+@code{minibuffer-complete-word}.
+
+ Here are some commands you can use to choose a completion from a
+window that displays a list of completions:
+
+@table @kbd
+@findex mouse-choose-completion
+@item Mouse-2
+Clicking mouse button 2 on a completion in the list of possible
+completions chooses that completion (@code{mouse-choose-completion}).
+You normally use this command while point is in the minibuffer; but you
+must click in the list of completions, not in the minibuffer itself.
+
+@findex switch-to-completions
+@item @key{PRIOR}
+@itemx M-v
+Typing @key{PRIOR} or @key{PAGE-UP}, or @kbd{M-v}, while in the
+minibuffer, selects the window showing the completion list buffer
+(@code{switch-to-completions}). This paves the way for using the
+commands below. (Selecting that window in the usual ways has the same
+effect, but this way is more convenient.)
+
+@findex choose-completion
+@item @key{RET}
+Typing @key{RET} @emph{in the completion list buffer} chooses the
+completion that point is in or next to (@code{choose-completion}). To
+use this command, you must first switch windows to the window that shows
+the list of completions.
+
+@findex next-completion
+@item @key{RIGHT}
+Typing the right-arrow key @key{RIGHT} @emph{in the completion list
+buffer} moves point to the following completion (@code{next-completion}).
+
+@findex previous-completion
+@item @key{LEFT}
+Typing the left-arrow key @key{LEFT} @emph{in the completion list
+buffer} moves point toward the beginning of the buffer, to the previous
+completion (@code{previous-completion}).
+@end table
+
+@node Strict Completion
+@subsection Strict Completion
+
+ There are three different ways that @key{RET} can work in completing
+minibuffers, depending on how the argument will be used.
+
+@itemize @bullet
+@item
+@dfn{Strict} completion is used when it is meaningless to give any
+argument except one of the known alternatives. For example, when
+@kbd{C-x k} reads the name of a buffer to kill, it is meaningless to
+give anything but the name of an existing buffer. In strict
+completion, @key{RET} refuses to exit if the text in the minibuffer
+does not complete to an exact match.
+
+@item
+@dfn{Cautious} completion is similar to strict completion, except that
+@key{RET} exits only if the text was an exact match already, not
+needing completion. If the text is not an exact match, @key{RET} does
+not exit, but it does complete the text. If it completes to an exact
+match, a second @key{RET} will exit.
+
+Cautious completion is used for reading file names for files that must
+already exist.
+
+@item
+@dfn{Permissive} completion is used when any string whatever is
+meaningful, and the list of completion alternatives is just a guide.
+For example, when @kbd{C-x C-f} reads the name of a file to visit, any
+file name is allowed, in case you want to create a file. In
+permissive completion, @key{RET} takes the text in the minibuffer
+exactly as given, without completing it.
+@end itemize
+
+ The completion commands display a list of all possible completions in
+a window whenever there is more than one possibility for the very next
+character. Also, typing @kbd{?} explicitly requests such a list. If
+the list of completions is long, you can scroll it with @kbd{C-M-v}
+(@pxref{Other Window}).
+
+@node Completion Options
+@subsection Completion Options
+
+@vindex completion-ignored-extensions
+ When completion is done on file names, certain file names are usually
+ignored. The variable @code{completion-ignored-extensions} contains a
+list of strings; a file whose name ends in any of those strings is
+ignored as a possible completion. The standard value of this variable
+has several elements including @code{".o"}, @code{".elc"}, @code{".dvi"}
+and @code{"~"}. The effect is that, for example, @samp{foo} can
+complete to @samp{foo.c} even though @samp{foo.o} exists as well.
+However, if @emph{all} the possible completions end in ``ignored''
+strings, then they are not ignored. Ignored extensions do not apply to
+lists of completions---those always mention all possible completions.
+
+@vindex completion-auto-help
+ Normally, a completion command that finds the next character is undetermined
+automatically displays a list of all possible completions. If the variable
+@code{completion-auto-help} is set to @code{nil}, this does not happen,
+and you must type @kbd{?} to display the possible completions.
+
+@pindex complete
+ The @code{complete} library implements a more powerful kind of
+completion that can complete multiple words at a time. For example, it
+can complete the command name abbreviation @code{p-b} into
+@code{print-buffer}, because no other command starts with two words
+whose initials are @samp{p} and @samp{b}. To use this library, put
+@code{(load "complete")} in your @file{~/.emacs} file (@pxref{Init
+File}).
+
+@cindex Icomplete mode
+ Icomplete mode presents a constantly-updated display that tells you
+what completions are available for the text you've entered so far. The
+command to enable or disable this minor mode is @kbd{M-x
+icomplete-mode}.
+
+@node Minibuffer History
+@section Minibuffer History
+@cindex minibuffer history
+@cindex history of minibuffer input
+
+ Every argument that you enter with the minibuffer is saved on a
+@dfn{minibuffer history list} so that you can use it again later in
+another argument. Special commands load the text of an earlier argument
+in the minibuffer. They discard the old minibuffer contents, so you can
+think of them as moving through the history of previous arguments.
+
+@table @kbd
+@item @key{UP}
+@itemx M-p
+Move to the next earlier argument string saved in the minibuffer history
+(@code{previous-history-element}).
+@item @key{DOWN}
+@itemx M-n
+Move to the next later argument string saved in the minibuffer history
+(@code{next-history-element}).
+@item M-r @var{regexp} @key{RET}
+Move to an earlier saved argument in the minibuffer history that has a
+match for @var{regexp} (@code{previous-matching-history-element}).
+@item M-s @var{regexp} @key{RET}
+Move to a later saved argument in the minibuffer history that has a
+match for @var{regexp} (@code{next-matching-history-element}).
+@end table
+
+@kindex M-p @r{(minibuffer history)}
+@kindex M-n @r{(minibuffer history)}
+@findex next-history-element
+@findex previous-history-element
+ The simplest way to reuse the saved arguments in the history list is
+to move through the history list one element at a time. While in the
+minibuffer, use @kbd{M-p} or up-arrow (@code{previous-history-element})
+to ``move to'' the next earlier minibuffer input, and use @kbd{M-n} or
+down-arrow (@code{next-history-element}) to ``move to'' the next later
+input.
+
+ The previous input that you fetch from the history entirely replaces
+the contents of the minibuffer. To use it as the argument, exit the
+minibuffer as usual with @key{RET}. You can also edit the text before
+you reuse it; this does not change the history element that you
+``moved'' to, but your new argument does go at the end of the history
+list in its own right.
+
+ For many minibuffer arguments there is a ``default'' value. In some
+cases, the minibuffer history commands know the default value. Then you
+can insert the default value into the minibuffer as text by using
+@kbd{M-n} to move ``into the future'' in the history. Eventually we
+hope to make this feature available whenever the minibuffer has a
+default value.
+
+@findex previous-matching-history-element
+@findex next-matching-history-element
+@kindex M-r @r{(minibuffer history)}
+@kindex M-s @r{(minibuffer history)}
+ There are also commands to search forward or backward through the
+history; they search for history elements that match a regular
+expression that you specify with the minibuffer. @kbd{M-r}
+(@code{previous-matching-history-element}) searches older elements in
+the history, while @kbd{M-s} (@code{next-matching-history-element})
+searches newer elements. By special dispensation, these commands can
+use the minibuffer to read their arguments even though you are already
+in the minibuffer when you issue them. As with incremental searching,
+an uppercase letter in the regular expression makes the search
+case-sensitive (@pxref{Search Case}).
+
+@ignore
+ We may change the precise way these commands read their arguments.
+Perhaps they will search for a match for the string given so far in the
+minibuffer; perhaps they will search for a literal match rather than a
+regular expression match; perhaps they will only accept matches at the
+beginning of a history element; perhaps they will read the string to
+search for incrementally like @kbd{C-s}. To find out what interface is
+actually available, type @kbd{C-h f previous-matching-history-element}.
+@end ignore
+
+ All uses of the minibuffer record your input on a history list, but
+there are separate history lists for different kinds of arguments. For
+example, there is a list for file names, used by all the commands that
+read file names. (As a special feature, this history list records
+the absolute file name, no more and no less, even if that is not how
+you entered the file name.)
+
+ There are several other very specific history lists, including one for
+command names read by @kbd{M-x}, one for buffer names, one for arguments
+of commands like @code{query-replace}, and one for compilation commands
+read by @code{compile}. Finally, there is one ``miscellaneous'' history
+list that most minibuffer arguments use.
+
+@vindex history-length
+ The variable @code{history-length} specifies the maximum length of a
+minibuffer history list; once a list gets that long, the oldest element
+is deleted each time an element is added. If the value of
+@code{history-length} is @code{t}, though, there is no maximum length
+and elements are never deleted.
+
+@node Repetition
+@section Repeating Minibuffer Commands
+@cindex command history
+@cindex history of commands
+
+ Every command that uses the minibuffer at least once is recorded on a
+special history list, together with the values of its arguments, so that
+you can repeat the entire command. In particular, every use of
+@kbd{M-x} is recorded there, since @kbd{M-x} uses the minibuffer to read
+the command name.
+
+@findex list-command-history
+@c widecommands
+@table @kbd
+@item C-x @key{ESC} @key{ESC}
+Re-execute a recent minibuffer command (@code{repeat-complex-command}).
+@item M-x list-command-history
+Display the entire command history, showing all the commands
+@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first.
+@end table
+
+@kindex C-x ESC ESC
+@findex repeat-complex-command
+ @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent
+minibuffer-using command. With no argument, it repeats the last such
+command. A numeric argument specifies which command to repeat; one
+means the last one, and larger numbers specify earlier ones.
+
+ @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command
+into a Lisp expression and then entering a minibuffer initialized with
+the text for that expression. If you type just @key{RET}, the command
+is repeated as before. You can also change the command by editing the
+Lisp expression. Whatever expression you finally submit is what will be
+executed. The repeated command is added to the front of the command
+history unless it is identical to the most recently executed command
+already there.
+
+ Even if you don't understand Lisp syntax, it will probably be obvious
+which command is displayed for repetition. If you do not change the
+text, it will repeat exactly as before.
+
+ Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can
+use the minibuffer history commands (@kbd{M-p}, @kbd{M-n}, @kbd{M-r},
+@kbd{M-s}; @pxref{Minibuffer History}) to move through the history list
+of saved entire commands. After finding the desired previous command,
+you can edit its expression as usual and then resubmit it by typing
+@key{RET} as usual.
+
+@vindex command-history
+ The list of previous minibuffer-using commands is stored as a Lisp
+list in the variable @code{command-history}. Each element is a Lisp
+expression which describes one command and its arguments. Lisp programs
+can re-execute a command by calling @code{eval} with the
+@code{command-history} element.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@iftex
+@chapter Miscellaneous Commands
+
+ This chapter contains several brief topics that do not fit anywhere
+else: reading netnews, running shell commands and shell subprocesses,
+using a single shared Emacs for utilities that expect to run an editor
+as a subprocess, printing hardcopy, sorting text, narrowing display to
+part of the buffer, editing double-column files and binary files, saving
+an Emacs session for later resumption, emulating other editors, and
+various diversions and amusements.
+
+@end iftex
+@node Gnus, Shell, Calendar/Diary, Top
+@section Gnus
+@cindex Gnus
+@cindex reading netnews
+
+Gnus is an Emacs package primarily designed for reading and posting
+Usenet news. It can also be used to read and respond to messages from a
+number of other sources---mail, remote directories, digests, and so on.
+
+Here we introduce Gnus and describe several basic features.
+@ifinfo
+For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
+@end ifinfo
+@iftex
+For full details on Gnus, type @kbd{M-x info} and then select the Gnus
+manual.
+@end iftex
+
+@findex gnus
+To start Gnus, type @kbd{M-x gnus @key{RET}}.
+
+@menu
+* Buffers of Gnus:: The group, summary, and article buffers.
+* Gnus Startup:: What you should know about starting Gnus.
+* Summary of Gnus:: A short description of the basic Gnus commands.
+@end menu
+
+@node Buffers of Gnus
+@subsection Gnus Buffers
+
+As opposed to most normal Emacs packages, Gnus uses a number of
+different buffers to display information and to receive commands. The
+three buffers users spend most of their time in are the @dfn{group
+buffer}, the @dfn{summary buffer} and the @dfn{article buffer}.
+
+The @dfn{group buffer} contains a list of groups. This is the first
+buffer Gnus displays when it starts up. It normally displays only the
+groups to which you subscribe and that contain unread articles. Use
+this buffer to select a specific group.
+
+The @dfn{summary buffer} lists one line for each article in a single
+group. By default, the author, the subject and the line number are
+displayed for each article, but this is customizable, like most aspects
+of Gnus display. The summary buffer is created when you select a group
+in the group buffer, and is killed when you exit the group. Use this
+buffer to select an article.
+
+The @dfn{article buffer} displays the article. In normal Gnus usage,
+you don't select this buffer---all useful article-oriented commands work
+in the summary buffer. But you can select the article buffer, and
+execute all Gnus commands from that buffer, if you want to.
+
+@node Gnus Startup
+@subsection When Gnus Starts Up
+
+At startup, Gnus reads your @file{.newsrc} news initialization file
+and attempts to communicate with the local news server, which is a
+repository of news articles. The news server need not be the same
+computer you are logged in on.
+
+If you start Gnus and connect to the server, but do not see any
+newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get
+a listing of all the groups. Then type @kbd{u} to toggle
+subscription to groups.
+
+The first time you start Gnus, Gnus subscribes you to a few selected
+groups. All other groups start out as @dfn{killed groups} for you; you
+can list them with @kbd{A k}. All new groups that subsequently come to
+exist at the news server become @dfn{zombie groups} for you; type @kbd{A
+z} to list them. You can subscribe to a group shown in these lists
+using the @kbd{u} command.
+
+When you quit Gnus with @kbd{q}, it automatically records in your
+@file{.newsrc} and @file{.newsrc.eld} initialization files the
+subscribed or unsubscribed status of all groups. You should normally
+not edit these files manually, but you may if you know how.
+
+@node Summary of Gnus
+@subsection Summary of Gnus Commands
+
+Reading news is a two step process:
+
+@enumerate
+@item
+Choose a group in the group buffer.
+
+@item
+Select articles from the summary buffer. Each article selected is
+displayed in the article buffer in a large window, below the summary
+buffer in its small window.
+@end enumerate
+
+ Each Gnus buffer has its own special commands; however, the meanings
+of any given key in the various Gnus buffers are usually analogous, even
+if not identical. Here are commands for the group and summary buffers:
+
+@table @kbd
+@kindex q @r{(Gnus Group mode)}
+@findex gnus-group-exit
+@item q
+In the group buffer, update your @file{.newsrc} initialization file
+and quit Gnus.
+
+In the summary buffer, exit the current group and return to the
+group buffer. Thus, typing @kbd{q} twice quits Gnus.
+
+@kindex L @r{(Gnus Group mode)}
+@findex gnus-group-list-all-groups
+@item L
+In the group buffer, list all the groups available on your news
+server (except those you have killed). This may be a long list!
+
+@kindex l @r{(Gnus Group mode)}
+@findex gnus-group-list-groups
+@item l
+In the group buffer, list only the groups to which you subscribe and
+which contain unread articles.
+
+@kindex u @r{(Gnus Group mode)}
+@findex gnus-group-unsubscribe-current-group
+@cindex subscribe groups
+@cindex unsubscribe groups
+@item u
+In the group buffer, unsubscribe from (or subscribe to) the group listed
+in the line that point is on. When you quit Gnus by typing @kbd{q},
+Gnus lists in your @file{.newsrc} file which groups you have subscribed
+to. The next time you start Gnus, you won't see this group,
+because Gnus normally displays only subscribed-to groups.
+
+@kindex C-k @r{(Gnus)}
+@findex gnus-group-kill-group
+@item C-k
+In the group buffer, ``kill'' the current line's group---don't
+even list it in @file{.newsrc} from now on. This affects future
+Gnus sessions as well as the present session.
+
+When you quit Gnus by typing @kbd{q}, Gnus writes information
+in the file @file{.newsrc} describing all newsgroups except those you
+have ``killed.''
+
+@kindex SPC @r{(Gnus)}
+@findex gnus-group-read-group
+@item @key{SPC}
+In the group buffer, select the group on the line under the cursor
+and display the first unread article in that group.
+
+@need 1000
+In the summary buffer,
+
+@itemize @bullet
+@item
+Select the article on the line under the cursor if none is selected.
+
+@item
+Scroll the text of the selected article (if there is one).
+
+@item
+Select the next unread article if at the end of the current article.
+@end itemize
+
+Thus, you can move through all the articles by repeatedly typing @key{SPC}.
+
+@kindex DEL @r{(Gnus)}
+@item @key{DEL}
+In the group buffer, move point to the previous group containing
+unread articles.
+
+@findex gnus-summary-prev-page
+In the summary buffer, scroll the text of the article backwards.
+
+@kindex n @r{(Gnus)}
+@findex gnus-group-next-unread-group
+@findex gnus-summary-next-unread-article
+@item n
+Move point to the next unread group, or select the next unread article.
+
+@kindex p @r{(Gnus)}
+@findex gnus-group-prev-unread-group
+@findex gnus-summary-prev-unread-article
+@item p
+Move point to the previous unread group, or select the previous
+unread article.
+
+@kindex C-n @r{(Gnus Group mode)}
+@findex gnus-group-next-group
+@kindex C-p @r{(Gnus Group mode)}
+@findex gnus-group-prev-group
+@kindex C-n @r{(Gnus Summary mode)}
+@findex gnus-summary-next-subject
+@kindex C-p @r{(Gnus Summary mode)}
+@findex gnus-summary-prev-subject
+@item C-n
+@itemx C-p
+Move point to the next or previous item, even if it is marked as read.
+This does not select the article or group on that line.
+
+@kindex s @r{(Gnus Summary mode)}
+@findex gnus-summary-isearch-article
+@item s
+In the summary buffer, do an incremental search of the current text in
+the article buffer, just as if you switched to the article buffer and
+typed @kbd{C-s}.
+
+@kindex M-s @r{(Gnus Summary mode)}
+@findex gnus-summary-search-article-forward
+@item M-s @var{regexp} @key{RET}
+In the summary buffer, search forward for articles containing a match
+for @var{regexp}.
+
+@end table
+
+@ignore
+@node Where to Look
+@subsection Where to Look Further
+
+@c Too many references to the name of the manual if done with xref in TeX!
+Gnus is powerful and customizable. Here are references to a few
+@ifinfo
+additional topics:
+
+@end ifinfo
+@iftex
+additional topics in @cite{The Gnus Manual}:
+
+@itemize @bullet
+@item
+Follow discussions on specific topics.@*
+See section ``Threading.''
+
+@item
+Read digests. See section ``Document Groups.''
+
+@item
+Refer to and jump to the parent of the current article.@*
+See section ``Finding the Parent.''
+
+@item
+Refer to articles by using Message-IDs included in the messages.@*
+See section ``Article Keymap.''
+
+@item
+Save articles. See section ``Saving Articles.''
+
+@item
+Have Gnus score articles according to various criteria, like author
+name, subject, or string in the body of the articles.@*
+See section ``Scoring.''
+
+@item
+Send an article to a newsgroup.@*
+See section ``Composing Messages.''
+@end itemize
+@end iftex
+@ifinfo
+@itemize @bullet
+@item
+Follow discussions on specific topics.@*
+@xref{Threading, , Reading Based on Conversation Threads,
+gnus, The Gnus Manual}.
+
+@item
+Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}.
+
+@item
+Refer to and jump to the parent of the current article.@*
+@xref{Finding the Parent, , , gnus, The Gnus Manual}.
+
+@item
+Refer to articles by using Message-IDs included in the messages.@*
+@xref{Article Keymap, , , gnus, The Gnus Manual}.
+
+@item
+Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}.
+
+@item
+Have Gnus score articles according to various criteria, like author
+name, subject, or string in the body of the articles.@*
+@xref{Scoring, , , gnus, The Gnus Manual}.
+
+@item
+Send an article to a newsgroup.@*
+@xref{Composing Messages, , , gnus, The Gnus Manual}.
+@end itemize
+@end ifinfo
+@end ignore
+
+@node Shell, Emacs Server, Gnus, Top
+@section Running Shell Commands from Emacs
+@cindex subshell
+@cindex shell commands
+
+ Emacs has commands for passing single command lines to inferior shell
+processes; it can also run a shell interactively with input and output to
+an Emacs buffer named @samp{*shell*}.
+
+@table @kbd
+@item M-! @var{cmd} @key{RET}
+Run the shell command line @var{cmd} and display the output
+(@code{shell-command}).
+@item M-| @var{cmd} @key{RET}
+Run the shell command line @var{cmd} with region contents as input;
+optionally replace the region with the output
+(@code{shell-command-on-region}).
+@item M-x shell
+Run a subshell with input and output through an Emacs buffer.
+You can then give commands interactively.
+@end table
+
+@menu
+* Single Shell:: How to run one shell command and return.
+* Interactive Shell:: Permanent shell taking input via Emacs.
+* Shell Mode:: Special Emacs commands used with permanent shell.
+* History: Shell History. Repeating previous commands in a shell buffer.
+* Options: Shell Options. Options for customizing Shell mode.
+* Remote Host:: Connecting to another computer.
+@end menu
+
+@node Single Shell
+@subsection Single Shell Commands
+
+@kindex M-!
+@findex shell-command
+ @kbd{M-!} (@code{shell-command}) reads a line of text using the
+minibuffer and executes it as a shell command in a subshell made just
+for that command. Standard input for the command comes from the null
+device. If the shell command produces any output, the output goes into
+an Emacs buffer named @samp{*Shell Command Output*}, which is displayed
+in another window but not selected. A numeric argument, as in @kbd{M-1
+M-!}, directs this command to insert any output into the current buffer.
+In that case, point is left before the output and the mark is set after
+the output.
+
+ If the shell command line ends in @samp{&}, it runs asynchronously.
+For a synchronous shell command, @code{shell-command} returns the
+command's exit status (0 means success), when it is called from a Lisp
+program.
+
+@kindex M-|
+@findex shell-command-on-region
+ @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but
+passes the contents of the region as the standard input to the shell
+command, instead of no input. If a numeric argument is used, meaning
+insert the output in the current buffer, then the old region is deleted
+first and the output replaces it as the contents of the region. It
+returns the command's exit status when it is called from a Lisp program.
+
+@vindex shell-file-name
+@cindex environment
+ Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the
+shell to use. This variable is initialized based on your @code{SHELL}
+environment variable when Emacs is started. If the file name does not
+specify a directory, the directories in the list @code{exec-path} are
+searched; this list is initialized based on the environment variable
+@code{PATH} when Emacs is started. Your @file{.emacs} file can override
+either or both of these default initializations.@refill
+
+ Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete.
+To stop waiting, type @kbd{C-g} to quit; that terminates the shell
+command with the signal @code{SIGINT}---the same signal that @kbd{C-c}
+normally generates in the shell. Emacs waits until the command actually
+terminates. If the shell command doesn't stop (because it ignores the
+@code{SIGINT} signal), type @kbd{C-g} again; this sends the command a
+@code{SIGKILL} signal which is impossible to ignore.
+
+ To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
+@kbd{C-x @key{RET} c} immediately beforehand. @xref{Specify Coding}.
+
+@vindex shell-command-default-error-buffer
+ Error output from the command is normally intermixed with the regular
+output. If you set the variable
+@code{shell-command-default-error-buffer} to a string, which is a buffer
+name, error output is inserted before point in the buffer of that name.
+
+@node Interactive Shell
+@subsection Interactive Inferior Shell
+
+@findex shell
+ To run a subshell interactively, putting its typescript in an Emacs
+buffer, use @kbd{M-x shell}. This creates (or reuses) a buffer named
+@samp{*shell*} and runs a subshell with input coming from and output going
+to that buffer. That is to say, any ``terminal output'' from the subshell
+goes into the buffer, advancing point, and any ``terminal input'' for
+the subshell comes from text in the buffer. To give input to the subshell,
+go to the end of the buffer and type the input, terminated by @key{RET}.
+
+ Emacs does not wait for the subshell to do anything. You can switch
+windows or buffers and edit them while the shell is waiting, or while it is
+running a command. Output from the subshell waits until Emacs has time to
+process it; this happens whenever Emacs is waiting for keyboard input or
+for time to elapse.
+
+ To make multiple subshells, rename the buffer @samp{*shell*} to
+something different using @kbd{M-x rename-uniquely}. Then type @kbd{M-x
+shell} again to create a new buffer @samp{*shell*} with its own
+subshell. If you rename this buffer as well, you can create a third
+one, and so on. All the subshells run independently and in parallel.
+
+@vindex explicit-shell-file-name
+@cindex @code{ESHELL} environment variable
+@cindex @code{SHELL} environment variable
+ The file name used to load the subshell is the value of the variable
+@code{explicit-shell-file-name}, if that is non-@code{nil}. Otherwise,
+the environment variable @code{ESHELL} is used, or the environment
+variable @code{SHELL} if there is no @code{ESHELL}. If the file name
+specified is relative, the directories in the list @code{exec-path} are
+searched; this list is initialized based on the environment variable
+@code{PATH} when Emacs is started. Your @file{.emacs} file can override
+either or both of these default initializations.
+
+ To specify a coding system for the shell, you can use the command
+@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can also
+specify a coding system after starting the shell by using @kbd{C-x
+@key{RET} p} in the shell buffer. @xref{Specify Coding}.
+
+ As soon as the subshell is started, it is sent as input the contents
+of the file @file{~/.emacs_@var{shellname}}, if that file exists, where
+@var{shellname} is the name of the file that the shell was loaded from.
+For example, if you use bash, the file sent to it is
+@file{~/.emacs_bash}.
+
+@vindex shell-pushd-regexp
+@vindex shell-popd-regexp
+@vindex shell-cd-regexp
+ @code{cd}, @code{pushd} and @code{popd} commands given to the inferior
+shell are watched by Emacs so it can keep the @samp{*shell*} buffer's
+default directory the same as the shell's working directory. These
+commands are recognized syntactically by examining lines of input that are
+sent. If you use aliases for these commands, you can tell Emacs to
+recognize them also. For example, if the value of the variable
+@code{shell-pushd-regexp} matches the beginning of a shell command line,
+that line is regarded as a @code{pushd} command. Change this variable when
+you add aliases for @samp{pushd}. Likewise, @code{shell-popd-regexp} and
+@code{shell-cd-regexp} are used to recognize commands with the meaning of
+@samp{popd} and @samp{cd}. These commands are recognized only at the
+beginning of a shell command line.@refill
+
+@vindex shell-set-directory-error-hook
+ If Emacs gets an error while trying to handle what it believes is a
+@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook
+@code{shell-set-directory-error-hook} (@pxref{Hooks}).
+
+@findex dirs
+ If Emacs does not properly track changes in the current directory of
+the subshell, use the command @kbd{M-x dirs} to ask the shell what its
+current directory is. This command works for shells that support the
+most common command syntax; it may not work for unusual shells.
+
+@findex dirtrack-mode
+ You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an
+alternative and more aggressive method of tracking changes in the
+current directory.
+
+ Emacs defines the environment variable @code{EMACS} in the subshell,
+with value @code{t}. A shell script can check this variable to
+determine whether it has been run from an Emacs subshell.
+
+@node Shell Mode
+@subsection Shell Mode
+@cindex Shell mode
+@cindex mode, Shell
+
+ Shell buffers use Shell mode, which defines several special keys
+attached to the @kbd{C-c} prefix. They are chosen to resemble the usual
+editing and job control characters present in shells that are not under
+Emacs, except that you must type @kbd{C-c} first. Here is a complete list
+of the special key bindings of Shell mode:
+
+@table @kbd
+@item @key{RET}
+@kindex RET @r{(Shell mode)}
+@findex comint-send-input
+At end of buffer send line as input; otherwise, copy current line to end
+of buffer and send it (@code{comint-send-input}). When a line is
+copied, any text at the beginning of the line that matches the variable
+@code{shell-prompt-pattern} is left out; this variable's value should be
+a regexp string that matches the prompts that your shell uses.
+
+@item @key{TAB}
+@kindex TAB @r{(Shell mode)}
+@findex comint-dynamic-complete
+Complete the command name or file name before point in the shell buffer
+(@code{comint-dynamic-complete}). @key{TAB} also completes history
+references (@pxref{History References}) and environment variable names.
+
+@vindex shell-completion-fignore
+@vindex comint-completion-fignore
+The variable @code{shell-completion-fignore} specifies a list of file
+name extensions to ignore in Shell mode completion. The default setting
+ignores file names ending in @samp{~}, @samp{#} or @samp{%}. Other
+related Comint modes use the variable @code{comint-completion-fignore}
+instead.
+
+@item M-?
+@kindex M-? @r{(Shell mode)}
+@findex comint-dynamic-list-filename@dots{}
+Display temporarily a list of the possible completions of the file name
+before point in the shell buffer
+(@code{comint-dynamic-list-filename-completions}).
+
+@item C-d
+@kindex C-d @r{(Shell mode)}
+@findex comint-delchar-or-maybe-eof
+Either delete a character or send @sc{EOF}
+(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell
+buffer, @kbd{C-d} sends @sc{EOF} to the subshell. Typed at any other
+position in the buffer, @kbd{C-d} deletes a character as usual.
+
+@item C-c C-a
+@kindex C-c C-a @r{(Shell mode)}
+@findex comint-bol
+Move to the beginning of the line, but after the prompt if any
+(@code{comint-bol}). If you repeat this command twice in a row, the
+second time it moves back to the process mark, which is the beginning of
+the input that you have not yet sent to the subshell. (Normally that is
+the same place---the end of the prompt on this line---but after @kbd{C-c
+@key{SPC}} the process mark may be in a previous line.)
+
+@item C-c @key{SPC}
+Accumulate multiple lines of input, then send them together. This
+command inserts a newline before point, but does not send the preceding
+text as input to the subshell---at least, not yet. Both lines, the one
+before this newline and the one after, will be sent together (along with
+the newline that separates them), when you type @key{RET}.
+
+@item C-c C-u
+@kindex C-c C-u @r{(Shell mode)}
+@findex comint-kill-input
+Kill all text pending at end of buffer to be sent as input
+(@code{comint-kill-input}).
+
+@item C-c C-w
+@kindex C-c C-w @r{(Shell mode)}
+Kill a word before point (@code{backward-kill-word}).
+
+@item C-c C-c
+@kindex C-c C-c @r{(Shell mode)}
+@findex comint-interrupt-subjob
+Interrupt the shell or its current subjob if any
+(@code{comint-interrupt-subjob}). This command also kills
+any shell input pending in the shell buffer and not yet sent.
+
+@item C-c C-z
+@kindex C-c C-z @r{(Shell mode)}
+@findex comint-stop-subjob
+Stop the shell or its current subjob if any (@code{comint-stop-subjob}).
+This command also kills any shell input pending in the shell buffer and
+not yet sent.
+
+@item C-c C-\
+@findex comint-quit-subjob
+@kindex C-c C-\ @r{(Shell mode)}
+Send quit signal to the shell or its current subjob if any
+(@code{comint-quit-subjob}). This command also kills any shell input
+pending in the shell buffer and not yet sent.
+
+@item C-c C-o
+@kindex C-c C-o @r{(Shell mode)}
+@findex comint-kill-output
+Kill the last batch of output from a shell command
+(@code{comint-kill-output}). This is useful if a shell command spews
+out lots of output that just gets in the way.
+
+@item C-c C-r
+@itemx C-M-l
+@kindex C-c C-r @r{(Shell mode)}
+@kindex C-M-l @r{(Shell mode)}
+@findex comint-show-output
+Scroll to display the beginning of the last batch of output at the top
+of the window; also move the cursor there (@code{comint-show-output}).
+
+@item C-c C-e
+@kindex C-c C-e @r{(Shell mode)}
+@findex comint-show-maximum-output
+Scroll to put the end of the buffer at the bottom of the window
+(@code{comint-show-maximum-output}).
+
+@item C-c C-f
+@kindex C-c C-f @r{(Shell mode)}
+@findex shell-forward-command
+@vindex shell-command-regexp
+Move forward across one shell command, but not beyond the current line
+(@code{shell-forward-command}). The variable @code{shell-command-regexp}
+specifies how to recognize the end of a command.
+
+@item C-c C-b
+@kindex C-c C-b @r{(Shell mode)}
+@findex shell-backward-command
+Move backward across one shell command, but not beyond the current line
+(@code{shell-backward-command}).
+
+@item C-c C-l
+@kindex C-c C-l @r{(Shell mode)}
+@findex comint-dynamic-list-input-ring
+Display the buffer's history of shell commands in another window
+(@code{comint-dynamic-list-input-ring}).
+
+@item M-x dirs
+Ask the shell what its current directory is, so that Emacs can agree
+with the shell.
+
+@item M-x send-invisible @key{RET} @var{text} @key{RET}
+@findex send-invisible
+Send @var{text} as input to the shell, after reading it without
+echoing. This is useful when a shell command runs a program that asks
+for a password.
+
+Alternatively, you can arrange for Emacs to notice password prompts
+and turn off echoing for them, as follows:
+
+@example
+(add-hook 'comint-output-filter-functions
+ 'comint-watch-for-password-prompt)
+@end example
+
+@item M-x comint-continue-subjob
+@findex comint-continue-subjob
+Continue the shell process. This is useful if you accidentally suspend
+the shell process.@footnote{You should not suspend the shell process.
+Suspending a subjob of the shell is a completely different matter---that
+is normal practice, but you must use the shell to continue the subjob;
+this command won't do it.}
+
+@item M-x comint-strip-ctrl-m
+@findex comint-strip-ctrl-m
+Discard all control-M characters from the current group of shell output.
+The most convenient way to use this command is to make it run
+automatically when you get output from the subshell. To do that,
+evaluate this Lisp expression:
+
+@example
+(add-hook 'comint-output-filter-functions
+ 'comint-strip-ctrl-m)
+@end example
+
+@item M-x comint-truncate-buffer
+@findex comint-truncate-buffer
+This command truncates the shell buffer to a certain maximum number of
+lines, specified by the variable @code{comint-buffer-maximum-size}.
+Here's how to do this automatically each time you get output from the
+subshell:
+
+@example
+(add-hook 'comint-output-filter-functions
+ 'comint-truncate-buffer)
+@end example
+@end table
+
+ Shell mode also customizes the paragraph commands so that only shell
+prompts start new paragraphs. Thus, a paragraph consists of an input
+command plus the output that follows it in the buffer.
+
+@cindex Comint mode
+@cindex mode, Comint
+ Shell mode is a derivative of Comint mode, a general-purpose mode for
+communicating with interactive subprocesses. Most of the features of
+Shell mode actually come from Comint mode, as you can see from the
+command names listed above. The special features of Shell mode in
+particular include the choice of regular expression for detecting
+prompts, the directory tracking feature, and a few user commands.
+
+ Other Emacs features that use variants of Comint mode include GUD
+(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}).
+
+@findex comint-run
+ You can use @kbd{M-x comint-run} to execute any program of your choice
+in a subprocess using unmodified Comint mode---without the
+specializations of Shell mode.
+
+@node Shell History
+@subsection Shell Command History
+
+ Shell buffers support three ways of repeating earlier commands. You
+can use the same keys used in the minibuffer; these work much as they do
+in the minibuffer, inserting text from prior commands while point
+remains always at the end of the buffer. You can move through the
+buffer to previous inputs in their original place, then resubmit them or
+copy them to the end. Or you can use a @samp{!}-style history
+reference.
+
+@menu
+* Ring: Shell Ring. Fetching commands from the history list.
+* Copy: Shell History Copying. Moving to a command and then copying it.
+* History References:: Expanding @samp{!}-style history references.
+@end menu
+
+@node Shell Ring
+@subsubsection Shell History Ring
+
+@table @kbd
+@findex comint-previous-input
+@kindex M-p @r{(Shell mode)}
+@item M-p
+Fetch the next earlier old shell command.
+
+@kindex M-n @r{(Shell mode)}
+@findex comint-next-input
+@item M-n
+Fetch the next later old shell command.
+
+@kindex M-r @r{(Shell mode)}
+@kindex M-s @r{(Shell mode)}
+@findex comint-previous-matching-input
+@findex comint-next-matching-input
+@item M-r @var{regexp} @key{RET}
+@itemx M-s @var{regexp} @key{RET}
+Search backwards or forwards for old shell commands that match @var{regexp}.
+
+@item C-c C-x @r{(Shell mode)}
+@findex comint-get-next-from-history
+Fetch the next subsequent command from the history.
+@end table
+
+ Shell buffers provide a history of previously entered shell commands. To
+reuse shell commands from the history, use the editing commands @kbd{M-p},
+@kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work just like the minibuffer
+history commands except that they operate on the text at the end of the
+shell buffer, where you would normally insert text to send to the shell.
+
+ @kbd{M-p} fetches an earlier shell command to the end of the shell buffer.
+Successive use of @kbd{M-p} fetches successively earlier shell commands,
+each replacing any text that was already present as potential shell input.
+@kbd{M-n} does likewise except that it finds successively more recent shell
+commands from the buffer.
+
+ The history search commands @kbd{M-r} and @kbd{M-s} read a regular
+expression and search through the history for a matching command. Aside
+from the choice of which command to fetch, they work just like @kbd{M-p}
+and @kbd{M-r}. If you enter an empty regexp, these commands reuse the
+same regexp used last time.
+
+ When you find the previous input you want, you can resubmit it by
+typing @key{RET}, or you can edit it first and then resubmit it if you
+wish.
+
+ Often it is useful to reexecute several successive shell commands that
+were previously executed in sequence. To do this, first find and
+reexecute the first command of the sequence. Then type @kbd{C-c C-x};
+that will fetch the following command---the one that follows the command
+you just repeated. Then type @key{RET} to reexecute this command. You
+can reexecute several successive commands by typing @kbd{C-c C-x
+@key{RET}} over and over.
+
+ These commands get the text of previous shell commands from a special
+history list, not from the shell buffer itself. Thus, editing the shell
+buffer, or even killing large parts of it, does not affect the history
+that these commands access.
+
+@vindex shell-input-ring-file-name
+ Some shells store their command histories in files so that you can
+refer to previous commands from previous shell sessions. Emacs reads
+the command history file for your chosen shell, to initialize its own
+command history. The file name is @file{~/.bash_history} for bash,
+@file{~/.sh_history} for ksh, and @file{~/.history} for other shells.
+
+@node Shell History Copying
+@subsubsection Shell History Copying
+
+@table @kbd
+@kindex C-c C-p @r{(Shell mode)}
+@findex comint-previous-prompt
+@item C-c C-p
+Move point to the previous prompt (@code{comint-previous-prompt}).
+
+@kindex C-c C-n @r{(Shell mode)}
+@findex comint-next-prompt
+@item C-c C-n
+Move point to the following prompt (@code{comint-next-prompt}).
+
+@kindex C-c RET @r{(Shell mode)}
+@findex comint-copy-old-input
+@item C-c @key{RET}
+Copy the input command which point is in, inserting the copy at the end
+of the buffer (@code{comint-copy-old-input}). This is useful if you
+move point back to a previous command. After you copy the command, you
+can submit the copy as input with @key{RET}. If you wish, you can
+edit the copy before resubmitting it.
+@end table
+
+ Moving to a previous input and then copying it with @kbd{C-c
+@key{RET}} produces the same results---the same buffer contents---that
+you would get by using @kbd{M-p} enough times to fetch that previous
+input from the history list. However, @kbd{C-c @key{RET}} copies the
+text from the buffer, which can be different from what is in the history
+list if you edit the input text in the buffer after it has been sent.
+
+@node History References
+@subsubsection Shell History References
+@cindex history reference
+
+ Various shells including csh and bash support @dfn{history references}
+that begin with @samp{!} and @samp{^}. Shell mode can understand these
+constructs and perform the history substitution for you. If you insert
+a history reference and type @key{TAB}, this searches the input history
+for a matching command, performs substitution if necessary, and places
+the result in the buffer in place of the history reference. For
+example, you can fetch the most recent command beginning with @samp{mv}
+with @kbd{! m v @key{TAB}}. You can edit the command if you wish, and
+then resubmit the command to the shell by typing @key{RET}.
+
+@vindex shell-prompt-pattern
+@vindex comint-prompt-regexp
+ History references take effect only following a shell prompt. The
+variable @code{shell-prompt-pattern} specifies how to recognize a shell
+prompt. Comint modes in general use the variable
+@code{comint-prompt-regexp} to specify how to find a prompt; Shell mode
+uses @code{shell-prompt-pattern} to set up the local value of
+@code{comint-prompt-regexp}.
+
+@vindex comint-input-autoexpand
+ Shell mode can optionally expand history references in the buffer when
+you send them to the shell. To request this, set the variable
+@code{comint-input-autoexpand} to @code{input}.
+
+@findex comint-magic-space
+ You can make @key{SPC} perform history expansion by binding @key{SPC} to
+the command @code{comint-magic-space}.
+
+@node Shell Options
+@subsection Shell Mode Options
+
+@vindex comint-scroll-to-bottom-on-input
+ If the variable @code{comint-scroll-to-bottom-on-input} is
+non-@code{nil}, insertion and yank commands scroll the selected window
+to the bottom before inserting.
+
+@vindex comint-scroll-show-maximum-output
+ If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then
+scrolling due to arrival of output tries to place the last line of text
+at the bottom line of the window, so as to show as much useful text as
+possible. (This mimics the scrolling behavior of many terminals.)
+The default is @code{nil}.
+
+@vindex comint-scroll-to-bottom-on-output
+ By setting @code{comint-scroll-to-bottom-on-output}, you can opt for
+having point jump to the end of the buffer whenever output arrives---no
+matter where in the buffer point was before. If the value is
+@code{this}, point jumps in the selected window. If the value is
+@code{all}, point jumps in each window that shows the comint buffer. If
+the value is @code{other}, point jumps in all nonselected windows that
+show the current buffer. The default value is @code{nil}, which means
+point does not jump to the end.
+
+@vindex comint-input-ignoredups
+ The variable @code{comint-input-ignoredups} controls whether successive
+identical inputs are stored in the input history. A non-@code{nil}
+value means to omit an input that is the same as the previous input.
+The default is @code{nil}, which means to store each input even if it is
+equal to the previous input.
+
+@vindex comint-completion-addsuffix
+@vindex comint-completion-recexact
+@vindex comint-completion-autolist
+ Three variables customize file name completion. The variable
+@code{comint-completion-addsuffix} controls whether completion inserts a
+space or a slash to indicate a fully completed file or directory name
+(non-@code{nil} means do insert a space or slash).
+@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB}
+to choose the shortest possible completion if the usual Emacs completion
+algorithm cannot add even a single character.
+@code{comint-completion-autolist}, if non-@code{nil}, says to list all
+the possible completions whenever completion is not exact.
+
+@findex comint-dynamic-complete-variable
+ The command @code{comint-dynamic-complete-variable} does variable-name
+completion using the environment variables as set within Emacs. The
+variables controlling file name completion apply to variable-name
+completion too. This command is normally available through the menu
+bar.
+
+@vindex shell-command-execonly
+ Command completion normally considers only executable files.
+If you set @code{shell-command-execonly} to @code{nil},
+it considers nonexecutable files as well.
+
+@findex shell-pushd-tohome
+@findex shell-pushd-dextract
+@findex shell-pushd-dunique
+ You can configure the behavior of @samp{pushd}. Variables control
+whether @samp{pushd} behaves like @samp{cd} if no argument is given
+(@code{shell-pushd-tohome}), pop rather than rotate with a numeric
+argument (@code{shell-pushd-dextract}), and only add directories to the
+directory stack if they are not already on it
+(@code{shell-pushd-dunique}). The values you choose should match the
+underlying shell, of course.
+
+@node Remote Host
+@subsection Remote Host Shell
+@cindex remote host
+@cindex connecting to remote host
+@cindex Telnet
+@cindex Rlogin
+
+ Emacs provides two commands for logging in to another computer
+and communicating with it through an Emacs buffer.
+
+@table @kbd
+@item M-x telnet @key{RET} @var{hostname} @key{RET}
+Set up a Telnet connection to the computer named @var{hostname}.
+@item M-x rlogin @key{RET} @var{hostname} @key{RET}
+Set up an Rlogin connection to the computer named @var{hostname}.
+@end table
+
+@findex telnet
+ Use @kbd{M-x telnet} to set up a Telnet connection to another
+computer. (Telnet is the standard Internet protocol for remote login.)
+It reads the host name of the other computer as an argument with the
+minibuffer. Once the connection is established, talking to the other
+computer works like talking to a subshell: you can edit input with the
+usual Emacs commands, and send it a line at a time by typing @key{RET}.
+The output is inserted in the Telnet buffer interspersed with the input.
+
+@findex rlogin
+@vindex rlogin-explicit-args
+ Use @kbd{M-x rlogin} to set up an Rlogin connection. Rlogin is
+another remote login communication protocol, essentially much like the
+Telnet protocol but incompatible with it, and supported only by certain
+systems. Rlogin's advantages are that you can arrange not to have to
+give your user name and password when communicating between two machines
+you frequently use, and that you can make an 8-bit-clean connection.
+(To do that in Emacs, set @code{rlogin-explicit-args} to @code{("-8")}
+before you run Rlogin.)
+
+ @kbd{M-x rlogin} sets up the default file directory of the Emacs
+buffer to access the remote host via FTP (@pxref{File Names}), and it
+tracks the shell commands that change the current directory, just like
+Shell mode.
+
+@findex rlogin-directory-tracking-mode
+ There are two ways of doing directory tracking in an Rlogin
+buffer---either with remote directory names
+@file{/@var{host}:@var{dir}/} or with local names (that works if the
+``remote'' machine shares file systems with your machine of origin).
+You can use the command @code{rlogin-directory-tracking-mode} to switch
+modes. No argument means use remote directory names, a positive
+argument means use local names, and a negative argument means turn
+off directory tracking.
+
+@node Emacs Server, Hardcopy, Shell, Top
+@section Using Emacs as a Server
+@pindex emacsclient
+@cindex Emacs as a server
+@cindex server, using Emacs as
+@cindex @code{EDITOR} environment variable
+
+ Various programs such as @code{mail} can invoke your choice of editor
+to edit a particular piece of text, such as a message that you are
+sending. By convention, most of these programs use the environment
+variable @code{EDITOR} to specify which editor to run. If you set
+@code{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
+inconvenient fashion, by starting a new, separate Emacs process. This
+is inconvenient because it takes time and because the new Emacs process
+doesn't share the buffers in the existing Emacs process.
+
+ You can arrange to use your existing Emacs process as the editor for
+programs like @code{mail} by using the Emacs client and Emacs server
+programs. Here is how.
+
+@cindex @code{TEXEDIT} environment variable
+ First, the preparation. Within Emacs, call the function
+@code{server-start}. (Your @file{.emacs} file can do this automatically
+if you add the expression @code{(server-start)} to it.) Then, outside
+Emacs, set the @code{EDITOR} environment variable to @samp{emacsclient}.
+(Note that some programs use a different environment variable; for
+example, to make @TeX{} use @samp{emacsclient}, you should set the
+@code{TEXEDIT} environment variable to @samp{emacsclient +%d %s}.)
+
+@kindex C-x #
+@findex server-edit
+ Then, whenever any program invokes your specified @code{EDITOR}
+program, the effect is to send a message to your principal Emacs telling
+it to visit a file. (That's what the program @code{emacsclient} does.)
+Emacs displays the buffer immediately and you can immediately begin
+editing it.
+
+ When you've finished editing that buffer, type @kbd{C-x #}
+(@code{server-edit}). This saves the file and sends a message back to
+the @code{emacsclient} program telling it to exit. The programs that
+use @code{EDITOR} wait for the ``editor'' (actually, @code{emacsclient})
+to exit. @kbd{C-x #} also checks for other pending external requests
+to edit various files, and selects the next such file.
+
+ You can switch to a server buffer manually if you wish; you don't have
+to arrive at it with @kbd{C-x #}. But @kbd{C-x #} is the only way to
+say that you are ``finished'' with one.
+
+@vindex server-window
+ If you set the variable @code{server-window} to a window or a frame,
+@kbd{C-x #} displays the server buffer in that window or in that frame.
+
+ While @code{mail} or another application is waiting for
+@code{emacsclient} to finish, @code{emacsclient} does not read terminal
+input. So the terminal that @code{mail} was using is effectively
+blocked for the duration. In order to edit with your principal Emacs,
+you need to be able to use it without using that terminal. There are
+two ways to do this:
+
+@itemize @bullet
+@item
+Using a window system, run @code{mail} and the principal Emacs in two
+separate windows. While @code{mail} is waiting for @code{emacsclient},
+the window where it was running is blocked, but you can use Emacs by
+switching windows.
+
+@item
+Use Shell mode in Emacs to run the other program such as @code{mail};
+then, @code{emacsclient} blocks only the subshell under Emacs, and you
+can still use Emacs to edit the file.
+@end itemize
+
+@vindex server-temp-file-regexp
+ Some programs write temporary files for you to edit. After you edit
+the temporary file, the program reads it back and deletes it. If the
+Emacs server is later asked to edit the same file name, it should assume
+this has nothing to do with the previous occasion for that file name.
+The server accomplishes this by killing the temporary file's buffer when
+you finish with the file. Use the variable
+@code{server-temp-file-regexp} to specify which files are temporary in
+this sense; its value should be a regular expression that matches file
+names that are temporary.
+
+ If you run @code{emacsclient} with the option @samp{--no-wait}, it
+returns immediately without waiting for you to ``finish'' the buffer in
+Emacs.
+
+@menu
+* Invoking emacsclient::
+@end menu
+
+@node Invoking emacsclient,, Emacs Server, Emacs Server
+@section Invoking @code{emacsclient}
+
+ To run the @code{emacsclient} program, specify file names as arguments,
+and optionally line numbers as well. Do it like this:
+
+@example
+emacsclient @r{@{}@r{[}+@var{line}@r{]} @var{filename}@r{@}}@dots{}
+@end example
+
+This tells Emacs to visit each of the specified files; if you specify a
+line number for a certain file, Emacs moves to that line in the file.
+
+Ordinarily, @code{emacsclient} does not return until you use the
+@kbd{C-x #} command on each of these buffers. When that happens, Emacs
+sends a message to the @code{emacsclient} program telling it to return.
+
+But if you use the option @samp{-n} or @samp{--no-wait} when running
+@code{emacsclient}, then it returns immediately. (You can take as long
+as you like to edit the files in Emacs.)
+
+
+@node Hardcopy, Postscript, Emacs Server, Top
+@section Hardcopy Output
+@cindex hardcopy
+
+ The Emacs commands for making hardcopy let you print either an entire
+buffer or just part of one, either with or without page headers.
+See also the hardcopy commands of Dired (@pxref{Misc File Ops})
+and the diary (@pxref{Diary Commands}).
+
+@table @kbd
+@item M-x print-buffer
+Print hardcopy of current buffer with page headings containing the file
+name and page number.
+@item M-x lpr-buffer
+Print hardcopy of current buffer without page headings.
+@item M-x print-region
+Like @code{print-buffer} but print only the current region.
+@item M-x lpr-region
+Like @code{lpr-buffer} but print only the current region.
+@end table
+
+@findex print-buffer
+@findex print-region
+@findex lpr-buffer
+@findex lpr-region
+@vindex lpr-switches
+ The hardcopy commands (aside from the Postscript commands) pass extra
+switches to the @code{lpr} program based on the value of the variable
+@code{lpr-switches}. Its value should be a list of strings, each string
+an option starting with @samp{-}. For example, to specify a line width
+of 80 columns for all the printing you do in Emacs, set
+@code{lpr-switches} like this:
+
+@example
+(setq lpr-switches '("-w80"))
+@end example
+
+@vindex printer-name
+ You can specify the printer to use by setting the variable
+@code{printer-name}.
+
+@vindex lpr-headers-switches
+@vindex lpr-commands
+@vindex lpr-add-switches
+ The variable @code{lpr-command} specifies the name of the printer
+program to run; the default value depends on your operating system type.
+On most systems, the default is @code{"lpr"}. The variable
+@code{lpr-headers-switches} similarly specifies the extra switches to
+use to make page headers. The variable @code{lpr-add-switches} controls
+whether to supply @samp{-T} and @samp{-J} options (suitable for
+@code{lpr}) to the printer program: @code{nil} means don't add them.
+@code{lpr-add-switches} should be @code{nil} if your printer program is
+not compatible with @code{lpr}.
+
+@node Postscript, Postscript Variables, Hardcopy, Top
+@section Postscript Hardcopy
+
+ These commands convert buffer contents to Postscript,
+either printing it or leaving it in another Emacs buffer.
+
+@table @kbd
+@item M-x ps-print-buffer
+Print hardcopy of the current buffer in Postscript form.
+@item M-x ps-print-region
+Print hardcopy of the current region in Postscript form.
+@item M-x ps-print-buffer-with-faces
+Print hardcopy of the current buffer in Postscript form, showing the
+faces used in the text by means of Postscript features.
+@item M-x ps-print-region-with-faces
+Print hardcopy of the current region in Postscript form, showing the
+faces used in the text.
+@item M-x ps-spool-buffer
+Generate Postscript for the current buffer text.
+@item M-x ps-spool-region
+Generate Postscript for the current region.
+@item M-x ps-spool-buffer-with-faces
+Generate Postscript for the current buffer, showing the faces used.
+@item M-x ps-spool-region-with-faces
+Generate Postscript for the current region, showing the faces used.
+@end table
+
+@findex ps-print-region
+@findex ps-print-buffer
+@findex ps-print-region-with-faces
+@findex ps-print-buffer-with-faces
+ The Postscript commands, @code{ps-print-buffer} and
+@code{ps-print-region}, print buffer contents in Postscript form. One
+command prints the entire buffer; the other, just the region. The
+corresponding @samp{-with-faces} commands,
+@code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces},
+use Postscript features to show the faces (fonts and colors) in the text
+properties of the text being printed.
+
+ If you are using a color display, you can print a buffer of program
+code with color highlighting by turning on Font-Lock mode in that
+buffer, and using @code{ps-print-buffer-with-faces}.
+
+@findex ps-spool-region
+@findex ps-spool-buffer
+@findex ps-spool-region-with-faces
+@findex ps-spool-buffer-with-faces
+ The commands whose names have @samp{spool} instead of @samp{print}
+generate the Postscript output in an Emacs buffer instead of sending
+it to the printer.
+
+@ifinfo
+ The following section describes variables for customizing these commands.
+@end ifinfo
+
+@node Postscript Variables, Sorting, Postscript, Top
+@section Variables for Postscript Hardcopy
+
+@vindex ps-lpr-command
+@vindex ps-lpr-switches
+@vindex ps-printer-name
+ All the Postscript hardcopy commands use the variables
+@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print
+the output. @code{ps-lpr-command} specifies the command name to run,
+@code{ps-lpr-switches} specifies command line options to use, and
+@code{ps-printer-name} specifies the printer. If you don't set the
+first two variables yourself, they take their initial values from
+@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name}
+is @code{nil}, @code{printer-name} is used.
+
+@vindex ps-print-header
+@vindex ps-print-color-p
+ The variable @code{ps-print-header} controls whether these commands
+add header lines to each page---set it to @code{nil} to turn headers
+off. You can turn off color processing by setting
+@code{ps-print-color-p} to @code{nil}.
+
+@vindex ps-paper-type
+@vindex ps-page-dimensions-database
+ The variable @code{ps-paper-type} specifies which size of paper to
+format for; legitimate values include @code{a4}, @code{a3},
+@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger},
+@code{legal}, @code{letter}, @code{letter-small}, @code{statement},
+@code{tabloid}. The default is @code{letter}. You can define
+additional paper sizes by changing the variable
+@code{ps-page-dimensions-database}.
+
+@vindex ps-landscape-mode
+ The variable @code{ps-landscape-mode} specifies the orientation of
+printing on the page. The default is @code{nil}, which stands for
+``portrait'' mode. Any non-@code{nil} value specifies ``landscape''
+mode.
+
+@vindex ps-number-of-columns
+ The variable @code{ps-number-of-columns} specifies the number of
+columns; it takes effect in both landscape and portrait mode. The
+default is 1.
+
+@vindex ps-font-family
+@vindex ps-font-size
+@vindex ps-font-info-database
+ The variable @code{ps-font-family} specifies which font family to use
+for printing ordinary text. Legitimate values include @code{Courier},
+@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and
+@code{Times}. The variable @code{ps-font-size} specifies the size of
+the font for ordinary text. It defaults to 8.5 points.
+
+ Many other customization variables for these commands are defined and
+described in the Lisp file @file{ps-print.el}.
+
+@node Sorting, Narrowing, Postscript Variables, Top
+@section Sorting Text
+@cindex sorting
+
+ Emacs provides several commands for sorting text in the buffer. All
+operate on the contents of the region (the text between point and the
+mark). They divide the text of the region into many @dfn{sort records},
+identify a @dfn{sort key} for each record, and then reorder the records
+into the order determined by the sort keys. The records are ordered so
+that their keys are in alphabetical order, or, for numeric sorting, in
+numeric order. In alphabetic sorting, all upper-case letters `A' through
+`Z' come before lower-case `a', in accord with the ASCII character
+sequence.
+
+ The various sort commands differ in how they divide the text into sort
+records and in which part of each record is used as the sort key. Most of
+the commands make each line a separate sort record, but some commands use
+paragraphs or pages as sort records. Most of the sort commands use each
+entire sort record as its own sort key, but some use only a portion of the
+record as the sort key.
+
+@findex sort-lines
+@findex sort-paragraphs
+@findex sort-pages
+@findex sort-fields
+@findex sort-numeric-fields
+@table @kbd
+@item M-x sort-lines
+Divide the region into lines, and sort by comparing the entire
+text of a line. A numeric argument means sort into descending order.
+
+@item M-x sort-paragraphs
+Divide the region into paragraphs, and sort by comparing the entire
+text of a paragraph (except for leading blank lines). A numeric
+argument means sort into descending order.
+
+@item M-x sort-pages
+Divide the region into pages, and sort by comparing the entire
+text of a page (except for leading blank lines). A numeric
+argument means sort into descending order.
+
+@item M-x sort-fields
+Divide the region into lines, and sort by comparing the contents of
+one field in each line. Fields are defined as separated by
+whitespace, so the first run of consecutive non-whitespace characters
+in a line constitutes field 1, the second such run constitutes field
+2, etc.
+
+Specify which field to sort by with a numeric argument: 1 to sort by
+field 1, etc. A negative argument means count fields from the right
+instead of from the left; thus, minus 1 means sort by the last field.
+If several lines have identical contents in the field being sorted, they
+keep same relative order that they had in the original buffer.
+
+@item M-x sort-numeric-fields
+Like @kbd{M-x sort-fields} except the specified field is converted
+to an integer for each line, and the numbers are compared. @samp{10}
+comes before @samp{2} when considered as text, but after it when
+considered as a number.
+
+@item M-x sort-columns
+Like @kbd{M-x sort-fields} except that the text within each line
+used for comparison comes from a fixed range of columns. See below
+for an explanation.
+
+@item M-x reverse-region
+Reverse the order of the lines in the region. This is useful for
+sorting into descending order by fields or columns, since those sort
+commands do not have a feature for doing that.
+@end table
+
+ For example, if the buffer contains this:
+
+@smallexample
+On systems where clash detection (locking of files being edited) is
+implemented, Emacs also checks the first time you modify a buffer
+whether the file has changed on disk since it was last visited or
+saved. If it has, you are asked to confirm that you want to change
+the buffer.
+@end smallexample
+
+@noindent
+applying @kbd{M-x sort-lines} to the entire buffer produces this:
+
+@smallexample
+On systems where clash detection (locking of files being edited) is
+implemented, Emacs also checks the first time you modify a buffer
+saved. If it has, you are asked to confirm that you want to change
+the buffer.
+whether the file has changed on disk since it was last visited or
+@end smallexample
+
+@noindent
+where the upper-case @samp{O} sorts before all lower-case letters. If
+you use @kbd{C-u 2 M-x sort-fields} instead, you get this:
+
+@smallexample
+implemented, Emacs also checks the first time you modify a buffer
+saved. If it has, you are asked to confirm that you want to change
+the buffer.
+On systems where clash detection (locking of files being edited) is
+whether the file has changed on disk since it was last visited or
+@end smallexample
+
+@noindent
+where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer},
+@samp{systems} and @samp{the}.
+
+@findex sort-columns
+ @kbd{M-x sort-columns} requires more explanation. You specify the
+columns by putting point at one of the columns and the mark at the other
+column. Because this means you cannot put point or the mark at the
+beginning of the first line of the text you want to sort, this command
+uses an unusual definition of `region': all of the line point is in is
+considered part of the region, and so is all of the line the mark is in,
+as well as all the lines in between.
+
+ For example, to sort a table by information found in columns 10 to 15,
+you could put the mark on column 10 in the first line of the table, and
+point on column 15 in the last line of the table, and then run
+@code{sort-columns}. Equivalently, you could run it with the mark on
+column 15 in the first line and point on column 10 in the last line.
+
+ This can be thought of as sorting the rectangle specified by point and
+the mark, except that the text on each line to the left or right of the
+rectangle moves along with the text inside the rectangle.
+@xref{Rectangles}.
+
+@vindex sort-fold-case
+ Many of the sort commands ignore case differences when comparing, if
+@code{sort-fold-case} is non-@code{nil}.
+
+@node Narrowing, Two-Column, Sorting, Top
+@section Narrowing
+@cindex widening
+@cindex restriction
+@cindex narrowing
+@cindex accessible portion
+
+ @dfn{Narrowing} means focusing in on some portion of the buffer,
+making the rest temporarily inaccessible. The portion which you can
+still get to is called the @dfn{accessible portion}. Canceling the
+narrowing, which makes the entire buffer once again accessible, is
+called @dfn{widening}. The amount of narrowing in effect in a buffer at
+any time is called the buffer's @dfn{restriction}.
+
+ Narrowing can make it easier to concentrate on a single subroutine or
+paragraph by eliminating clutter. It can also be used to restrict the
+range of operation of a replace command or repeating keyboard macro.
+
+@c WideCommands
+@table @kbd
+@item C-x n n
+Narrow down to between point and mark (@code{narrow-to-region}).
+@item C-x n w
+Widen to make the entire buffer accessible again (@code{widen}).
+@item C-x n p
+Narrow down to the current page (@code{narrow-to-page}).
+@item C-x n d
+Narrow down to the current defun (@code{narrow-to-defun}).
+@end table
+
+ When you have narrowed down to a part of the buffer, that part appears
+to be all there is. You can't see the rest, you can't move into it
+(motion commands won't go outside the accessible part), you can't change
+it in any way. However, it is not gone, and if you save the file all
+the inaccessible text will be saved. The word @samp{Narrow} appears in
+the mode line whenever narrowing is in effect.
+
+@kindex C-x n n
+@findex narrow-to-region
+ The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}).
+It sets the current buffer's restrictions so that the text in the current
+region remains accessible but all text before the region or after the region
+is inaccessible. Point and mark do not change.
+
+@kindex C-x n p
+@findex narrow-to-page
+@kindex C-x n d
+@findex narrow-to-defun
+ Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow
+down to the current page. @xref{Pages}, for the definition of a page.
+@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun
+containing point (@pxref{Defuns}).
+
+@kindex C-x n w
+@findex widen
+ The way to cancel narrowing is to widen with @kbd{C-x n w}
+(@code{widen}). This makes all text in the buffer accessible again.
+
+ You can get information on what part of the buffer you are narrowed down
+to using the @kbd{C-x =} command. @xref{Position Info}.
+
+ Because narrowing can easily confuse users who do not understand it,
+@code{narrow-to-region} is normally a disabled command. Attempting to use
+this command asks for confirmation and gives you the option of enabling it;
+if you enable the command, confirmation will no longer be required for
+it. @xref{Disabling}.
+
+@node Two-Column, Editing Binary Files, Narrowing, Top
+@section Two-Column Editing
+@cindex two-column editing
+@cindex splitting columns
+@cindex columns, splitting
+
+ Two-column mode lets you conveniently edit two side-by-side columns of
+text. It uses two side-by-side windows, each showing its own
+buffer.
+
+ There are three ways to enter two-column mode:
+
+@table @asis
+@item @kbd{@key{F2} 2} or @kbd{C-x 6 2}
+@kindex F2 2
+@kindex C-x 6 2
+@findex 2C-two-columns
+Enter two-column mode with the current buffer on the left, and on the
+right, a buffer whose name is based on the current buffer's name
+(@code{2C-two-columns}). If the right-hand buffer doesn't already
+exist, it starts out empty; the current buffer's contents are not
+changed.
+
+This command is appropriate when the current buffer is empty or contains
+just one column and you want to add another column.
+
+@item @kbd{@key{F2} s} or @kbd{C-x 6 s}
+@kindex F2 s
+@kindex C-x 6 s
+@findex 2C-split
+Split the current buffer, which contains two-column text, into two
+buffers, and display them side by side (@code{2C-split}). The current
+buffer becomes the left-hand buffer, but the text in the right-hand
+column is moved into the right-hand buffer. The current column
+specifies the split point. Splitting starts with the current line and
+continues to the end of the buffer.
+
+This command is appropriate when you have a buffer that already contains
+two-column text, and you wish to separate the columns temporarily.
+
+@item @kbd{@key{F2} b @var{buffer} @key{RET}}
+@itemx @kbd{C-x 6 b @var{buffer} @key{RET}}
+@kindex F2 b
+@kindex C-x 6 b
+@findex 2C-associate-buffer
+Enter two-column mode using the current buffer as the left-hand buffer,
+and using buffer @var{buffer} as the right-hand buffer
+(@code{2C-associate-buffer}).
+@end table
+
+ @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which
+is a string that appears on each line between the two columns. You can
+specify the width of the separator with a numeric argument to
+@kbd{@key{F2} s}; that many characters, before point, constitute the
+separator string. By default, the width is 1, so the column separator
+is the character before point.
+
+ When a line has the separator at the proper place, @kbd{@key{F2} s}
+puts the text after the separator into the right-hand buffer, and
+deletes the separator. Lines that don't have the column separator at
+the proper place remain unsplit; they stay in the left-hand buffer, and
+the right-hand buffer gets an empty line to correspond. (This is the
+way to write a line that ``spans both columns while in two-column
+mode'': write it in the left-hand buffer, and put an empty line in the
+right-hand buffer.)
+
+@kindex F2 RET
+@kindex C-x 6 RET
+@findex 2C-newline
+ The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}}
+(@code{2C-newline}) inserts a newline in each of the two buffers at
+corresponding positions. This is the easiest way to add a new line to
+the two-column text while editing it in split buffers.
+
+@kindex F2 1
+@kindex C-x 6 1
+@findex 2C-merge
+ When you have edited both buffers as you wish, merge them with
+@kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the
+text from the right-hand buffer as a second column in the other buffer.
+To go back to two-column editing, use @kbd{@key{F2} s}.
+
+@kindex F2 d
+@kindex C-x 6 d
+@findex 2C-dissociate
+ Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers,
+leaving each as it stands (@code{2C-dissociate}). If the other buffer,
+the one not current when you type @kbd{@key{F2} d}, is empty,
+@kbd{@key{F2} d} kills it.
+
+@node Editing Binary Files, Saving Emacs Sessions, Two-Column, Top
+@section Editing Binary Files
+
+@cindex Hexl mode
+@cindex mode, Hexl
+@cindex editing binary files
+ There is a special major mode for editing binary files: Hexl mode. To
+use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit
+the file. This command converts the file's contents to hexadecimal and
+lets you edit the translation. When you save the file, it is converted
+automatically back to binary.
+
+ You can also use @kbd{M-x hexl-mode} to translate an existing buffer
+into hex. This is useful if you visit a file normally and then discover
+it is a binary file.
+
+ Ordinary text characters overwrite in Hexl mode. This is to reduce
+the risk of accidentally spoiling the alignment of data in the file.
+There are special commands for insertion. Here is a list of the
+commands of Hexl mode:
+
+@c I don't think individual index entries for these commands are useful--RMS.
+@table @kbd
+@item C-M-d
+Insert a byte with a code typed in decimal.
+
+@item C-M-o
+Insert a byte with a code typed in octal.
+
+@item C-M-x
+Insert a byte with a code typed in hex.
+
+@item C-x [
+Move to the beginning of a 1k-byte ``page.''
+
+@item C-x ]
+Move to the end of a 1k-byte ``page.''
+
+@item M-g
+Move to an address specified in hex.
+
+@item M-j
+Move to an address specified in decimal.
+
+@item C-c C-c
+Leave Hexl mode, going back to the major mode this buffer had before you
+invoked @code{hexl-mode}.
+@end table
+
+@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top
+@section Saving Emacs Sessions
+@cindex saving sessions
+@cindex desktop
+
+ You can use the Desktop library to save the state of Emacs from one
+session to another. Saving the state means that Emacs starts up with
+the same set of buffers, major modes, buffer positions, and so on that
+the previous Emacs session had.
+
+@vindex desktop-enable
+ To use Desktop, you should use the Customization buffer (@pxref{Easy
+Customization}) to set @code{desktop-enable} to a non-@code{nil} value,
+or add these lines at the end of your @file{.emacs} file:
+
+@example
+(desktop-load-default)
+(desktop-read)
+@end example
+
+@noindent
+@findex desktop-save
+The first time you save the state of the Emacs session, you must do it
+manually, with the command @kbd{M-x desktop-save}. Once you have done
+that, exiting Emacs will save the state again---not only the present
+Emacs session, but also subsequent sessions. You can also save the
+state at any time, without exiting Emacs, by typing @kbd{M-x
+desktop-save} again.
+
+ In order for Emacs to recover the state from a previous session, you
+must start it with the same current directory as you used when you
+started the previous session. This is because @code{desktop-read} looks
+in the current directory for the file to read. This means that you can
+have separate saved sessions in different directories; the directory in
+which you start Emacs will control which saved session to use.
+
+@vindex desktop-files-not-to-save
+ The variable @code{desktop-files-not-to-save} controls which files are
+excluded from state saving. Its value is a regular expression that
+matches the files to exclude. By default, remote (ftp-accessed) files
+are excluded; this is because visiting them again in the subsequent
+session would be slow. If you want to include these files in state
+saving, set @code{desktop-files-not-to-save} to @code{"^$"}.
+@xref{Remote Files}.
+
+@node Recursive Edit, Emulation, Saving Emacs Sessions, Top
+@section Recursive Editing Levels
+@cindex recursive editing level
+@cindex editing level, recursive
+
+ A @dfn{recursive edit} is a situation in which you are using Emacs
+commands to perform arbitrary editing while in the middle of another
+Emacs command. For example, when you type @kbd{C-r} inside of a
+@code{query-replace}, you enter a recursive edit in which you can change
+the current buffer. On exiting from the recursive edit, you go back to
+the @code{query-replace}.
+
+@kindex C-M-c
+@findex exit-recursive-edit
+@cindex exiting recursive edit
+ @dfn{Exiting} the recursive edit means returning to the unfinished
+command, which continues execution. The command to exit is @kbd{C-M-c}
+(@code{exit-recursive-edit}).
+
+ You can also @dfn{abort} the recursive edit. This is like exiting,
+but also quits the unfinished command immediately. Use the command
+@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}.
+
+ The mode line shows you when you are in a recursive edit by displaying
+square brackets around the parentheses that always surround the major and
+minor mode names. Every window's mode line shows this, in the same way,
+since being in a recursive edit is true of Emacs as a whole rather than
+any particular window or buffer.
+
+ It is possible to be in recursive edits within recursive edits. For
+example, after typing @kbd{C-r} in a @code{query-replace}, you may type a
+command that enters the debugger. This begins a recursive editing level
+for the debugger, within the recursive editing level for @kbd{C-r}.
+Mode lines display a pair of square brackets for each recursive editing
+level currently in progress.
+
+ Exiting the inner recursive edit (such as, with the debugger @kbd{c}
+command) resumes the command running in the next level up. When that
+command finishes, you can then use @kbd{C-M-c} to exit another recursive
+editing level, and so on. Exiting applies to the innermost level only.
+Aborting also gets out of only one level of recursive edit; it returns
+immediately to the command level of the previous recursive edit. If you
+wish, you can then abort the next recursive editing level.
+
+ Alternatively, the command @kbd{M-x top-level} aborts all levels of
+recursive edits, returning immediately to the top-level command reader.
+
+ The text being edited inside the recursive edit need not be the same text
+that you were editing at top level. It depends on what the recursive edit
+is for. If the command that invokes the recursive edit selects a different
+buffer first, that is the buffer you will edit recursively. In any case,
+you can switch buffers within the recursive edit in the normal manner (as
+long as the buffer-switching keys have not been rebound). You could
+probably do all the rest of your editing inside the recursive edit,
+visiting files and all. But this could have surprising effects (such as
+stack overflow) from time to time. So remember to exit or abort the
+recursive edit when you no longer need it.
+
+ In general, we try to minimize the use of recursive editing levels in
+GNU Emacs. This is because they constrain you to ``go back'' in a
+particular order---from the innermost level toward the top level. When
+possible, we present different activities in separate buffers so that
+you can switch between them as you please. Some commands switch to a
+new major mode which provides a command to switch back. These
+approaches give you more flexibility to go back to unfinished tasks in
+the order you choose.
+
+@node Emulation, Dissociated Press, Recursive Edit, Top
+@section Emulation
+@cindex emulating other editors
+@cindex other editors
+@cindex EDT
+@cindex vi
+
+ GNU Emacs can be programmed to emulate (more or less) most other
+editors. Standard facilities can emulate these:
+
+@table @asis
+@item EDT (DEC VMS editor)
+@findex edt-emulation-on
+@findex edt-emulation-off
+Turn on EDT emulation with @kbd{M-x edt-emulation-on}. @kbd{M-x
+edt-emulation-off} restores normal Emacs command bindings.
+
+Most of the EDT emulation commands are keypad keys, and most standard
+Emacs key bindings are still available. The EDT emulation rebindings
+are done in the global keymap, so there is no problem switching
+buffers or major modes while in EDT emulation.
+
+@item vi (Berkeley editor)
+@findex viper-mode
+Viper is the newest emulator for vi. It implements several levels of
+emulation; level 1 is closest to vi itself, while level 5 departs
+somewhat from strict emulation to take advantage of the capabilities of
+Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you
+the rest of the way and ask for the emulation level. @inforef{Top,
+Viper, viper}.
+
+@item vi (another emulator)
+@findex vi-mode
+@kbd{M-x vi-mode} enters a major mode that replaces the previously
+established major mode. All of the vi commands that, in real vi, enter
+``input'' mode are programmed instead to return to the previous major
+mode. Thus, ordinary Emacs serves as vi's ``input'' mode.
+
+Because vi emulation works through major modes, it does not work
+to switch buffers during emulation. Return to normal Emacs first.
+
+If you plan to use vi emulation much, you probably want to bind a key
+to the @code{vi-mode} command.
+
+@item vi (alternate emulator)
+@findex vip-mode
+@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi
+more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator
+is changed from ordinary Emacs so you can use @key{ESC} to go back to
+emulated vi command mode. To get from emulated vi command mode back to
+ordinary Emacs, type @kbd{C-z}.
+
+This emulation does not work through major modes, and it is possible
+to switch buffers in various ways within the emulator. It is not
+so necessary to assign a key to the command @code{vip-mode} as
+it is with @code{vi-mode} because terminating insert mode does
+not use it.
+
+@inforef{Top, VIP, vip}, for full information.
+@end table
+
+@node Dissociated Press, Amusements, Emulation, Top
+@section Dissociated Press
+
+@findex dissociated-press
+ @kbd{M-x dissociated-press} is a command for scrambling a file of text
+either word by word or character by character. Starting from a buffer of
+straight English, it produces extremely amusing output. The input comes
+from the current Emacs buffer. Dissociated Press writes its output in a
+buffer named @samp{*Dissociation*}, and redisplays that buffer after every
+couple of lines (approximately) so you can read the output as it comes out.
+
+ Dissociated Press asks every so often whether to continue generating
+output. Answer @kbd{n} to stop it. You can also stop at any time by
+typing @kbd{C-g}. The dissociation output remains in the
+@samp{*Dissociation*} buffer for you to copy elsewhere if you wish.
+
+@cindex presidentagon
+ Dissociated Press operates by jumping at random from one point in the
+buffer to another. In order to produce plausible output rather than
+gibberish, it insists on a certain amount of overlap between the end of
+one run of consecutive words or characters and the start of the next.
+That is, if it has just printed out `president' and then decides to jump
+to a different point in the file, it might spot the `ent' in `pentagon'
+and continue from there, producing `presidentagon'.@footnote{This
+dissociword actually appeared during the Vietnam War, when it was very
+appropriate.} Long sample texts produce the best results.
+
+@cindex againformation
+ A positive argument to @kbd{M-x dissociated-press} tells it to operate
+character by character, and specifies the number of overlap characters. A
+negative argument tells it to operate word by word and specifies the number
+of overlap words. In this mode, whole words are treated as the elements to
+be permuted, rather than characters. No argument is equivalent to an
+argument of two. For your againformation, the output goes only into the
+buffer @samp{*Dissociation*}. The buffer you start with is not changed.
+
+@cindex Markov chain
+@cindex ignoriginal
+@cindex techniquitous
+ Dissociated Press produces nearly the same results as a Markov chain
+based on a frequency table constructed from the sample text. It is,
+however, an independent, ignoriginal invention. Dissociated Press
+techniquitously copies several consecutive characters from the sample
+between random choices, whereas a Markov chain would choose randomly for
+each word or character. This makes for more plausible sounding results,
+and runs faster.
+
+@cindex outragedy
+@cindex buggestion
+@cindex properbose
+@cindex mustatement
+@cindex developediment
+@cindex userenced
+ It is a mustatement that too much use of Dissociated Press can be a
+developediment to your real work. Sometimes to the point of outragedy.
+And keep dissociwords out of your documentation, if you want it to be well
+userenced and properbose. Have fun. Your buggestions are welcome.
+
+@node Amusements, Customization, Dissociated Press, Top
+@section Other Amusements
+@cindex boredom
+@findex hanoi
+@findex yow
+@findex gomoku
+@findex mpuz
+@cindex tower of Hanoi
+
+ If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are
+considerably bored, give it a numeric argument. If you are very very
+bored, try an argument of 9. Sit back and watch.
+
+@cindex Go Moku
+ If you want a little more personal involvement, try @kbd{M-x gomoku},
+which plays the game Go Moku with you.
+
+@findex blackbox
+@findex mpuz
+@cindex puzzles
+ @kbd{M-x blackbox} and @kbd{M-x mpuz} are two kinds of puzzles.
+@code{blackbox} challenges you to determine the location of objects
+inside a box by tomography. @code{mpuz} displays a multiplication
+puzzle with letters standing for digits in a code that you must
+guess---to guess a value, type a letter and then the digit you think it
+stands for.
+
+@findex dunnet
+ @kbd{M-x dunnet} runs an adventure-style exploration game, which is
+a bigger sort of puzzle.
+
+ When you are frustrated, try the famous Eliza program. Just do
+@kbd{M-x doctor}. End each input by typing @key{RET} twice.
+
+@cindex Zippy
+ When you are feeling strange, type @kbd{M-x yow}.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1997, 1999 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node International, Major Modes, Frames, Top
+@chapter International Character Set Support
+@cindex MULE
+@cindex international scripts
+@cindex multibyte characters
+@cindex encoding of characters
+
+@cindex Chinese
+@cindex Devanagari
+@cindex Hindi
+@cindex Marathi
+@cindex Ethiopian
+@cindex Greek
+@cindex IPA
+@cindex Japanese
+@cindex Korean
+@cindex Lao
+@cindex Russian
+@cindex Thai
+@cindex Tibetan
+@cindex Vietnamese
+ Emacs supports a wide variety of international character sets,
+including European variants of the Latin alphabet, as well as Chinese,
+Devanagari (Hindi and Marathi), Ethiopian, Greek, IPA, Japanese, Korean,
+Lao, Russian, Thai, Tibetan, and Vietnamese scripts. These features
+have been merged from the modified version of Emacs known as MULE (for
+``MULti-lingual Enhancement to GNU Emacs'')
+
+@menu
+* International Intro:: Basic concepts of multibyte characters.
+* Enabling Multibyte:: Controlling whether to use multibyte characters.
+* Language Environments:: Setting things up for the language you use.
+* Input Methods:: Entering text characters not on your keyboard.
+* Select Input Method:: Specifying your choice of input methods.
+* Multibyte Conversion:: How single-byte characters convert to multibyte.
+* Coding Systems:: Character set conversion when you read and
+ write files, and so on.
+* Recognize Coding:: How Emacs figures out which conversion to use.
+* Specify Coding:: Various ways to choose which conversion to use.
+* Fontsets:: Fontsets are collections of fonts
+ that cover the whole spectrum of characters.
+* Defining Fontsets:: Defining a new fontset.
+* Single-Byte European Support::
+ You can pick one European character set
+ to use without multibyte characters.
+@end menu
+
+@node International Intro
+@section Introduction to International Character Sets
+
+ The users of these scripts have established many more-or-less standard
+coding systems for storing files. Emacs internally uses a single
+multibyte character encoding, so that it can intermix characters from
+all these scripts in a single buffer or string. This encoding
+represents each non-ASCII character as a sequence of bytes in the range
+0200 through 0377. Emacs translates between the multibyte character
+encoding and various other coding systems when reading and writing
+files, when exchanging data with subprocesses, and (in some cases) in
+the @kbd{C-q} command (@pxref{Multibyte Conversion}).
+
+@kindex C-h h
+@findex view-hello-file
+ The command @kbd{C-h h} (@code{view-hello-file}) displays the file
+@file{etc/HELLO}, which shows how to say ``hello'' in many languages.
+This illustrates various scripts.
+
+ Keyboards, even in the countries where these character sets are used,
+generally don't have keys for all the characters in them. So Emacs
+supports various @dfn{input methods}, typically one for each script or
+language, to make it convenient to type them.
+
+@kindex C-x RET
+ The prefix key @kbd{C-x @key{RET}} is used for commands that pertain
+to multibyte characters, coding systems, and input methods.
+
+@node Enabling Multibyte
+@section Enabling Multibyte Characters
+
+ You can enable or disable multibyte character support, either for
+Emacs as a whole, or for a single buffer. When multibyte characters are
+disabled in a buffer, then each byte in that buffer represents a
+character, even codes 0200 through 0377. The old features for
+supporting the European character sets, ISO Latin-1 and ISO Latin-2,
+work as they did in Emacs 19 and also work for the other ISO 8859
+character sets.
+
+ However, there is no need to turn off multibyte character support to
+use ISO Latin; the Emacs multibyte character set includes all the
+characters in these character sets, and Emacs can translate
+automatically to and from the ISO codes.
+
+ To edit a particular file in unibyte representation, visit it using
+@code{find-file-literally}. @xref{Visiting}. To convert a buffer in
+multibyte representation into a single-byte representation of the same
+characters, the easiest way is to save the contents in a file, kill the
+buffer, and find the file again with @code{find-file-literally}. You
+can also use @kbd{C-x @key{RET} c}
+(@code{universal-coding-system-argument}) and specify @samp{raw-text} as
+the coding system with which to find or save a file. @xref{Specify
+Coding}. Finding a file as @samp{raw-text} doesn't disable format
+conversion, uncompression and auto mode selection as
+@code{find-file-literally} does.
+
+@vindex enable-multibyte-characters
+@vindex default-enable-multibyte-characters
+ To turn off multibyte character support by default, start Emacs with
+the @samp{--unibyte} option (@pxref{Initial Options}), or set the
+environment variable @samp{EMACS_UNIBYTE}. You can also customize
+@code{enable-multibyte-characters} or, equivalently, directly set the
+variable @code{default-enable-multibyte-characters} in your init file to
+have basically the same effect as @samp{--unibyte}.
+
+ Multibyte strings are not created during initialization from the
+values of environment variables, @file{/etc/passwd} entries etc.@: that
+contain non-ASCII 8-bit characters. However, the initialization file is
+normally read as multibyte---like Lisp files in general---even with
+@samp{--unibyte}. To avoid multibyte strings being generated by
+non-ASCII characters in it, put @samp{-*-unibyte: t;-*-} in a comment on
+the first line. Do the same for initialization files for packages like
+Gnus.
+
+ The mode line indicates whether multibyte character support is enabled
+in the current buffer. If it is, there are two or more characters (most
+often two dashes) before the colon near the beginning of the mode line.
+When multibyte characters are not enabled, just one dash precedes the
+colon.
+
+@node Language Environments
+@section Language Environments
+@cindex language environments
+
+ All supported character sets are supported in Emacs buffers whenever
+multibyte characters are enabled; there is no need to select a
+particular language in order to display its characters in an Emacs
+buffer. However, it is important to select a @dfn{language environment}
+in order to set various defaults. The language environment really
+represents a choice of preferred script (more or less) rather than a
+choice of language.
+
+ The language environment controls which coding systems to recognize
+when reading text (@pxref{Recognize Coding}). This applies to files,
+incoming mail, netnews, and any other text you read into Emacs. It may
+also specify the default coding system to use when you create a file.
+Each language environment also specifies a default input method.
+
+@findex set-language-environment
+ The way to select a language environment is with the command @kbd{M-x
+set-language-environment}. It makes no difference which buffer is
+current when you use this command, because the effects apply globally to
+the Emacs session. The supported language environments include:
+
+@quotation
+Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-Alternativnyj,
+Cyrillic-ISO, Cyrillic-KOI8, Devanagari, English, Ethiopic, Greek,
+Hebrew, Japanese, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4,
+Latin-5, Thai, Tibetan, and Vietnamese.
+@end quotation
+
+ Some operating systems let you specify the language you are using by
+setting locale environment variables. Emacs handles one common special
+case of this: if your locale name for character types contains the
+string @samp{8859-@var{n}}, Emacs automatically selects the
+corresponding language environment.
+
+@kindex C-h L
+@findex describe-language-environment
+ To display information about the effects of a certain language
+environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
+@key{RET}} (@code{describe-language-environment}). This tells you which
+languages this language environment is useful for, and lists the
+character sets, coding systems, and input methods that go with it. It
+also shows some sample text to illustrate scripts used in this language
+environment. By default, this command describes the chosen language
+environment.
+
+@vindex set-language-environment-hook
+ You can customize any language environment with the normal hook
+@code{set-language-environment-hook}. The command
+@code{set-language-environment} runs that hook after setting up the new
+language environment. The hook functions can test for a specific
+language environment by checking the variable
+@code{current-language-environment}.
+
+@vindex exit-language-environment-hook
+ Before it starts to set up the new language environment,
+@code{set-language-environment} first runs the hook
+@code{exit-language-environment-hook}. This hook is useful for undoing
+customizations that were made with @code{set-language-environment-hook}.
+For instance, if you set up a special key binding in a specific language
+environment using @code{set-language-environment-hook}, you should set
+up @code{exit-language-environment-hook} to restore the normal binding
+for that key.
+
+@node Input Methods
+@section Input Methods
+
+@cindex input methods
+ An @dfn{input method} is a kind of character conversion designed
+specifically for interactive input. In Emacs, typically each language
+has its own input method; sometimes several languages which use the same
+characters can share one input method. A few languages support several
+input methods.
+
+ The simplest kind of input method works by mapping ASCII letters into
+another alphabet. This is how the Greek and Russian input methods work.
+
+ A more powerful technique is composition: converting sequences of
+characters into one letter. Many European input methods use composition
+to produce a single non-ASCII letter from a sequence that consists of a
+letter followed by accent characters (or vice versa). For example, some
+methods convert the sequence @kbd{a'} into a single accented letter.
+These input methods have no special commands of their own; all they do
+is compose sequences of printing characters.
+
+ The input methods for syllabic scripts typically use mapping followed
+by composition. The input methods for Thai and Korean work this way.
+First, letters are mapped into symbols for particular sounds or tone
+marks; then, sequences of these which make up a whole syllable are
+mapped into one syllable sign.
+
+ Chinese and Japanese require more complex methods. In Chinese input
+methods, first you enter the phonetic spelling of a Chinese word (in
+input method @code{chinese-py}, among others), or a sequence of portions
+of the character (input methods @code{chinese-4corner} and
+@code{chinese-sw}, and others). Since one phonetic spelling typically
+corresponds to many different Chinese characters, you must select one of
+the alternatives using special Emacs commands. Keys such as @kbd{C-f},
+@kbd{C-b}, @kbd{C-n}, @kbd{C-p}, and digits have special definitions in
+this situation, used for selecting among the alternatives. @key{TAB}
+displays a buffer showing all the possibilities.
+
+ In Japanese input methods, first you input a whole word using
+phonetic spelling; then, after the word is in the buffer, Emacs converts
+it into one or more characters using a large dictionary. One phonetic
+spelling corresponds to many differently written Japanese words, so you
+must select one of them; use @kbd{C-n} and @kbd{C-p} to cycle through
+the alternatives.
+
+ Sometimes it is useful to cut off input method processing so that the
+characters you have just entered will not combine with subsequent
+characters. For example, in input method @code{latin-1-postfix}, the
+sequence @kbd{e '} combines to form an @samp{e} with an accent. What if
+you want to enter them as separate characters?
+
+ One way is to type the accent twice; that is a special feature for
+entering the separate letter and accent. For example, @kbd{e ' '} gives
+you the two characters @samp{e'}. Another way is to type another letter
+after the @kbd{e}---something that won't combine with that---and
+immediately delete it. For example, you could type @kbd{e e @key{DEL}
+'} to get separate @samp{e} and @samp{'}.
+
+ Another method, more general but not quite as easy to type, is to use
+@kbd{C-\ C-\} between two characters to stop them from combining. This
+is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
+@ifinfo
+@xref{Select Input Method}.
+@end ifinfo
+
+ @kbd{C-\ C-\} is especially useful inside an incremental search,
+because it stops waiting for more characters to combine, and starts
+searching for what you have already entered.
+
+@vindex input-method-verbose-flag
+@vindex input-method-highlight-flag
+ The variables @code{input-method-highlight-flag} and
+@code{input-method-verbose-flag} control how input methods explain what
+is happening. If @code{input-method-highlight-flag} is non-@code{nil},
+the partial sequence is highlighted in the buffer. If
+@code{input-method-verbose-flag} is non-@code{nil}, the list of possible
+characters to type next is displayed in the echo area (but not when you
+are in the minibuffer).
+
+@node Select Input Method
+@section Selecting an Input Method
+
+@table @kbd
+@item C-\
+Enable or disable use of the selected input method.
+
+@item C-x @key{RET} C-\ @var{method} @key{RET}
+Select a new input method for the current buffer.
+
+@item C-h I @var{method} @key{RET}
+@itemx C-h C-\ @var{method} @key{RET}
+@findex describe-input-method
+@kindex C-h I
+@kindex C-h C-\
+Describe the input method @var{method} (@code{describe-input-method}).
+By default, it describes the current input method (if any).
+This description should give you the full details of how to
+use any particular input method.
+
+@item M-x list-input-methods
+Display a list of all the supported input methods.
+@end table
+
+@findex set-input-method
+@vindex current-input-method
+@kindex C-x RET C-\
+ To choose an input method for the current buffer, use @kbd{C-x
+@key{RET} C-\} (@code{set-input-method}). This command reads the
+input method name with the minibuffer; the name normally starts with the
+language environment that it is meant to be used with. The variable
+@code{current-input-method} records which input method is selected.
+
+@findex toggle-input-method
+@kindex C-\
+ Input methods use various sequences of ASCII characters to stand for
+non-ASCII characters. Sometimes it is useful to turn off the input
+method temporarily. To do this, type @kbd{C-\}
+(@code{toggle-input-method}). To reenable the input method, type
+@kbd{C-\} again.
+
+ If you type @kbd{C-\} and you have not yet selected an input method,
+it prompts for you to specify one. This has the same effect as using
+@kbd{C-x @key{RET} C-\} to specify an input method.
+
+@vindex default-input-method
+ Selecting a language environment specifies a default input method for
+use in various buffers. When you have a default input method, you can
+select it in the current buffer by typing @kbd{C-\}. The variable
+@code{default-input-method} specifies the default input method
+(@code{nil} means there is none).
+
+@findex quail-set-keyboard-layout
+ Some input methods for alphabetic scripts work by (in effect)
+remapping the keyboard to emulate various keyboard layouts commonly used
+for those scripts. How to do this remapping properly depends on your
+actual keyboard layout. To specify which layout your keyboard has, use
+the command @kbd{M-x quail-set-keyboard-layout}.
+
+@findex list-input-methods
+ To display a list of all the supported input methods, type @kbd{M-x
+list-input-methods}. The list gives information about each input
+method, including the string that stands for it in the mode line.
+
+@node Multibyte Conversion
+@section Unibyte and Multibyte Non-ASCII characters
+
+ When multibyte characters are enabled, character codes 0240 (octal)
+through 0377 (octal) are not really legitimate in the buffer. The valid
+non-ASCII printing characters have codes that start from 0400.
+
+ If you type a self-inserting character in the invalid range 0240
+through 0377, Emacs assumes you intended to use one of the ISO
+Latin-@var{n} character sets, and converts it to the Emacs code
+representing that Latin-@var{n} character. You select @emph{which} ISO
+Latin character set to use through your choice of language environment
+@iftex
+(see above).
+@end iftex
+@ifinfo
+(@pxref{Language Environments}).
+@end ifinfo
+If you do not specify a choice, the default is Latin-1.
+
+ The same thing happens when you use @kbd{C-q} to enter an octal code
+in this range.
+
+@node Coding Systems
+@section Coding Systems
+@cindex coding systems
+
+ Users of various languages have established many more-or-less standard
+coding systems for representing them. Emacs does not use these coding
+systems internally; instead, it converts from various coding systems to
+its own system when reading data, and converts the internal coding
+system to other coding systems when writing data. Conversion is
+possible in reading or writing files, in sending or receiving from the
+terminal, and in exchanging data with subprocesses.
+
+ Emacs assigns a name to each coding system. Most coding systems are
+used for one language, and the name of the coding system starts with the
+language name. Some coding systems are used for several languages;
+their names usually start with @samp{iso}. There are also special
+coding systems @code{no-conversion}, @code{raw-text} and
+@code{emacs-mule} which do not convert printing characters at all.
+
+@cindex end-of-line conversion
+ In addition to converting various representations of non-ASCII
+characters, a coding system can perform end-of-line conversion. Emacs
+handles three different conventions for how to separate lines in a file:
+newline, carriage-return linefeed, and just carriage-return.
+
+@table @kbd
+@item C-h C @var{coding} @key{RET}
+Describe coding system @var{coding}.
+
+@item C-h C @key{RET}
+Describe the coding systems currently in use.
+
+@item M-x list-coding-systems
+Display a list of all the supported coding systems.
+@end table
+
+@kindex C-h C
+@findex describe-coding-system
+ The command @kbd{C-h C} (@code{describe-coding-system}) displays
+information about particular coding systems. You can specify a coding
+system name as argument; alternatively, with an empty argument, it
+describes the coding systems currently selected for various purposes,
+both in the current buffer and as the defaults, and the priority list
+for recognizing coding systems (@pxref{Recognize Coding}).
+
+@findex list-coding-systems
+ To display a list of all the supported coding systems, type @kbd{M-x
+list-coding-systems}. The list gives information about each coding
+system, including the letter that stands for it in the mode line
+(@pxref{Mode Line}).
+
+@cindex end-of-line conversion
+@cindex MS-DOS end-of-line conversion
+@cindex Macintosh end-of-line conversion
+ Each of the coding systems that appear in this list---except for
+@code{no-conversion}, which means no conversion of any kind---specifies
+how and whether to convert printing characters, but leaves the choice of
+end-of-line conversion to be decided based on the contents of each file.
+For example, if the file appears to use the sequence carriage-return
+linefeed to separate lines, DOS end-of-line conversion will be used.
+
+ Each of the listed coding systems has three variants which specify
+exactly what to do for end-of-line conversion:
+
+@table @code
+@item @dots{}-unix
+Don't do any end-of-line conversion; assume the file uses
+newline to separate lines. (This is the convention normally used
+on Unix and GNU systems.)
+
+@item @dots{}-dos
+Assume the file uses carriage-return linefeed to separate lines, and do
+the appropriate conversion. (This is the convention normally used on
+Microsoft systems.@footnote{It is also specified for MIME `text/*'
+bodies and in other network transport contexts. It is different
+from the SGML reference syntax record-start/record-end format which
+Emacs doesn't support directly.})
+
+@item @dots{}-mac
+Assume the file uses carriage-return to separate lines, and do the
+appropriate conversion. (This is the convention normally used on the
+Macintosh system.)
+@end table
+
+ These variant coding systems are omitted from the
+@code{list-coding-systems} display for brevity, since they are entirely
+predictable. For example, the coding system @code{iso-latin-1} has
+variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and
+@code{iso-latin-1-mac}.
+
+ The coding system @code{raw-text} is good for a file which is mainly
+ASCII text, but may contain byte values above 127 which are not meant to
+encode non-ASCII characters. With @code{raw-text}, Emacs copies those
+byte values unchanged, and sets @code{enable-multibyte-characters} to
+@code{nil} in the current buffer so that they will be interpreted
+properly. @code{raw-text} handles end-of-line conversion in the usual
+way, based on the data encountered, and has the usual three variants to
+specify the kind of end-of-line conversion to use.
+
+ In contrast, the coding system @code{no-conversion} specifies no
+character code conversion at all---none for non-ASCII byte values and
+none for end of line. This is useful for reading or writing binary
+files, tar files, and other files that must be examined verbatim. It,
+too, sets @code{enable-multibyte-characters} to @code{nil}.
+
+ The easiest way to edit a file with no conversion of any kind is with
+the @kbd{M-x find-file-literally} command. This uses
+@code{no-conversion}, and also suppresses other Emacs features that
+might convert the file contents before you see them. @xref{Visiting}.
+
+ The coding system @code{emacs-mule} means that the file contains
+non-ASCII characters stored with the internal Emacs encoding. It
+handles end-of-line conversion based on the data encountered, and has
+the usual three variants to specify the kind of end-of-line conversion.
+
+@node Recognize Coding
+@section Recognizing Coding Systems
+
+ Most of the time, Emacs can recognize which coding system to use for
+any given file---once you have specified your preferences.
+
+ Some coding systems can be recognized or distinguished by which byte
+sequences appear in the data. However, there are coding systems that
+cannot be distinguished, not even potentially. For example, there is no
+way to distinguish between Latin-1 and Latin-2; they use the same byte
+values with different meanings.
+
+ Emacs handles this situation by means of a priority list of coding
+systems. Whenever Emacs reads a file, if you do not specify the coding
+system to use, Emacs checks the data against each coding system,
+starting with the first in priority and working down the list, until it
+finds a coding system that fits the data. Then it converts the file
+contents assuming that they are represented in this coding system.
+
+ The priority list of coding systems depends on the selected language
+environment (@pxref{Language Environments}). For example, if you use
+French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use
+Czech, you probably want Latin-2 to be preferred. This is one of the
+reasons to specify a language environment.
+
+@findex prefer-coding-system
+ However, you can alter the priority list in detail with the command
+@kbd{M-x prefer-coding-system}. This command reads the name of a coding
+system from the minibuffer, and adds it to the front of the priority
+list, so that it is preferred to all others. If you use this command
+several times, each use adds one element to the front of the priority
+list.
+
+ If you use a coding system that specifies the end-of-line conversion
+type, such as @code{iso-8859-1-dos}, what that means is that Emacs
+should attempt to recognize @code{iso-8859-1} with priority, and should
+use DOS end-of-line conversion in case it recognizes @code{iso-8859-1}.
+
+@vindex file-coding-system-alist
+ Sometimes a file name indicates which coding system to use for the
+file. The variable @code{file-coding-system-alist} specifies this
+correspondence. There is a special function
+@code{modify-coding-system-alist} for adding elements to this list. For
+example, to read and write all @samp{.txt} files using the coding system
+@code{china-iso-8bit}, you can execute this Lisp expression:
+
+@smallexample
+(modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)
+@end smallexample
+
+@noindent
+The first argument should be @code{file}, the second argument should be
+a regular expression that determines which files this applies to, and
+the third argument says which coding system to use for these files.
+
+@vindex inhibit-eol-conversion
+ Emacs recognizes which kind of end-of-line conversion to use based on
+the contents of the file: if it sees only carriage-returns, or only
+carriage-return linefeed sequences, then it chooses the end-of-line
+conversion accordingly. You can inhibit the automatic use of
+end-of-line conversion by setting the variable @code{inhibit-eol-conversion}
+to non-@code{nil}.
+
+@vindex coding
+ You can specify the coding system for a particular file using the
+@samp{-*-@dots{}-*-} construct at the beginning of a file, or a local
+variables list at the end (@pxref{File Variables}). You do this by
+defining a value for the ``variable'' named @code{coding}. Emacs does
+not really have a variable @code{coding}; instead of setting a variable,
+it uses the specified coding system for the file. For example,
+@samp{-*-mode: C; coding: latin-1;-*-} specifies use of the Latin-1
+coding system, as well as C mode. If you specify the coding explicitly
+in the file, that overrides @code{file-coding-system-alist}.
+
+@vindex auto-coding-alist
+ The variable @code{auto-coding-alist} is the strongest way to specify
+the coding system for certain patterns of file names; this variable even
+overrides @samp{-*-coding:-*-} tags in the file itself. Emacs uses this
+feature for tar and archive files, to prevent Emacs from being confused
+by a @samp{-*-coding:-*-} tag in a member of the archive and thinking it
+applies to the archive file as a whole.
+
+@vindex buffer-file-coding-system
+ Once Emacs has chosen a coding system for a buffer, it stores that
+coding system in @code{buffer-file-coding-system} and uses that coding
+system, by default, for operations that write from this buffer into a
+file. This includes the commands @code{save-buffer} and
+@code{write-region}. If you want to write files from this buffer using
+a different coding system, you can specify a different coding system for
+the buffer using @code{set-buffer-file-coding-system} (@pxref{Specify
+Coding}).
+
+@vindex sendmail-coding-system
+ When you send a message with Mail mode (@pxref{Sending Mail}), Emacs has
+four different ways to determine the coding system to use for encoding
+the message text. It tries the buffer's own value of
+@code{buffer-file-coding-system}, if that is non-@code{nil}. Otherwise,
+it uses the value of @code{sendmail-coding-system}, if that is
+non-@code{nil}. The third way is to use the default coding system for
+new files, which is controlled by your choice of language environment,
+if that is non-@code{nil}. If all of these three values are @code{nil},
+Emacs encodes outgoing mail using the Latin-1 coding system.
+
+@vindex rmail-decode-mime-charset
+ When you get new mail in Rmail, each message is translated
+automatically from the coding system it is written in---as if it were a
+separate file. This uses the priority list of coding systems that you
+have specified. If a MIME message specifies a character set, Rmail
+obeys that specification, unless @code{rmail-decode-mime-charset} is
+@code{nil}.
+
+@vindex rmail-file-coding-system
+ For reading and saving Rmail files themselves, Emacs uses the coding
+system specified by the variable @code{rmail-file-coding-system}. The
+default value is @code{nil}, which means that Rmail files are not
+translated (they are read and written in the Emacs internal character
+code).
+
+@node Specify Coding
+@section Specifying a Coding System
+
+ In cases where Emacs does not automatically choose the right coding
+system, you can use these commands to specify one:
+
+@table @kbd
+@item C-x @key{RET} f @var{coding} @key{RET}
+Use coding system @var{coding} for the visited file
+in the current buffer.
+
+@item C-x @key{RET} c @var{coding} @key{RET}
+Specify coding system @var{coding} for the immediately following
+command.
+
+@item C-x @key{RET} k @var{coding} @key{RET}
+Use coding system @var{coding} for keyboard input.
+
+@item C-x @key{RET} t @var{coding} @key{RET}
+Use coding system @var{coding} for terminal output.
+
+@item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
+Use coding systems @var{input-coding} and @var{output-coding} for
+subprocess input and output in the current buffer.
+
+@item C-x @key{RET} x @var{coding} @key{RET}
+Use coding system @var{coding} for transferring selections to and from
+other programs through the window system.
+
+@item C-x @key{RET} X @var{coding} @key{RET}
+Use coding system @var{coding} for transferring @emph{one}
+selection---the next one---to or from the window system.
+@end table
+
+@kindex C-x RET f
+@findex set-buffer-file-coding-system
+ The command @kbd{C-x @key{RET} f} (@code{set-buffer-file-coding-system})
+specifies the file coding system for the current buffer---in other
+words, which coding system to use when saving or rereading the visited
+file. You specify which coding system using the minibuffer. Since this
+command applies to a file you have already visited, it affects only the
+way the file is saved.
+
+@kindex C-x RET c
+@findex universal-coding-system-argument
+ Another way to specify the coding system for a file is when you visit
+the file. First use the command @kbd{C-x @key{RET} c}
+(@code{universal-coding-system-argument}); this command uses the
+minibuffer to read a coding system name. After you exit the minibuffer,
+the specified coding system is used for @emph{the immediately following
+command}.
+
+ So if the immediately following command is @kbd{C-x C-f}, for example,
+it reads the file using that coding system (and records the coding
+system for when the file is saved). Or if the immediately following
+command is @kbd{C-x C-w}, it writes the file using that coding system.
+Other file commands affected by a specified coding system include
+@kbd{C-x C-i} and @kbd{C-x C-v}, as well as the other-window variants of
+@kbd{C-x C-f}.
+
+ @kbd{C-x @key{RET} c} also affects commands that start subprocesses,
+including @kbd{M-x shell} (@pxref{Shell}).
+
+ However, if the immediately following command does not use the coding
+system, then @kbd{C-x @key{RET} c} ultimately has no effect.
+
+ An easy way to visit a file with no conversion is with the @kbd{M-x
+find-file-literally} command. @xref{Visiting}.
+
+@vindex default-buffer-file-coding-system
+ The variable @code{default-buffer-file-coding-system} specifies the
+choice of coding system to use when you create a new file. It applies
+when you find a new file, and when you create a buffer and then save it
+in a file. Selecting a language environment typically sets this
+variable to a good choice of default coding system for that language
+environment.
+
+@kindex C-x RET t
+@findex set-terminal-coding-system
+ The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
+specifies the coding system for terminal output. If you specify a
+character code for terminal output, all characters output to the
+terminal are translated into that coding system.
+
+ This feature is useful for certain character-only terminals built to
+support specific languages or character sets---for example, European
+terminals that support one of the ISO Latin character sets. You need to
+specify the terminal coding system when using multibyte text, so that
+Emacs knows which characters the terminal can actually handle.
+
+ By default, output to the terminal is not translated at all, unless
+Emacs can deduce the proper coding system from your terminal type.
+
+@kindex C-x RET k
+@findex set-keyboard-coding-system
+ The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system})
+specifies the coding system for keyboard input. Character-code
+translation of keyboard input is useful for terminals with keys that
+send non-ASCII graphic characters---for example, some terminals designed
+for ISO Latin-1 or subsets of it.
+
+ By default, keyboard input is not translated at all.
+
+ There is a similarity between using a coding system translation for
+keyboard input, and using an input method: both define sequences of
+keyboard input that translate into single characters. However, input
+methods are designed to be convenient for interactive use by humans, and
+the sequences that are translated are typically sequences of ASCII
+printing characters. Coding systems typically translate sequences of
+non-graphic characters.
+
+@kindex C-x RET x
+@kindex C-x RET X
+@findex set-selection-coding-system
+@findex set-next-selection-coding-system
+ The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system})
+specifies the coding system for sending selected text to the window
+system, and for receiving the text of selections made in other
+applications. This command applies to all subsequent selections, until
+you override it by using the command again. The command @kbd{C-x
+@key{RET} X} (@code{set-next-selection-coding-system}) specifies the
+coding system for the next selection made in Emacs or read by Emacs.
+
+@kindex C-x RET p
+@findex set-buffer-process-coding-system
+ The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system})
+specifies the coding system for input and output to a subprocess. This
+command applies to the current buffer; normally, each subprocess has its
+own buffer, and thus you can use this command to specify translation to
+and from a particular subprocess by giving the command in the
+corresponding buffer.
+
+ By default, process input and output are not translated at all.
+
+@vindex file-name-coding-system
+ The variable @code{file-name-coding-system} specifies a coding system
+to use for encoding file names. If you set the variable to a coding
+system name (as a Lisp symbol or a string), Emacs encodes file names
+using that coding system for all file operations. This makes it
+possible to use non-ASCII characters in file names---or, at least, those
+non-ASCII characters which the specified coding system can encode.
+
+ If @code{file-name-coding-system} is @code{nil}, Emacs uses a default
+coding system determined by the selected language environment. In the
+default language environment, any non-ASCII characters in file names are
+not encoded specially; they appear in the file system using the internal
+Emacs representation.
+
+ @strong{Warning:} if you change @code{file-name-coding-system} (or the
+language environment) in the middle of an Emacs session, problems can
+result if you have already visited files whose names were encoded using
+the earlier coding system and cannot be encoded (or are encoded
+differently) under the new coding system. If you try to save one of
+these buffers under the visited file name, saving may use the wrong file
+name, or it may get an error. If such a problem happens, use @kbd{C-x
+C-w} to specify a new file name for that buffer.
+
+@node Fontsets
+@section Fontsets
+@cindex fontsets
+
+ A font for X Windows typically defines shapes for one alphabet or
+script. Therefore, displaying the entire range of scripts that Emacs
+supports requires a collection of many fonts. In Emacs, such a
+collection is called a @dfn{fontset}. A fontset is defined by a list of
+fonts, each assigned to handle a range of character codes.
+
+ Each fontset has a name, like a font. The available X fonts are
+defined by the X server; fontsets, however, are defined within Emacs
+itself. Once you have defined a fontset, you can use it within Emacs by
+specifying its name, anywhere that you could use a single font. Of
+course, Emacs fontsets can use only the fonts that the X server
+supports; if certain characters appear on the screen as hollow boxes,
+this means that the fontset in use for them has no font for those
+characters.
+
+ Emacs creates two fontsets automatically: the @dfn{standard fontset}
+and the @dfn{startup fontset}. The standard fontset is most likely to
+have fonts for a wide variety of non-ASCII characters; however, this is
+not the default for Emacs to use. (By default, Emacs tries to find a
+font which has bold and italic variants.) You can specify use of the
+standard fontset with the @samp{-fn} option, or with the @samp{Font} X
+resource (@pxref{Font X}). For example,
+
+@example
+emacs -fn fontset-standard
+@end example
+
+ A fontset does not necessarily specify a font for every character
+code. If a fontset specifies no font for a certain character, or if it
+specifies a font that does not exist on your system, then it cannot
+display that character properly. It will display that character as an
+empty box instead.
+
+@vindex highlight-wrong-size-font
+ The fontset height and width are determined by the ASCII characters
+(that is, by the font used for ASCII characters in that fontset). If
+another font in the fontset has a different height, or a different
+width, then characters assigned to that font are clipped to the
+fontset's size. If @code{highlight-wrong-size-font} is non-@code{nil},
+a box is displayed around these wrong-size characters as well.
+
+@node Defining Fontsets
+@section Defining fontsets
+
+@vindex standard-fontset-spec
+@cindex standard fontset
+ Emacs creates a standard fontset automatically according to the value
+of @code{standard-fontset-spec}. This fontset's name is
+
+@example
+-*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard
+@end example
+
+@noindent
+or just @samp{fontset-standard} for short.
+
+ Bold, italic, and bold-italic variants of the standard fontset are
+created automatically. Their names have @samp{bold} instead of
+@samp{medium}, or @samp{i} instead of @samp{r}, or both.
+
+@cindex startup fontset
+ If you specify a default ASCII font with the @samp{Font} resource or
+the @samp{-fn} argument, Emacs generates a fontset from it
+automatically. This is the @dfn{startup fontset} and its name is
+@code{fontset-startup}. It does this by replacing the @var{foundry},
+@var{family}, @var{add_style}, and @var{average_width} fields of the
+font name with @samp{*}, replacing @var{charset_registry} field with
+@samp{fontset}, and replacing @var{charset_encoding} field with
+@samp{startup}, then using the resulting string to specify a fontset.
+
+ For instance, if you start Emacs this way,
+
+@example
+emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
+@end example
+
+@noindent
+Emacs generates the following fontset and uses it for the initial X
+window frame:
+
+@example
+-*-*-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
+@end example
+
+ With the X resource @samp{Emacs.Font}, you can specify a fontset name
+just like an actual font name. But be careful not to specify a fontset
+name in a wildcard resource like @samp{Emacs*Font}---that wildcard
+specification applies to various other purposes, such as menus, and
+menus cannot handle fontsets.
+
+ You can specify additional fontsets using X resources named
+@samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0.
+The resource value should have this form:
+
+@smallexample
+@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
+@end smallexample
+
+@noindent
+@var{fontpattern} should have the form of a standard X font name, except
+for the last two fields. They should have the form
+@samp{fontset-@var{alias}}.
+
+ The fontset has two names, one long and one short. The long name is
+@var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You
+can refer to the fontset by either name.
+
+ The construct @samp{@var{charset}:@var{font}} specifies which font to
+use (in this fontset) for one particular character set. Here,
+@var{charset} is the name of a character set, and @var{font} is the
+font to use for that character set. You can use this construct any
+number of times in defining one fontset.
+
+ For the other character sets, Emacs chooses a font based on
+@var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values
+that describe the character set. For the ASCII character font,
+@samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}.
+
+ In addition, when several consecutive fields are wildcards, Emacs
+collapses them into a single wildcard. This is to prevent use of
+auto-scaled fonts. Fonts made by scaling larger fonts are not usable
+for editing, and scaling a smaller font is not useful because it is
+better to use the smaller font in its own size, which Emacs does.
+
+ Thus if @var{fontpattern} is this,
+
+@example
+-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
+@end example
+
+@noindent
+the font specification for ASCII characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-ISO8859-1
+@end example
+
+@noindent
+and the font specification for Chinese GB2312 characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-gb2312*-*
+@end example
+
+ You may not have any Chinese font matching the above font
+specification. Most X distributions include only Chinese fonts that
+have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In
+such a case, @samp{Fontset-@var{n}} can be specified as below:
+
+@smallexample
+Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
+ chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
+@end smallexample
+
+@noindent
+Then, the font specifications for all but Chinese GB2312 characters have
+@samp{fixed} in the @var{family} field, and the font specification for
+Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
+field.
+
+@findex create-fontset-from-fontset-spec
+ The function that processes the fontset resource value to create the
+fontset is called @code{create-fontset-from-fontset-spec}. You can also
+call this function explicitly to create a fontset.
+
+ @xref{Font X}, for more information about font naming in X.
+
+@node Single-Byte European Support
+@section Single-byte European Character Support
+
+@cindex European character sets
+@cindex accented characters
+@cindex ISO Latin character sets
+@cindex Unibyte operation
+@vindex enable-multibyte-characters
+ The ISO 8859 Latin-@var{n} character sets define character codes in
+the range 160 to 255 to handle the accented letters and punctuation
+needed by various European languages. If you disable multibyte
+characters, Emacs can still handle @emph{one} of these character codes
+at a time. To specify @emph{which} of these codes to use, invoke
+@kbd{M-x set-language-environment} and specify a suitable language
+environment such as @samp{Latin-@var{n}}.
+
+ For more information about unibyte operation, see @ref{Enabling
+Multibyte}. Note particularly that you probably want to ensure that
+your initialization files are read as unibyte if they contain non-ASCII
+characters.
+
+@vindex unibyte-display-via-language-environment
+ Emacs can also display those characters, provided the terminal or font
+in use supports them. This works automatically. Alternatively, if you
+are using a window system, Emacs can also display single-byte characters
+through fontsets, in effect by displaying the equivalent multibyte
+characters according to the current language environment. To request
+this, set the variable @code{unibyte-display-via-language-environment}
+to a non-@code{nil} value.
+
+@cindex @code{iso-ascii} library
+ If your terminal does not support display of the Latin-1 character
+set, Emacs can display these characters as ASCII sequences which at
+least give you a clear idea of what the characters are. To do this,
+load the library @code{iso-ascii}. Similar libraries for other
+Latin-@var{n} character sets could be implemented, but we don't have
+them yet.
+
+@findex standard-display-8bit
+@cindex 8-bit display
+ Normally non-ISO-8859 characters (between characters 128 and 159
+inclusive) are displayed as octal escapes. You can change this for
+non-standard `extended' versions of ISO-8859 character sets by using the
+function @code{standard-display-8bit} in the @code{disp-table} library.
+
+ There are three different ways you can input single-byte non-ASCII
+characters:
+
+@itemize @bullet
+@item
+If your keyboard can generate character codes 128 and up, representing
+non-ASCII characters, execute the following expression to enable Emacs to
+understand them:
+
+@example
+(set-input-mode (car (current-input-mode))
+ (nth 1 (current-input-mode))
+ 0)
+@end example
+
+@item
+You can use an input method for the selected language environment.
+@xref{Input Methods}. When you use an input method in a unibyte buffer,
+the non-ASCII character you specify with it is converted to unibyte.
+
+@kindex C-x 8
+@cindex @code{iso-transl} library
+@item
+For Latin-1 only, you can use the
+key @kbd{C-x 8} as a ``compose character'' prefix for entry of
+non-ASCII Latin-1 printing characters. @kbd{C-x 8} is good for
+insertion (in the minibuffer as well as other buffers), for searching,
+and in any other context where a key sequence is allowed.
+
+@kbd{C-x 8} works by loading the @code{iso-transl} library. Once that
+library is loaded, the @key{ALT} modifier key, if you have one, serves
+the same purpose as @kbd{C-x 8}; use @key{ALT} together with an accent
+character to modify the following letter. In addition, if you have keys
+for the Latin-1 ``dead accent characters'', they too are defined to
+compose with the following character, once @code{iso-transl} is loaded.
+@end itemize
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Picture, Sending Mail, Abbrevs, Top
+@chapter Editing Pictures
+@cindex pictures
+@cindex making pictures out of text characters
+@findex edit-picture
+
+ To edit a picture made out of text characters (for example, a picture
+of the division of a register into fields, as a comment in a program),
+use the command @kbd{M-x edit-picture} to enter Picture mode.
+
+ In Picture mode, editing is based on the @dfn{quarter-plane} model of
+text, according to which the text characters lie studded on an area that
+stretches infinitely far to the right and downward. The concept of the end
+of a line does not exist in this model; the most you can say is where the
+last nonblank character on the line is found.
+
+ Of course, Emacs really always considers text as a sequence of
+characters, and lines really do have ends. But Picture mode replaces
+the most frequently-used commands with variants that simulate the
+quarter-plane model of text. They do this by inserting spaces or by
+converting tabs to spaces.
+
+ Most of the basic editing commands of Emacs are redefined by Picture mode
+to do essentially the same thing but in a quarter-plane way. In addition,
+Picture mode defines various keys starting with the @kbd{C-c} prefix to
+run special picture editing commands.
+
+ One of these keys, @kbd{C-c C-c}, is pretty important. Often a
+picture is part of a larger file that is usually edited in some other
+major mode. @kbd{M-x edit-picture} records the name of the previous
+major mode so you can use the @kbd{C-c C-c} command
+(@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c C-c}
+also deletes spaces from the ends of lines, unless given a numeric
+argument.
+
+ The special commands of Picture mode all work in other modes (provided
+the @file{picture} library is loaded), but are not bound to keys except
+in Picture mode. The descriptions below talk of moving ``one column''
+and so on, but all the picture mode commands handle numeric arguments as
+their normal equivalents do.
+
+@vindex picture-mode-hook
+ Turning on Picture mode runs the hook @code{picture-mode-hook}
+(@pxref{Hooks}).
+
+@menu
+* Basic Picture:: Basic concepts and simple commands of Picture Mode.
+* Insert in Picture:: Controlling direction of cursor motion
+ after "self-inserting" characters.
+* Tabs in Picture:: Various features for tab stops and indentation.
+* Rectangles in Picture:: Clearing and superimposing rectangles.
+@end menu
+
+@node Basic Picture, Insert in Picture, Picture, Picture
+@section Basic Editing in Picture Mode
+
+@findex picture-forward-column
+@findex picture-backward-column
+@findex picture-move-down
+@findex picture-move-up
+@cindex editing in Picture mode
+
+ Most keys do the same thing in Picture mode that they usually do, but
+do it in a quarter-plane style. For example, @kbd{C-f} is rebound to
+run @code{picture-forward-column}, a command which moves point one
+column to the right, inserting a space if necessary so that the actual
+end of the line makes no difference. @kbd{C-b} is rebound to run
+@code{picture-backward-column}, which always moves point left one
+column, converting a tab to multiple spaces if necessary. @kbd{C-n} and
+@kbd{C-p} are rebound to run @code{picture-move-down} and
+@code{picture-move-up}, which can either insert spaces or convert tabs
+as necessary to make sure that point stays in exactly the same column.
+@kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last
+nonblank character on the line. There is no need to change @kbd{C-a},
+as the choice of screen model does not affect beginnings of
+lines.
+
+@findex picture-newline
+ Insertion of text is adapted to the quarter-plane screen model through
+the use of Overwrite mode (@pxref{Minor Modes}). Self-inserting characters
+replace existing text, column by column, rather than pushing existing text
+to the right. @key{RET} runs @code{picture-newline}, which just moves to
+the beginning of the following line so that new text will replace that
+line.
+
+@findex picture-backward-clear-column
+@findex picture-clear-column
+@findex picture-clear-line
+ Picture mode provides erasure instead of deletion and killing of
+text. @key{DEL} (@code{picture-backward-clear-column}) replaces the
+preceding character with a space rather than removing it; this moves
+point backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the
+next character or characters with spaces, but does not move point. (If
+you want to clear characters to spaces and move forward over them, use
+@key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the
+contents of lines, but does not delete the newlines from the
+buffer.
+
+@findex picture-open-line
+ To do actual insertion, you must use special commands. @kbd{C-o}
+(@code{picture-open-line}) creates a blank line after the current line;
+it never splits a line. @kbd{C-M-o} (@code{split-line}) makes sense in
+Picture mode, so it is not changed. @kbd{C-j}
+(@code{picture-duplicate-line}) inserts below the current line another
+line with the same contents.@refill
+
+@kindex C-c C-d @r{(Picture mode)}
+ To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d}
+(which is defined as @code{delete-char}, as @kbd{C-d} is in other
+modes), or one of the picture rectangle commands (@pxref{Rectangles in
+Picture}).
+
+@node Insert in Picture, Tabs in Picture, Basic Picture, Picture
+@section Controlling Motion after Insert
+
+@findex picture-movement-up
+@findex picture-movement-down
+@findex picture-movement-left
+@findex picture-movement-right
+@findex picture-movement-nw
+@findex picture-movement-ne
+@findex picture-movement-sw
+@findex picture-movement-se
+@kindex C-c < @r{(Picture mode)}
+@kindex C-c > @r{(Picture mode)}
+@kindex C-c ^ @r{(Picture mode)}
+@kindex C-c . @r{(Picture mode)}
+@kindex C-c ` @r{(Picture mode)}
+@kindex C-c ' @r{(Picture mode)}
+@kindex C-c / @r{(Picture mode)}
+@kindex C-c \ @r{(Picture mode)}
+ Since ``self-inserting'' characters in Picture mode overwrite and move
+point, there is no essential restriction on how point should be moved.
+Normally point moves right, but you can specify any of the eight
+orthogonal or diagonal directions for motion after a ``self-inserting''
+character. This is useful for drawing lines in the buffer.
+
+@table @kbd
+@item C-c <
+Move left after insertion (@code{picture-movement-left}).
+@item C-c >
+Move right after insertion (@code{picture-movement-right}).
+@item C-c ^
+Move up after insertion (@code{picture-movement-up}).
+@item C-c .
+Move down after insertion (@code{picture-movement-down}).
+@item C-c `
+Move up and left (``northwest'') after insertion (@code{picture-movement-nw}).
+@item C-c '
+Move up and right (``northeast'') after insertion
+(@code{picture-movement-ne}).
+@item C-c /
+Move down and left (``southwest'') after insertion
+@*(@code{picture-movement-sw}).
+@item C-c \
+Move down and right (``southeast'') after insertion
+@*(@code{picture-movement-se}).
+@end table
+
+@kindex C-c C-f @r{(Picture mode)}
+@kindex C-c C-b @r{(Picture mode)}
+@findex picture-motion
+@findex picture-motion-reverse
+ Two motion commands move based on the current Picture insertion
+direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the
+same direction as motion after ``insertion'' currently does, while @kbd{C-c
+C-b} (@code{picture-motion-reverse}) moves in the opposite direction.
+
+@node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
+@section Picture Mode Tabs
+
+@kindex M-TAB @r{(Picture mode)}
+@findex picture-tab-search
+@vindex picture-tab-chars
+ Two kinds of tab-like action are provided in Picture mode. Use
+@kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing.
+With no argument, it moves to a point underneath the next
+``interesting'' character that follows whitespace in the previous
+nonblank line. ``Next'' here means ``appearing at a horizontal position
+greater than the one point starts out at.'' With an argument, as in
+@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting
+character in the current line. @kbd{M-@key{TAB}} does not change the
+text; it only moves point. ``Interesting'' characters are defined by
+the variable @code{picture-tab-chars}, which should define a set of
+characters. The syntax for this variable is like the syntax used inside
+of @samp{[@dots{}]} in a regular expression---but without the @samp{[}
+and the @samp{]}. Its default value is @code{"!-~"}.
+
+@findex picture-tab
+ @key{TAB} itself runs @code{picture-tab}, which operates based on the
+current tab stop settings; it is the Picture mode equivalent of
+@code{tab-to-tab-stop}. Normally it just moves point, but with a numeric
+argument it clears the text that it moves over.
+
+@kindex C-c TAB @r{(Picture mode)}
+@findex picture-set-tab-stops
+ The context-based and tab-stop-based forms of tabbing are brought
+together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}).
+This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
+would consider significant in the current line. The use of this command,
+together with @key{TAB}, can get the effect of context-based tabbing. But
+@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
+
+ It may be convenient to prevent use of actual tab characters in
+pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing
+up the picture. You can do this by setting the variable
+@code{indent-tabs-mode} to @code{nil}. @xref{Just Spaces}.
+
+@node Rectangles in Picture,, Tabs in Picture, Picture
+@section Picture Mode Rectangle Commands
+@cindex rectangles and Picture mode
+@cindex Picture mode and rectangles
+
+ Picture mode defines commands for working on rectangular pieces of the
+text in ways that fit with the quarter-plane model. The standard rectangle
+commands may also be useful (@pxref{Rectangles}).
+
+@table @kbd
+@item C-c C-k
+Clear out the region-rectangle with spaces
+(@code{picture-clear-rectangle}). With argument, delete the text.
+@item C-c C-w @var{r}
+Similar but save rectangle contents in register @var{r} first
+(@code{picture-clear-rectangle-to-register}).
+@item C-c C-y
+Copy last killed rectangle into the buffer by overwriting, with upper
+left corner at point (@code{picture-yank-rectangle}). With argument,
+insert instead.
+@item C-c C-x @var{r}
+Similar, but use the rectangle in register @var{r}
+(@code{picture-yank-rectangle-from-register}).
+@end table
+
+@kindex C-c C-k @r{(Picture mode)}
+@kindex C-c C-w @r{(Picture mode)}
+@findex picture-clear-rectangle
+@findex picture-clear-rectangle-to-register
+ The picture rectangle commands @kbd{C-c C-k}
+(@code{picture-clear-rectangle}) and @kbd{C-c C-w}
+(@code{picture-clear-rectangle-to-register}) differ from the standard
+rectangle commands in that they normally clear the rectangle instead of
+deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
+mode.
+
+ However, deletion of rectangles can be useful in Picture mode, so
+these commands delete the rectangle if given a numeric argument.
+@kbd{C-c C-k} either with or without a numeric argument saves the
+rectangle for @kbd{C-c C-y}.
+
+@kindex C-c C-y @r{(Picture mode)}
+@kindex C-c C-x @r{(Picture mode)}
+@findex picture-yank-rectangle
+@findex picture-yank-rectangle-from-register
+ The Picture mode commands for yanking rectangles differ from the
+standard ones in overwriting instead of inserting. This is the same way
+that Picture mode insertion of other text differs from other modes.
+@kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts (by overwriting)
+the rectangle that was most recently killed, while @kbd{C-c C-x}
+(@code{picture-yank-rectangle-from-register}) does likewise for the
+rectangle found in a specified register.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Programs, Building, Text, Top
+@chapter Editing Programs
+@cindex Lisp editing
+@cindex C editing
+@cindex program editing
+
+ Emacs has many commands designed to understand the syntax of programming
+languages such as Lisp and C. These commands can
+
+@itemize @bullet
+@item
+Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
+@item
+Move over or mark top-level expressions---@dfn{defuns}, in Lisp;
+functions, in C (@pxref{Defuns}).
+@item
+Show how parentheses balance (@pxref{Matching}).
+@item
+Insert, kill or align comments (@pxref{Comments}).
+@item
+Follow the usual indentation conventions of the language
+(@pxref{Program Indent}).
+@end itemize
+
+ The commands for words, sentences and paragraphs are very useful in
+editing code even though their canonical application is for editing
+human language text. Most symbols contain words (@pxref{Words});
+sentences can be found in strings and comments (@pxref{Sentences}).
+Paragraphs per se don't exist in code, but the paragraph commands are
+useful anyway, because programming language major modes define
+paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
+Judicious use of blank lines to make the program clearer will also
+provide useful chunks of text for the paragraph commands to work
+on.
+
+ The selective display feature is useful for looking at the overall
+structure of a function (@pxref{Selective Display}). This feature causes
+only the lines that are indented less than a specified amount to appear
+on the screen.
+
+@menu
+* Program Modes:: Major modes for editing programs.
+* Lists:: Expressions with balanced parentheses.
+* List Commands:: The commands for working with list and sexps.
+* Defuns:: Each program is made up of separate functions.
+ There are editing commands to operate on them.
+* Program Indent:: Adjusting indentation to show the nesting.
+* Matching:: Insertion of a close-delimiter flashes matching open.
+* Comments:: Inserting, killing, and aligning comments.
+* Balanced Editing:: Inserting two matching parentheses at once, etc.
+* Symbol Completion:: Completion on symbol names of your program or language.
+* Which Function:: Which Function mode shows which function you are in.
+* Documentation:: Getting documentation of functions you plan to call.
+* Change Log:: Maintaining a change history for your program.
+* Tags:: Go direct to any function in your program in one
+ command. Tags remembers which file it is in.
+* Emerge:: A convenient way of merging two versions of a program.
+* C Modes:: Special commands of C, C++, Objective-C,
+ Java, and Pike modes.
+* Fortran:: Fortran mode and its special features.
+* Asm Mode:: Asm mode and its special features.
+@end menu
+
+@node Program Modes
+@section Major Modes for Programming Languages
+
+@cindex modes for programming languages
+@cindex Perl mode
+@cindex Icon mode
+@cindex Awk mode
+@cindex Makefile mode
+@cindex Tcl mode
+@cindex CPerl mode
+ Emacs also has major modes for the programming languages Lisp, Scheme
+(a variant of Lisp), Awk, C, C++, Fortran, Icon, Java, Objective-C,
+Pascal, Perl, Pike, CORBA IDL, and Tcl. There is also a major mode for
+makefiles, called Makefile mode. An second alternative mode for Perl is
+called CPerl mode.
+
+ Ideally, a major mode should be implemented for each programming
+language that you might want to edit with Emacs; but often the mode for
+one language can serve for other syntactically similar languages. The
+language modes that exist are those that someone decided to take the
+trouble to write.
+
+ There are several forms of Lisp mode, which differ in the way they
+interface to Lisp execution. @xref{Executing Lisp}.
+
+ Each of the programming language major modes defines the @key{TAB} key
+to run an indentation function that knows the indentation conventions of
+that language and updates the current line's indentation accordingly.
+For example, in C mode @key{TAB} is bound to @code{c-indent-line}.
+@kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB};
+thus, it too indents in a mode-specific fashion.
+
+@kindex DEL @r{(programming modes)}
+@findex backward-delete-char-untabify
+ In most programming languages, indentation is likely to vary from line to
+line. So the major modes for those languages rebind @key{DEL} to treat a
+tab as if it were the equivalent number of spaces (using the command
+@code{backward-delete-char-untabify}). This makes it possible to rub out
+indentation one column at a time without worrying whether it is made up of
+spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point,
+in these modes.
+
+ Programming language modes define paragraphs to be separated only by
+blank lines, so that the paragraph commands remain useful. Auto Fill mode,
+if enabled in a programming language major mode, indents the new lines
+which it creates.
+
+@cindex mode hook
+@vindex c-mode-hook
+@vindex lisp-mode-hook
+@vindex emacs-lisp-mode-hook
+@vindex lisp-interaction-mode-hook
+@vindex scheme-mode-hook
+@vindex muddle-mode-hook
+ Turning on a major mode runs a normal hook called the @dfn{mode hook},
+which is the value of a Lisp variable. Each major mode has a mode hook,
+and the hook's name is always made from the mode command's name by
+adding @samp{-hook}. For example, turning on C mode runs the hook
+@code{c-mode-hook}, while turning on Lisp mode runs the hook
+@code{lisp-mode-hook}. @xref{Hooks}.
+
+@node Lists
+@section Lists and Sexps
+
+@cindex Control-Meta
+ By convention, Emacs keys for dealing with balanced expressions are
+usually Control-Meta characters. They tend to be analogous in
+function to their Control and Meta equivalents. These commands are
+usually thought of as pertaining to expressions in programming
+languages, but can be useful with any language in which some sort of
+parentheses exist (including human languages).
+
+@cindex list
+@cindex sexp
+@cindex expression
+@cindex parentheses, moving across
+@cindex matching parenthesis, moving to
+ These commands fall into two classes. Some deal only with @dfn{lists}
+(parenthetical groupings). They see nothing except parentheses, brackets,
+braces (whichever ones must balance in the language you are working with),
+and escape characters that might be used to quote those.
+
+ The other commands deal with expressions or @dfn{sexps}. The word `sexp'
+is derived from @dfn{s-expression}, the ancient term for an expression in
+Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It
+refers to an expression in whatever language your program is written in.
+Each programming language has its own major mode, which customizes the
+syntax tables so that expressions in that language count as sexps.
+
+ Sexps typically include symbols, numbers, and string constants, as well
+as anything contained in parentheses, brackets or braces.
+
+ In languages that use prefix and infix operators, such as C, it is not
+possible for all expressions to be sexps. For example, C mode does not
+recognize @samp{foo + bar} as a sexp, even though it @emph{is} a C expression;
+it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
+@samp{+} as punctuation between them. This is a fundamental ambiguity:
+both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
+move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a
+single sexp in C mode.
+
+ Some languages have obscure forms of expression syntax that nobody
+has bothered to make Emacs understand properly.
+
+@node List Commands
+@section List And Sexp Commands
+
+@c doublewidecommands
+@table @kbd
+@item C-M-f
+Move forward over a sexp (@code{forward-sexp}).
+@item C-M-b
+Move backward over a sexp (@code{backward-sexp}).
+@item C-M-k
+Kill sexp forward (@code{kill-sexp}).
+@item C-M-@key{DEL}
+Kill sexp backward (@code{backward-kill-sexp}).
+@item C-M-u
+Move up and backward in list structure (@code{backward-up-list}).
+@item C-M-d
+Move down and forward in list structure (@code{down-list}).
+@item C-M-n
+Move forward over a list (@code{forward-list}).
+@item C-M-p
+Move backward over a list (@code{backward-list}).
+@item C-M-t
+Transpose expressions (@code{transpose-sexps}).
+@item C-M-@@
+Put mark after following expression (@code{mark-sexp}).
+@end table
+
+@kindex C-M-f
+@kindex C-M-b
+@findex forward-sexp
+@findex backward-sexp
+ To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If
+the first significant character after point is an opening delimiter
+(@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
+moves past the matching closing delimiter. If the character begins a
+symbol, string, or number, @kbd{C-M-f} moves over that.
+
+ The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
+sexp. The detailed rules are like those above for @kbd{C-M-f}, but with
+directions reversed. If there are any prefix characters (single-quote,
+backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
+over them as well. The sexp commands move across comments as if they
+were whitespace in most modes.
+
+ @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
+specified number of times; with a negative argument, it moves in the
+opposite direction.
+
+@kindex C-M-k
+@findex kill-sexp
+@kindex C-M-DEL
+@findex backward-kill-sexp
+ Killing a whole sexp can be done with @kbd{C-M-k} (@code{kill-sexp})
+or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}). @kbd{C-M-k} kills
+the characters that @kbd{C-M-f} would move over, and @kbd{C-M-@key{DEL}}
+kills the characters that @kbd{C-M-b} would move over.
+
+@kindex C-M-n
+@kindex C-M-p
+@findex forward-list
+@findex backward-list
+ The @dfn{list commands} move over lists, as the sexp commands do, but skip
+blithely over any number of other kinds of sexps (symbols, strings, etc.).
+They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
+(@code{backward-list}). The main reason they are useful is that they
+usually ignore comments (since the comments usually do not contain any
+lists).@refill
+
+@kindex C-M-u
+@kindex C-M-d
+@findex backward-up-list
+@findex down-list
+ @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
+that's possible. To move @emph{up} one (or @var{n}) levels, use @kbd{C-M-u}
+(@code{backward-up-list}).
+@kbd{C-M-u} moves backward up past one unmatched opening delimiter. A
+positive argument serves as a repeat count; a negative argument reverses
+direction of motion and also requests repetition, so it moves forward and
+up one or more levels.@refill
+
+ To move @emph{down} in list structure, use @kbd{C-M-d}
+(@code{down-list}). In Lisp mode, where @samp{(} is the only opening
+delimiter, this is nearly the same as searching for a @samp{(}. An
+argument specifies the number of levels of parentheses to go down.
+
+@cindex transposition
+@kindex C-M-t
+@findex transpose-sexps
+ A somewhat random-sounding command which is nevertheless handy is
+@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp
+across the next one. An argument serves as a repeat count, and a
+negative argument drags backwards (thus canceling out the effect of
+@kbd{C-M-t} with a positive argument). An argument of zero, rather than
+doing nothing, transposes the sexps ending after point and the mark.
+
+@kindex C-M-@@
+@findex mark-sexp
+ To set the region around the next sexp in the buffer, use @kbd{C-M-@@}
+(@code{mark-sexp}), which sets mark at the same place that @kbd{C-M-f}
+would move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In
+particular, a negative argument is useful for putting the mark at the
+beginning of the previous sexp.
+
+ The list and sexp commands' understanding of syntax is completely
+controlled by the syntax table. Any character can, for example, be
+declared to be an opening delimiter and act like an open parenthesis.
+@xref{Syntax}.
+
+@node Defuns
+@section Defuns
+@cindex defuns
+
+ In Emacs, a parenthetical grouping at the top level in the buffer is
+called a @dfn{defun}. The name derives from the fact that most top-level
+lists in a Lisp file are instances of the special form @code{defun}, but
+any top-level parenthetical grouping counts as a defun in Emacs parlance
+regardless of what its contents are, and regardless of the programming
+language in use. For example, in C, the body of a function definition is a
+defun.
+
+@c doublewidecommands
+@table @kbd
+@item C-M-a
+Move to beginning of current or preceding defun
+(@code{beginning-of-defun}).
+@item C-M-e
+Move to end of current or following defun (@code{end-of-defun}).
+@item C-M-h
+Put region around whole current or following defun (@code{mark-defun}).
+@end table
+
+@kindex C-M-a
+@kindex C-M-e
+@kindex C-M-h
+@findex beginning-of-defun
+@findex end-of-defun
+@findex mark-defun
+ The commands to move to the beginning and end of the current defun are
+@kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
+
+@findex c-mark-function
+ If you wish to operate on the current defun, use @kbd{C-M-h}
+(@code{mark-defun}) which puts point at the beginning and mark at the end
+of the current or next defun. For example, this is the easiest way to get
+ready to move the defun to a different place in the text. In C mode,
+@kbd{C-M-h} runs the function @code{c-mark-function}, which is almost the
+same as @code{mark-defun}; the difference is that it backs up over the
+argument declarations, function name and returned data type so that the
+entire C function is inside the region. @xref{Marking Objects}.
+
+ Emacs assumes that any open-parenthesis found in the leftmost column
+is the start of a defun. Therefore, @strong{never put an
+open-parenthesis at the left margin in a Lisp file unless it is the
+start of a top-level list. Never put an open-brace or other opening
+delimiter at the beginning of a line of C code unless it starts the body
+of a function.} The most likely problem case is when you want an
+opening delimiter at the start of a line inside a string. To avoid
+trouble, put an escape character (@samp{\}, in C and Emacs Lisp,
+@samp{/} in some other Lisp dialects) before the opening delimiter. It
+will not affect the contents of the string.
+
+ In the remotest past, the original Emacs found defuns by moving upward a
+level of parentheses until there were no more levels to go up. This always
+required scanning all the way back to the beginning of the buffer, even for
+a small function. To speed up the operation, Emacs was changed to assume
+that any @samp{(} (or other character assigned the syntactic class of
+opening-delimiter) at the left margin is the start of a defun. This
+heuristic is nearly always right and avoids the costly scan; however,
+it mandates the convention described above.
+
+@node Program Indent
+@section Indentation for Programs
+@cindex indentation for programs
+
+ The best way to keep a program properly indented is to use Emacs to
+reindent it as you change it. Emacs has commands to indent properly
+either a single line, a specified number of lines, or all of the lines
+inside a single parenthetical grouping.
+
+@menu
+* Basic Indent:: Indenting a single line.
+* Multi-line Indent:: Commands to reindent many lines at once.
+* Lisp Indent:: Specifying how each Lisp function should be indented.
+* C Indent:: Extra features for indenting C and related modes.
+* Custom C Indent:: Controlling indentation style for C and related modes.
+@end menu
+
+ Emacs also provides a Lisp pretty-printer in the library @code{pp}.
+This program reformats a Lisp object with indentation chosen to look nice.
+
+@node Basic Indent
+@subsection Basic Program Indentation Commands
+
+@c WideCommands
+@table @kbd
+@item @key{TAB}
+Adjust indentation of current line.
+@item C-j
+Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
+@end table
+
+@kindex TAB @r{(programming modes)}
+@findex c-indent-line
+@findex lisp-indent-line
+ The basic indentation command is @key{TAB}, which gives the current line
+the correct indentation as determined from the previous lines. The
+function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line}
+in Lisp mode, @code{c-indent-line} in C mode, etc. These functions
+understand different syntaxes for different languages, but they all do
+about the same thing. @key{TAB} in any programming-language major mode
+inserts or deletes whitespace at the beginning of the current line,
+independent of where point is in the line. If point is inside the
+whitespace at the beginning of the line, @key{TAB} leaves it at the end of
+that whitespace; otherwise, @key{TAB} leaves point fixed with respect to
+the characters around it.
+
+ Use @kbd{C-q @key{TAB}} to insert a tab at point.
+
+@kindex C-j
+@findex newline-and-indent
+ When entering lines of new code, use @kbd{C-j} (@code{newline-and-indent}),
+which is equivalent to a @key{RET} followed by a @key{TAB}. @kbd{C-j} creates
+a blank line and then gives it the appropriate indentation.
+
+ @key{TAB} indents the second and following lines of the body of a
+parenthetical grouping each under the preceding one; therefore, if you
+alter one line's indentation to be nonstandard, the lines below will
+tend to follow it. This behavior is convenient in cases where you have
+overridden the standard result of @key{TAB} because you find it
+unaesthetic for a particular line.
+
+ Remember that an open-parenthesis, open-brace or other opening delimiter
+at the left margin is assumed by Emacs (including the indentation routines)
+to be the start of a function. Therefore, you must never have an opening
+delimiter in column zero that is not the beginning of a function, not even
+inside a string. This restriction is vital for making the indentation
+commands fast; you must simply accept it. @xref{Defuns}, for more
+information on this.
+
+@node Multi-line Indent
+@subsection Indenting Several Lines
+
+ When you wish to reindent several lines of code which have been altered
+or moved to a different level in the list structure, you have several
+commands available.
+
+@table @kbd
+@item C-M-q
+Reindent all the lines within one list (@code{indent-sexp}).
+@item C-u @key{TAB}
+Shift an entire list rigidly sideways so that its first line
+is properly indented.
+@item C-M-\
+Reindent all lines in the region (@code{indent-region}).
+@end table
+
+@kindex C-M-q
+@findex indent-sexp
+ You can reindent the contents of a single list by positioning point
+before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
+Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable
+commands in other modes). The indentation of the line the sexp starts on
+is not changed; therefore, only the relative indentation within the list,
+and not its position, is changed. To correct the position as well, type a
+@key{TAB} before the @kbd{C-M-q}.
+
+@kindex C-u TAB
+ If the relative indentation within a list is correct but the
+indentation of its first line is not, go to that line and type @kbd{C-u
+@key{TAB}}. @key{TAB} with a numeric argument reindents the current
+line as usual, then reindents by the same amount all the lines in the
+grouping starting on the current line. In other words, it reindents the
+whole grouping rigidly as a unit. It is clever, though, and does not
+alter lines that start inside strings, or C preprocessor lines when in C
+mode.
+
+ Another way to specify the range to be reindented is with the region.
+The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to
+every line whose first character is between point and mark.
+
+@node Lisp Indent
+@subsection Customizing Lisp Indentation
+@cindex customizing Lisp indentation
+
+ The indentation pattern for a Lisp expression can depend on the function
+called by the expression. For each Lisp function, you can choose among
+several predefined patterns of indentation, or define an arbitrary one with
+a Lisp program.
+
+ The standard pattern of indentation is as follows: the second line of the
+expression is indented under the first argument, if that is on the same
+line as the beginning of the expression; otherwise, the second line is
+indented underneath the function name. Each following line is indented
+under the previous line whose nesting depth is the same.
+
+@vindex lisp-indent-offset
+ If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
+the usual indentation pattern for the second line of an expression, so that
+such lines are always indented @code{lisp-indent-offset} more columns than
+the containing list.
+
+@vindex lisp-body-indent
+ The standard pattern is overridden for certain functions. Functions
+whose names start with @code{def} always indent the second line by
+@code{lisp-body-indent} extra columns beyond the open-parenthesis
+starting the expression.
+
+ The standard pattern can be overridden in various ways for individual
+functions, according to the @code{lisp-indent-function} property of the
+function name. There are four possibilities for this property:
+
+@table @asis
+@item @code{nil}
+This is the same as no property; the standard indentation pattern is used.
+@item @code{defun}
+The pattern used for function names that start with @code{def} is used for
+this function also.
+@item a number, @var{number}
+The first @var{number} arguments of the function are
+@dfn{distinguished} arguments; the rest are considered the @dfn{body}
+of the expression. A line in the expression is indented according to
+whether the first argument on it is distinguished or not. If the
+argument is part of the body, the line is indented @code{lisp-body-indent}
+more columns than the open-parenthesis starting the containing
+expression. If the argument is distinguished and is either the first
+or second argument, it is indented @emph{twice} that many extra columns.
+If the argument is distinguished and not the first or second argument,
+the standard pattern is followed for that line.
+@item a symbol, @var{symbol}
+@var{symbol} should be a function name; that function is called to
+calculate the indentation of a line within this expression. The
+function receives two arguments:
+@table @asis
+@item @var{state}
+The value returned by @code{parse-partial-sexp} (a Lisp primitive for
+indentation and nesting computation) when it parses up to the
+beginning of this line.
+@item @var{pos}
+The position at which the line being indented begins.
+@end table
+@noindent
+It should return either a number, which is the number of columns of
+indentation for that line, or a list whose car is such a number. The
+difference between returning a number and returning a list is that a
+number says that all following lines at the same nesting level should
+be indented just like this one; a list says that following lines might
+call for different indentations. This makes a difference when the
+indentation is being computed by @kbd{C-M-q}; if the value is a
+number, @kbd{C-M-q} need not recalculate indentation for the following
+lines until the end of the list.
+@end table
+
+@node C Indent
+@subsection Commands for C Indentation
+
+ Here are the commands for indentation in C mode and related modes:
+
+@table @code
+@item C-c C-q
+@kindex C-c C-q @r{(C mode)}
+@findex c-indent-defun
+Reindent the current top-level function definition or aggregate type
+declaration (@code{c-indent-defun}).
+
+@item C-M-q
+@kindex C-M-q @r{(C mode)}
+@findex c-indent-exp
+Reindent each line in the balanced expression that follows point
+(@code{c-indent-exp}). A prefix argument inhibits error checking and
+warning messages about invalid syntax.
+
+@item @key{TAB}
+@findex c-indent-command
+Reindent the current line, and/or in some cases insert a tab character
+(@code{c-indent-command}).
+
+If @code{c-tab-always-indent} is @code{t}, this command always reindents
+the current line and does nothing else. This is the default.
+
+If that variable is @code{nil}, this command reindents the current line
+only if point is at the left margin or in the line's indentation;
+otherwise, it inserts a tab (or the equivalent number of spaces,
+if @code{indent-tabs-mode} is @code{nil}).
+
+Any other value (not @code{nil} or @code{t}) means always reindent the
+line, and also insert a tab if within a comment, a string, or a
+preprocessor directive.
+
+@item C-u @key{TAB}
+Reindent the current line according to its syntax; also rigidly reindent
+any other lines of the expression that starts on the current line.
+@xref{Multi-line Indent}.
+@end table
+
+ To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
+first selects the whole buffer as the region, then reindents that
+region.
+
+ To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
+to the front of the block and then reindents it all.
+
+@node Custom C Indent
+@subsection Customizing C Indentation
+
+ C mode and related modes use a simple yet flexible mechanism for
+customizing indentation. The mechanism works in two steps: first it
+classifies the line syntactically according to its contents and context;
+second, it associates each kind of syntactic construct with an
+indentation offset which you can customize.
+
+@menu
+* Syntactic Analysis::
+* Indentation Calculation::
+* Changing Indent Style::
+* Syntactic Symbols::
+* Variables for C Indent::
+* C Indent Styles::
+@end menu
+
+@node Syntactic Analysis
+@subsubsection Step 1---Syntactic Analysis
+@cindex syntactic analysis
+
+ In the first step, the C indentation mechanism looks at the line
+before the one you are currently indenting and determines the syntactic
+components of the construct on that line. It builds a list of these
+syntactic components, each of which contains a @dfn{syntactic symbol}
+and sometimes also a buffer position. Some syntactic symbols describe
+grammatical elements, for example @code{statement} and
+@code{substatement}; others describe locations amidst grammatical
+elements, for example @code{class-open} and @code{knr-argdecl}.
+
+ Conceptually, a line of C code is always indented relative to the
+indentation of some line higher up in the buffer. This is represented
+by the buffer positions in the syntactic component list.
+
+ Here is an example. Suppose we have the following code in a C++ mode
+buffer (the line numbers don't actually appear in the buffer):
+
+@example
+1: void swap (int& a, int& b)
+2: @{
+3: int tmp = a;
+4: a = b;
+5: b = tmp;
+6: @}
+@end example
+
+ If you type @kbd{C-c C-s} (which runs the command
+@code{c-show-syntactic-information}) on line 4, it shows the result of
+the indentation mechanism for that line:
+
+@example
+((statement . 32))
+@end example
+
+ This indicates that the line is a statement and it is indented
+relative to buffer position 32, which happens to be the @samp{i} in
+@code{int} on line 3. If you move the cursor to line 3 and type
+@kbd{C-c C-s}, it displays this:
+
+@example
+((defun-block-intro . 28))
+@end example
+
+ This indicates that the @code{int} line is the first statement in a
+block, and is indented relative to buffer position 28, which is the
+brace just after the function header.
+
+@noindent
+Here is another example:
+
+@example
+1: int add (int val, int incr, int doit)
+2: @{
+3: if (doit)
+4: @{
+5: return (val + incr);
+6: @}
+7: return (val);
+8: @}
+@end example
+
+@noindent
+Typing @kbd{C-c C-s} on line 4 displays this:
+
+@example
+((substatement-open . 43))
+@end example
+
+ This says that the brace @emph{opens} a substatement block. By the
+way, a @dfn{substatement} indicates the line after an @code{if},
+@code{else}, @code{while}, @code{do}, @code{switch}, @code{for},
+@code{try}, @code{catch}, @code{finally}, or @code{synchronized}
+statement.
+
+@cindex syntactic component
+@cindex syntactic symbol
+@vindex c-syntactic-context
+ Within the C indentation commands, after a line has been analyzed
+syntactically for indentation, the variable @code{c-syntactic-context}
+contains a list that describes the results. Each element in this list
+is a @dfn{syntactic component}: a cons cell containing a syntactic
+symbol and (optionally) its corresponding buffer position. There may be
+several elements in a component list; typically only one element has a
+buffer position.
+
+@node Indentation Calculation
+@subsubsection Step 2---Indentation Calculation
+@cindex Indentation Calculation
+
+ The C indentation mechanism calculates the indentation for the current
+line using the list of syntactic components, @code{c-syntactic-context},
+derived from syntactic analysis. Each component is a cons cell that
+contains a syntactic symbol and may also contain a buffer position.
+
+ Each component contributes to the final total indentation of the line
+in two ways. First, the syntactic symbol identifies an element of
+@code{c-offsets-alist}, which is an association list mapping syntactic
+symbols into indentation offsets. Each syntactic symbol's offset adds
+to the total indentation. Second, if the component includes a buffer
+position, the column number of that position adds to the indentation.
+All these offsets and column numbers, added together, give the total
+indentation.
+
+ The following examples demonstrate the workings of the C indentation
+mechanism:
+
+@example
+1: void swap (int& a, int& b)
+2: @{
+3: int tmp = a;
+4: a = b;
+5: b = tmp;
+6: @}
+@end example
+
+ Suppose that point is on line 3 and you type @key{TAB} to reindent the
+line. As explained above (@pxref{Syntactic Analysis}), the syntactic
+component list for that line is:
+
+@example
+((defun-block-intro . 28))
+@end example
+
+ In this case, the indentation calculation first looks up
+@code{defun-block-intro} in the @code{c-offsets-alist} alist. Suppose
+that it finds the integer 2; it adds this to the running total
+(initialized to zero), yielding a updated total indentation of 2 spaces.
+
+ The next step is to find the column number of buffer position 28.
+Since the brace at buffer position 28 is in column zero, this adds 0 to
+the running total. Since this line has only one syntactic component,
+the total indentation for the line is 2 spaces.
+
+@example
+1: int add (int val, int incr, int doit)
+2: @{
+3: if (doit)
+4: @{
+5: return(val + incr);
+6: @}
+7: return(val);
+8: @}
+@end example
+
+ If you type @key{TAB} on line 4, the same process is performed, but
+with different data. The syntactic component list for this line is:
+
+@example
+((substatement-open . 43))
+@end example
+
+ Here, the indentation calculation's first job is to look up the
+symbol @code{substatement-open} in @code{c-offsets-alist}. Let's assume
+that the offset for this symbol is 2. At this point the running total
+is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43,
+which is the @samp{i} in @code{if} on line 3. This character is in
+column 2 on that line. Adding this yields a total indentation of 4
+spaces.
+
+@vindex c-strict-syntax-p
+ If a syntactic symbol in the analysis of a line does not appear in
+@code{c-offsets-alist}, it is ignored; if in addition the variable
+@code{c-strict-syntax-p} is non-@code{nil}, it is an error.
+
+@node Changing Indent Style
+@subsubsection Changing Indentation Style
+
+ There are two ways to customize the indentation style for the C-like
+modes. First, you can select one of several predefined styles, each of
+which specifies offsets for all the syntactic symbols. For more
+flexibility, you can customize the handling of individual syntactic
+symbols. @xref{Syntactic Symbols}, for a list of all defined syntactic
+symbols.
+
+@table @kbd
+@item M-x c-set-style @key{RET} @var{style} @key{RET}
+Select predefined indentation style @var{style}. Type @kbd{?} when
+entering @var{style} to see a list of supported styles; to find out what
+a style looks like, select it and reindent some C code.
+
+@item C-c C-o @var{symbol} @key{RET} @var{offset} @key{RET}
+Set the indentation offset for syntactic symbol @var{symbol}
+(@code{c-set-offset}). The second argument @var{offset} specifies the
+new indentation offset.
+@end table
+
+ The @code{c-offsets-alist} variable controls the amount of
+indentation to give to each syntactic symbol. Its value is an
+association list, and each element of the list has the form
+@code{(@var{syntactic-symbol} . @var{offset})}. By changing the offsets
+for various syntactic symbols, you can customize indentation in fine
+detail. To change this alist, use @code{c-set-offset} (see below).
+
+ Each offset value in @code{c-offsets-alist} can be an integer, a
+function or variable name, a list, or one of the following symbols: @code{+},
+@code{-}, @code{++}, @code{--}, @code{*}, or @code{/}, indicating positive or negative
+multiples of the variable @code{c-basic-offset}. Thus, if you want to
+change the levels of indentation to be 3 spaces instead of 2 spaces, set
+@code{c-basic-offset} to 3.
+
+ Using a function as the offset value provides the ultimate flexibility
+in customizing indentation. The function is called with a single
+argument containing the @code{cons} of the syntactic symbol and
+the buffer position, if any. The function should return an integer
+offset.
+
+ If the offset value is a list, its elements are processed according
+to the rules above until a non-@code{nil} value is found. That value is
+then added to the total indentation in the normal manner. The primary
+use for this is to combine the results of several functions.
+
+@kindex C-c C-o @r{(C mode)}
+@findex c-set-offset
+ The command @kbd{C-c C-o} (@code{c-set-offset}) is the easiest way to
+set offsets, both interactively or in your @file{~/.emacs} file. First
+specify the syntactic symbol, then the offset you want. @xref{Syntactic
+Symbols}, for a list of valid syntactic symbols and their meanings.
+
+@node Syntactic Symbols
+@subsubsection Syntactic Symbols
+
+ Here is a table of valid syntactic symbols for indentation in C and
+related modes, with their syntactic meanings. Normally, most of these
+symbols are assigned offsets in @code{c-offsets-alist}.
+
+@table @code
+@item string
+Inside a multi-line string.
+
+@item c
+Inside a multi-line C style block comment.
+
+@item defun-open
+On a brace that opens a function definition.
+
+@item defun-close
+On a brace that closes a function definition.
+
+@item defun-block-intro
+In the first line in a top-level defun.
+
+@item class-open
+On a brace that opens a class definition.
+
+@item class-close
+On a brace that closes a class definition.
+
+@item inline-open
+On a brace that opens an in-class inline method.
+
+@item inline-close
+On a brace that closes an in-class inline method.
+
+@item extern-lang-open
+On a brace that opens an external language block.
+
+@item extern-lang-close
+On a brace that closes an external language block.
+
+@item func-decl-cont
+The region between a function definition's argument list and the defun
+opening brace (excluding K&R function definitions). In C, you cannot
+put anything but whitespace and comments between them; in C++ and Java,
+@code{throws} declarations and other things can appear in this context.
+
+@item knr-argdecl-intro
+On the first line of a K&R C argument declaration.
+
+@item knr-argdecl
+In one of the subsequent lines in a K&R C argument declaration.
+
+@item topmost-intro
+On the first line in a topmost construct definition.
+
+@item topmost-intro-cont
+On the topmost definition continuation lines.
+
+@item member-init-intro
+On the first line in a member initialization list.
+
+@item member-init-cont
+On one of the subsequent member initialization list lines.
+
+@item inher-intro
+On the first line of a multiple inheritance list.
+
+@item inher-cont
+On one of the subsequent multiple inheritance lines.
+
+@item block-open
+On a statement block open brace.
+
+@item block-close
+On a statement block close brace.
+
+@item brace-list-open
+On the opening brace of an @code{enum} or @code{static} array list.
+
+@item brace-list-close
+On the closing brace of an @code{enum} or @code{static} array list.
+
+@item brace-list-intro
+On the first line in an @code{enum} or @code{static} array list.
+
+@item brace-list-entry
+On one of the subsequent lines in an @code{enum} or @code{static} array
+list.
+
+@item brace-entry-open
+On one of the subsequent lines in an @code{enum} or @code{static} array
+list, when the line begins with an open brace.
+
+@item statement
+On an ordinary statement.
+
+@item statement-cont
+On a continuation line of a statement.
+
+@item statement-block-intro
+On the first line in a new statement block.
+
+@item statement-case-intro
+On the first line in a @code{case} ``block.''
+
+@item statement-case-open
+On the first line in a @code{case} block starting with brace.
+
+@item inexpr-statement
+On a statement block inside an expression. This is used for a GNU
+extension to the C language, and for Pike special functions that take a
+statement block as an argument.
+
+@item inexpr-class
+On a class definition inside an expression. This is used for anonymous
+classes and anonymous array initializers in Java.
+
+@item substatement
+On the first line after an @code{if}, @code{while}, @code{for},
+@code{do}, or @code{else}.
+
+@item substatement-open
+On the brace that opens a substatement block.
+
+@item case-label
+On a @code{case} or @code{default} label.
+
+@item access-label
+On a C++ @code{private}, @code{protected}, or @code{public} access label.
+
+@item label
+On any ordinary label.
+
+@item do-while-closure
+On the @code{while} that ends a @code{do}-@code{while} construct.
+
+@item else-clause
+On the @code{else} of an @code{if}-@code{else} construct.
+
+@item catch-clause
+On the @code{catch} and @code{finally} lines in
+@code{try}@dots{}@code{catch} constructs in C++ and Java.
+
+@item comment-intro
+On a line containing only a comment introduction.
+
+@item arglist-intro
+On the first line in an argument list.
+
+@item arglist-cont
+On one of the subsequent argument list lines when no arguments follow on
+the same line as the arglist opening parenthesis.
+
+@item arglist-cont-nonempty
+On one of the subsequent argument list lines when at least one argument
+follows on the same line as the arglist opening parenthesis.
+
+@item arglist-close
+On the closing parenthesis of an argument list.
+
+@item stream-op
+On one of the lines continuing a stream operator construct.
+
+@item inclass
+On a construct that is nested inside a class definition. The
+indentation is relative to the open brace of the class definition.
+
+@item inextern-lang
+On a construct that is nested inside an external language block.
+
+@item inexpr-statement
+On the first line of statement block inside an expression. This is used
+for the GCC extension to C that uses the syntax @code{(@{ @dots{} @})}.
+It is also used for the special functions that takes a statement block
+as an argument in Pike.
+
+@item inexpr-class
+On the first line of a class definition inside an expression. This is
+used for anonymous classes and anonymous array initializers in Java.
+
+@item cpp-macro
+On the start of a cpp macro.
+
+@item friend
+On a C++ @code{friend} declaration.
+
+@item objc-method-intro
+On the first line of an Objective-C method definition.
+
+@item objc-method-args-cont
+On one of the lines continuing an Objective-C method definition.
+
+@item objc-method-call-cont
+On one of the lines continuing an Objective-C method call.
+
+@item inlambda
+Like @code{inclass}, but used inside lambda (i.e. anonymous) functions. Only
+used in Pike.
+
+@item lambda-intro-cont
+On a line continuing the header of a lambda function, between the
+@code{lambda} keyword and the function body. Only used in Pike.
+@end table
+
+@node Variables for C Indent
+@subsubsection Variables for C Indentation
+
+ This section describes additional variables which control the
+indentation behavior of C mode and related mode.
+
+@table @code
+@item c-offsets-alist
+@vindex c-offsets-alist
+Association list of syntactic symbols and their indentation offsets.
+You should not set this directly, only with @code{c-set-offset}.
+@xref{Changing Indent Style}, for details.
+
+@item c-style-alist
+@vindex c-style-alist
+Variable for defining indentation styles; see below.
+
+@item c-basic-offset
+@vindex c-basic-offset
+Amount of basic offset used by @code{+} and @code{-} symbols in
+@code{c-offsets-alist}.@refill
+
+@item c-special-indent-hook
+@vindex c-special-indent-hook
+Hook for user-defined special indentation adjustments. This hook is
+called after a line is indented by C mode and related modes.
+@end table
+
+ The variable @code{c-style-alist} specifies the predefined indentation
+styles. Each element has form @code{(@var{name}
+@var{variable-setting}@dots{})}, where @var{name} is the name of the
+style. Each @var{variable-setting} has the form @code{(@var{variable}
+. @var{value})}; @var{variable} is one of the customization variables
+used by C mode, and @var{value} is the value for that variable when
+using the selected style.
+
+ When @var{variable} is @code{c-offsets-alist}, that is a special case:
+@var{value} is appended to the front of the value of @code{c-offsets-alist}
+instead of replacing that value outright. Therefore, it is not necessary
+for @var{value} to specify each and every syntactic symbol---only those
+for which the style differs from the default.
+
+ The indentation of lines containing only comments is also affected by
+the variable @code{c-comment-only-line-offset} (@pxref{Comments in C}).
+
+@node C Indent Styles
+@subsubsection C Indentation Styles
+@cindex c indentation styles
+
+ A @dfn{C style} is a collection of indentation style customizations.
+Emacs comes with several predefined indentation styles for C and related
+modes, including @code{gnu}, @code{k&r}, @code{bsd}, @code{stroustrup},
+@code{linux}, @code{python}, @code{java}, @code{whitesmith},
+@code{ellemtel}, and @code{cc-mode}. The default style is @code{gnu}.
+
+@findex c-set-style
+@vindex c-default-style
+ To choose the style you want, use the command @kbd{M-x c-set-style}.
+Specify a style name as an argument (case is not significant in C style
+names). The chosen style only affects newly visited buffers, not those
+you are already editing. You can also set the variable
+@code{c-default-style} to specify the style for various major modes.
+Its value should be an alist, in which each element specifies one major
+mode and which indentation style to use for it. For example,
+
+@example
+(setq c-default-style
+ '((java-mode . "java") (other . "gnu")))
+@end example
+
+@noindent
+specifies an explicit choice for Java mode, and the default @samp{gnu}
+style for the other C-like modes.
+
+@findex c-add-style
+ To define a new C indentation style, call the function
+@code{c-add-style}:
+
+@example
+(c-add-style @var{name} @var{values} @var{use-now})
+@end example
+
+@noindent
+Here @var{name} is the name of the new style (a string), and
+@var{values} is an alist whose elements have the form
+@code{(@var{variable} . @var{value})}. The variables you specify should
+be among those documented in @ref{Variables for C Indent}.
+
+If @var{use-now} is non-@code{nil}, @code{c-add-style} switches to the
+new style after defining it.
+
+@node Matching
+@section Automatic Display Of Matching Parentheses
+@cindex matching parentheses
+@cindex parentheses, displaying matches
+
+ The Emacs parenthesis-matching feature is designed to show
+automatically how parentheses match in the text. Whenever you type a
+self-inserting character that is a closing delimiter, the cursor moves
+momentarily to the location of the matching opening delimiter, provided
+that is on the screen. If it is not on the screen, some text near it is
+displayed in the echo area. Either way, you can tell what grouping is
+being closed off.
+
+ In Lisp, automatic matching applies only to parentheses. In C, it
+applies to braces and brackets too. Emacs knows which characters to regard
+as matching delimiters based on the syntax table, which is set by the major
+mode. @xref{Syntax}.
+
+ If the opening delimiter and closing delimiter are mismatched---such as
+in @samp{[x)}---a warning message is displayed in the echo area. The
+correct matches are specified in the syntax table.
+
+@vindex blink-matching-paren
+@vindex blink-matching-paren-distance
+@vindex blink-matching-delay
+ Three variables control parenthesis match display.
+@code{blink-matching-paren} turns the feature on or off; @code{nil}
+turns it off, but the default is @code{t} to turn match display on.
+@code{blink-matching-delay} says how many seconds to wait; the default
+is 1, but on some systems it is useful to specify a fraction of a
+second. @code{blink-matching-paren-distance} specifies how many
+characters back to search to find the matching opening delimiter. If
+the match is not found in that far, scanning stops, and nothing is
+displayed. This is to prevent scanning for the matching delimiter from
+wasting lots of time when there is no match. The default is 12,000.
+
+@cindex Show Paren mode
+@findex show-paren-mode
+ When using X Windows, you can request a more powerful alternative kind
+of automatic parenthesis matching by enabling Show Paren mode. This
+mode turns off the usual kind of matching parenthesis display and
+instead uses highlighting to show what matches. Whenever point is after
+a close parenthesis, the close parenthesis and its matching open
+parenthesis are both highlighted; otherwise, if point is before an open
+parenthesis, the matching close parenthesis is highlighted. (There is
+no need to highlight the open parenthesis after point because the cursor
+appears on top of that character.) Use the command @kbd{M-x
+show-paren-mode} to enable or disable this mode.
+
+@node Comments
+@section Manipulating Comments
+@cindex comments
+
+ Because comments are such an important part of programming, Emacs
+provides special commands for editing and inserting comments.
+
+@menu
+* Comment Commands::
+* Multi-Line Comments::
+* Options for Comments::
+@end menu
+
+@node Comment Commands
+@subsection Comment Commands
+
+@kindex M-;
+@cindex indentation for comments
+@findex indent-for-comment
+
+ The comment commands insert, kill and align comments.
+
+@c WideCommands
+@table @kbd
+@item M-;
+Insert or align comment (@code{indent-for-comment}).
+@item C-x ;
+Set comment column (@code{set-comment-column}).
+@item C-u - C-x ;
+Kill comment on current line (@code{kill-comment}).
+@item C-M-j
+Like @key{RET} followed by inserting and aligning a comment
+(@code{indent-new-comment-line}).
+@item M-x comment-region
+Add or remove comment delimiters on all the lines in the region.
+@end table
+
+ The command that creates a comment is @kbd{M-;} (@code{indent-for-comment}).
+If there is no comment already on the line, a new comment is created,
+aligned at a specific column called the @dfn{comment column}. The comment
+is created by inserting the string Emacs thinks comments should start with
+(the value of @code{comment-start}; see below). Point is left after that
+string. If the text of the line extends past the comment column, then the
+indentation is done to a suitable boundary (usually, at least one space is
+inserted). If the major mode has specified a string to terminate comments,
+that is inserted after point, to keep the syntax valid.
+
+ @kbd{M-;} can also be used to align an existing comment. If a line
+already contains the string that starts comments, then @kbd{M-;} just moves
+point after it and reindents it to the conventional place. Exception:
+comments starting in column 0 are not moved.
+
+ Some major modes have special rules for indenting certain kinds of
+comments in certain contexts. For example, in Lisp code, comments which
+start with two semicolons are indented as if they were lines of code,
+instead of at the comment column. Comments which start with three
+semicolons are supposed to start at the left margin. Emacs understands
+these conventions by indenting a double-semicolon comment using @key{TAB},
+and by not changing the indentation of a triple-semicolon comment at all.
+
+@example
+;; This function is just an example
+;;; Here either two or three semicolons are appropriate.
+(defun foo (x)
+;;; And now, the first part of the function:
+ ;; The following line adds one.
+ (1+ x)) ; This line adds one.
+@end example
+
+ In C code, a comment preceded on its line by nothing but whitespace
+is indented like a line of code.
+
+ Even when an existing comment is properly aligned, @kbd{M-;} is still
+useful for moving directly to the start of the comment.
+
+@kindex C-u - C-x ;
+@findex kill-comment
+ @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line,
+if there is one. The indentation before the start of the comment is killed
+as well. If there does not appear to be a comment in the line, nothing is
+done. To reinsert the comment on another line, move to the end of that
+line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that
+@kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
+with a negative argument. That command is programmed so that when it
+receives a negative argument it calls @code{kill-comment}. However,
+@code{kill-comment} is a valid command which you could bind directly to a
+key if you wanted to.
+
+@node Multi-Line Comments
+@subsection Multiple Lines of Comments
+
+@kindex C-M-j
+@cindex blank lines in programs
+@findex indent-new-comment-line
+ If you are typing a comment and wish to continue it on another line,
+you can use the command @kbd{C-M-j} (@code{indent-new-comment-line}).
+This terminates the comment you are typing, creates a new blank line
+afterward, and begins a new comment indented under the old one. When
+Auto Fill mode is on, going past the fill column while typing a comment
+causes the comment to be continued in just this fashion. If point is
+not at the end of the line when @kbd{C-M-j} is typed, the text on
+the rest of the line becomes part of the new comment line.
+
+@findex comment-region
+ To turn existing lines into comment lines, use the @kbd{M-x
+comment-region} command. It adds comment delimiters to the lines that start
+in the region, thus commenting them out. With a negative argument, it
+does the opposite---it deletes comment delimiters from the lines in the
+region.
+
+ With a positive argument, @code{comment-region} duplicates the last
+character of the comment start sequence it adds; the argument specifies
+how many copies of the character to insert. Thus, in Lisp mode,
+@kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating
+the comment delimiter is a way of calling attention to the comment. It
+can also affect how the comment is indented. In Lisp, for proper
+indentation, you should use an argument of two, if between defuns, and
+three, if within a defun.
+
+@vindex comment-padding
+ The variable @code{comment-padding} specifies how many spaces
+@code{comment-region} should insert on each line between the
+comment delimiter and the line's original text. The default is 1.
+
+@node Options for Comments
+@subsection Options Controlling Comments
+
+@vindex comment-column
+@kindex C-x ;
+@findex set-comment-column
+ The comment column is stored in the variable @code{comment-column}. You
+can set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
+(@code{set-comment-column}) sets the comment column to the column point is
+at. @kbd{C-u C-x ;} sets the comment column to match the last comment
+before point in the buffer, and then does a @kbd{M-;} to align the
+current line's comment under the previous one. Note that @kbd{C-u - C-x ;}
+runs the function @code{kill-comment} as described above.
+
+ The variable @code{comment-column} is per-buffer: setting the variable
+in the normal fashion affects only the current buffer, but there is a
+default value which you can change with @code{setq-default}.
+@xref{Locals}. Many major modes initialize this variable for the
+current buffer.
+
+@vindex comment-start-skip
+ The comment commands recognize comments based on the regular
+expression that is the value of the variable @code{comment-start-skip}.
+Make sure this regexp does not match the null string. It may match more
+than the comment starting delimiter in the strictest sense of the word;
+for example, in C mode the value of the variable is @code{@t{"/\\*+
+*"}}, which matches extra stars and spaces after the @samp{/*} itself.
+(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
+the string, which is needed to deny the first star its special meaning
+in regexp syntax. @xref{Regexps}.)
+
+@vindex comment-start
+@vindex comment-end
+ When a comment command makes a new comment, it inserts the value of
+@code{comment-start} to begin it. The value of @code{comment-end} is
+inserted after point, so that it will follow the text that you will insert
+into the comment. In C mode, @code{comment-start} has the value
+@w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
+
+@vindex comment-multi-line
+ The variable @code{comment-multi-line} controls how @kbd{C-M-j}
+(@code{indent-new-comment-line}) behaves when used inside a comment. If
+@code{comment-multi-line} is @code{nil}, as it normally is, then the
+comment on the starting line is terminated and a new comment is started
+on the new following line. If @code{comment-multi-line} is not
+@code{nil}, then the new following line is set up as part of the same
+comment that was found on the starting line. This is done by not
+inserting a terminator on the old line, and not inserting a starter on
+the new line. In languages where multi-line comments work, the choice
+of value for this variable is a matter of taste.
+
+@vindex comment-indent-function
+ The variable @code{comment-indent-function} should contain a function
+that will be called to compute the indentation for a newly inserted
+comment or for aligning an existing comment. It is set differently by
+various major modes. The function is called with no arguments, but with
+point at the beginning of the comment, or at the end of a line if a new
+comment is to be inserted. It should return the column in which the
+comment ought to start. For example, in Lisp mode, the indent hook
+function bases its decision on how many semicolons begin an existing
+comment, and on the code in the preceding lines.
+
+@node Balanced Editing
+@section Editing Without Unbalanced Parentheses
+
+@table @kbd
+@item M-(
+Put parentheses around next sexp(s) (@code{insert-parentheses}).
+@item M-)
+Move past next close parenthesis and reindent
+(@code{move-past-close-and-reindent}).
+@end table
+
+@kindex M-(
+@kindex M-)
+@findex insert-parentheses
+@findex move-past-close-and-reindent
+ The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
+(@code{move-past-close-and-reindent}) are designed to facilitate a style
+of editing which keeps parentheses balanced at all times. @kbd{M-(}
+inserts a pair of parentheses, either together as in @samp{()}, or, if
+given an argument, around the next several sexps. It leaves point after
+the open parenthesis. The command @kbd{M-)} moves past the close
+parenthesis, deleting any indentation preceding it, and indenting with
+@kbd{C-j} after it.
+
+ For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-(
+F O O}, which has the same effect except for leaving the cursor before
+the close parenthesis.
+
+@vindex parens-require-spaces
+ @kbd{M-(} may insert a space before the open parenthesis, depending on
+the syntax class of the preceding character. Set
+@code{parens-require-spaces} to @code{nil} value if you wish to inhibit
+this.
+
+@node Symbol Completion
+@section Completion for Symbol Names
+@cindex completion (symbol names)
+
+ Usually completion happens in the minibuffer. But one kind of completion
+is available in all buffers: completion for symbol names.
+
+@kindex M-TAB
+ The character @kbd{M-@key{TAB}} runs a command to complete the partial
+symbol before point against the set of meaningful symbol names. Any
+additional characters determined by the partial name are inserted at
+point.
+
+ If the partial name in the buffer has more than one possible completion
+and they have no additional characters in common, a list of all possible
+completions is displayed in another window.
+
+@cindex completion using tags
+@cindex tags completion
+@cindex Info index completion
+@findex complete-symbol
+ In most programming language major modes, @kbd{M-@key{TAB}} runs the
+command @code{complete-symbol}, which provides two kinds of completion.
+Normally it does completion based on a tags table (@pxref{Tags}); with a
+numeric argument (regardless of the value), it does completion based on
+the names listed in the Info file indexes for your language. Thus, to
+complete the name of a symbol defined in your own program, use
+@kbd{M-@key{TAB}} with no argument; to complete the name of a standard
+library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
+completion works only if there is an Info file for the standard library
+functions of your language, and only if it is installed at your site.
+
+@cindex Lisp symbol completion
+@cindex completion in Lisp
+@findex lisp-complete-symbol
+ In Emacs-Lisp mode, the name space for completion normally consists of
+nontrivial symbols present in Emacs---those that have function
+definitions, values or properties. However, if there is an
+open-parenthesis immediately before the beginning of the partial symbol,
+only symbols with function definitions are considered as completions.
+The command which implements this is @code{lisp-complete-symbol}.
+
+ In Text mode and related modes, @kbd{M-@key{TAB}} completes words
+based on the spell-checker's dictionary. @xref{Spelling}.
+
+@node Which Function
+@section Which Function Mode
+
+ Which Function mode is a minor mode that displays the current function
+name in the mode line, as you move around in a buffer.
+
+@findex which-function-mode
+@vindex which-func-modes
+ To enable (or disable) Which Function mode, use the command @kbd{M-x
+which-function-mode}. This command is global; it applies to all
+buffers, both existing ones and those yet to be created. However, this
+only affects certain major modes, those listed in the value of
+@code{which-func-modes}. (If the value is @code{t}, then Which Function
+mode applies to all major modes that know how to support it---which are
+the major modes that support Imenu.)
+
+@node Documentation
+@section Documentation Commands
+
+ As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
+(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
+be used to print documentation of functions and variables that you want to
+call. These commands use the minibuffer to read the name of a function or
+variable to document, and display the documentation in a window.
+
+ For extra convenience, these commands provide default arguments based on
+the code in the neighborhood of point. @kbd{C-h f} sets the default to the
+function called in the innermost list containing point. @kbd{C-h v} uses
+the symbol name around or adjacent to point as its default.
+
+@cindex Eldoc mode
+@findex eldoc-mode
+ For Emacs Lisp code, you can also use Eldoc mode. This minor mode
+constantly displays in the echo area the argument list for the function
+being called at point. (In other words, it finds the function call that
+point is contained in, and displays the argument list of that function.)
+Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use
+the command @kbd{M-x eldoc-mode} to enable or disable this feature.
+
+@findex info-lookup-symbol
+@findex info-lookup-file
+@kindex C-h C-i
+ For C, Lisp, and other languages, you can use @kbd{C-h C-i}
+(@code{info-lookup-symbol}) to view the Info documentation for a symbol.
+You specify the symbol with the minibuffer; by default, it uses the
+symbol that appears in the buffer at point. The major mode determines
+where to look for documentation for the symbol---which Info files and
+which indices. You can also use @kbd{M-x info-lookup-file} to look for
+documentation for a file name.
+
+@findex manual-entry
+ You can read the ``man page'' for an operating system command, library
+function, or system call, with the @kbd{M-x manual-entry} command. It
+runs the @code{man} program to format the man page, and runs it
+asynchronously if your system permits, so that you can keep on editing
+while the page is being formatted. (MS-DOS and MS-Windows 3 do not
+permit asynchronous subprocesses, so on these systems you cannot edit
+while Emacs waits for @code{man} to exit.) The result goes in a buffer
+named @samp{*Man @var{topic}*}. These buffers use a special major mode,
+Man mode, that facilitates scrolling and examining other manual pages.
+For details, type @kbd{C-h m} while in a man page buffer.
+
+@vindex Man-fontify-manpage-flag
+ For a long man page, setting the faces properly can take substantial
+time. By default, Emacs uses faces in man pages if Emacs can display
+different fonts or colors. You can turn off use of faces in man pages
+by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}.
+
+@findex Man-fontify-manpage
+ If you insert the text of a man page into an Emacs buffer in some
+other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
+perform the same conversions that @kbd{M-x manual-entry} does.
+
+ Eventually the GNU project hopes to replace most man pages with
+better-organized manuals that you can browse with Info. @xref{Misc
+Help}. Since this process is only partially completed, it is still
+useful to read manual pages.
+
+@node Change Log
+@section Change Logs
+
+@cindex change log
+@kindex C-x 4 a
+@findex add-change-log-entry-other-window
+ The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
+file for the file you are editing
+(@code{add-change-log-entry-other-window}).
+
+ A change log file contains a chronological record of when and why you
+have changed a program, consisting of a sequence of entries describing
+individual changes. Normally it is kept in a file called
+@file{ChangeLog} in the same directory as the file you are editing, or
+one of its parent directories. A single @file{ChangeLog} file can
+record changes for all the files in its directory and all its
+subdirectories.
+
+ A change log entry starts with a header line that contains your name,
+your email address (taken from the variable @code{user-mail-address}),
+and the current date and time. Aside from these header lines, every
+line in the change log starts with a space or a tab. The bulk of the
+entry consists of @dfn{items}, each of which starts with a line starting
+with whitespace and a star. Here are two entries, both dated in May
+1993, each with two items:
+
+@iftex
+@medbreak
+@end iftex
+@smallexample
+1993-05-25 Richard Stallman <rms@@gnu.org>
+
+ * man.el: Rename symbols `man-*' to `Man-*'.
+ (manual-entry): Make prompt string clearer.
+
+ * simple.el (blink-matching-paren-distance):
+ Change default to 12,000.
+
+1993-05-24 Richard Stallman <rms@@gnu.org>
+
+ * vc.el (minor-mode-map-alist): Don't use it if it's void.
+ (vc-cancel-version): Doc fix.
+@end smallexample
+
+@noindent
+(Previous Emacs versions used a different format for the date.)
+
+ One entry can describe several changes; each change should have its
+own item. Normally there should be a blank line between items. When
+items are related (parts of the same change, in different places), group
+them by leaving no blank line between them. The second entry above
+contains two items grouped in this way.
+
+ @kbd{C-x 4 a} visits the change log file and creates a new entry
+unless the most recent entry is for today's date and your name. It also
+creates a new item for the current file. For many languages, it can
+even guess the name of the function or other object that was changed.
+
+@cindex Change Log mode
+@findex change-log-mode
+ The change log file is visited in Change Log mode. In this major
+mode, each bunch of grouped items counts as one paragraph, and each
+entry is considered a page. This facilitates editing the entries.
+@kbd{C-j} and auto-fill indent each new line like the previous line;
+this is convenient for entering the contents of an entry.
+
+ Version control systems are another way to keep track of changes in your
+program and keep a change log. @xref{Log Buffer}.
+
+@node Tags
+@section Tags Tables
+@cindex tags table
+
+ A @dfn{tags table} is a description of how a multi-file program is
+broken up into files. It lists the names of the component files and the
+names and positions of the functions (or other named subunits) in each
+file. Grouping the related files makes it possible to search or replace
+through all the files with one command. Recording the function names
+and positions makes possible the @kbd{M-.} command which finds the
+definition of a function by looking up which of the files it is in.
+
+ Tags tables are stored in files called @dfn{tags table files}. The
+conventional name for a tags table file is @file{TAGS}.
+
+ Each entry in the tags table records the name of one tag, the name of the
+file that the tag is defined in (implicitly), and the position in that file
+of the tag's definition.
+
+ Just what names from the described files are recorded in the tags table
+depends on the programming language of the described file. They
+normally include all functions and subroutines, and may also include
+global variables, data types, and anything else convenient. Each name
+recorded is called a @dfn{tag}.
+
+@menu
+* Tag Syntax:: Tag syntax for various types of code and text files.
+* Create Tags Table:: Creating a tags table with @code{etags}.
+* Select Tags Table:: How to visit a tags table.
+* Find Tag:: Commands to find the definition of a specific tag.
+* Tags Search:: Using a tags table for searching and replacing.
+* List Tags:: Listing and finding tags defined in a file.
+@end menu
+
+@node Tag Syntax
+@subsection Source File Tag Syntax
+
+ Here is how tag syntax is defined for the most popular languages:
+
+@itemize @bullet
+@item
+In C code, any C function or typedef is a tag, and so are definitions of
+@code{struct}, @code{union} and @code{enum}. @code{#define} macro
+definitions and @code{enum} constants are also tags, unless you specify
+@samp{--no-defines} when making the tags table. Similarly, global
+variables are tags, unless you specify @samp{--no-globals}. Use of
+@samp{--no-globals} and @samp{--no-defines} can make the tags table file
+much smaller.
+
+@item
+In C++ code, in addition to all the tag constructs of C code, member
+functions are also recognized, and optionally member variables if you
+use the @samp{--members} option. Tags for variables and functions in
+classes are named @samp{@var{class}::@var{variable}} and
+@samp{@var{class}::@var{function}}.
+
+@item
+In Java code, tags include all the constructs recognized in C++, plus
+the @code{extends} and @code{implements} constructs. Tags for variables
+and functions in classes are named @samp{@var{class}.@var{variable}} and
+@samp{@var{class}.@var{function}}.
+
+@item
+In La@TeX{} text, the argument of any of the commands @code{\chapter},
+@code{\section}, @code{\subsection}, @code{\subsubsection},
+@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
+@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
+tag.@refill
+
+Other commands can make tags as well, if you specify them in the
+environment variable @code{TEXTAGS} before invoking @code{etags}. The
+value of this environment variable should be a colon-separated list of
+command names. For example,
+
+@example
+TEXTAGS="def:newcommand:newenvironment"
+export TEXTAGS
+@end example
+
+@noindent
+specifies (using Bourne shell syntax) that the commands @samp{\def},
+@samp{\newcommand} and @samp{\newenvironment} also define tags.
+
+@item
+In Lisp code, any function defined with @code{defun}, any variable
+defined with @code{defvar} or @code{defconst}, and in general the first
+argument of any expression that starts with @samp{(def} in column zero, is
+a tag.
+
+@item
+In Scheme code, tags include anything defined with @code{def} or with a
+construct whose name starts with @samp{def}. They also include variables
+set with @code{set!} at top level in the file.
+@end itemize
+
+ Several other languages are also supported:
+
+@itemize @bullet
+@item
+In assembler code, labels appearing at the beginning of a line,
+followed by a colon, are tags.
+
+@item
+In Bison or Yacc input files, each rule defines as a tag the nonterminal
+it constructs. The portions of the file that contain C code are parsed
+as C code.
+
+@item
+In Cobol code, tags are paragraph names; that is, any word starting in
+column 8 and followed by a period.
+
+@item
+In Erlang code, the tags are the functions, records, and macros defined
+in the file.
+
+@item
+In Fortran code, functions, subroutines and blockdata are tags.
+
+@item
+In Objective C code, tags include Objective C definitions for classes,
+class categories, methods, and protocols.
+
+@item
+In Pascal code, the tags are the functions and procedures defined in
+the file.
+
+@item
+In Perl code, the tags are the procedures defined by the @code{sub}
+keyword.
+
+@item
+In Postscript code, the tags are the functions.
+
+@item
+In Prolog code, a tag name appears at the left margin.
+@end itemize
+
+ You can also generate tags based on regexp matching (@pxref{Create
+Tags Table}) to handle other formats and languages.
+
+@node Create Tags Table
+@subsection Creating Tags Tables
+@cindex @code{etags} program
+
+ The @code{etags} program is used to create a tags table file. It knows
+the syntax of several languages, as described in
+@iftex
+the previous section.
+@end iftex
+@ifinfo
+@ref{Tag Syntax}.
+@end ifinfo
+Here is how to run @code{etags}:
+
+@example
+etags @var{inputfiles}@dots{}
+@end example
+
+@noindent
+The @code{etags} program reads the specified files, and writes a tags table
+named @file{TAGS} in the current working directory. @code{etags}
+recognizes the language used in an input file based on its file name and
+contents. You can specify the language with the
+@samp{--language=@var{name}} option, described below.
+
+ If the tags table data become outdated due to changes in the files
+described in the table, the way to update the tags table is the same way it
+was made in the first place. It is not necessary to do this often.
+
+ If the tags table fails to record a tag, or records it for the wrong
+file, then Emacs cannot possibly find its definition. However, if the
+position recorded in the tags table becomes a little bit wrong (due to
+some editing in the file that the tag definition is in), the only
+consequence is a slight delay in finding the tag. Even if the stored
+position is very wrong, Emacs will still find the tag, but it must
+search the entire file for it.
+
+ So you should update a tags table when you define new tags that you want
+to have listed, or when you move tag definitions from one file to another,
+or when changes become substantial. Normally there is no need to update
+the tags table after each edit, or even every day.
+
+ One tags table can effectively include another. Specify the included
+tags file name with the @samp{--include=@var{file}} option when creating
+the file that is to include it. The latter file then acts as if it
+contained all the files specified in the included file, as well as the
+files it directly contains.
+
+ If you specify the source files with relative file names when you run
+@code{etags}, the tags file will contain file names relative to the
+directory where the tags file was initially written. This way, you can
+move an entire directory tree containing both the tags file and the
+source files, and the tags file will still refer correctly to the source
+files.
+
+ If you specify absolute file names as arguments to @code{etags}, then
+the tags file will contain absolute file names. This way, the tags file
+will still refer to the same files even if you move it, as long as the
+source files remain in the same place. Absolute file names start with
+@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
+
+ When you want to make a tags table from a great number of files, you
+may have problems listing them on the command line, because some systems
+have a limit on its length. The simplest way to circumvent this limit
+is to tell @code{etags} to read the file names from its standard input,
+by typing a dash in place of the file names, like this:
+
+@example
+find . -name "*.[chCH]" -print | etags -
+@end example
+
+ Use the option @samp{--language=@var{name}} to specify the language
+explicitly. You can intermix these options with file names; each one
+applies to the file names that follow it. Specify
+@samp{--language=auto} to tell @code{etags} to resume guessing the
+language from the file names and file contents. Specify
+@samp{--language=none} to turn off language-specific processing
+entirely; then @code{etags} recognizes tags by regexp matching alone.
+@samp{etags --help} prints the list of the languages @code{etags} knows,
+and the file name rules for guessing the language.
+
+ The @samp{--regex} option provides a general way of recognizing tags
+based on regexp matching. You can freely intermix it with file names.
+Each @samp{--regex} option adds to the preceding ones, and applies only
+to the following files. The syntax is:
+
+@example
+--regex=/@var{tagregexp}[/@var{nameregexp}]/
+@end example
+
+@noindent
+where @var{tagregexp} is used to match the lines to tag. It is always
+anchored, that is, it behaves as if preceded by @samp{^}. If you want
+to account for indentation, just match any initial number of blanks by
+beginning your regular expression with @samp{[ \t]*}. In the regular
+expressions, @samp{\} quotes the next character, and @samp{\t} stands
+for the tab character. Note that @code{etags} does not handle the other
+C escape sequences for special characters.
+
+@cindex interval operator (in regexps)
+ The syntax of regular expressions in @code{etags} is the same as in
+Emacs, augmented with the @dfn{interval operator}, which works as in
+@code{grep} and @code{ed}. The syntax of an interval operator is
+@samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
+expression at least @var{m} times and up to @var{n} times.
+
+ You should not match more characters with @var{tagregexp} than that
+needed to recognize what you want to tag. If the match is such that
+more characters than needed are unavoidably matched by @var{tagregexp},
+you may find useful to add a @var{nameregexp}, in order to narrow the tag
+scope. You can find some examples below.
+
+ The @samp{-R} option deletes all the regexps defined with
+@samp{--regex} options. It applies to the file names following it, as
+you can see from the following example:
+
+@example
+etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
+ bar.ber -R --lang=lisp los.er
+@end example
+
+@noindent
+Here @code{etags} chooses the parsing language for @file{voo.doo} and
+@file{bar.ber} according to their contents. @code{etags} also uses
+@var{reg1} to recognize additional tags in @file{voo.doo}, and both
+@var{reg1} and @var{reg2} to recognize additional tags in
+@file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
+matching, to recognize tags in @file{los.er}.
+
+ Here are some more examples. The regexps are quoted to protect them
+from shell interpretation.
+
+@itemize @bullet
+@item
+Tag the @code{DEFVAR} macros in the emacs source files:
+
+@smallexample
+--regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+@end smallexample
+
+@item
+Tag VHDL files (this example is a single long line, broken here for
+formatting reasons):
+
+@smallexample
+--language=none
+--regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
+--regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+@end smallexample
+
+@item
+Tag Tcl files (this last example shows the usage of a @var{nameregexp}):
+
+@smallexample
+--lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'
+@end smallexample
+@end itemize
+
+ For a list of the other available @code{etags} options, execute
+@code{etags --help}.
+
+@node Select Tags Table
+@subsection Selecting a Tags Table
+
+@vindex tags-file-name
+@findex visit-tags-table
+ Emacs has at any time one @dfn{selected} tags table, and all the commands
+for working with tags tables use the selected one. To select a tags table,
+type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
+argument. The name @file{TAGS} in the default directory is used as the
+default file name.
+
+ All this command does is store the file name in the variable
+@code{tags-file-name}. Emacs does not actually read in the tags table
+contents until you try to use them. Setting this variable yourself is just
+as good as using @code{visit-tags-table}. The variable's initial value is
+@code{nil}; that value tells all the commands for working with tags tables
+that they must ask for a tags table file name to use.
+
+ Using @code{visit-tags-table} when a tags table is already loaded
+gives you a choice: you can add the new tags table to the current list
+of tags tables, or start a new list. The tags commands use all the tags
+tables in the current list. If you start a new list, the new tags table
+is used @emph{instead} of others. If you add the new table to the
+current list, it is used @emph{as well as} the others. When the tags
+commands scan the list of tags tables, they don't always start at the
+beginning of the list; they start with the first tags table (if any)
+that describes the current file, proceed from there to the end of the
+list, and then scan from the beginning of the list until they have
+covered all the tables in the list.
+
+@vindex tags-table-list
+ You can specify a precise list of tags tables by setting the variable
+@code{tags-table-list} to a list of strings, like this:
+
+@c keep this on two lines for formatting in smallbook
+@example
+@group
+(setq tags-table-list
+ '("~/emacs" "/usr/local/lib/emacs/src"))
+@end group
+@end example
+
+@noindent
+This tells the tags commands to look at the @file{TAGS} files in your
+@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
+directory. The order depends on which file you are in and which tags
+table mentions that file, as explained above.
+
+ Do not set both @code{tags-file-name} and @code{tags-table-list}.
+
+@node Find Tag
+@subsection Finding a Tag
+
+ The most important thing that a tags table enables you to do is to find
+the definition of a specific tag.
+
+@table @kbd
+@item M-.@: @var{tag} @key{RET}
+Find first definition of @var{tag} (@code{find-tag}).
+@item C-u M-.
+Find next alternate definition of last tag specified.
+@item C-u - M-.
+Go back to previous tag found.
+@item C-M-. @var{pattern} @key{RET}
+Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
+@item C-u C-M-.
+Find the next tag whose name matches the last pattern used.
+@item C-x 4 .@: @var{tag} @key{RET}
+Find first definition of @var{tag}, but display it in another window
+(@code{find-tag-other-window}).
+@item C-x 5 .@: @var{tag} @key{RET}
+Find first definition of @var{tag}, and create a new frame to select the
+buffer (@code{find-tag-other-frame}).
+@item M-*
+Pop back to where you previously invoked @kbd{M-.} and friends.
+@end table
+
+@kindex M-.
+@findex find-tag
+ @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
+a specified tag. It searches through the tags table for that tag, as a
+string, and then uses the tags table info to determine the file that the
+definition is in and the approximate character position in the file of
+the definition. Then @code{find-tag} visits that file, moves point to
+the approximate character position, and searches ever-increasing
+distances away to find the tag definition.
+
+ If an empty argument is given (just type @key{RET}), the sexp in the
+buffer before or around point is used as the @var{tag} argument.
+@xref{Lists}, for info on sexps.
+
+ You don't need to give @kbd{M-.} the full name of the tag; a part
+will do. This is because @kbd{M-.} finds tags in the table which
+contain @var{tag} as a substring. However, it prefers an exact match
+to a substring match. To find other tags that match the same
+substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
+M-.}; this does not read a tag name, but continues searching the tags
+table's text for another tag containing the same substring last used.
+If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
+alternative to @kbd{C-u M-.}.
+
+@kindex C-x 4 .
+@findex find-tag-other-window
+@kindex C-x 5 .
+@findex find-tag-other-frame
+ Like most commands that can switch buffers, @code{find-tag} has a
+variant that displays the new buffer in another window, and one that
+makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
+the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
+which invokes @code{find-tag-other-frame}.
+
+ To move back to places you've found tags recently, use @kbd{C-u -
+M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
+command can take you to another buffer. @kbd{C-x 4 .} with a negative
+argument finds the previous tag location in another window.
+
+@kindex M-*
+@findex pop-tag-mark
+@vindex find-tag-marker-ring-length
+ As well as going back to places you've found tags recently, you can go
+back to places @emph{from where} you found them. Use @kbd{M-*}, which
+invokes the command @code{pop-tag-mark}, for this. Typically you would
+find and study the definition of something with @kbd{M-.} and then
+return to where you were with @kbd{M-*}.
+
+ Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
+a depth determined by the variable @code{find-tag-marker-ring-length}.
+
+@findex find-tag-regexp
+@kindex C-M-.
+ The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
+match a specified regular expression. It is just like @kbd{M-.} except
+that it does regexp matching instead of substring matching.
+
+@node Tags Search
+@subsection Searching and Replacing with Tags Tables
+
+ The commands in this section visit and search all the files listed in the
+selected tags table, one by one. For these commands, the tags table serves
+only to specify a sequence of files to search.
+
+@table @kbd
+@item M-x tags-search @key{RET} @var{regexp} @key{RET}
+Search for @var{regexp} through the files in the selected tags
+table.
+@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
+Perform a @code{query-replace-regexp} on each file in the selected tags table.
+@item M-,
+Restart one of the commands above, from the current location of point
+(@code{tags-loop-continue}).
+@end table
+
+@findex tags-search
+ @kbd{M-x tags-search} reads a regexp using the minibuffer, then
+searches for matches in all the files in the selected tags table, one
+file at a time. It displays the name of the file being searched so you
+can follow its progress. As soon as it finds an occurrence,
+@code{tags-search} returns.
+
+@kindex M-,
+@findex tags-loop-continue
+ Having found one match, you probably want to find all the rest. To find
+one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
+@code{tags-search}. This searches the rest of the current buffer, followed
+by the remaining files of the tags table.@refill
+
+@findex tags-query-replace
+ @kbd{M-x tags-query-replace} performs a single
+@code{query-replace-regexp} through all the files in the tags table. It
+reads a regexp to search for and a string to replace with, just like
+ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
+tags-search}, but repeatedly, processing matches according to your
+input. @xref{Replace}, for more information on query replace.
+
+ It is possible to get through all the files in the tags table with a
+single invocation of @kbd{M-x tags-query-replace}. But often it is
+useful to exit temporarily, which you can do with any input event that
+has no special query replace meaning. You can resume the query replace
+subsequently by typing @kbd{M-,}; this command resumes the last tags
+search or replace command that you did.
+
+ The commands in this section carry out much broader searches than the
+@code{find-tag} family. The @code{find-tag} commands search only for
+definitions of tags that match your substring or regexp. The commands
+@code{tags-search} and @code{tags-query-replace} find every occurrence
+of the regexp, as ordinary search commands and replace commands do in
+the current buffer.
+
+ These commands create buffers only temporarily for the files that they
+have to search (those which are not already visited in Emacs buffers).
+Buffers in which no match is found are quickly killed; the others
+continue to exist.
+
+ It may have struck you that @code{tags-search} is a lot like
+@code{grep}. You can also run @code{grep} itself as an inferior of
+Emacs and have Emacs show you the matching lines one by one. This works
+much like running a compilation; finding the source locations of the
+@code{grep} matches works like finding the compilation errors.
+@xref{Compilation}.
+
+@node List Tags
+@subsection Tags Table Inquiries
+
+@table @kbd
+@item M-x list-tags @key{RET} @var{file} @key{RET}
+Display a list of the tags defined in the program file @var{file}.
+@item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
+Display a list of all tags matching @var{regexp}.
+@end table
+
+@findex list-tags
+ @kbd{M-x list-tags} reads the name of one of the files described by
+the selected tags table, and displays a list of all the tags defined in
+that file. The ``file name'' argument is really just a string to
+compare against the file names recorded in the tags table; it is read as
+a string rather than as a file name. Therefore, completion and
+defaulting are not available, and you must enter the file name the same
+way it appears in the tags table. Do not include a directory as part of
+the file name unless the file name recorded in the tags table includes a
+directory.
+
+@findex tags-apropos
+ @kbd{M-x tags-apropos} is like @code{apropos} for tags
+(@pxref{Apropos}). It reads a regexp, then finds all the tags in the
+selected tags table whose entries match that regexp, and displays the
+tag names found.
+
+ You can also perform completion in the buffer on the name space of tag
+names in the current tags tables. @xref{Symbol Completion}.
+
+@node Emerge
+@section Merging Files with Emerge
+@cindex Emerge
+@cindex merging files
+
+It's not unusual for programmers to get their signals crossed and modify
+the same program in two different directions. To recover from this
+confusion, you need to merge the two versions. Emerge makes this
+easier. See also @ref{Comparing Files}, for commands to compare
+in a more manual fashion, and @ref{Emerge,,, ediff, The Ediff Manual}.
+
+@menu
+* Overview of Emerge:: How to start Emerge. Basic concepts.
+* Submodes of Emerge:: Fast mode vs. Edit mode.
+ Skip Prefers mode and Auto Advance mode.
+* State of Difference:: You do the merge by specifying state A or B
+ for each difference.
+* Merge Commands:: Commands for selecting a difference,
+ changing states of differences, etc.
+* Exiting Emerge:: What to do when you've finished the merge.
+* Combining in Emerge:: How to keep both alternatives for a difference.
+* Fine Points of Emerge:: Misc.
+@end menu
+
+@node Overview of Emerge
+@subsection Overview of Emerge
+
+To start Emerge, run one of these four commands:
+
+@table @kbd
+@item M-x emerge-files
+@findex emerge-files
+Merge two specified files.
+
+@item M-x emerge-files-with-ancestor
+@findex emerge-files-with-ancestor
+Merge two specified files, with reference to a common ancestor.
+
+@item M-x emerge-buffers
+@findex emerge-buffers
+Merge two buffers.
+
+@item M-x emerge-buffers-with-ancestor
+@findex emerge-buffers-with-ancestor
+Merge two buffers with reference to a common ancestor in a third
+buffer.
+@end table
+
+@cindex merge buffer (Emerge)
+@cindex A and B buffers (Emerge)
+ The Emerge commands compare two files or buffers, and display the
+comparison in three buffers: one for each input text (the @dfn{A buffer}
+and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
+takes place. The merge buffer shows the full merged text, not just the
+differences. Wherever the two input texts differ, you can choose which
+one of them to include in the merge buffer.
+
+ The Emerge commands that take input from existing buffers use only the
+accessible portions of those buffers, if they are narrowed
+(@pxref{Narrowing}).
+
+ If a common ancestor version is available, from which the two texts to
+be merged were both derived, Emerge can use it to guess which
+alternative is right. Wherever one current version agrees with the
+ancestor, Emerge presumes that the other current version is a deliberate
+change which should be kept in the merged version. Use the
+@samp{with-ancestor} commands if you want to specify a common ancestor
+text. These commands read three file or buffer names---variant A,
+variant B, and the common ancestor.
+
+ After the comparison is done and the buffers are prepared, the
+interactive merging starts. You control the merging by typing special
+@dfn{merge commands} in the merge buffer. The merge buffer shows you a
+full merged text, not just differences. For each run of differences
+between the input texts, you can choose which one of them to keep, or
+edit them both together.
+
+ The merge buffer uses a special major mode, Emerge mode, with commands
+for making these choices. But you can also edit the buffer with
+ordinary Emacs commands.
+
+ At any given time, the attention of Emerge is focused on one
+particular difference, called the @dfn{selected} difference. This
+difference is marked off in the three buffers like this:
+
+@example
+vvvvvvvvvvvvvvvvvvvv
+@var{text that differs}
+^^^^^^^^^^^^^^^^^^^^
+@end example
+
+@noindent
+Emerge numbers all the differences sequentially and the mode
+line always shows the number of the selected difference.
+
+ Normally, the merge buffer starts out with the A version of the text.
+But when the A version of a difference agrees with the common ancestor,
+then the B version is initially preferred for that difference.
+
+ Emerge leaves the merged text in the merge buffer when you exit. At
+that point, you can save it in a file with @kbd{C-x C-w}. If you give a
+numeric argument to @code{emerge-files} or
+@code{emerge-files-with-ancestor}, it reads the name of the output file
+using the minibuffer. (This is the last file name those commands read.)
+Then exiting from Emerge saves the merged text in the output file.
+
+ Normally, Emerge commands save the output buffer in its file when you
+exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
+save the output buffer, but you can save it yourself if you wish.
+
+@node Submodes of Emerge
+@subsection Submodes of Emerge
+
+ You can choose between two modes for giving merge commands: Fast mode
+and Edit mode. In Fast mode, basic merge commands are single
+characters, but ordinary Emacs commands are disabled. This is
+convenient if you use only merge commands. In Edit mode, all merge
+commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
+commands are also available. This allows editing the merge buffer, but
+slows down Emerge operations.
+
+ Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
+Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
+and @samp{F}.
+
+ Emerge has two additional submodes that affect how particular merge
+commands work: Auto Advance mode and Skip Prefers mode.
+
+ If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
+advance to the next difference. This lets you go through the merge
+faster as long as you simply choose one of the alternatives from the
+input. The mode line indicates Auto Advance mode with @samp{A}.
+
+ If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
+skip over differences in states prefer-A and prefer-B (@pxref{State of
+Difference}). Thus you see only differences for which neither version
+is presumed ``correct.'' The mode line indicates Skip Prefers mode with
+@samp{S}.
+
+@findex emerge-auto-advance-mode
+@findex emerge-skip-prefers-mode
+ Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
+clear Auto Advance mode. Use @kbd{s s}
+(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
+These commands turn on the mode with a positive argument, turns it off
+with a negative or zero argument, and toggle the mode with no argument.
+
+@node State of Difference
+@subsection State of a Difference
+
+ In the merge buffer, a difference is marked with lines of @samp{v} and
+@samp{^} characters. Each difference has one of these seven states:
+
+@table @asis
+@item A
+The difference is showing the A version. The @kbd{a} command always
+produces this state; the mode line indicates it with @samp{A}.
+
+@item B
+The difference is showing the B version. The @kbd{b} command always
+produces this state; the mode line indicates it with @samp{B}.
+
+@item default-A
+@itemx default-B
+The difference is showing the A or the B state by default, because you
+haven't made a choice. All differences start in the default-A state
+(and thus the merge buffer is a copy of the A buffer), except those for
+which one alternative is ``preferred'' (see below).
+
+When you select a difference, its state changes from default-A or
+default-B to plain A or B. Thus, the selected difference never has
+state default-A or default-B, and these states are never displayed in
+the mode line.
+
+The command @kbd{d a} chooses default-A as the default state, and @kbd{d
+b} chooses default-B. This chosen default applies to all differences
+which you haven't ever selected and for which no alternative is preferred.
+If you are moving through the merge sequentially, the differences you
+haven't selected are those following the selected one. Thus, while
+moving sequentially, you can effectively make the A version the default
+for some sections of the merge buffer and the B version the default for
+others by using @kbd{d a} and @kbd{d b} between sections.
+
+@item prefer-A
+@itemx prefer-B
+The difference is showing the A or B state because it is
+@dfn{preferred}. This means that you haven't made an explicit choice,
+but one alternative seems likely to be right because the other
+alternative agrees with the common ancestor. Thus, where the A buffer
+agrees with the common ancestor, the B version is preferred, because
+chances are it is the one that was actually changed.
+
+These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
+
+@item combined
+The difference is showing a combination of the A and B states, as a
+result of the @kbd{x c} or @kbd{x C} commands.
+
+Once a difference is in this state, the @kbd{a} and @kbd{b} commands
+don't do anything to it unless you give them a numeric argument.
+
+The mode line displays this state as @samp{comb}.
+@end table
+
+@node Merge Commands
+@subsection Merge Commands
+
+ Here are the Merge commands for Fast mode; in Edit mode, precede them
+with @kbd{C-c C-c}:
+
+@table @kbd
+@item p
+Select the previous difference.
+
+@item n
+Select the next difference.
+
+@item a
+Choose the A version of this difference.
+
+@item b
+Choose the B version of this difference.
+
+@item C-u @var{n} j
+Select difference number @var{n}.
+
+@item .
+Select the difference containing point. You can use this command in the
+merge buffer or in the A or B buffer.
+
+@item q
+Quit---finish the merge.
+
+@item C-]
+Abort---exit merging and do not save the output.
+
+@item f
+Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
+
+@item e
+Go into Edit mode.
+
+@item l
+Recenter (like @kbd{C-l}) all three windows.
+
+@item -
+Specify part of a prefix numeric argument.
+
+@item @var{digit}
+Also specify part of a prefix numeric argument.
+
+@item d a
+Choose the A version as the default from here down in
+the merge buffer.
+
+@item d b
+Choose the B version as the default from here down in
+the merge buffer.
+
+@item c a
+Copy the A version of this difference into the kill ring.
+
+@item c b
+Copy the B version of this difference into the kill ring.
+
+@item i a
+Insert the A version of this difference at point.
+
+@item i b
+Insert the B version of this difference at point.
+
+@item m
+Put point and mark around the difference.
+
+@item ^
+Scroll all three windows down (like @kbd{M-v}).
+
+@item v
+Scroll all three windows up (like @kbd{C-v}).
+
+@item <
+Scroll all three windows left (like @kbd{C-x <}).
+
+@item >
+Scroll all three windows right (like @kbd{C-x >}).
+
+@item |
+Reset horizontal scroll on all three windows.
+
+@item x 1
+Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
+to full size.)
+
+@item x c
+Combine the two versions of this difference (@pxref{Combining in
+Emerge}).
+
+@item x f
+Show the names of the files/buffers Emerge is operating on, in a Help
+window. (Use @kbd{C-u l} to restore windows.)
+
+@item x j
+Join this difference with the following one.
+(@kbd{C-u x j} joins this difference with the previous one.)
+
+@item x s
+Split this difference into two differences. Before you use this
+command, position point in each of the three buffers at the place where
+you want to split the difference.
+
+@item x t
+Trim identical lines off the top and bottom of the difference.
+Such lines occur when the A and B versions are
+identical but differ from the ancestor version.
+@end table
+
+@node Exiting Emerge
+@subsection Exiting Emerge
+
+ The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
+the results into the output file if you specified one. It restores the
+A and B buffers to their proper contents, or kills them if they were
+created by Emerge and you haven't changed them. It also disables the
+Emerge commands in the merge buffer, since executing them later could
+damage the contents of the various buffers.
+
+ @kbd{C-]} aborts the merge. This means exiting without writing the
+output file. If you didn't specify an output file, then there is no
+real difference between aborting and finishing the merge.
+
+ If the Emerge command was called from another Lisp program, then its
+return value is @code{t} for successful completion, or @code{nil} if you
+abort.
+
+@node Combining in Emerge
+@subsection Combining the Two Versions
+
+ Sometimes you want to keep @emph{both} alternatives for a particular
+difference. To do this, use @kbd{x c}, which edits the merge buffer
+like this:
+
+@example
+@group
+#ifdef NEW
+@var{version from A buffer}
+#else /* not NEW */
+@var{version from B buffer}
+#endif /* not NEW */
+@end group
+@end example
+
+@noindent
+@vindex emerge-combine-versions-template
+While this example shows C preprocessor conditionals delimiting the two
+alternative versions, you can specify the strings to use by setting
+the variable @code{emerge-combine-versions-template} to a string of your
+choice. In the string, @samp{%a} says where to put version A, and
+@samp{%b} says where to put version B. The default setting, which
+produces the results shown above, looks like this:
+
+@example
+@group
+"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
+@end group
+@end example
+
+@node Fine Points of Emerge
+@subsection Fine Points of Emerge
+
+ During the merge, you mustn't try to edit the A and B buffers yourself.
+Emerge modifies them temporarily, but ultimately puts them back the way
+they were.
+
+ You can have any number of merges going at once---just don't use any one
+buffer as input to more than one merge at once, since the temporary
+changes made in these buffers would get in each other's way.
+
+ Starting Emerge can take a long time because it needs to compare the
+files fully. Emacs can't do anything else until @code{diff} finishes.
+Perhaps in the future someone will change Emerge to do the comparison in
+the background when the input files are large---then you could keep on
+doing other things with Emacs until Emerge is ready to accept
+commands.
+
+@vindex emerge-startup-hook
+ After setting up the merge, Emerge runs the hook
+@code{emerge-startup-hook} (@pxref{Hooks}).
+
+@node C Modes
+@section C and Related Modes
+@cindex C mode
+@cindex Java mode
+@cindex Pike mode
+@cindex IDL mode
+@cindex CORBA IDL mode
+@cindex Objective C mode
+@cindex C++ mode
+@cindex mode, Java
+@cindex mode, C
+@cindex mode, Objective C
+@cindex mode, CORBA IDL
+@cindex mode, Pike
+
+ This section describes special features available in C, C++,
+Objective-C, Java, CORBA IDL, and Pike modes. When we say ``C mode and
+related modes,'' those are the modes we mean.
+
+@menu
+* Motion in C::
+* Electric C::
+* Hungry Delete::
+* Other C Commands::
+* Comments in C::
+@end menu
+
+@node Motion in C
+@subsection C Mode Motion Commands
+
+ This section describes commands for moving point, in C mode and
+related modes.
+
+@table @code
+@item C-c C-u
+@kindex C-c C-u @r{(C mode)}
+@findex c-up-conditional
+Move point back to the containing preprocessor conditional, leaving the
+mark behind. A prefix argument acts as a repeat count. With a negative
+argument, move point forward to the end of the containing
+preprocessor conditional. When going backwards, @code{#elif} is treated
+like @code{#else} followed by @code{#if}. When going forwards,
+@code{#elif} is ignored.@refill
+
+@item C-c C-p
+@kindex C-c C-p @r{(C mode)}
+@findex c-backward-conditional
+Move point back over a preprocessor conditional, leaving the mark
+behind. A prefix argument acts as a repeat count. With a negative
+argument, move forward.
+
+@item C-c C-n
+@kindex C-c C-n @r{(C mode)}
+@findex c-forward-conditional
+Move point forward across a preprocessor conditional, leaving the mark
+behind. A prefix argument acts as a repeat count. With a negative
+argument, move backward.
+
+@item M-a
+@kindex ESC a
+@findex c-beginning-of-statement
+Move point to the beginning of the innermost C statement
+(@code{c-beginning-of-statement}). If point is already at the beginning
+of a statement, move to the beginning of the preceding statement. With
+prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
+
+If point is within a string or comment, or next to a comment (only
+whitespace between them), this command moves by sentences instead of
+statements.
+
+When called from a program, this function takes three optional
+arguments: the numeric prefix argument, a buffer position limit
+(don't move back before that place), and a flag that controls whether
+to do sentence motion when inside of a comment.
+
+@item M-e
+@kindex ESC e
+@findex c-end-of-statement
+Move point to the end of the innermost C statement; like @kbd{M-a}
+except that it moves in the other direction (@code{c-end-of-statement}).
+
+@item M-x c-backward-into-nomenclature
+@findex c-backward-into-nomenclature
+Move point backward to beginning of a C++ nomenclature section or word.
+With prefix argument @var{n}, move @var{n} times. If @var{n} is
+negative, move forward. C++ nomenclature means a symbol name in the
+style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter
+begins a section or word.
+
+In the GNU project, we recommend using underscores to separate words
+within an identifier in C or C++, rather than using case distinctions.
+
+@item M-x c-forward-into-nomenclature
+@findex c-forward-into-nomenclature
+Move point forward to end of a C++ nomenclature section or word.
+With prefix argument @var{n}, move @var{n} times.
+@end table
+
+@node Electric C
+@subsection Electric C Characters
+
+ In C mode and related modes, certain printing characters are
+``electric''---in addition to inserting themselves, they also reindent
+the current line and may insert newlines. This feature is controlled by
+the variable @code{c-auto-newline}. The ``electric'' characters are
+@kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<},
+@kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}.
+
+ Electric characters insert newlines only when the @dfn{auto-newline}
+feature is enabled (indicated by @samp{/a} in the mode line after the
+mode name). This feature is controlled by the variable
+@code{c-auto-newline}. You can turn this feature on or off with the
+command @kbd{C-c C-a}:
+
+@table @kbd
+@item C-c C-a
+@kindex C-c C-a @r{(C mode)}
+@findex c-toggle-auto-state
+Toggle the auto-newline feature (@code{c-toggle-auto-state}). With a
+prefix argument, this command turns the auto-newline feature on if the
+argument is positive, and off if it is negative.
+@end table
+
+ The colon character is electric because that is appropriate for a
+single colon. But when you want to insert a double colon in C++, the
+electric behavior of colon is inconvenient. You can insert a double
+colon with no reindentation or newlines by typing @kbd{C-c :}:
+
+@table @kbd
+@item C-c :
+@kindex C-c : @r{(C mode)}
+@findex c-scope-operator
+Insert a double colon scope operator at point, without reindenting the
+line or adding any newlines (@code{c-scope-operator}).
+@end table
+
+ The electric @kbd{#} key reindents the line if it appears to be the
+beginning of a preprocessor directive. This happens when the value of
+@code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn
+this feature off by setting @code{c-electric-pound-behavior} to
+@code{nil}.
+
+ The variable @code{c-hanging-braces-alist} controls the insertion of
+newlines before and after inserted braces. It is an association list
+with elements of the following form: @code{(@var{syntactic-symbol}
+. @var{nl-list})}. Most of the syntactic symbols that appear in
+@code{c-offsets-alist} are meaningful here as well.
+
+ The list @var{nl-list} may contain either of the symbols
+@code{before} or @code{after}, or both; or it may be @code{nil}. When a
+brace is inserted, the syntactic context it defines is looked up in
+@code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used
+to determine where newlines are inserted: either before the brace,
+after, or both. If not found, the default is to insert a newline both
+before and after braces.
+
+ The variable @code{c-hanging-colons-alist} controls the insertion of
+newlines before and after inserted colons. It is an association list
+with elements of the following form: @code{(@var{syntactic-symbol}
+. @var{nl-list})}. The list @var{nl-list} may contain either of the
+symbols @code{before} or @code{after}, or both; or it may be @code{nil}.
+
+ When a colon is inserted, the syntactic symbol it defines is looked
+up in this list, and if found, the @var{nl-list} is used to determine
+where newlines are inserted: either before the brace, after, or both.
+If the syntactic symbol is not found in this list, no newlines are
+inserted.
+
+ Electric characters can also delete newlines automatically when the
+auto-newline feature is enabled. This feature makes auto-newline more
+acceptable, by deleting the newlines in the most common cases where you
+do not want them. Emacs can recognize several cases in which deleting a
+newline might be desirable; by setting the variable
+@code{c-cleanup-list}, you can specify @emph{which} of these cases that
+should happen. The variable's value is a list of symbols, each
+describing one case for possible deletion of a newline. Here are the
+meaningful symbols, and their meanings:
+
+@table @code
+@item brace-catch-brace
+Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the
+entire construct on a single line. The clean-up occurs when you type
+the @samp{@{}, if there is nothing between the braces aside from
+@code{catch} and @var{condition}.
+
+@item brace-else-brace
+Clean up @samp{@} else @{} constructs by placing the entire construct on
+a single line. The clean-up occurs when you type the @samp{@{} after
+the @code{else}, but only if there is nothing but white space between
+the braces and the @code{else}.
+
+@item brace-elseif-brace
+Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire
+construct on a single line. The clean-up occurs when you type the
+@samp{@{}, if there is nothing but white space between the @samp{@}} and
+@samp{@{} aside from the keywords and the @code{if}-condition.
+
+@item empty-defun-braces
+Clean up empty defun braces by placing the braces on the same
+line. Clean-up occurs when you type the closing brace.
+
+@item defun-close-semi
+Clean up the semicolon after a @code{struct} or similar type
+declaration, by placing the semicolon on the same line as the closing
+brace. Clean-up occurs when you type the semicolon.
+
+@item list-close-comma
+Clean up commas following braces in array and aggregate
+initializers. Clean-up occurs when you type the comma.
+
+@item scope-operator
+Clean up double colons which may designate a C++ scope operator, by
+placing the colons together. Clean-up occurs when you type the second
+colon, but only when the two colons are separated by nothing but
+whitespace.
+@end table
+
+@node Hungry Delete
+@subsection Hungry Delete Feature in C
+
+ When the @dfn{hungry-delete} feature is enabled (indicated by
+@samp{/h} or @samp{/ah} in the mode line after the mode name), a single
+@key{DEL} command deletes all preceding whitespace, not just one space.
+To turn this feature on or off, use @kbd{C-c C-d}:
+
+@table @kbd
+@item C-c C-d
+@kindex C-c C-d @r{(C mode)}
+@findex c-toggle-hungry-state
+Toggle the hungry-delete feature (@code{c-toggle-hungry-state}). With a
+prefix argument, this command turns the hungry-delete feature on if the
+argument is positive, and off if it is negative.
+
+@item C-c C-t
+@kindex C-c C-t @r{(C mode)}
+@findex c-toggle-auto-hungry-state
+Toggle the auto-newline and hungry-delete features, both at once
+(@code{c-toggle-auto-hungry-state}).
+@end table
+
+@vindex c-hungry-delete-key
+ The variable @code{c-hungry-delete-key} controls whether the
+hungry-delete feature is enabled.
+
+@node Other C Commands
+@subsection Other Commands for C Mode
+
+@table @kbd
+@item C-M-h
+@findex c-mark-function
+@kindex C-M-h @r{(C mode)}
+Put mark at the end of a function definition, and put point at the
+beginning (@code{c-mark-function}).
+
+@item M-q
+@kindex M-q @r{(C mode)}
+@findex c-fill-paragraph
+Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
+If any part of the current line is a comment or within a comment, this
+command fills the comment or the paragraph of it that point is in,
+preserving the comment indentation and comment delimiters.
+
+@item C-c C-e
+@cindex macro expansion in C
+@cindex expansion of C macros
+@findex c-macro-expand
+@kindex C-c C-e @r{(C mode)}
+Run the C preprocessor on the text in the region, and show the result,
+which includes the expansion of all the macro calls
+(@code{c-macro-expand}). The buffer text before the region is also
+included in preprocessing, for the sake of macros defined there, but the
+output from this part isn't shown.
+
+When you are debugging C code that uses macros, sometimes it is hard to
+figure out precisely how the macros expand. With this command, you
+don't have to figure it out; you can see the expansions.
+
+@item C-c C-\
+@findex c-backslash-region
+@kindex C-c C-\ @r{(C mode)}
+Insert or align @samp{\} characters at the ends of the lines of the
+region (@code{c-backslash-region}). This is useful after writing or
+editing a C macro definition.
+
+If a line already ends in @samp{\}, this command adjusts the amount of
+whitespace before it. Otherwise, it inserts a new @samp{\}. However,
+the last line in the region is treated specially; no @samp{\} is
+inserted on that line, and any @samp{\} there is deleted.
+
+@item M-x cpp-highlight-buffer
+@cindex preprocessor highlighting
+@findex cpp-highlight-buffer
+Highlight parts of the text according to its preprocessor conditionals.
+This command displays another buffer named @samp{*CPP Edit*}, which
+serves as a graphic menu for selecting how to display particular kinds
+of conditionals and their contents. After changing various settings,
+click on @samp{[A]pply these settings} (or go to that buffer and type
+@kbd{a}) to rehighlight the C mode buffer accordingly.
+
+@item C-c C-s
+@findex c-show-syntactic-information
+@kindex C-c C-s @r{(C mode)}
+Display the syntactic information about the current source line
+(@code{c-show-syntactic-information}). This is the information that
+directs how the line is indented.
+@end table
+
+@node Comments in C
+@subsection Comments in C Modes
+
+ C mode and related modes use a number of variables for controlling
+comment format.
+
+@table @code
+@item c-comment-only-line-offset
+@vindex c-comment-only-line-offset
+Extra offset for line which contains only the start of a comment. It
+can be either an integer or a cons cell of the form
+@code{(@var{non-anchored-offset} . @var{anchored-offset})}, where
+@var{non-anchored-offset} is the amount of offset given to
+non-column-zero anchored comment-only lines, and @var{anchored-offset}
+is the amount of offset to give column-zero anchored comment-only lines.
+Just an integer as value is equivalent to @code{(@var{val} . 0)}.
+
+@item c-comment-start-regexp
+@vindex c-comment-start-regexp
+This buffer-local variable specifies how to recognize the start of a comment.
+
+@item c-hanging-comment-ender-p
+@vindex c-hanging-comment-ender-p
+If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
+comment terminator of a block comment on a line by itself. The default
+value is @code{t}, which puts the comment-end delimiter @samp{*/} at the
+end of the last line of the comment text.
+
+@item c-hanging-comment-starter-p
+@vindex c-hanging-comment-starter-p
+If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
+starting delimiter of a block comment on a line by itself. The default
+value is @code{t}, which puts the comment-start delimiter @samp{/*} at
+the beginning of the first line of the comment text.
+@end table
+
+@node Fortran
+@section Fortran Mode
+@cindex Fortran mode
+@cindex mode, Fortran
+
+ Fortran mode provides special motion commands for Fortran statements and
+subprograms, and indentation commands that understand Fortran conventions
+of nesting, line numbers and continuation statements. Fortran mode has
+its own Auto Fill mode that breaks long lines into proper Fortran
+continuation lines.
+
+ Special commands for comments are provided because Fortran comments
+are unlike those of other languages. Built-in abbrevs optionally save
+typing when you insert Fortran keywords.
+
+@findex fortran-mode
+ Use @kbd{M-x fortran-mode} to switch to this major mode. This command
+runs the hook @code{fortran-mode-hook} (@pxref{Hooks}).
+
+@menu
+* Motion: Fortran Motion. Moving point by statements or subprograms.
+* Indent: Fortran Indent. Indentation commands for Fortran.
+* Comments: Fortran Comments. Inserting and aligning comments.
+* Autofill: Fortran Autofill. Auto fill minor mode for Fortran.
+* Columns: Fortran Columns. Measuring columns for valid Fortran.
+* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
+* Misc: Fortran Misc. Other Fortran mode features.
+@end menu
+
+@node Fortran Motion
+@subsection Motion Commands
+
+ Fortran mode provides special commands to move by subprograms (functions
+and subroutines) and by statements. There is also a command to put the
+region around one subprogram, convenient for killing it or moving it.
+
+@kindex C-M-a @r{(Fortran mode)}
+@kindex C-M-e @r{(Fortran mode)}
+@kindex C-M-h @r{(Fortran mode)}
+@kindex C-c C-p @r{(Fortran mode)}
+@kindex C-c C-n @r{(Fortran mode)}
+@findex beginning-of-fortran-subprogram
+@findex end-of-fortran-subprogram
+@findex mark-fortran-subprogram
+@findex fortran-previous-statement
+@findex fortran-next-statement
+
+@table @kbd
+@item C-M-a
+Move to beginning of subprogram
+(@code{beginning-of-fortran-subprogram}).
+@item C-M-e
+Move to end of subprogram (@code{end-of-fortran-subprogram}).
+@item C-M-h
+Put point at beginning of subprogram and mark at end
+(@code{mark-fortran-subprogram}).
+@item C-c C-n
+Move to beginning of current or next statement
+(@code{fortran-next-statement}).
+@item C-c C-p
+Move to beginning of current or previous statement
+(@code{fortran-previous-statement}).
+@end table
+
+@node Fortran Indent
+@subsection Fortran Indentation
+
+ Special commands and features are needed for indenting Fortran code in
+order to make sure various syntactic entities (line numbers, comment line
+indicators and continuation line flags) appear in the columns that are
+required for standard Fortran.
+
+@menu
+* Commands: ForIndent Commands. Commands for indenting Fortran.
+* Contline: ForIndent Cont. How continuation lines indent.
+* Numbers: ForIndent Num. How line numbers auto-indent.
+* Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
+* Vars: ForIndent Vars. Variables controlling Fortran indent style.
+@end menu
+
+@node ForIndent Commands
+@subsubsection Fortran Indentation Commands
+
+@table @kbd
+@item @key{TAB}
+Indent the current line (@code{fortran-indent-line}).
+@item C-j
+Indent the current and start a new indented line
+(@code{fortran-indent-new-line}).
+@item C-M-j
+Break the current line and set up a continuation line.
+@item M-^
+Join this line to the previous line.
+@item C-M-q
+Indent all the lines of the subprogram point is in
+(@code{fortran-indent-subprogram}).
+@end table
+
+@findex fortran-indent-line
+ Fortran mode redefines @key{TAB} to reindent the current line for
+Fortran (@code{fortran-indent-line}). This command indents line numbers
+and continuation markers to their required columns, and independently
+indents the body of the statement based on its nesting in the program.
+
+@kindex C-j @r{(Fortran mode)}
+@findex fortran-indent-new-line
+ The key @kbd{C-j} runs the command @code{fortran-indent-new-line},
+which reindents the current line then makes and indents a new line.
+This command is useful to reindent the closing statement of @samp{do}
+loops and other blocks before starting a new line.
+
+@kindex C-M-q @r{(Fortran mode)}
+@findex fortran-indent-subprogram
+ The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
+to reindent all the lines of the Fortran subprogram (function or
+subroutine) containing point.
+
+@kindex C-M-j @r{(Fortran mode)}
+@findex fortran-split-line
+ The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits
+a line in the appropriate fashion for Fortran. In a non-comment line,
+the second half becomes a continuation line and is indented
+accordingly. In a comment line, both halves become separate comment
+lines.
+
+@kindex M-^ @r{(Fortran mode)}
+@findex fortran-join-line
+ @kbd{M-^} runs the command @code{fortran-join-line}, which is more or
+less the inverse of @code{fortran-split-line}. It joins the current
+line to the previous line in a suitable way for Fortran code.
+
+@node ForIndent Cont
+@subsubsection Continuation Lines
+@cindex Fortran continuation lines
+
+@vindex fortran-continuation-string
+ Most modern Fortran compilers allow two ways of writing continuation
+lines. If the first non-space character on a line is in column 5, then
+that line is a continuation of the previous line. We call this
+@dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The
+variable @code{fortran-continuation-string} specifies what character to
+put on column 5. A line that starts with a tab character followed by
+any digit except @samp{0} is also a continuation line. We call this
+style of continuation @dfn{tab format}.
+
+@vindex indent-tabs-mode @r{(Fortran mode)}
+ Fortran mode can make either style of continuation line, but you
+must specify which one you prefer. The value of the variable
+@code{indent-tabs-mode} controls the choice: @code{nil} for fixed
+format, and non-@code{nil} for tab format. You can tell which style
+is presently in effect by the presence or absence of the string
+@samp{Tab} in the mode line.
+
+ If the text on a line starts with the conventional Fortran
+continuation marker @samp{$}, or if it begins with any non-whitespace
+character in column 5, Fortran mode treats it as a continuation line.
+When you indent a continuation line with @key{TAB}, it converts the line
+to the current continuation style. When you split a Fortran statement
+with @kbd{C-M-j}, the continuation marker on the newline is created
+according to the continuation style.
+
+ The setting of continuation style affects several other aspects of
+editing in Fortran mode. In fixed format mode, the minimum column
+number for the body of a statement is 6. Lines inside of Fortran
+blocks that are indented to larger column numbers always use only the
+space character for whitespace. In tab format mode, the minimum
+column number for the statement body is 8, and the whitespace before
+column 8 must always consist of one tab character.
+
+@vindex fortran-tab-mode-default
+@vindex fortran-analyze-depth
+ When you enter Fortran mode for an existing file, it tries to deduce the
+proper continuation style automatically from the file contents. The first
+line that begins with either a tab character or six spaces determines the
+choice. The variable @code{fortran-analyze-depth} specifies how many lines
+to consider (at the beginning of the file); if none of those lines
+indicates a style, then the variable @code{fortran-tab-mode-default}
+specifies the style. If it is @code{nil}, that specifies fixed format, and
+non-@code{nil} specifies tab format.
+
+@node ForIndent Num
+@subsubsection Line Numbers
+
+ If a number is the first non-whitespace in the line, Fortran
+indentation assumes it is a line number and moves it to columns 0
+through 4. (Columns always count from 0 in GNU Emacs.)
+
+@vindex fortran-line-number-indent
+ Line numbers of four digits or less are normally indented one space.
+The variable @code{fortran-line-number-indent} controls this; it
+specifies the maximum indentation a line number can have. Line numbers
+are indented to right-justify them to end in column 4 unless that would
+require more than this maximum indentation. The default value of the
+variable is 1.
+
+@vindex fortran-electric-line-number
+ Simply inserting a line number is enough to indent it according to
+these rules. As each digit is inserted, the indentation is recomputed.
+To turn off this feature, set the variable
+@code{fortran-electric-line-number} to @code{nil}. Then inserting line
+numbers is like inserting anything else.
+
+@node ForIndent Conv
+@subsubsection Syntactic Conventions
+
+ Fortran mode assumes that you follow certain conventions that simplify
+the task of understanding a Fortran program well enough to indent it
+properly:
+
+@itemize @bullet
+@item
+Two nested @samp{do} loops never share a @samp{continue} statement.
+
+@item
+Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do}
+and others are written without embedded whitespace or line breaks.
+
+Fortran compilers generally ignore whitespace outside of string
+constants, but Fortran mode does not recognize these keywords if they
+are not contiguous. Constructs such as @samp{else if} or @samp{end do}
+are acceptable, but the second word should be on the same line as the
+first and not on a continuation line.
+@end itemize
+
+@noindent
+If you fail to follow these conventions, the indentation commands may
+indent some lines unaesthetically. However, a correct Fortran program
+retains its meaning when reindented even if the conventions are not
+followed.
+
+@node ForIndent Vars
+@subsubsection Variables for Fortran Indentation
+
+@vindex fortran-do-indent
+@vindex fortran-if-indent
+@vindex fortran-structure-indent
+@vindex fortran-continuation-indent
+@vindex fortran-check-all-num@dots{}
+@vindex fortran-minimum-statement-indent@dots{}
+ Several additional variables control how Fortran indentation works:
+
+@table @code
+@item fortran-do-indent
+Extra indentation within each level of @samp{do} statement (default 3).
+
+@item fortran-if-indent
+Extra indentation within each level of @samp{if} statement (default 3).
+This value is also used for extra indentation within each level of the
+Fortran 90 @samp{where} statement.
+
+@item fortran-structure-indent
+Extra indentation within each level of @samp{structure}, @samp{union}, or
+@samp{map} statements (default 3).
+
+@item fortran-continuation-indent
+Extra indentation for bodies of continuation lines (default 5).
+
+@item fortran-check-all-num-for-matching-do
+If this is @code{nil}, indentation assumes that each @samp{do} statement
+ends on a @samp{continue} statement. Therefore, when computing
+indentation for a statement other than @samp{continue}, it can save time
+by not checking for a @samp{do} statement ending there. If this is
+non-@code{nil}, indenting any numbered statement must check for a
+@samp{do} that ends there. The default is @code{nil}.
+
+@item fortran-blink-matching-if
+If this is @code{t}, indenting an @samp{endif} statement moves the
+cursor momentarily to the matching @samp{if} statement to show where it
+is. The default is @code{nil}.
+
+@item fortran-minimum-statement-indent-fixed
+Minimum indentation for fortran statements when using fixed format
+continuation line style. Statement bodies are never indented less than
+this much. The default is 6.
+
+@item fortran-minimum-statement-indent-tab
+Minimum indentation for fortran statements for tab format continuation line
+style. Statement bodies are never indented less than this much. The
+default is 8.
+@end table
+
+@node Fortran Comments
+@subsection Fortran Comments
+
+ The usual Emacs comment commands assume that a comment can follow a line
+of code. In Fortran, the standard comment syntax requires an entire line
+to be just a comment. Therefore, Fortran mode replaces the standard Emacs
+comment commands and defines some new variables.
+
+ Fortran mode can also handle a nonstandard comment syntax where comments
+start with @samp{!} and can follow other text. Because only some Fortran
+compilers accept this syntax, Fortran mode will not insert such comments
+unless you have said in advance to do so. To do this, set the variable
+@code{comment-start} to @samp{"!"} (@pxref{Variables}).
+
+@table @kbd
+@item M-;
+Align comment or insert new comment (@code{fortran-comment-indent}).
+
+@item C-x ;
+Applies to nonstandard @samp{!} comments only.
+
+@item C-c ;
+Turn all lines of the region into comments, or (with argument) turn them back
+into real code (@code{fortran-comment-region}).
+@end table
+
+ @kbd{M-;} in Fortran mode is redefined as the command
+@code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this
+recognizes any kind of existing comment and aligns its text appropriately;
+if there is no existing comment, a comment is inserted and aligned. But
+inserting and aligning comments are not the same in Fortran mode as in
+other modes.
+
+ When a new comment must be inserted, if the current line is blank, a
+full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
+comment is inserted if you have said you want to use them. Otherwise a
+full-line comment is inserted on a new line before the current line.
+
+ Nonstandard @samp{!} comments are aligned like comments in other
+languages, but full-line comments are different. In a standard full-line
+comment, the comment delimiter itself must always appear in column zero.
+What can be aligned is the text within the comment. You can choose from
+three styles of alignment by setting the variable
+@code{fortran-comment-indent-style} to one of these values:
+
+@vindex fortran-comment-indent-style
+@vindex fortran-comment-line-extra-indent
+@table @code
+@item fixed
+Align the text at a fixed column, which is the sum of
+@code{fortran-comment-line-extra-indent} and the minimum statement
+indentation. This is the default.
+
+The minimum statement indentation is
+@code{fortran-minimum-statement-indent-fixed} for fixed format
+continuation line style and @code{fortran-minimum-statement-indent-tab}
+for tab format style.
+
+@item relative
+Align the text as if it were a line of code, but with an additional
+@code{fortran-comment-line-extra-indent} columns of indentation.
+
+@item nil
+Don't move text in full-line comments automatically at all.
+@end table
+
+@vindex fortran-comment-indent-char
+ In addition, you can specify the character to be used to indent within
+full-line comments by setting the variable
+@code{fortran-comment-indent-char} to the single-character string you want
+to use.
+
+@vindex comment-line-start
+@vindex comment-line-start-skip
+ Fortran mode introduces two variables @code{comment-line-start} and
+@code{comment-line-start-skip}, which play for full-line comments the same
+roles played by @code{comment-start} and @code{comment-start-skip} for
+ordinary text-following comments. Normally these are set properly by
+Fortran mode, so you do not need to change them.
+
+ The normal Emacs comment command @kbd{C-x ;} has not been redefined. If
+you use @samp{!} comments, this command can be used with them. Otherwise
+it is useless in Fortran mode.
+
+@kindex C-c ; @r{(Fortran mode)}
+@findex fortran-comment-region
+@vindex fortran-comment-region
+ The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
+lines of the region into comments by inserting the string @samp{C$$$} at
+the front of each one. With a numeric argument, it turns the region
+back into live code by deleting @samp{C$$$} from the front of each line
+in it. The string used for these comments can be controlled by setting
+the variable @code{fortran-comment-region}. Note that here we have an
+example of a command and a variable with the same name; these two uses
+of the name never conflict because in Lisp and in Emacs it is always
+clear from the context which one is meant.
+
+@node Fortran Autofill
+@subsection Fortran Auto Fill Mode
+
+ Fortran Auto Fill mode is a minor mode which automatically splits
+Fortran statements as you insert them when they become too wide.
+Splitting a statement involves making continuation lines using
+@code{fortran-continuation-string} (@pxref{ForIndent Cont}). This
+splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and
+also in the Fortran indentation commands.
+
+@findex fortran-auto-fill-mode
+ @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it
+was off, or off if it was on. This command works the same as @kbd{M-x
+auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A
+positive numeric argument turns Fortran Auto Fill mode on, and a
+negative argument turns it off. You can see when Fortran Auto Fill mode
+is in effect by the presence of the word @samp{Fill} in the mode line,
+inside the parentheses. Fortran Auto Fill mode is a minor mode, turned
+on or off for each buffer individually. @xref{Minor Modes}.
+
+@vindex fortran-break-before-delimiters
+ Fortran Auto Fill mode breaks lines at spaces or delimiters when the
+lines get longer than the desired width (the value of @code{fill-column}).
+The delimiters that Fortran Auto Fill mode may break at are @samp{,},
+@samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}.
+The line break comes after the delimiter if the variable
+@code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by
+default), the break comes before the delimiter.
+
+ By default, Fortran Auto Fill mode is not enabled. If you want this
+feature turned on permanently, add a hook function to
+@code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}.
+@xref{Hooks}.
+
+@node Fortran Columns
+@subsection Checking Columns in Fortran
+
+@table @kbd
+@item C-c C-r
+Display a ``column ruler'' momentarily above the current line
+(@code{fortran-column-ruler}).
+@item C-c C-w
+Split the current window horizontally temporarily so that it is 72
+columns wide. This may help you avoid making lines longer than the
+72-character limit that some Fortran compilers impose
+(@code{fortran-window-create-momentarily}).
+@end table
+
+@kindex C-c C-r @r{(Fortran mode)}
+@findex fortran-column-ruler
+@vindex fortran-column-ruler
+ The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
+ruler momentarily above the current line. The comment ruler is two lines
+of text that show you the locations of columns with special significance in
+Fortran programs. Square brackets show the limits of the columns for line
+numbers, and curly brackets show the limits of the columns for the
+statement body. Column numbers appear above them.
+
+ Note that the column numbers count from zero, as always in GNU Emacs.
+As a result, the numbers may be one less than those you are familiar
+with; but the positions they indicate in the line are standard for
+Fortran.
+
+ The text used to display the column ruler depends on the value of
+the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is
+@code{nil}, then the value of the variable
+@code{fortran-column-ruler-fixed} is used as the column ruler.
+Otherwise, the variable @code{fortran-column-ruler-tab} is displayed.
+By changing these variables, you can change the column ruler display.
+
+@kindex C-c C-w @r{(Fortran mode)}
+@findex fortran-window-create
+ For even more help, use @kbd{C-c C-w} (@code{fortran-window-create}), a
+command which splits the current window horizontally, making a window 72
+columns wide. By editing in this window you can immediately see when you
+make a line too wide to be correct Fortran.
+
+@node Fortran Abbrev
+@subsection Fortran Keyword Abbrevs
+
+ Fortran mode provides many built-in abbrevs for common keywords and
+declarations. These are the same sort of abbrev that you can define
+yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}.
+
+ The built-in abbrevs are unusual in one way: they all start with a
+semicolon. You cannot normally use semicolon in an abbrev, but Fortran
+mode makes this possible by changing the syntax of semicolon to ``word
+constituent.''
+
+ For example, one built-in Fortran abbrev is @samp{;c} for
+@samp{continue}. If you insert @samp{;c} and then insert a punctuation
+character such as a space or a newline, the @samp{;c} expands automatically
+to @samp{continue}, provided Abbrev mode is enabled.@refill
+
+ Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
+Fortran abbrevs and what they stand for.
+
+@node Fortran Misc
+@subsection Other Fortran Mode Commands
+
+@table @kbd
+@item C-x n d
+Narrow to the current Fortran subprogram.
+@end table
+
+@kindex C-x n d @r{(Fortran mode)}
+@findex fortran-narrow-to-subprogram
+ Fortran mode redefines the key @kbd{C-x n d} to run the command
+@code{fortran-narrow-to-subprogram}, which is the Fortran analogue
+of the key's usual definition. It narrows the buffer to the subprogram
+containing point.
+
+@node Asm Mode
+@section Asm Mode
+
+@cindex Asm mode
+Asm mode is a major mode for editing files of assembler code. It
+defines these commands:
+
+@table @kbd
+@item @key{TAB}
+@code{tab-to-tab-stop}.
+@item C-j
+Insert a newline and then indent using @code{tab-to-tab-stop}.
+@item :
+Insert a colon and then remove the indentation from before the label
+preceding colon. Then do @code{tab-to-tab-stop}.
+@item ;
+Insert or align a comment.
+@end table
+
+ The variable @code{asm-comment-char} specifies which character
+starts comments in assembler syntax.
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/reftex
+@settitle RefTeX User Manual
+@dircategory Editors
+@direntry
+* RefTeX: (reftex). Emacs support for LaTeX cross-references and citations.
+@end direntry
+@synindex ky cp
+@syncodeindex vr cp
+@syncodeindex fn cp
+@set VERSION 4.6
+@set EDITION 4.6
+@set DATE September 1999
+@set AUTHOR Carsten Dominik
+@set AUTHOR-EMAIL dominik@@strw.leidenuniv.nl
+@set MAINTAINER Carsten Dominik
+@set MAINTAINER-EMAIL dominik@@strw.leidenuniv.nl
+@c %**end of header
+@finalout
+
+@c Macro definitions
+
+@c Subheadings inside a table. Need a difference between info and the rest.
+@macro tablesubheading{text}
+@ifinfo
+@subsubheading \text\
+@end ifinfo
+@ifnotinfo
+@item @b{\text\}
+@end ifnotinfo
+@end macro
+
+@ifinfo
+This file documents @b{Ref@TeX{}}, a package to do labels, references,
+citations and indices for LaTeX documents with Emacs.@refill
+
+This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
+@b{Ref@TeX{}} @value{VERSION}@refill
+
+Copyright (c) 1997, 1998, 1999 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX
+and print the results, provided the printed document
+carries a copying permission notice identical to this
+one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified
+versions of this manual under the conditions for
+verbatim copying, provided that the entire resulting
+derive work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute
+translations of this manual into another language,
+under the above conditions for modified versions,
+except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+@end ifinfo
+
+@titlepage
+@title Ref@TeX{} User Manual
+@subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs
+@subtitle Edition @value{EDITION}, @value{DATE}
+
+@author by Carsten Dominik
+@page
+Copyright @copyright{} 1997, 1998 Free Software Foundation, Inc.
+
+@sp 2
+This is edition @value{EDITION} of the @cite{Ref@TeX{} User Manual} for
+@b{Ref@TeX{}} version @value{VERSION}, @value{DATE}.@refill
+
+@sp 2
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
+Permission is granted to copy and distribute modified
+versions of this manual under the conditions for
+verbatim copying, provided that the entire resulting
+derive work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute
+translations of this manual into another language,
+under the above conditions for modified versions,
+except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+@end titlepage
+@page
+
+@ifinfo
+@node Top,,,(dir)
+
+@b{Ref@TeX{}} is a package for managing Labels, References,
+Citations and index entries with GNU Emacs.@refill
+
+Don't be discouraged by the size of this manual, which covers
+@b{Ref@TeX{}} in great depth. All you need to know to use
+@b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a
+Nutshell}). You can go back later to other parts of this document when
+needed.@refill
+
+@menu
+* Introduction:: Quick-Start information.
+
+* Table of Contents:: A Tool to move around quickly.
+* Labels and References:: Creating and referencing labels.
+* Citations:: Creating Citations.
+* Index Support:: Creating and Checking Index Entries.
+* Viewing Cross-References:: Who references or cites what?
+
+* RefTeXs Menu:: The Ref menu in the menubar.
+* Keybindings:: The default keybindings.
+* Faces:: Fontification of RefTeX's buffers.
+* Multifile Documents:: Document spread over many files.
+* Language Support:: How to support other languages.
+* Finding Files:: Included TeX files and BibTeX .bib files.
+* AUCTeX:: Cooperation with AUCTeX.
+* Optimizations:: When RefTeX is too slow.
+* Problems and Work-Arounds:: First Aid.
+* Imprint:: Author, Web-site, Thanks
+
+* Commands:: Which are the available commands.
+* Options:: How to extend and configure RefTeX.
+* Keymaps and Hooks:: For customization.
+* Changes:: A List of recent changes to RefTeX.
+
+The Index
+
+* Index:: The full index.
+
+@detailmenu
+
+Introduction
+
+* Installation:: How to install and activate RefTeX.
+* RefTeX in a Nutshell:: A brief summary and quick guide.
+
+Labels and References
+
+* Creating Labels::
+* Referencing Labels::
+* Builtin Label Environments:: The environments RefTeX knows about.
+* Defining Label Environments:: ... and environments it doesn't.
+* Reference Info:: View the label corresponding to a \ref.
+* xr (LaTeX package):: References to external documents.
+* varioref (LaTeX package):: How to create \vref instead of \ref.
+* fancyref (LaTeX package):: How to create \fref instead of \ref.
+
+Defining Label Environments
+
+* Theorem and Axiom:: Defined with @code{\newenvironment}.
+* Quick Equation:: When a macro sets the label type.
+* Figure Wrapper:: When a macro argument is a label.
+* Adding Magic Words:: Other words for other languages.
+* Using \eqref:: How to switch to this AMS-LaTeX macro.
+* Non-Standard Environments:: Environments without \begin and \end
+* Putting it Together:: How to combine many entries.
+
+Citations
+
+* Creating Citations:: How to create them.
+* Citation Styles:: Natbib, Harvard, Chicago and Co.
+* Citation Info:: View the corresponding database entry.
+* Chapterbib and Bibunits:: Multiple bibliographies in a Document.
+* Citations Outside LaTeX:: How to make citations in Emails etc.
+
+Index Support
+
+* Creating Index Entries::
+* Displaying and Editing the Index::
+* Builtin Index Macros:: The index macros RefTeX knows about.
+* Defining Index Macros:: ... and macros it doesn't.
+
+AUCTeX
+
+* AUCTeX-RefTeX Interface:: How both packages work together
+* Style Files:: AUCTeX's style files can support RefTeX
+* Bib-Cite:: Hypertext reading of a document
+
+Options, Keymaps, Hooks
+
+* Options (Table of Contents)::
+* Options (Defining Label Environments)::
+* Options (Creating Labels)::
+* Options (Referencing Labels)::
+* Options (Creating Citations)::
+* Options (Index Support)::
+* Options (Viewing Cross-References)::
+* Options (Finding Files)::
+* Options (Optimizations)::
+* Options (Fontification)::
+* Options (Misc)::
+
+@end detailmenu
+@end menu
+
+@end ifinfo
+
+@node Introduction, Table of Contents, , Top
+@chapter Introduction
+@cindex Introduction
+
+@b{Ref@TeX{}} is a specialized package for support of labels,
+references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps
+itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite},
+and @code{\index}. Using these macros usually requires looking up
+different parts of the document and searching through BibTeX database
+files. @b{Ref@TeX{}} automates these time--consuming tasks almost
+entirely. It also provides functions to display the structure of a
+document and to move around in this structure quickly.@refill
+
+@iftex
+Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}}
+in great depth. All you need to know to use @b{Ref@TeX{}} can be
+summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go
+back later to other parts of this document when needed.
+@end iftex
+
+@xref{Imprint}, for information about who to contact for help, bug
+reports or suggestions.
+
+@menu
+* Installation:: How to install and activate RefTeX.
+* RefTeX in a Nutshell:: A brief summary and quick guide.
+@end menu
+
+@node Installation, RefTeX in a Nutshell, , Introduction
+@section Installation
+@cindex Installation
+
+@b{Ref@TeX{}} is bundled and pre--installed with Emacs since version 20.2.
+It was also bundled and pre--installed with XEmacs 19.16--20.x. XEmacs
+21.x users want to install the corresponding plug-in package which is
+available from the
+@uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}. See
+the XEmacs 21.x documentation on package installation for
+details.@refill
+
+Users of earlier Emacs distributions (including Emacs 19) can get a copy
+of the @b{Ref@TeX{}} distribution from the maintainers web-page.
+@xref{Imprint}, for more information.@refill
+
+@section Environment
+@cindex Finding files
+@cindex BibTeX database files, not found
+@cindex TeX files, not found
+@cindex @code{TEXINPUTS}, environment variable
+@cindex @code{BIBINPUTS}, environment variable
+
+@b{Ref@TeX{}} needs to access all files which are part of a multifile
+document, and the BibTeX database files requested by the
+@code{\bibliography} command. To find these files, @b{Ref@TeX{}} will
+require a search path, i.e. a list of directories to check. Normally
+this list is stored in the environment variables @code{TEXINPUTS} and
+@code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some
+systems these variables do not contain the full search path. If
+@b{Ref@TeX{}} does not work for you because it cannot find some files,
+read @ref{Finding Files}.
+
+@section Entering @b{Ref@TeX{}} Mode
+
+@findex turn-on-reftex
+@findex reftex-mode
+@vindex LaTeX-mode-hook
+@vindex latex-mode-hook
+To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use
+@kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX
+files, add the following lines to your @file{.emacs} file:@refill
+
+@example
+(add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode
+(add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode
+@end example
+
+@page
+@node RefTeX in a Nutshell, , Installation, Introduction
+@section @b{Ref@TeX{}} in a Nutshell
+@cindex Quick-Start
+@cindex Getting Started
+@cindex RefTeX in a Nutshell
+@cindex Nutshell, RefTeX in a
+
+@enumerate
+@item
+@b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show
+a table of contents of the document. This buffer can display sections,
+labels and index entries defined in the document. From the buffer, you
+can jump quickly to every part of your document. Press @kbd{?} to get
+help.@refill
+
+@item
+@b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels
+and to find the correct key for references quickly. It distinguishes
+labels for different environments, knows about all standard
+environments (and many others), and can be configured to recognize any
+additional labeled environments you have defined yourself (variable
+@code{reftex-label-alist}).@refill
+
+@itemize @bullet
+@item
+@b{Creating Labels}@*
+Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
+@b{Ref@TeX{}} will either
+@itemize @minus
+@item
+derive a label from context (default for section labels)
+@item
+prompt for a label string (default for figures and tables) or
+@item
+insert a simple label made of a prefix and a number (all other
+environments)@refill
+@end itemize
+@noindent
+Which labels are created how is configurable with the variable
+@code{reftex-insert-label-flags}.@refill
+
+@item
+@b{Referencing Labels}@* To make a reference, type @kbd{C-c )}
+(@code{reftex-reference}). This shows an outline of the document with
+all labels of a certain type (figure, equation,...) and some label
+context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro
+into the original buffer.@refill
+@end itemize
+
+@item
+@b{Citations}@*
+Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a
+regular expression to search in current BibTeX database files (as
+specified in the @code{\bibliography} command) and pull out a list of
+matches for you to choose from. The list is @emph{formatted} and
+sorted. The selected article is referenced as @samp{\cite@{@var{key}@}}
+(see the variable @code{reftex-cite-format} if you want to insert
+different macros).@refill
+
+@item
+@b{Index Support}@*
+@b{Ref@TeX{}} helps to enter index entries. It also compiles all
+entries into an alphabetically sorted @file{*Index*} buffer which you
+can use to check and edit the entries. @b{Ref@TeX{}} knows about the
+standard index macros and can be configured to recognize any additional
+macros you have defined (@code{reftex-index-macros}). Multiple indices
+are supported.@refill
+
+@itemize @bullet
+@item
+@b{Creating Index Entries}@*
+Type @kbd{C-c /} (@code{reftex-index-selection-or-word}) to index the
+current selection or the word at the cursor with the default macro (see
+the variable @code{reftex-index-default-macro}).@*
+Type @kbd{C-c <} (@code{reftex-index}) to insert a general index macro.
+@b{Ref@TeX{}} will offer a list of available macros and provide
+completion for the index tag (used to identify one of multiple indices)
+and for the entry itself (useful with subentries).
+
+@refill
+
+@item
+@b{Displaying the Index}@* To display the compiled index in a special
+buffer, type @kbd{C-c >} (@code{reftex-display-index}). From that
+buffer you can check and edit all entries. The index can be restricted
+to those entries defined in a single document section or in a user
+defined region.@refill
+@end itemize
+
+@page
+@item @b{Viewing Cross-References}@*
+When point is on the @var{key} argument of a cross--referencing macro
+(@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
+@code{\index}, and variations) or inside a BibTeX database entry, you
+can press @kbd{C-c &} (@code{reftex-view-crossref}) to display
+corresponding locations in the document and associated BibTeX database
+files.@refill @* When the enclosing macro is @code{\cite} or @code{\ref}
+and no other message occupies the echo area, information about the
+citation or label will automatically be displayed in the echo
+area.@refill
+
+@item
+@b{Multifile Documents}@*
+Multifile Documents are fully supported. The included files must have a
+file variable @code{TeX-master} or @code{tex-main-file} pointing to the
+master file. @b{Ref@TeX{}} provides cross-referencing information from
+all parts of the document, and across document borders
+(@file{xr.sty}).@refill
+
+@item
+@b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in
+order to find labels and other information. It does it automatically
+once and updates its list internally when @code{reftex-label} and
+@code{reftex-index} are used. To enforce reparsing, call any of the
+commands described above with a raw @kbd{C-u} prefix, or press the
+@kbd{r} key in the label selection buffer, the table of contents
+buffer, or the index buffer.@refill
+
+@item
+@b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can
+cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX
+contains style files which trigger appropriate settings in
+@b{Ref@TeX{}}, so that for many of the popular LaTeX packages no
+additional customizations will be necessary.@refill
+
+@item
+@b{Useful Settings}@* To make @b{Ref@TeX{}} faster for large documents,
+try these:@refill
+@lisp
+(setq reftex-enable-partial-scans t)
+(setq reftex-save-parse-info t)
+(setq reftex-use-multiple-selection-buffers t)
+@end lisp
+
+To integrate with AUCTeX, use
+@lisp
+(setq reftex-plug-into-AUCTeX t)
+@end lisp
+
+To make your own LaTeX macro definitions known to @b{Ref@TeX{}},
+customize the variables@refill
+@example
+@code{reftex-label-alist} @r{(for label macros/environments)}
+@code{reftex-section-levels} @r{(for sectioning commands)}
+@code{reftex-cite-format} @r{(for @code{\cite}-like macros)}
+@code{reftex-index-macros} @r{(for @code{\index}-like macros)}
+@code{reftex-index-default-macro} @r{(to set the default macro)}
+@end example
+If you have a large number of macros defined, you may want to write
+an AUCTeX style file to support them with both AUCTeX and
+@b{Ref@TeX{}}.@refill
+
+@item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus
+until you have picked up the key bindings. For an overview of what you
+can do in each of the different special buffers, press @kbd{?}. Read
+the manual if you get stuck. The first part of the manual explains in
+a tutorial way how to use and customize @b{Ref@TeX{}}. The second
+part is a command and variable reference.@refill
+@end enumerate
+
+@node Table of Contents, Labels and References, Introduction, Top
+@chapter Table of Contents
+@cindex @file{*toc*} buffer
+@cindex Table of contents buffer
+@findex reftex-toc
+@kindex C-c =
+
+Pressing the keys @kbd{C-c =} pops up a buffer showing the table of
+contents of the document. By default, this @file{*toc*} buffer shows
+only the sections of a document. Using the @kbd{l} and @kbd{i} keys you
+can display all labels and index entries defined in the document as
+well.@refill
+
+With the cursor in any of the lines denoting a location in the
+document, simple key strokes will display the corresponding part in
+another window, jump to that location, or perform other actions.@refill
+
+@kindex ?
+Here is a list of special commands in the @file{*toc*} buffer. A
+summary of this information is always available by pressing
+@kbd{?}.@refill
+
+@table @kbd
+
+@tablesubheading{General}
+@item ?
+Display a summary of commands.
+
+@item 0-9, -
+Prefix argument.
+
+@tablesubheading{Moving around}
+@item n
+Goto next entry in the table of context.
+
+@item p
+Goto previous entry in the table of context.
+
+@item C-c C-n
+Goto next section heading. Useful when many labels and index entries
+separate section headings.@refill
+
+@item C-c C-p
+Goto previous section heading.
+
+@tablesubheading{Access to document locations}
+@item @key{SPC}
+Show the corresponding location in another window. This command does
+@emph{not} select that other window.@refill
+
+@item @key{TAB}
+Goto the location in another window.
+
+@item @key{RET}
+Go to the location and hide the @file{*toc*} buffer. This will restore
+the window configuration before @code{reftex-toc} (@kbd{C-c =}) was
+called.@refill
+
+@item mouse-2
+@vindex reftex-highlight-selection
+Clicking with mouse button 2 on a line has the same effect as @key{RET}.
+See also variable @code{reftex-highlight-selection}, @ref{Options
+(Fontification)}.@refill
+
+@item f
+@vindex reftex-toc-follow-mode
+@vindex reftex-revisit-to-follow
+Toggle follow mode. When follow mode is active, the other window will
+always show the location corresponding to the line at point in the
+@file{*toc*} buffer. This is similar to pressing @key{SPC} after each
+cursor motion. The default for this flag can be set with the variable
+@code{reftex-toc-follow-mode}. Note that only context in files already
+visited is shown. @b{Ref@TeX{}} will not visit a file just for follow
+mode. See, however, the variable
+@code{reftex-revisit-to-follow}.@refill
+
+@item .
+Show calling point in another window. This is the point from where
+@code{reftex-toc} was last called.
+
+@tablesubheading{Exiting}
+@item q
+Hide the @file{*toc*} buffer, return to the position where
+@code{reftex-toc} was last called.@refill
+
+@item k
+Kill the @file{*toc*} buffer, return to the position where
+@code{reftex-toc} was last called.@refill
+
+@item C-c >
+Switch to the @file{*Index*} buffer of this document. With prefix
+@samp{2}, restrict the index to the section at point in the @file{*toc*}
+buffer.
+
+@tablesubheading{Controlling what gets displayed}
+
+@item F
+@vindex reftex-toc-include-file-boundaries
+Toggle the display of the file borders of a multifile document in the
+@file{*toc*} buffer. The default for this flag can be set with the
+variable @code{reftex-toc-include-file-boundaries}.@refill
+
+@item l
+@vindex reftex-toc-include-labels
+Toggle the display of labels in the @file{*toc*} buffer. The default
+for this flag can be set with the variable
+@code{reftex-toc-include-labels}. When called with a prefix argument,
+@b{Ref@TeX{}} will prompt for a label type and include only labels of
+the selected type in the @file{*toc*} buffer. The mode line @samp{L<>}
+indicator shows which labels are included.@refill
+
+@item i
+@vindex reftex-toc-include-index-entries
+Toggle the display of index entries in the @file{*toc*} buffer. The
+default for this flag can be set with the variable
+@code{reftex-toc-include-index-entries}. When called with a prefix
+argument, @b{Ref@TeX{}} will prompt for a specific index and include
+only entries in the selected index in the @file{*toc*} buffer. The mode
+line @samp{I<>} indicator shows which index is used.@refill
+
+@item c
+@vindex reftex-toc-include-context
+Toggle the display of label and index context in the @file{*toc*}
+buffer. The default for this flag can be set with the variable
+@code{reftex-toc-include-context}.@refill
+
+@tablesubheading{Updating the buffer}
+
+@item g
+Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the
+document.@refill
+
+@item r
+@vindex reftex-enable-partial-scans
+Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When
+@code{reftex-enable-partial-scans} is non-nil, rescan only the file this
+location is defined in, not the entire document.@refill
+
+@item C-u r
+Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}
+buffer.@refill
+
+@item x
+Switch to the @file{*toc*} buffer of an external document. When the
+current document is using the @code{xr} package (@pxref{xr (LaTeX
+package)}), @b{Ref@TeX{}} will switch to one of the external
+documents.@refill
+
+@end table
+
+@vindex reftex-toc-map
+In order to define additional commands for the @file{*toc*} buffer, the
+keymap @code{reftex-toc-map} may be used.@refill
+
+@cindex Sectioning commands
+@cindex KOMA-Script, LaTeX classes
+@cindex LaTeX classes, KOMA-Script
+@vindex reftex-section-levels
+The section macros recognized by @b{Ref@TeX{}} are all LaTeX section
+macros (from @code{\part} to @code{\subsubparagraph}) and the commands
+@code{\addchap} and @code{\addsec} from the KOMA-Script classes.
+Additional macros can be configured with the variable
+@code{reftex-section-levels}.
+
+@node Labels and References, Citations, Table of Contents, Top
+@chapter Labels and References
+@cindex Labels in LaTeX
+@cindex References in LaTeX
+@cindex Label category
+@cindex Label environment
+@cindex @code{\label}
+
+LaTeX provides a powerful mechanism to deal with cross--references in a
+document. When writing a document, any part of it can be marked with a
+label, like @samp{\label@{mark@}}. LaTeX records the current value of a
+certain counter when a label is defined. Later references to this label
+(like @samp{\ref@{mark@}}) will produce the recorded value of the
+counter.@refill
+
+Labels can be used to mark sections, figures, tables, equations,
+footnotes, items in enumerate lists etc. LaTeX is context sensitive in
+doing this: A label defined in a figure environment automatically
+records the figure counter, not the section counter.@refill
+
+Several different environments can share a common counter and therefore
+a common label category. E.g. labels in both @code{equation} and
+@code{eqnarray} environments record the value of the same counter - the
+equation counter.@refill
+
+@menu
+* Creating Labels::
+* Referencing Labels::
+* Builtin Label Environments:: The environments RefTeX knows about.
+* Defining Label Environments:: ... and environments it doesn't.
+* Reference Info:: View the label corresponding to a \ref.
+* xr (LaTeX package):: References to external documents.
+* varioref (LaTeX package):: How to create \vref instead of \ref.
+* fancyref (LaTeX package):: How to create \fref instead of \ref.
+@end menu
+
+@node Creating Labels, Referencing Labels, , Labels and References
+@section Creating Labels
+@cindex Creating labels
+@cindex Labels, creating
+@cindex Labels, deriving from context
+@kindex C-c (
+@findex reftex-label
+
+In order to create a label in a LaTeX document, press @kbd{C-c (}
+(@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive
+and will figure out the environment it currently is in and adapt the
+label to that environment. A label usually consists of a short prefix
+indicating the type of the label and a unique mark. @b{Ref@TeX{}} has
+3 different modes to create this mark.@refill
+
+@enumerate
+@item
+@vindex reftex-translate-to-ascii-function
+@vindex reftex-derive-label-parameters
+@vindex reftex-label-illegal-re
+@vindex reftex-abbrev-parameters
+A label can be derived from context. This means, @b{Ref@TeX{}} takes
+the context of the label definition and constructs a label from
+that@footnote{Note that the context may contain constructs which are
+illegal in labels. @b{Ref@TeX{}} will therefore strip the accent from
+accented Latin-1 characters and remove everything else which is not
+legal in labels. This mechanism is safe, but may not be satisfactory
+for non-western languages. Check the following variables if you need to
+change things: @code{reftex-translate-to-ascii-function},
+@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
+@code{reftex-abbrev-parameters}.}. This works best for section labels,
+where the section heading is used to construct a label. In fact,
+@b{Ref@TeX{}}'s default settings use this method only for section
+labels. You will be asked to confirm the derived label, or edit
+it.@refill
+
+@item
+We may also use a simple unique number to identify a label. This is
+mostly useful for labels where it is difficult to come up with a very
+good descriptive name. @b{Ref@TeX{}}'s default settings use this method
+for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}}
+tends to write documents with many equations and finds it impossible
+to come up with good names for each of them. These simple labels are
+inserted without query, and are therefore very fast. Good descriptive
+names are not really necessary as @b{Ref@TeX{}} will provide context to
+reference a label (@pxref{Referencing Labels}).@refill
+
+@item
+The third method is to ask the user for a label. This is most
+useful for things which are easy to describe briefly and do not turn up
+too frequently in a document. @b{Ref@TeX{}} uses this for figures and
+tables. Of course, one can enter the label directly by typing the full
+@samp{\label@{mark@}}. The advantage of using @code{reftex-label}
+anyway is that @b{Ref@TeX{}} will know that a new label has been defined.
+It will then not be necessary to rescan the document in order to access
+this label later.@refill
+@end enumerate
+
+@vindex reftex-insert-label-flags
+If you want to change the way certain labels are created, check out the
+variable @code{reftex-insert-label-flags} (@pxref{Options (Creating
+Labels)}).@refill
+
+If you are using AUCTeX to write your LaTeX documents, you can
+set it up to delegate the creation of labels to
+@b{Ref@TeX{}}. @xref{AUCTeX}, for more information.
+
+@node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References
+@section Referencing Labels
+@cindex Referencing labels
+@cindex Labels, referencing
+@cindex Selection buffer, labels
+@cindex Selection process
+@cindex @code{\ref}
+@kindex C-c )
+@findex reftex-reference
+
+Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c
+)} in order to reference a label (reftex-reference). This will start a
+selection process and finally insert the complete @samp{\ref@{label@}}
+into the buffer.@refill
+
+First, @b{Ref@TeX{}} will determine the label category which is required.
+Often that can be figured out from context. For example, if you
+write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows
+that an equation label is going to be referenced. If it cannot figure
+out what label category is needed, it will query for one.@refill
+
+You will then be presented with a label selection menu. This is a
+special buffer which contains an outline of the document along with all
+labels of the given label category. In addition, next to the label
+there will be one line of context of the label definition, which is some
+text in the buffer near the label definition. Usually this is
+sufficient to identify the label. If you are unsure about a certain
+label, pressing @key{SPC} will show the label definition point in
+another window.@refill
+
+In order to reference a label, move to cursor to the correct label and
+press @key{RET}. You can also reference several labels with a single
+call to @code{reftex-reference} by marking entries with the @kbd{m}
+key (see below).
+
+@kindex ?
+Here is a list of special commands in the selection buffer. A summary
+of this information is always available from the selection process by
+pressing @kbd{?}.@refill
+
+
+
+@table @kbd
+@tablesubheading{General}
+@item ?
+Show a summary of available commands.
+
+@item 0-9,-
+Prefix argument.
+
+@tablesubheading{Moving around}
+@item n
+Go to next label.
+
+@item p
+Go to previous label.
+
+@item b
+Jump back to the position where you last left the selection buffer.
+Normally this should get you back to the last referenced label.@refill
+
+@item C-c C-n
+Goto next section heading.
+
+@item C-c C-p
+Goto previous section heading.
+
+@tablesubheading{Displaying Context}
+@item @key{SPC}
+Show the surroundings of the definition of the current label in another
+window. See also the @kbd{f} key.@refill
+
+@item f
+@vindex reftex-revisit-to-follow
+Toggle follow mode. When follow mode is active, the other window will
+always display the full context of the current label. This is similar
+to pressing @key{SPC} after each cursor motion. Note that only context
+in files already visited is shown. @b{RefTeX} will not visit a file
+just for follow mode. See, however, the variable
+@code{reftex-revisit-to-follow}.@refill
+
+@item .
+Show insertion point in another window. This is the point from where you
+called @code{reftex-reference}.@refill
+
+@tablesubheading{Selecting a label and creating the reference}
+@item @key{RET}
+Insert a reference to the label at point into the buffer from which the
+selection process was started. When entries have been marked, @key{RET}
+references all marked labels.@refill
+
+@item mouse-2
+@vindex reftex-highlight-selection
+Clicking with mouse button 2 on a label will accept it like @key{RET}
+would. See also variable @code{reftex-highlight-selection}, @ref{Options
+(Misc)}.@refill
+
+@vindex reftex-multiref-punctuation
+@item m - + ,
+Mark the current entry. When several entries have been marked, pressing
+@kbd{RET} will accept all of them and place them into several
+@code{\ref} macros. The special markers @samp{,-+} also store a
+separator to be inserted before the corresponding reference. So marking
+six entries with the keys @samp{m , , - , +} will give a reference list
+like this (see the variable @code{reftex-multiref-punctuation})
+@example
+In eqs. (1), (2), (3)--(4), (5) and (6)
+@end example
+
+@item u
+Unmark a marked entry.
+
+@c FIXME: Do we need `A' as well for consistency?
+@cindex LaTeX packages, @code{saferef}
+@cindex @code{saferef}, LaTeX package
+@item a
+Accept the marked entries and put all labels as a comma-separated list
+into one @emph{single} @code{\ref} macro. Some packages like
+@file{saferef.sty} support multiple references in this way.@refill
+
+@item l
+Use the last referenced label(s) again. This is equivalent to moving to
+that label and pressing @key{RET}.@refill
+
+@item @key{TAB}
+Enter a label with completion. This may also be a label which does not
+yet exist in the document.
+
+@item v
+@cindex @code{varioref}, LaTeX package
+@cindex @code{\vref}
+@cindex LaTeX packages, @code{varioref}
+Toggle between @code{\ref} and @code{\vref} macro for references. The
+@code{\vref} macro is defined in the @code{varioref} LaTeX package.
+With this key you can force @b{Ref@TeX{}} to insert a @code{\vref}
+macro. The current state of this flag is displayed by the @samp{S<>}
+indicator in the mode line of the selection buffer.@refill
+
+@item V
+@cindex @code{fancyref}, LaTeX package
+@cindex @code{\fref}
+@cindex @code{\Fref}
+@cindex LaTeX packages, @code{fancyref}
+Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The
+@code{\fref} and @code{\Fref} macros are defined in the @code{fancyref}
+LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a
+@code{\fref} or @code{\Fref} macro. The current state of this flag is
+displayed by the @samp{S<>} indicator in the mode line of the
+selection buffer.
+
+@tablesubheading{Exiting}
+
+@item q
+Exit the selection process without inserting any reference into the
+buffer.@refill
+
+@tablesubheading{Controlling what gets displayed}
+@vindex reftex-label-menu-flags
+The defaults for the following flags can be configured with the variable
+@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
+
+@item c
+Toggle the display of the one-line label definition context in the
+selection buffer.@refill
+
+@item F
+Toggle the display of the file borders of a multifile document in the
+selection buffer.@refill
+
+@item t
+Toggle the display of the table of contents in the selection buffer.@refill
+
+@item #
+Toggle the display of a label counter in the selection buffer.@refill
+
+@item %
+Toggle the display of labels hidden in comments in the selection
+buffers. Sometimes, you may have commented out parts of your document.
+If these parts contain label definitions, @b{Ref@TeX{}} can still display
+and reference these labels.@refill
+
+@tablesubheading{Updating the buffer}
+@item g
+Update the menu. This will rebuilt the menu from the internal label
+list, but not reparse the document (see @kbd{r}).@refill
+
+@item r
+@vindex reftex-enable-partial-scans
+Reparse the document to update the information on all labels and rebuild
+the menu. If the variable @code{reftex-enable-partial-scans} is
+non-@code{nil} and your document is a multifile document, this will
+reparse only a part of the document (the file in which the label at
+point was defined).@refill
+
+@item C-u r
+Reparse the @emph{entire} document.
+
+@item s
+Switch the label category. After prompting for another label category,
+a menu for that category will be shown.@refill
+
+@item x
+Reference a label from an external document. With the LaTeX package
+@code{xr} it is possible to reference labels defined in another
+document. This key will switch to the label menu of an external
+document and let you select a label from there (@pxref{xr (LaTeX
+package),,xr}).@refill
+
+@end table
+
+@vindex reftex-select-label-map
+In order to define additional commands for the selection process, the
+keymap @code{reftex-select-label-map} may be used.@refill
+
+@node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References
+@section Builtin Label Environments
+@cindex Builtin label environments
+@cindex Label environments, builtin
+@cindex Environments, builtin
+@vindex reftex-label-alist
+@vindex reftex-label-alist-builtin
+
+@b{Ref@TeX{}} needs to be aware of the environments which can be referenced
+with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}}
+recognizes all labeled environments and macros discussed in @cite{The
+LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley
+1994.}. These are:@refill
+
+@itemize @minus
+@item
+@cindex @code{figure}, LaTeX environment
+@cindex @code{figure*}, LaTeX environment
+@cindex @code{table}, LaTeX environment
+@cindex @code{table*}, LaTeX environment
+@cindex @code{equation}, LaTeX environment
+@cindex @code{eqnarray}, LaTeX environment
+@cindex @code{enumerate}, LaTeX environment
+@cindex @code{\footnote}, LaTeX macro
+@cindex LaTeX macro @code{footnote}
+@cindex LaTeX core
+@code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation},
+@code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is
+the LaTeX core stuff)@refill
+@item
+@cindex AMS-LaTeX
+@cindex @code{amsmath}, LaTeX package
+@cindex LaTeX packages, @code{amsmath}
+@cindex @code{align}, AMS-LaTeX environment
+@cindex @code{gather}, AMS-LaTeX environment
+@cindex @code{multline}, AMS-LaTeX environment
+@cindex @code{flalign}, AMS-LaTeX environment
+@cindex @code{alignat}, AMS-LaTeX environment
+@cindex @code{xalignat}, AMS-LaTeX environment
+@cindex @code{xxalignat}, AMS-LaTeX environment
+@cindex @code{subequations}, AMS-LaTeX environment
+@code{align}, @code{gather}, @code{multline}, @code{flalign},
+@code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations}
+(from AMS-LaTeX's @file{amsmath.sty} package)@refill
+@item
+@cindex @code{endnote}, LaTeX package
+@cindex LaTeX packages, @code{endnote}
+@cindex @code{\endnote}, LaTeX macro
+the @code{\endnote} macro (from @file{endnotes.sty})
+@item
+@cindex @code{fancybox}, LaTeX package
+@cindex LaTeX packages, @code{fancybox}
+@cindex @code{Beqnarray}, LaTeX environment
+@code{Beqnarray} (@file{fancybox.sty})
+@item
+@cindex @code{floatfig}, LaTeX package
+@cindex LaTeX packages, @code{floatfig}
+@cindex @code{floatingfig}, LaTeX environment
+@code{floatingfig} (@file{floatfig.sty})
+@item
+@cindex @code{longtable}, LaTeX package
+@cindex LaTeX packages, @code{longtable}
+@cindex @code{longtable}, LaTeX environment
+@code{longtable} (@file{longtable.sty})
+@item
+@cindex @code{picinpar}, LaTeX package
+@cindex LaTeX packages, @code{picinpar}
+@cindex @code{figwindow}, LaTeX environment
+@cindex @code{tabwindow}, LaTeX environment
+@code{figwindow}, @code{tabwindow} (@file{picinpar.sty})
+@item
+@cindex @code{sidecap}, LaTeX package
+@cindex LaTeX packages, @code{sidecap}
+@cindex @code{SCfigure}, LaTeX environment
+@cindex @code{SCtable}, LaTeX environment
+@code{SCfigure}, @code{SCtable} (@file{sidecap.sty})
+@item
+@cindex @code{rotating}, LaTeX package
+@cindex LaTeX packages, @code{rotating}
+@cindex @code{sidewaysfigure}, LaTeX environment
+@cindex @code{sidewaystable}, LaTeX environment
+@code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty})
+@item
+@cindex @code{subfig}, LaTeX package
+@cindex LaTeX packages, @code{subfigure}
+@cindex @code{subfigure}, LaTeX environment
+@cindex @code{subfigure*}, LaTeX environment
+@code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro
+(@file{subfigure.sty})@refill
+@item
+@cindex @code{supertab}, LaTeX package
+@cindex LaTeX packages, @code{supertab}
+@cindex @code{supertabular}, LaTeX environment
+@code{supertabular} (@file{supertab.sty})
+@item
+@cindex @code{wrapfig}, LaTeX package
+@cindex LaTeX packages, @code{wrapfig}
+@cindex @code{wrapfigure}, LaTeX environment
+@code{wrapfigure} (@file{wrapfig.sty})
+@end itemize
+
+If you want to use other labeled environments, defined with
+@code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize
+them (@pxref{Defining Label Environments}).@refill
+
+@node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References
+@section Defining Label Environments
+@cindex Label environments, defining
+
+@vindex reftex-label-alist
+@b{Ref@TeX{}} can be configured to recognize additional labeled
+environments and macros. This is done with the variable
+@code{reftex-label-alist} (@pxref{Options (Defining Label
+Environments)}). If you are not familiar with Lisp, you can use the
+@code{custom} library to configure this rather complex variable. To do
+this, use
+
+@example
+@kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}
+@end example
+
+@vindex reftex-label-alist-builtin
+Here we will discuss a few examples, in order to make things clearer.
+It can also be instructive to look at the constant
+@code{reftex-label-alist-builtin} which contains the entries for
+all the builtin environments and macros (@pxref{Builtin Label
+Environments}).@refill
+
+@menu
+* Theorem and Axiom:: Defined with @code{\newenvironment}.
+* Quick Equation:: When a macro sets the label type.
+* Figure Wrapper:: When a macro argument is a label.
+* Adding Magic Words:: Other words for other languages.
+* Using \eqref:: How to switch to this AMS-LaTeX macro.
+* Non-Standard Environments:: Environments without \begin and \end
+* Putting it Together:: How to combine many entries.
+@end menu
+
+@node Theorem and Axiom, Quick Equation, , Defining Label Environments
+@subsection Theorem and Axiom Environments
+@cindex @code{theorem}, newtheorem
+@cindex @code{axiom}, newtheorem
+@cindex @code{\newtheorem}
+
+Suppose you are using @code{\newtheorem} in LaTeX in order to define two
+new environments, @code{theorem} and @code{axiom}@refill
+
+@example
+\newtheorem@{axiom@}@{Axiom@}
+\newtheorem@{theorem@}@{Theorem@}
+@end example
+
+@noindent
+to be used like this:
+
+@example
+\begin@{axiom@}
+\label@{ax:first@}
+ ....
+\end@{axiom@}
+@end example
+
+So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new
+labeled environments which define their own label categories. We can
+either use Lisp to do this (e.g. in @file{.emacs}) or use the custom
+library. With Lisp it would look like this
+
+@lisp
+(setq reftex-label-alist
+ '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax."))
+ ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th."))))
+@end lisp
+
+The type indicator characters @code{?a} and @code{?h} are used for
+prompts when @b{Ref@TeX{}} queries for a label type. @code{?h}
+was chosen for @code{theorem} since @code{?t} is already taken by
+@code{table}. Note that also @code{?s}, @code{?f}, @code{?e},
+@code{?i}, @code{?n} are already used for standard environments.@refill
+
+@noindent
+The labels for Axioms and Theorems will have the prefixes @samp{ax:} and
+@samp{thr:}, respectively. @xref{AUCTeX}, for information on how
+AUCTeX can use @b{Ref@TeX{}} to automatically create labels when a new
+environment is inserted into a buffer.@refill
+
+@noindent
+The @samp{~\ref@{%s@}} is a format string indicating how to insert
+references to these labels.@refill
+
+@noindent
+The next item indicates how to grab context of the label definition.@refill
+@itemize @minus
+@item
+@code{t} means to get it from a default location (from the beginning of
+a @code{\macro} or after the @code{\begin} statement). @code{t} is
+@emph{not} a good choice for eqnarray and similar environments.@refill
+@item
+@code{nil} means to use the text right after the label definition.@refill
+@item
+For more complex ways of getting context, see the variable
+@code{reftex-label-alist} (@ref{Options (Defining Label
+Environments)}).@refill
+@end itemize
+
+The strings at the end of each entry are used to guess the correct label
+type from the word before point when creating a reference. E.g. if you
+write: @samp{As we have shown in Theorem} and then press @kbd{C-c )},
+@b{Ref@TeX{}} will know that you are looking for a theorem label and restrict
+the menu to only these labels without even asking.@refill
+
+To do the same configuration with @code{customize}, you need to click on
+the @code{[INS]} button twice to create two templates and fill them in
+like this:@refill
+
+@example
+Reftex Label Alist: [Hide]
+[INS] [DEL] Package or Detailed : [Value Menu] Detailed:
+ Environment or \macro : [Value Menu] String: axiom
+ Type specification : [Value Menu] Char : a
+ Label prefix string : [Value Menu] String: ax:
+ Label reference format: [Value Menu] String: ~\ref@{%s@}
+ Context method : [Value Menu] After label
+ Magic words:
+ [INS] [DEL] String: axiom
+ [INS] [DEL] String: ax.
+ [INS]
+[INS] [DEL] Package or Detailed : [Value Menu] Detailed:
+ Environment or \macro : [Value Menu] String: theorem
+ Type specification : [Value Menu] Char : h
+ Label prefix string : [Value Menu] String: thr:
+ Label reference format: [Value Menu] String: ~\ref@{%s@}
+ Context method : [Value Menu] Default position
+ Magic words:
+ [INS] [DEL] String: theorem
+ [INS] [DEL] String: theor.
+ [INS] [DEL] String: th.
+ [INS]
+@end example
+
+@vindex reftex-insert-label-flags
+@vindex reftex-label-menu-flags
+Depending on how you would like the label insertion and selection for
+the new environments to work, you might want to add the letters @samp{a}
+and @samp{h} to some of the flags in the variables
+@code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
+and @code{reftex-label-menu-flags} (@pxref{Options (Referencing
+Labels)}).@refill
+
+
+@node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments
+@subsection Quick Equation Macro
+@cindex Quick equation macro
+@cindex Macros as environment wrappers
+
+Suppose you would like to have a macro for quick equations. It
+could be defined like this:
+
+@example
+\newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@}
+@end example
+
+@noindent
+and used like this:
+
+@example
+Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}.
+@end example
+
+We need to tell @b{Ref@TeX{}} that any label defined in the argument of the
+@code{\quickeq} is an equation label. Here is how to do this with lisp:
+
+@lisp
+(setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil)))
+@end lisp
+
+The first element in this list is now the macro with empty braces as an
+@emph{image} of the macro arguments. @code{?e} indicates that this is
+an equation label, the different @code{nil} elements indicate to use the
+default values for equations. The @samp{1} as the fifth element
+indicates that the context of the label definition should be the 1st
+argument of the macro.@refill
+
+Here is again how this would look in the customization buffer:
+
+@example
+Reftex Label Alist: [Hide]
+[INS] [DEL] Package or Detailed : [Value Menu] Detailed:
+ Environment or \macro : [Value Menu] String: \quickeq@{@}
+ Type specification : [Value Menu] Char : e
+ Label prefix string : [Value Menu] Default
+ Label reference format: [Value Menu] Default
+ Context method : [Value Menu] Macro arg nr: 1
+ Magic words:
+ [INS]
+@end example
+
+@node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments
+@subsection Figure Wrapping Macro
+@cindex Macros as environment wrappers
+@cindex Figure wrapping macro
+
+Suppose you want to make figures not directly with the figure
+environment, but with a macro like
+
+@example
+\newcommand@{\myfig@}[5][tbp]@{%
+ \begin@{figure@}[#1]
+ \epsimp[#5]@{#2@}
+ \caption@{#3@}
+ \label@{#4@}
+ \end@{figure@}@}
+@end example
+
+@noindent
+which would be called like
+
+@example
+\myfig[htp]@{filename@}@{caption text@}@{label@}@{1@}
+@end example
+
+Now we need to tell @b{Ref@TeX{}} that the 4th argument of the
+@code{\myfig} macro @emph{is itself} a figure label, and where to find
+the context.@refill
+
+@lisp
+(setq reftex-label-alist
+ '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))
+@end lisp
+
+The empty pairs of brackets indicate the different arguments of the
+@code{\myfig} macro. The @samp{*} marks the label argument. @code{?f}
+indicates that this is a figure label which will be listed together with
+labels from normal figure environments. The @code{nil} entries for
+prefix and reference format mean to use the defaults for figure labels.
+The @samp{3} for the context method means to grab the 3rd macro argument
+- the caption.@refill
+
+As a side effect of this configuration, @code{reftex-label} will now
+insert the required naked label (without the @code{\label} macro) when
+point is directly after the opening parenthesis of a @code{\myfig} macro
+argument.@refill
+
+Again, here the configuration in the customization buffer:
+
+@example
+[INS] [DEL] Package or Detailed : [Value Menu] Detailed:
+ Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@}
+ Type specification : [Value Menu] Char : f
+ Label prefix string : [Value Menu] Default
+ Label reference format: [Value Menu] Default
+ Context method : [Value Menu] Macro arg nr: 3
+ Magic words:
+ [INS]
+@end example
+
+@node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments
+@subsection Adding Magic Words
+@cindex Magic words
+@cindex German magic words
+@cindex Label category
+
+Sometimes you don't want to define a new label environment or macro, but
+just change the information associated with a label category. Maybe you
+want to add some magic words, for another language. Changing only the
+information associated with a label category is done by giving
+@code{nil} for the environment name and then specify the items you want
+to define. Here is an example which adds German magic words to all
+predefined label categories.@refill
+
+@lisp
+(setq reftex-label-alist
+ '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil"))
+ (nil ?e nil nil nil ("Gleichung" "Gl."))
+ (nil ?t nil nil nil ("Tabelle"))
+ (nil ?f nil nil nil ("Figur" "Abbildung" "Abb."))
+ (nil ?n nil nil nil ("Anmerkung" "Anm."))
+ (nil ?i nil nil nil ("Punkt"))))
+@end lisp
+
+@node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments
+@subsection Using @code{\eqref}
+@cindex @code{\eqref}, AMS-LaTeX macro
+@cindex AMS-LaTeX
+@cindex Label category
+
+Another case where one only wants to change the information associated
+with the label category is to change the macro which is used for
+referencing the label. When working with the AMS-LaTeX stuff, you might
+prefer @code{\eqref} for doing equation references. Here is how to
+do this:
+
+@lisp
+(setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil)))
+@end lisp
+
+@b{Ref@TeX{}} has also a predefined symbol for this special purpose. The
+following is equivalent to the line above.@refill
+
+@lisp
+(setq reftex-label-alist '(AMSTeX))
+@end lisp
+
+Note that this is automatically done by the @file{amsmath.el} style file
+of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX,
+this configuration will not be necessary.@refill
+
+@node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments
+@subsection Non-standard Environments
+@cindex Non-standard environments
+@cindex Environments without @code{\begin}
+@cindex Special parser functions
+@cindex Parser functions, for special environments
+
+Some LaTeX packages define environment-like structures without using the
+standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse
+these directly, but you can write your own special-purpose parser and
+use it instead of the name of an environment in an entry for
+@code{reftex-label-alist}. The function should check if point is
+currently in the special environment it was written to detect. If so,
+it must return a buffer position indicating the start of this
+environment. The return value must be @code{nil} on failure to detect
+the environment. The function is called with one argument @var{bound}.
+If non-@code{nil}, @var{bound} is a boundary for backwards searches
+which should be observed. We will discuss two examples.@refill
+
+@cindex LaTeX commands, abbreviated
+
+Some people define abbreviations for
+environments, like @code{\be} for @code{\begin@{equation@}}, and
+@code{\ee} for @code{\end@{equation@}}. The parser function would have
+to search backward for these macros. When the first match is
+@code{\ee}, point is not in this environment. When the first match is
+@code{\be}, point is in this environment and the function must return
+the beginning of the match. To avoid scanning too far, we can also look
+for empty lines which cannot occure inside an equation environment.
+Here is the setup:@refill
+
+@lisp
+;; Setup entry in reftex-label-alist, using all defaults for equations
+(setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil)))
+
+(defun detect-be-ee (bound)
+ ;; Search backward for the macros or an empty line
+ (if (re-search-backward
+ "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t)
+ (if (match-beginning 2)
+ (match-beginning 2) ; Return start of environment
+ nil) ; Return nil because env is closed
+ nil)) ; Return nil for not found
+@end lisp
+
+@cindex @code{linguex}, LaTeX package
+@cindex LaTeX packages, @code{linguex}
+A more complex example is the @file{linguex.sty} package which defines
+list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are
+terminated by @samp{\z.} or by an empty line.@refill
+
+@example
+\ex. \label@{ex:12@} Some text in an exotic language ...
+ \a. \label@{ex:13@} more stuff
+ \b. \label@{ex:14@} still more stuff
+ \a. List on a deeper level
+ \b. Another item
+ \b. and the third one
+ \z.
+ \b. Third item on this level.
+
+... text after the empty line terminating all lists
+@end example
+
+The difficulty is that the @samp{\a.} lists can nest and that an empty
+line terminates all list levels in one go. So we have to count nesting
+levels between @samp{\a.} and @samp{\z.}. Here is the implementation
+for @b{Ref@TeX{}}.
+
+@lisp
+(setq reftex-label-alist
+ '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
+
+(defun detect-linguex (bound)
+ (let ((cnt 0))
+ (catch 'exit
+ (while
+ ;; Search backward for all possible delimiters
+ (re-search-backward
+ (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|"
+ "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)")
+ nil t)
+ ;; Check which delimiter was matched.
+ (cond
+ ((match-beginning 1)
+ ;; empty line terminates all - return nil
+ (throw 'exit nil))
+ ((match-beginning 2)
+ ;; \z. terminates one list level - decrease nesting count
+ (decf cnt))
+ ((match-beginning 3)
+ ;; \ex. : return match unless there was a \z. on this level
+ (throw 'exit (if (>= cnt 0) (match-beginning 3) nil)))
+ ((match-beginning 4)
+ ;; \a. : return match when on level 0, otherwise
+ ;; increment nesting count
+ (if (>= cnt 0)
+ (throw 'exit (match-beginning 4))
+ (incf cnt))))))))
+@end lisp
+
+@node Putting it Together, , Non-Standard Environments, Defining Label Environments
+@subsection Putting it all together
+
+When you have to put several entries into @code{reftex-label-alist}, just
+put them after each other in a list, or create that many templates in
+the customization buffer. Here is a lisp example which uses several of
+the entries described above:
+
+@lisp
+(setq reftex-label-alist
+ '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax."))
+ ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th."))
+ ("\\quickeq@{@}" ?e nil nil 1 nil)
+ AMSTeX
+ ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)
+ (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex."))))
+@end lisp
+
+@node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References
+@section Reference Info
+@findex reftex-view-crossref
+@findex reftex-mouse-view-crossref
+@cindex Cross-references, displaying
+@cindex Reference info
+@cindex Displaying cross-references
+@cindex Viewing cross-references
+@kindex C-c &
+@kindex S-mouse-2
+
+When point is idle on the argument of a @code{\ref} macro, the echo area
+will display some information about the label referenced there. Note
+that the information is only displayed if the echo area is not occupied
+by a different message.
+
+@b{Ref@TeX{}} can also display the label definition corresponding to a
+@code{\ref} macro, or all reference locations corresponding to a
+@code{\label} macro. @xref{Viewing Cross-References}, for more
+information.@refill
+
+@node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References
+@section @code{xr}: Cross-Document References
+@cindex @code{xr}, LaTeX package
+@cindex LaTeX packages, @code{xr}
+@cindex @code{\externaldocument}
+@cindex External documents
+@cindex References to external documents
+@cindex Cross-document references
+
+The LaTeX package @code{xr} makes it possible to create references to
+labels defined in external documents. The preamble of a document using
+@code{xr} will contain something like this:@refill
+
+@example
+\usepackage@{xr@}
+\externaldocument[V1-]@{volume1@}
+\externaldocument[V3-]@{volume3@}
+@end example
+
+@noindent
+and we can make references to any labels defined in these
+external documents by using the prefixes @samp{V1-} and @samp{V3-},
+respectively.@refill
+
+@b{Ref@TeX{}} can be used to create such references as well. Start the
+referencing process normally, by pressing @kbd{C-c )}. Select a label
+type if necessary. When you see the label selection buffer, pressing
+@kbd{x} will switch to the label selection buffer of one of the external
+documents. You may then select a label as before and @b{Ref@TeX{}} will
+insert it along with the required prefix.@refill
+
+For this kind of inter-document cross-references, saving of parsing
+information and the use of multiple selection buffers can mean a large
+speed-up (@pxref{Optimizations}).@refill
+
+@node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References
+@section @code{varioref}: Variable Page References
+@cindex @code{varioref}, LaTeX package
+@cindex @code{\vref}
+@cindex LaTeX packages, @code{varioref}
+@vindex reftex-vref-is-default
+@code{varioref} is a frequently used LaTeX package to create
+cross--references with page information. When you want to make a
+reference with the @code{\vref} macro, just press the @kbd{v} key in the
+selection buffer to toggle between @code{\ref} and @code{\vref}
+(@pxref{Referencing Labels}). The mode line of the selection buffer
+shows the current status of this switch. If you find that you almost
+always use @code{\vref}, you may want to make it the default by
+customizing the variable @code{reftex-vref-is-default}. If this
+toggling seems too inconvenient, you can also use the command
+@code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}.
+Or use AUCTeX to create your macros (@pxref{AUCTeX}).@refill
+
+@node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References
+@section @code{fancyref}: Fancy Cross References
+@cindex @code{fancyref}, LaTeX package
+@cindex @code{\fref}
+@cindex @code{\Fref}
+@cindex LaTeX packages, @code{fancyref}
+@vindex reftex-fref-is-default
+@code{fancyref} is a LaTeX package where a macro call like
+@code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of
+the referenced counter but also the complete text around it, like
+@samp{Figure 3 on the preceding page}. In order to make it work you
+need to use label prefixes like @samp{fig:} consistently - something
+@b{Ref@TeX{}} does automatically. When you want to make a reference
+with the @code{\fref} macro, just press the @kbd{V} key in the selection
+buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref}
+(@pxref{Referencing Labels}). The mode line of the selection buffer
+shows the current status of this switch. If this cycling seems
+inconvenient, you can also use the commands @code{reftex-fancyref-fref}
+and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c
+f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros
+(@pxref{AUCTeX}).@refill
+
+@node Citations, Index Support, Labels and References, Top
+@chapter Citations
+@cindex Citations
+@cindex @code{\cite}
+
+Citations in LaTeX are done with the @code{\cite} macro or variations of
+it. The argument of the macro is a citation key which identifies an
+article or book in either a BibTeX database file or in an explicit
+@code{thebibliography} environment in the document. @b{Ref@TeX{}}'s
+support for citations helps to select the correct key quickly.@refill
+
+@menu
+* Creating Citations:: How to create them.
+* Citation Styles:: Natbib, Harvard, Chicago and Co.
+* Citation Info:: View the corresponding database entry.
+* Chapterbib and Bibunits:: Multiple bibliographies in a Document.
+* Citations Outside LaTeX:: How to make citations in Emails etc.
+@end menu
+
+@node Creating Citations, Citation Styles, , Citations
+@section Creating Citations
+@cindex Creating citations
+@cindex Citations, creating
+@findex reftex-citation
+@kindex C-c [
+@cindex Selection buffer, citations
+@cindex Selection process
+
+In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then
+prompts for a regular expression which will be used to search through
+the database and present the list of matches to choose from in a
+selection process similar to that for selecting labels
+(@pxref{Referencing Labels}).@refill
+
+The regular expression uses an extended syntax: @samp{&&} defines a
+logic @code{and} for regular expressions. For example
+@samp{Einstein&&Bose} will match all articles which mention
+Bose-Einstein condensation, or which are co-authored by Bose and
+Einstein. When entering the regular expression, you can complete on
+known citation keys.@refill
+
+@cindex @code{\bibliography}
+@cindex @code{thebibliography}, LaTeX environment
+@cindex @code{BIBINPUTS}, environment variable
+@cindex @code{TEXBIB}, environment variable
+@b{Ref@TeX{}} prefers to use BibTeX database files specified with a
+@code{\bibliography} macro to collect its information. Just like
+BibTeX, it will search for the specified files in the current directory
+and along the path given in the environment variable @code{BIBINPUTS}.
+If you do not use BibTeX, but the document contains an explicit
+@code{thebibliography} environment, @b{Ref@TeX{}} will collect its
+information from there. Note that in this case the information
+presented in the selection buffer will just be a copy of relevant
+@code{\bibitem} entries, not the structured listing available with
+BibTeX database files.@refill
+
+@kindex ?
+In the selection buffer, the following keys provide special commands. A
+summary of this information is always available from the selection
+process by pressing @kbd{?}.@refill
+
+@table @kbd
+@tablesubheading{General}
+@item ?
+Show a summary of available commands.
+
+@item 0-9,-
+Prefix argument.
+
+@tablesubheading{Moving around}
+@item n
+Go to next article.
+
+@item p
+Go to previous article.
+
+@tablesubheading{Access to full database entries}
+@item @key{SPC}
+Show the database entry corresponding to the article at point, in
+another window. See also the @kbd{f} key.@refill
+
+@item f
+Toggle follow mode. When follow mode is active, the other window will
+always display the full database entry of the current article. This is
+equivalent to pressing @key{SPC} after each cursor motion. With BibTeX
+entries, follow mode can be rather slow.@refill
+
+@tablesubheading{Selecting entries and creating the citation}
+@item @key{RET}
+Insert a citation referencing the article at point into the buffer from
+which the selection process was started.@refill
+
+@item mouse-2
+@vindex reftex-highlight-selection
+Clicking with mouse button 2 on a citation will accept it like @key{RET}
+would. See also variable @code{reftex-highlight-selection}, @ref{Options
+(Misc)}.@refill
+
+@item m
+Mark the current entry. When one or several entries are marked,
+pressing @kbd{a} or @kbd{A} accepts all marked entries. Also,
+@key{RET} behaves like the @kbd{a} key.
+
+@item u
+Unmark a marked entry.
+
+@item a
+Accept all (marked) entries in the selection buffer and create a single
+@code{\cite} macro referring to them.@refill
+
+@item A
+Accept all (marked) entries in the selection buffer and create a
+separate @code{\cite} macro for each of it.@refill
+
+@item @key{TAB}
+Enter a citation key with completion. This may also be a key which does
+not yet exist.
+
+@item .
+Show insertion point in another window. This is the point from where you
+called @code{reftex-citation}.@refill
+
+@tablesubheading{Exiting}
+@item q
+Exit the selection process without inserting a citation into the
+buffer.@refill
+
+@tablesubheading{Updating the buffer}
+
+@item g
+Start over with a new regular expression. The full database will be
+rescanned with the new expression (see also @kbd{r}).@refill
+
+@c FIXME: Should we use something else here? r is usually rescan!
+@item r
+Refine the current selection with another regular expression. This will
+@emph{not} rescan the entire database, but just the already selected
+entries.@refill
+
+@end table
+
+@vindex reftex-select-bib-map
+In order to define additional commands for this selection process, the
+keymap @code{reftex-select-bib-map} may be used.@refill
+
+@node Citation Styles, Citation Info, Creating Citations, Citations
+@section Citation Styles
+@cindex Citation styles
+@cindex Citation styles, @code{natbib}
+@cindex Citation styles, @code{harvard}
+@cindex Citation styles, @code{chicago}
+@cindex @code{natbib}, citation style
+@cindex @code{harvard}, citation style
+@cindex @code{chicago}, citation style
+
+@vindex reftex-cite-format
+The standard LaTeX macro @code{\cite} works well with numeric or simple
+key citations. To deal with the more complex task of author-year
+citations as used in many natural sciences, a variety of packages has
+been developed which define derived forms of the @code{\cite} macro.
+@b{Ref@TeX{}} can be configured to produce these citation macros as well by
+setting the variable @code{reftex-cite-format}. For the most commonly
+used packages (@code{natbib}, @code{harvard}, @code{chicago}) this may
+be done from the menu, under @code{Ref->Citation Styles}. Since there
+are usually several macros to create the citations, executing
+@code{reftex-citation} (@kbd{C-c [}) starts by prompting for the correct
+macro. For the Natbib style, this looks like this:
+
+@example
+SELECT A CITATION FORMAT
+
+[^M] \cite@{%l@}
+[t] \citet@{%l@}
+[T] \citet*@{%l@}
+[p] \citep@{%l@}
+[P] \citep*@{%l@}
+[e] \citep[e.g.][]@{%l@}
+[s] \citep[see][]@{%l@}
+[a] \citeauthor@{%l@}
+[A] \citeauthor*@{%l@}
+[y] \citeyear@{%l@}
+@end example
+
+Following the most generic of these packages, @code{natbib}, the builtin
+citation packages always accept the @kbd{t} key for a @emph{textual}
+citation (like: @code{Jones et al. (1997) have shown...}) as well as
+the @kbd{p} key for a parenthetical citation (like: @code{As shown
+earlier (Jones et al, 1997)}).@refill
+
+To make one of these styles the default, customize the variable
+@code{reftex-cite-format} or put into @file{.emacs}:
+
+@lisp
+(setq reftex-cite-format 'natbib)
+@end lisp
+
+You can also use AUCTeX style files to automatically set the
+citation style based on the @code{usepackage} commands in a given
+document. @xref{Style Files}, for information on how to set up the style
+files correctly.@refill
+
+@node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top
+@section Citation Info
+@cindex Displaying citations
+@cindex Citations, displaying
+@cindex Citation info
+@cindex Viewing citations
+@kindex C-c &
+@kindex S-mouse-2
+@findex reftex-view-crossref
+@findex reftex-mouse-view-crossref
+
+When point is idle on the argument of a @code{\cite} macro, the echo area
+will display some information about the article cited there. Note
+that the information is only displayed if the echo area is not occupied
+by a different message.
+
+@b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database
+entry corresponding to a @code{\cite} macro, or all citation locations
+corresponding to a @code{\bibitem} or BibTeX database entry.
+@xref{Viewing Cross-References}.@refill
+
+@node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations
+@section Chapterbib and Bibunits
+@cindex @code{chapterbib}, LaTeX package
+@cindex @code{bibunits}, LaTeX package
+@cindex Bibliographies, multiple
+
+@code{chapterbib} and @code{bibunits} are two LaTeX packages which
+produce multiple bibliographies in a document. This is no problem for
+@b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database
+files. If they do not, it is best to have each document part in a
+separate file (as it is required for @code{chapterbib} anyway). Then
+@b{Ref@TeX{}} will still scan the locally relevant databases correctly. If
+you have multiple bibliographies within a @emph{single file}, this may
+or may not be the case.
+
+@node Citations Outside LaTeX, , Chapterbib and Bibunits, Citations
+@section Citations outside LaTeX
+@cindex Citations outside LaTeX
+@vindex reftex-default-bibliography
+
+The command @code{reftex-citation} can also be executed outside a LaTeX
+buffer. This can be useful to reference articles in the mail buffer and
+other documents. You should @emph{not} enter @code{reftex-mode} for
+this, just execute the command. The list of BibTeX files will in this
+case be taken from the variable @code{reftex-default-bibliography}.
+Setting the variable @code{reftex-cite-format} to the symbol
+@code{locally} does a decent job of putting all relevant information
+about a citation directly into the buffer. Here is the lisp code to add
+the @kbd{C-c [} binding to the mail buffer. It also provides a local
+binding for @code{reftex-cite-format}.@refill
+
+@lisp
+(add-hook
+ 'mail-setup-hook
+ (lambda ()
+ (define-key mail-mode-map "\C-c["
+ (lambda ()
+ (interactive)
+ (require 'reftex)
+ (let ((reftex-cite-format 'locally))
+ (reftex-citation))))))
+@end lisp
+
+@node Index Support, Viewing Cross-References, Citations, Top
+@chapter Index Support
+@cindex Index Support
+@cindex @code{\index}
+
+LaTeX has builtin support for creating an Index. The LaTeX core
+supports two different indices, the standard index and a glossary. With
+the help of special LaTeX packages (@file{multind.sty} or
+@file{index.sty}), any number of indices can be supported.
+
+Index entries are created with the @code{\index@{@var{entry}@}} macro.
+All entries defined in a document are written out to the @file{.aux}
+file. A separate tool must be used to convert this information into a
+nicely formatted index. Tools used with LaTeX include @code{MakeIndex}
+and @code{xindy}.@refill
+
+Indexing is a lot of work and must follow strict conventions, so that
+the same word looks the same in all index entries referencing it, and in
+order to avoid spurious multiple entries. Therefore, the author of a
+document will most likely define special macros to make this easier. To
+make @b{Ref@TeX{}} support for indexing possible, these special macros
+must be added to @b{Ref@TeX{}}'s configuration (@pxref{Defining Index
+Macros}).@refill
+
+@menu
+* Creating Index Entries::
+* Displaying and Editing the Index::
+* Builtin Index Macros:: The index macros RefTeX knows about.
+* Defining Index Macros:: ... and macros it doesn't.
+@end menu
+
+@node Creating Index Entries, Displaying and Editing the Index, , Index Support
+@section Creating Index Entries
+@cindex Creating index entries
+@cindex Index entries, creating
+@kindex C-c <
+@findex reftex-index
+
+First you need to make sure that @b{Ref@TeX{}} knows about the index
+style being used in the current document. @b{Ref@TeX{}} has builtin
+support for the default @code{\index} and @code{\glossary} macros.
+Other LaTeX packages, like the @file{multind} or @file{index} package,
+redefine the @code{\index} macro to have an additional argument, and
+@b{Ref@TeX{}} needs to be configured for those. A sufficiently new
+version of AUCTeX (9.10c or later) will do this automatically. If you
+really don't use AUCTeX (you should!), this configuration needs to be
+done by hand with the menu (@code{Ref->Index Style}), or globally for
+all your documents with
+
+@lisp
+(setq reftex-index-macros '((multind)) @r{or}
+(setq reftex-index-macros '((index))
+@end lisp
+
+@kindex C-c /
+@findex reftex-index-selection-or-word
+
+In order to index the current selection or the word at the cursor press
+@kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the
+selection or word @samp{@var{word}} to be replaced with
+@samp{\index@{@var{word}@}@var{word}}. The macro which is used
+(@code{\index} by default) can be configured with the variable
+@code{reftex-index-default-macro}. When the command is called with a
+prefix argument (@kbd{C-u C-c /}), you get a chance to edit the
+generated index entry. Use this to change the case of the word or to
+make the entry a subentry, for example by entering
+@samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes
+(@kbd{C-u C-u C-c /}), you will be asked for the index macro as well.
+When there is nothing selected and no word at point, this command will
+just call @code{reftex-index}, described below.
+
+In order to create a general index entry, press @kbd{C-c <}
+(@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the
+available index macros and for its arguments. Completion will be
+available for the index entry and, if applicable, the index tag. The
+index tag is a string identifying one of multiple indices. With the
+@file{multind} and @file{index} packages, this tag is the first argument
+to the redefined @code{\index} macro.@refill
+
+@findex reftex-index-globally
+
+There is also a command @code{reftex-index-globally}@footnote{This
+function is still experimentally and may change or go away.} which
+copies an index entry near point to other occurrences of the same word
+in the document. @b{Ref@TeX{}} assumes that the word you want to index
+is in direct contact with the index macro, e.g.
+@samp{\index@{@var{word}@}@var{word}} or
+@samp{@var{word}\index@{@var{word}@}}. If there is no such word, it
+uses the key argument of the index macro. After making you confirm the
+precise search and replace strings, a query-replace over the entire
+document will be launched.
+
+@node Displaying and Editing the Index, Builtin Index Macros, Creating Index Entries, Index Support
+@section Displaying and Editing the Index
+@cindex Displaying the Index
+@cindex Editing the Index
+@cindex Index entries, creating
+@cindex Index, displaying
+@cindex Index, editing
+@kindex C-c >
+@findex reftex-display-index
+
+In order to compile and display the index, press @kbd{C-c >}. If the
+document uses multiple indices, @b{Ref@TeX{}} will ask you to select
+one. Then, all index entries will be sorted alphabetically and
+displayed in a special buffer, the @file{*Index*} buffer. From that
+buffer you can check and edit each entry.@refill
+
+The index can be restricted to the current section or the region. Then
+only entries in that part of the document will go into the compiled
+index. To restrict to the current section, use a numeric prefix
+@samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current
+region, make the region active and use a numeric prefix @samp{3} (press
+@kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the
+restriction can be moved from one section to the next with the @kbd{<}
+and @kbd{>} keys.@refill
+
+One caveat: @b{Ref@TeX{}} finds the definition point of an index entry
+by searching near the buffer position where it had found to macro during
+scanning. If you have several identical index entries in the same
+buffer and significant changes have shifted the entries around, you must
+rescan the buffer to ensure the correspondence between the
+@file{*Index*} buffer and the definition locations. It is therefore
+advisable to rescan the document (with @kbd{r} or @kbd{C-u r})
+frequently while editing the index from the @file{*Index*}
+buffer.@refill
+
+@kindex ?
+Here is a list of special commands available in the @file{*Index*} buffer. A
+summary of this information is always available by pressing
+@kbd{?}.@refill
+
+@table @kbd
+@tablesubheading{General}
+@item ?
+Display a summary of commands.
+
+@item 0-9, -
+Prefix argument.
+
+@tablesubheading{Moving around}
+@item ! A..Z
+Pressing any capital letter will jump to the corresponding section in
+the @file{*Index*} buffer. The exclamation mark is special and jumps to
+the first entries alphabetically sorted below @samp{A}. These are
+usually non-alphanumeric characters.@refill
+@item n
+Go to next entry.@refill
+@item p
+Go to previous entry.@refill
+
+@tablesubheading{Access to document locations}
+@item @key{SPC}
+Show the place in the document where this index entry is defined.@refill
+
+@item @key{TAB}
+Go to the definition of the current index entry in another
+window.@refill
+
+@item @key{RET}
+Go to the definition of the current index entry and hide the
+@file{*Index*} buffer.@refill
+
+@item f
+@vindex reftex-index-follow-mode
+@vindex reftex-revisit-to-follow
+Toggle follow mode. When follow mode is active, the other window will
+always show the location corresponding to the line in the @file{*Index*}
+buffer at point. This is similar to pressing @key{SPC} after each
+cursor motion. The default for this flag can be set with the variable
+@code{reftex-index-follow-mode}. Note that only context in files
+already visited is shown. @b{Ref@TeX{}} will not visit a file just for
+follow mode. See, however, the variable
+@code{reftex-revisit-to-follow}.@refill
+
+@tablesubheading{Entry editing}
+@item e
+Edit the current index entry. In the minibuffer, you can edit the
+index macro which defines this entry.@refill
+
+@item C-k
+Kill the index entry. Currently not implemented because I don't know
+how to implement an @code{undo} function for this.@refill
+
+@item *
+Edit the @var{key} part of the entry. This is the initial part of the
+entry which determines the location of the entry in the index.@refill
+
+@item |
+Edit the @var{attribute} part of the entry. This is the part after the
+vertical bar. With @code{MakeIndex}, this part is an encapsulating
+macro. With @code{xindy}, it is called @emph{attribute} and is a
+property of the index entry that can lead to special formatting. When
+called with @kbd{C-u} prefix, kill the entire @var{attribute}
+part.@refill
+
+@item @@
+Edit the @var{visual} part of the entry. This is the part after the
+@samp{@@} which is used by @code{MakeIndex} to change the visual
+appearance of the entry in the index. When called with @kbd{C-u}
+prefix, kill the entire @var{visual} part.@refill
+
+@item (
+Toggle the beginning of page range property @samp{|(} of the
+entry.@refill
+
+@item )
+Toggle the end of page range property @samp{|)} of the entry.@refill
+
+@item _
+Make the current entry a subentry. This command will prompt for the
+superordinate entry and insert it.@refill
+
+@item ^
+Remove the highest superordinate entry. If the current entry is a
+subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy
+(@samp{bbb!ccc}).@refill
+
+@item &
+Globalize the current entry. This runs a search-and-replace through the
+entire document in order to index the same word at other places. Rescan
+the document in order to get the new entries into the index buffer. For
+details, see the command @code{reftex-index-globally},
+@ref{Commands}.@refill
+
+@tablesubheading{Exiting}
+@item q
+Hide the @file{*Index*} buffer.@refill
+
+@item k
+Kill the @file{*Index*} buffer.@refill
+
+@item C-c =
+Switch to the Table of Contents buffer of this document.@refill
+
+@tablesubheading{Controlling what gets displayed}
+@item c
+@vindex reftex-index-include-context
+Toggle the display of short context in the @file{*Index*} buffer. The
+default for this flag can be set with the variable
+@code{reftex-index-include-context}.@refill
+
+@item @}
+Restrict the index to a single document section. The corresponding
+section number will be displayed in the @code{R<>} indication in the
+mode line and in the header of the @file{*Index*} buffer.@refill
+
+@item @{
+Widen the index to contain all entries of the document.@refill
+
+@item <
+When the index is currently restricted, move the restriction to the
+previous section.@refill
+
+@item >
+When the index is currently restricted, move the restriction to the
+next section.@refill
+
+@tablesubheading{Updating the buffer}
+@item g
+Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the
+document. However, it sorts the entries again, so that edited entries
+will move to the correct position.@refill
+
+@item r
+@vindex reftex-enable-partial-scans
+Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When
+@code{reftex-enable-partial-scans} is non-nil, rescan only the file this
+location is defined in, not the entire document.@refill
+
+@item C-u r
+Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*}
+buffer.@refill
+
+@item s
+Switch to a different index (for documents with multiple
+indices).@refill
+@end table
+
+
+@node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support
+@section Builtin Index Macros
+@cindex Builtin index macros
+@cindex Index macros, builtin
+@vindex reftex-index-macros
+@cindex @code{multind}, LaTeX package
+@cindex @code{index}, LaTeX package
+@cindex LaTeX packages, @code{multind}
+@cindex LaTeX packages, @code{index}
+
+@b{Ref@TeX{}} by default recognizes the @code{\index} and
+@code{\glossary} macros which are defined in the LaTeX core. It has
+also builtin support for the re-implementations of the @code{\index}
+macro of the @file{multind} and @file{index} packages. However, since
+the different definitions of the @code{\index} macro are incompatible,
+you will have to explicitly specify the index style used.
+@xref{Creating Index Entries}, for information on how to do that.
+
+@node Defining Index Macros, , Builtin Index Macros, Index Support
+@section Defining Index Macros
+@cindex Defining Index Macros
+@cindex Index macros, defining
+@vindex reftex-index-macros
+
+When writing a document with an index you will probably define
+additional macros which make entries into the index.
+Let's look at an example.
+
+@example
+\newcommand@{\ix@}[1]@{#1\index@{#1@}@}
+\newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@}
+\newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@}
+@end example
+
+The first macro @code{\ix} typesets its argument in the text and places
+it into the index. The second macro @code{\nindex} typesets its
+argument in the text and places it into a separate index with the tag
+@samp{name}@footnote{We are using the syntax of the @file{index} package
+here.}. The last macro also places its argument into the index, but as
+subitems under the main index entry @samp{Astronomical Objects}. Here
+is how to make @b{Ref@TeX{}} recognize and correctly interpret these
+macros, first with Emacs Lisp.
+
+@lisp
+(setq reftex-index-macros
+ '(("\\ix@{*@}" "idx" ?x "" nil)
+ ("\\nindex@{*@}" "name" ?n "" nil)
+ ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil)))
+@end lisp
+
+Note that the index tag is @samp{idx} for the main index, and
+@samp{name} for the name index. @samp{idx} and @samp{glo} are reserved
+for the default index and for the glossary.
+
+The character arguments @code{?x}, @code{?n}, and @code{?o} are for
+quick identification of these macros when @b{Ref@TeX{}} inserts new
+index entries with @code{reftex-index}. These codes need to be
+unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the
+@code{\index}, @code{\index*}, and @code{\glossary} macros,
+respectively.
+
+The following string is empty unless your macro adds a superordinate
+entry to the index key - this is the case for the @code{\astobj} macro.
+
+To do the same thing with customize, you need to fill in the templates
+like this:
+
+@example
+Repeat:
+[INS] [DEL] List:
+ Macro with args: \ix@{*@}
+ Index Tag : [Value Menu] String: idx
+ Access Key : x
+ Key Prefix :
+ Exclusion hook : nil
+[INS] [DEL] List:
+ Macro with args: \nindex@{*@}
+ Index Tag : [Value Menu] String: name
+ Access Key : n
+ Key Prefix :
+ Exclusion hook : nil
+[INS] [DEL] List:
+ Macro with args: \astobj@{*@}
+ Index Tag : [Value Menu] String: idx
+ Access Key : o
+ Key Prefix : Astronomical Objects!
+ Exclusion hook : nil
+[INS]
+@end example
+
+With the macro @code{\ix} defined, you may want to change the default
+macro used for indexing a text phrase (@pxref{Creating Index Entries}).
+This would be done like this
+
+@lisp
+(setq reftex-index-default-macro '(?x "idx" nil))
+@end lisp
+
+which specifies that the macro identified with the character @code{?x} (the
+@code{\ix} macro) should be used for indexing phrases and words already
+in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}).
+The index tag is "idx", and the final @code{nil} means that it is not
+necessary to repeat the phrase outside the macro, because the macro
+indexes @emph{and} typesets is argument.
+
+@node Viewing Cross-References, RefTeXs Menu, Index Support, Top
+@chapter Viewing Cross--References
+@findex reftex-view-crossref
+@findex reftex-mouse-view-crossref
+@kindex C-c &
+@kindex S-mouse-2
+
+@b{Ref@TeX{}} can display cross--referencing information. This means,
+if two document locations are linked, @b{Ref@TeX{}} can display the
+matching location(s) in another window. The @code{\label} and @code{\ref}
+macros are one way of establishing such a link. Also, a @code{\cite}
+macro is linked to the corresponding @code{\bibitem} macro or a BibTeX
+database entry.@refill
+
+The feature is invoked by pressing @kbd{C-c &}
+(@code{reftex-view-crossref}) while point is on the @var{key} argument
+of a macro involved in cross--referencing. You can also click with
+@kbd{S-mouse-2} on the macro argument. Here is what will happen for
+individual classes of macros:@refill
+
+@table @asis
+
+@item @code{\ref}
+@cindex @code{\ref}
+Display the corresponding label definition. All usual
+variants@footnote{all macros that start with @samp{ref} or end with
+@samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for
+cross--reference display. This works also for labels defined in an
+external document when the current document refers to them through the
+@code{xr} interface (@pxref{xr (LaTeX package)}).@refill
+
+@item @code{\label}
+@cindex @code{\label}
+@vindex reftex-label-alist
+Display a document location which references this label. Pressing
+@kbd{C-c &} several times moves through the entire document and finds
+all locations. Not only the @code{\label} macro but also other macros
+with label arguments (as configured with @code{reftex-label-alist}) are
+active for cross--reference display.@refill
+
+@item @code{\cite}
+@cindex @code{\cite}
+Display the corresponding BibTeX database entry or @code{\bibitem}.
+All usual variants@footnote{all macros that either start or end with
+@samp{cite}} of the @code{\cite} macro are active for cross--reference
+display.@refill
+
+@item @code{\bibitem}
+@cindex @code{\bibitem}
+Display a document location which cites this article. Pressing
+@kbd{C-c &} several times moves through the entire document and finds
+all locations.@refill
+
+@item BibTeX
+@cindex BibTeX buffer, viewing cite locations from
+@cindex Viewing cite locations from BibTeX buffer
+@kbd{C-c &} is also active in BibTeX buffers. All locations in a
+document where the database entry at point is cited will be displayed.
+On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to
+the document you want to search. Subsequent calls will use the same
+document, until you break this link with a prefix argument to @kbd{C-c
+&}.@refill
+
+@item @code{\index}
+@cindex @code{\index}
+Display other locations in the document which are marked by an index
+macro with the same key argument. Along with the standard @code{\index}
+and @code{\glossary} macros, all macros configured in
+@code{reftex-index-macros} will be recognized.@refill
+@end table
+
+@vindex reftex-view-crossref-macros
+While the display of cross referencing information for the above
+mentioned macros is hard--coded, you can configure additional relations
+in the variable @code{reftex-view-crossref-macros}.
+
+@iftex
+@chapter All the Rest
+@end iftex
+
+@node RefTeXs Menu, Keybindings, Viewing Cross-References, Top
+@section @b{Ref@TeX{}}'s Menu
+@cindex RefTeXs Menu
+@cindex Menu, in the menu bar
+
+@b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems
+which support this. From this menu you can access all of
+@b{Ref@TeX{}}'s commands and a few of its options. There is also a
+@code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s
+entire set of options.@refill
+
+@node Keybindings, Faces, RefTeXs Menu, Top
+@section Default Keybindings
+@cindex Keybindings, summary
+
+Here is a summary of the available keybindings.
+
+@kindex C-c =
+@kindex C-c (
+@kindex C-c )
+@kindex C-c [
+@kindex C-c &
+@kindex S-mouse-2
+@kindex C-c /
+@kindex C-c <
+@kindex C-c >
+@example
+@kbd{C-c =} @code{reftex-toc}
+@kbd{C-c (} @code{reftex-label}
+@kbd{C-c )} @code{reftex-reference}
+@kbd{C-c [} @code{reftex-citation}
+@kbd{C-c &} @code{reftex-view-crossref}
+@kbd{S-mouse-2} @code{reftex-mouse-view-crossref}
+@kbd{C-c /} @code{reftex-index-selection-or-word}
+@kbd{C-c <} @code{reftex-index}
+@kbd{C-c >} @code{reftex-display-index}
+@end example
+
+Note that the @kbd{S-mouse-2} binding is only provided if this key is
+not already used by some other package. @b{Ref@TeX{}} will not override an
+existing binding to @kbd{S-mouse-2}.@refill
+
+Personally, I also bind some functions in the users @kbd{C-c} map for
+easier access.@refill
+
+@c FIXME: Do we need bindings for the Index macros here as well?
+@c C-c i C-c I or so????
+@c How about keybindings for reftex-reset-mode and reftex-parse-document?
+@kindex C-c t
+@kindex C-c l
+@kindex C-c r
+@kindex C-c c
+@kindex C-c v
+@kindex C-c s
+@kindex C-c g
+@example
+@kbd{C-c t} @code{reftex-toc}
+@kbd{C-c l} @code{reftex-label}
+@kbd{C-c r} @code{reftex-reference}
+@kbd{C-c c} @code{reftex-citation}
+@kbd{C-c v} @code{reftex-view-crossref}
+@kbd{C-c s} @code{reftex-search-document}
+@kbd{C-c g} @code{reftex-grep-document}
+@end example
+
+@noindent These keys are reserved for the user, so I cannot bind them by
+default. If you want to have these keybindings available, set in your
+@file{.emacs} file:
+
+@vindex reftex-extra-bindings
+@lisp
+(setq reftex-extra-bindings t)
+@end lisp
+
+@vindex reftex-load-hook
+Changing and adding to @b{Ref@TeX{}}'s keybindings is best done in the hook
+@code{reftex-load-hook}. For information on the keymaps
+which should be used to add keys, see @ref{Keymaps and Hooks}.
+
+@node Faces, AUCTeX, Keybindings, Top
+@section Faces
+@cindex Faces
+
+@b{Ref@TeX{}} uses faces when available to structure the selection and
+table of contents buffers. It does not create its own faces, but uses
+the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will
+use faces only when @code{font-lock} is loaded. This seems to be
+reasonable because people who like faces will very likely have it
+loaded. If you wish to turn off fontification or change the involved
+faces, see @ref{Options (Fontification)}.@refill
+
+@node Multifile Documents, Language Support, AUCTeX, Top
+@section Multifile Documents
+@cindex Multifile documents
+@cindex Documents, spread over files
+
+The following is relevant when working with documents spread over many
+files:@refill
+
+@itemize @bullet
+@item
+@b{Ref@TeX{}} has full support for multifile documents. You can edit parts of
+several (multifile) documents at the same time without conflicts.
+@b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and
+@code{query-replace} on all files which are part of a multifile
+document.@refill
+
+@item
+@vindex tex-main-file
+@vindex TeX-master
+All files belonging to a multifile document should have a File Variable
+(@code{TeX-master} for AUCTeX or @code{tex-main-file} for the
+standard Emacs LaTeX mode) set to the name of the master file. See the
+documentation of your (La)TeX mode and @ref{File Variables,,,emacs, The
+GNU Emacs Manual}.@refill
+
+@item
+The context of a label definition must be found in the same file as the
+label itself in order to be processed correctly by @b{Ref@TeX{}}. The only
+exception is that section labels referring to a section statement
+outside the current file can still use that section title as
+context.@refill
+@end itemize
+
+@node Language Support, Finding Files, Multifile Documents, Top
+@section Language Support
+@cindex Language support
+
+Some parts of @b{Ref@TeX{}} are language dependent. The default
+settings work well for English. If you are writing in a different
+language, the following hints may be useful:
+
+@itemize @bullet
+@item
+@vindex reftex-derive-label-parameters
+@vindex reftex-abbrev-parameters
+The mechanism to derive a label from context includes the abbreviation
+of words and omission of unimportant words. These mechanisms may have
+to be changed for other languages. See the variables
+@code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}.
+
+@item
+@vindex reftex-translate-to-ascii-function
+@vindex reftex-label-illegal-re
+Also, when a label is derived from context, @b{Ref@TeX{}} clears the
+context string from non-ASCII characters in order to make a legal label.
+If there should ever be a version of @TeX{} which allows extended
+characters @emph{in labels}, then we will have to look at the
+variables @code{reftex-translate-to-ascii-function} and
+@code{reftex-label-illegal-re}.
+
+@item
+When a label is referenced, @b{Ref@TeX{}} looks at the word before point
+to guess which label type is required. These @emph{magic words} are
+different in every language. For an example of how to add magic words,
+see @ref{Adding Magic Words}.
+
+@vindex reftex-multiref-punctuation
+@vindex reftex-cite-punctuation
+@item
+@b{Ref@TeX{}} inserts ``punctuation'' for multiple references and
+for the author list in citations. Some of this may be language
+dependent. See the variables @code{reftex-multiref-punctuation} and
+@code{reftex-cite-punctuation}.
+@end itemize
+
+@node Finding Files, Optimizations, Language Support, Top
+@section Finding Files
+@cindex Finding files
+
+In order to find files included in a document via @code{\input} or
+@code{\include}, @b{Ref@TeX{}} searches all directories specified in the
+environment variable @code{TEXINPUTS}. Similarly, it will search the
+path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for
+BibTeX database files.
+
+When searching, @b{Ref@TeX{}} will also expand recursive path
+definitions (directories ending in @samp{//} or @samp{!!}). But it will
+only search and expand directories @emph{explicitly} given in these
+variables. This may cause problems under the following circumstances:
+
+@itemize @bullet
+@item
+Most TeX system have a default search path for both TeX files and BibTeX
+files which is defined in some setup file. Usually this default path is
+for system files which @b{Ref@TeX{}} does not need to see. But if your
+document needs TeX files or BibTeX database files in a directory only
+given in the default search path, @b{Ref@TeX{}} will fail to find them.
+@item
+Some TeX systems do not use environment variables at all in order to
+specify the search path. Both default and user search path are then
+defined in setup files.
+@end itemize
+
+@noindent
+There are three ways to solve this problem:
+
+@itemize @bullet
+@item
+Specify all relevant directories explicitly in the environment
+variables. If for some reason you don't want to mess with the default
+variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own
+variables and configure @b{Ref@TeX{}} to use them instead:
+
+@lisp
+(setq reftex-texpath-environment-variables '("MYTEXINPUTS"))
+(setq reftex-bibpath-environment-variables '("MYBIBINPUTS"))
+@end lisp
+
+@item
+Specify the full search path directly in @b{Ref@TeX{}}'s variables.
+
+@lisp
+(setq reftex-texpath-environment-variables
+ '("./inp:/home/cd/tex//:/usr/local/tex//"))
+(setq reftex-bibpath-environment-variables
+ '("/home/cd/tex/lit/"))
+@end lisp
+
+@item
+Some TeX systems provide stand--alone programs to do the file search just
+like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the
+@code{kpathsearch} library which provides the command @code{kpsewhich}
+to search for files. @b{Ref@TeX{}} can be configured to use this
+program. Note that the exact syntax of the @code{kpsewhich}
+command depends upon the version of that program.
+
+@lisp
+(setq reftex-use-external-file-finders t)
+(setq reftex-external-file-finders
+ '(("tex" "kpsewhich -format=.tex %f")
+ ("bib" "kpsewhich -format=.bib %f")))
+@end lisp
+@end itemize
+
+@node Optimizations, Problems and Work-Arounds, Finding Files, Top
+@section Optimizations
+@cindex Optimizations
+
+Implementing the principle of least surprises, the default settings of
+@b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However,
+when using @b{Ref@TeX{}} for a large project and/or on a small computer,
+there are ways to improve speed or memory usage.@refill
+
+@itemize @bullet
+@item
+@b{Removing Lookup Buffers}@*
+@cindex Removing lookup buffers
+@b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX
+database files for lookup purposes. These buffers are kept, so that
+subsequent use of the same files is fast. If you can't afford keeping
+these buffers around, and if you can live with a speed penalty, try
+
+@vindex reftex-keep-temporary-buffers
+@lisp
+(setq reftex-keep-temporary-buffers nil)
+@end lisp
+
+@item
+@b{Partial Document Scans}@*
+@cindex Partial documents scans
+@cindex Document scanning, partial
+A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label}
+(@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}),
+@code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c
+=}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates
+re-parsing of the entire document in order to update the parsing
+information. For a large document this can be unnecessary, in
+particular if only one file has changed. @b{Ref@TeX{}} can be configured
+to do partial scans instead of full ones. @kbd{C-u} re-parsing then
+does apply only to the current buffer and files included from it.
+Likewise, the @kbd{r} key in both the label selection buffer and the
+table-of-contents buffer will only prompt scanning of the file in which
+the label or section macro near the cursor was defined. Re-parsing of
+the entire document is still available by using @kbd{C-u C-u} as a
+prefix, or the capital @kbd{R} key in the menus. To use this feature,
+try@refill
+
+@vindex reftex-enable-partial-scans
+@lisp
+(setq reftex-enable-partial-scans t)
+@end lisp
+
+@item
+@b{Saving Parser Information}@*
+@cindex Saving parser information
+@cindex Parse information, saving to a file
+Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full
+scan, when you start working with a document. To avoid this, parsing
+information can be stored in a file. The file @file{MASTER.rel} is used
+for storing information about a document with master file
+@file{MASTER.tex}. It is written automatically when you kill a buffer
+in @code{reftex-mode} or when you exit Emacs. The information is
+restored when you begin working with a document in a new editing
+session. To use this feature, put into @file{.emacs}:@refill
+
+@vindex reftex-save-parse-info
+@lisp
+(setq reftex-save-parse-info t)
+@end lisp
+
+@item
+@b{Automatic Document Scans}@*
+@cindex Automatic document scans
+@cindex Document scanning, automatic
+At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the
+document. If this gets into your way, it can be turned off with
+
+@vindex reftex-allow-automatic-rescan
+@lisp
+(setq reftex-allow-automatic-rescan nil)
+@end lisp
+
+@b{Ref@TeX{}} will then occasionally annotate new labels in the selection
+buffer, saying that their position in the label list in uncertain. A
+manual document scan will fix this.@refill
+
+@item
+@b{Multiple Selection Buffers}@*
+@cindex Multiple selection buffers
+@cindex Selection buffers, multiple
+Normally, the selection buffer @file{*RefTeX Select*} is re-created for
+every selection process. In documents with very many labels this can
+take several seconds. @b{Ref@TeX{}} provides an option to create a
+separate selection buffer for each label type and to keep this buffer
+from one selection to the next. These buffers are updated automatically
+only when a new label has been added in the buffers category with
+@code{reftex-label}. Updating the buffer takes as long as recreating it
+- so the time saving is limited to cases where no new labels of that
+category have been added. To turn on this feature, use@refill
+
+@vindex reftex-use-multiple-selection-buffers
+@lisp
+(setq reftex-use-multiple-selection-buffers t)
+@end lisp
+
+@noindent
+@cindex Selection buffers, updating
+You can also inhibit the automatic updating entirely. Then the
+selection buffer will always pop up very fast, but may not contain the
+most recently defined labels. You can always update the buffer by hand,
+with the @kbd{g} key. To get this behavior, use instead@refill
+
+@vindex reftex-auto-update-selection-buffers
+@lisp
+(setq reftex-use-multiple-selection-buffers t
+ reftex-auto-update-selection-buffers nil)
+@end lisp
+@end itemize
+
+@need 2000
+@noindent
+@b{As a summary}, here are the settings I recommend for heavy use of
+@b{Ref@TeX{}} with large documents:
+
+@lisp
+@group
+(setq reftex-enable-partial-scans t
+ reftex-save-parse-info t
+ reftex-use-multiple-selection-buffers t)
+@end group
+@end lisp
+
+@page
+@node AUCTeX, Multifile Documents, Faces, Top
+@section @w{AUC @TeX{}}
+@cindex @code{AUCTeX}, Emacs package
+@cindex Emacs packages, @code{AUCTeX}
+
+AUCTeX is without doubt the best major mode for editing TeX and LaTeX
+files with Emacs. If AUCTeX is not part of you Emacs distribution, you
+can get it@footnote{XEmacs 21.x users may
+want to install the corresponding XEmacs package.} by ftp from the
+@uref{http://www.sunsite.auc.dk/auctex/,AUCTeX distribution site}.
+
+@menu
+* AUCTeX-RefTeX Interface:: How both packages work together
+* Style Files:: AUCTeX's style files can support RefTeX
+* Bib-Cite:: Hypertext reading of a document
+@end menu
+
+@node AUCTeX-RefTeX Interface, Style Files, , AUCTeX
+@subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface
+
+@b{Ref@TeX{}} contains code to interface with AUCTeX. When this
+interface is turned on, both packages will interact closely. Instead of
+using @b{Ref@TeX{}}'s commands directly, you can then also use them
+indirectly as part of the AUCTeX
+environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be
+needed for all of this to work. Parts of it work also with earlier
+versions.}. The interface is turned on with@refill
+
+@lisp
+(setq reftex-plug-into-AUCTeX t)
+@end lisp
+
+If you need finer control about which parts of the interface are used
+and which not, read the docstring of the variable
+@code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x
+customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}.
+
+The following list describes the individual parts of the interface.
+
+@itemize @bullet
+@item
+@findex reftex-label
+@vindex LaTeX-label-function, @r{AUCTeX}
+@kindex C-c C-e
+@kindex C-c C-s
+@findex LaTeX-section, @r{AUCTeX}
+@findex TeX-insert-macro, @r{AUCTeX}
+@b{AUCTeX calls @code{reftex-label} to insert labels}@*
+When a new section is created with @kbd{C-c C-s}, or a new environment
+is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to
+go with it. With the interface, @code{reftex-label} is called instead.
+For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and
+@b{Ref@TeX{}} will insert
+
+@example
+\begin@{equation@}
+\label@{eq:1@}
+
+\end@{equation@}
+@end example
+
+@noindent
+without further prompts.
+
+Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}}
+will offer its default label which is derived from the section title.
+
+@item
+@b{AUCTeX tells @b{Ref@TeX{}} about new sections}@*
+When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not
+have to rescan the buffer in order to see it.@refill
+
+@item
+@findex reftex-arg-label
+@findex TeX-arg-label, @r{AUCTeX function}
+@findex reftex-arg-ref
+@findex TeX-arg-ref, @r{AUCTeX function}
+@findex reftex-arg-cite
+@findex TeX-arg-cite, @r{AUCTeX function}
+@findex reftex-arg-index
+@findex TeX-arg-index, @r{AUCTeX function}
+@findex TeX-insert-macro, @r{AUCTeX function}
+@kindex C-c @key{RET}
+@b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro
+interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for
+macro arguments. Internally, it uses the functions
+@code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to
+prompt for arguments which are labels, citation keys and index entries.
+The interface takes over these functions@footnote{@code{fset} is used to
+do this, which is not reversible. However, @b{Ref@TeX{}} implements the
+old functionality when you later decide to turn off the interface.} and
+supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For
+example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}}
+will supply its label selection process (@pxref{Referencing
+Labels}).@refill
+
+@item
+@b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@*
+@b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list.
+@end itemize
+
+@node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX
+@subsection Style Files
+@cindex Style files, AUCTeX
+@findex TeX-add-style-hook, @r{AUCTeX}
+Style files are Emacs Lisp files which are evaluated by AUCTeX in
+association with the @code{\documentclass} and @code{\usepackage}
+commands of a document. Support for @b{Ref@TeX{}} in such a style file
+is useful when the LaTeX style defines macros or environments connected
+with labels, citations, or the index. Many style files
+(e.g. @file{amsmath.el} or @file{natbib.el}) distributed with AUCTeX
+already support @b{Ref@TeX{}} in this way.@refill
+
+Before calling a @b{Ref@TeX{}} function, the style hook should always
+test for the availability of the function, so that the style file will
+also work for people who do not use @b{Ref@TeX{}}. @refill
+
+Additions made with style files in the way described below remain local
+to the current document. For example, if one package uses AMSTeX, the
+style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but
+this will not affect other documents.@refill
+
+@findex reftex-add-label-environments
+@findex reftex-add-to-label-alist
+A style hook may contain calls to
+@code{reftex-add-label-environments}@footnote{This used to be the
+function @code{reftex-add-to-label-alist} which is still available as an
+alias for compatibility.} which defines additions to
+@code{reftex-label-alist}. The argument taken by this function must have
+the same format as @code{reftex-label-alist}. The @file{amsmath.el}
+style file of AUCTeX for example contains the following:@refill
+
+@lisp
+@group
+(TeX-add-style-hook "amsmath"
+ (lambda ()
+ (if (fboundp 'reftex-add-label-environments)
+ (reftex-add-label-environments '(AMSTeX)))))
+@end group
+@end lisp
+
+@noindent
+@findex LaTeX-add-environments, @r{AUCTeX}
+while a package @code{myprop} defining a @code{proposition} environment
+with @code{\newtheorem} might use@refill
+
+@lisp
+@group
+(TeX-add-style-hook "myprop"
+ (lambda ()
+ (LaTeX-add-environments '("proposition" LaTeX-env-label))
+ (if (fboundp 'reftex-add-label-environments)
+ (reftex-add-label-environments
+ '(("proposition" ?p "prop:" "~\\ref@{%s@}" t
+ ("Proposition" "Prop.")))))))
+@end group
+@end lisp
+
+@findex reftex-set-cite-format
+Similarly, a style hook may contain a call to
+@code{reftex-set-cite-format} to set the citation format. The style
+file @file{natbib.el} for the Natbib citation style does switch
+@b{Ref@TeX{}}'s citation format like this:@refill
+
+@lisp
+(TeX-add-style-hook "natbib"
+ (lambda ()
+ (if (fboundp 'reftex-set-cite-format)
+ (reftex-set-cite-format 'natbib))))
+@end lisp
+
+@findex reftex-add-index-macros
+The hook may contain a call to @code{reftex-add-index-macros} to
+define additional @code{\index}-like macros. The argument must have
+the same format as @code{reftex-index-macros}. It may be a symbol, to
+trigger support for one of the builtin index packages. For example,
+the style @file{multind.el} contains
+
+@lisp
+(TeX-add-style-hook "multind"
+ (lambda ()
+ (and (fboundp 'reftex-add-index-macros)
+ (reftex-add-index-macros '(multind)))))
+@end lisp
+
+If you have your own package @file{myindex} which defines the
+following macros to be used with the LaTeX @file{index.sty} file
+@example
+\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@}
+\newcommand@{\aindex@}[1]@{#1\index[author]@{#1@}
+@end example
+
+you could write this in the style file @file{myindex.el}:
+
+@lisp
+(TeX-add-style-hook "myindex"
+ (lambda ()
+ (TeX-add-symbols
+ '("molec" TeX-arg-index)
+ '("aindex" TeX-arg-index))
+ (if (fboundp 'reftex-add-index-macros)
+ (reftex-add-index-macros
+ '(("molec@{*@}" "idx" ?m "Molecules!" nil)
+ ("aindex@{*@}" "author" ?a "" nil))))))
+@end lisp
+
+@findex reftex-add-section-levels
+Finally the hook may contain a call to @code{reftex-add-section-levels}
+to define additional section statements. For example, the FoilTeX class
+has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here
+is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these:
+
+@lisp
+(TeX-add-style-hook "foils"
+ (lambda ()
+ (if (fboundp 'reftex-add-section-levels)
+ (reftex-add-section-levels '(("foilhead" . 3)
+ ("rotatefoilhead" . 3))))))
+@end lisp
+
+@node Bib-Cite, , Style Files, AUCTeX
+@subsection Bib-Cite
+@cindex @code{bib-cite}, Emacs package
+@cindex Emacs packages, @code{bib-cite}
+
+Once you have written a document with labels, references and citations,
+it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has
+some support for that: @code{reftex-view-crossref} (bound to @kbd{C-c
+&}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and
+@code{reftex-search-document}. A somewhat fancier interface with mouse
+highlighting is provided (among other things) by Peter S. Galbraith's
+@file{bib-cite.el}. There is some overlap in the functionalities of
+Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with
+AUCTeX.@refill
+
+Bib-cite version 3.06 and later can be configured so that bib-cite's
+mouse functions use @b{Ref@TeX{}} for displaying references and citations.
+This can be useful in particular when working with the LaTeX @code{xr}
+package or with an explicit @code{thebibliography} environment (rather
+than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To
+make use of this feature, try@refill
+
+@vindex bib-cite-use-reftex-view-crossref
+@lisp
+(setq bib-cite-use-reftex-view-crossref t)
+@end lisp
+
+@page
+@node Problems and Work-Arounds, Imprint, Optimizations, Top
+@section Problems and Work-arounds
+@cindex Problems and work-arounds
+
+@itemize @bullet
+@item
+@b{LaTeX commands}@*
+@cindex LaTeX commands, not found
+@code{\input}, @code{\include}, @code{\bibliography} and @code{\section}
+(etc.) statements have to be first on a line (except for white space).@refill
+
+@item
+@b{Commented regions}@*
+@cindex Labels, commented out
+@b{Ref@TeX{}} sees also labels in regions commented out and will refuse to
+make duplicates of such labels. This is considered to be a feature.@refill
+
+@item
+@b{Wrong section numbers}@*
+@cindex Section numbers, wrong
+@vindex reftex-enable-partial-scans
+When using partial scans (@code{reftex-enable-partial-scans}), the section
+numbers in the table of contents may eventually become wrong. A full
+scan will fix this.@refill
+
+@item
+@b{Local settings}@*
+@cindex Settings, local
+@findex reftex-add-label-environments
+@findex reftex-set-cite-format
+@findex reftex-add-section-levels
+The label environment definitions in @code{reftex-label-alist} are
+global and apply to all documents. If you need to make definitions
+local to a document, because they would interfere with settings in other
+documents, you should use AUCTeX and set up style files with calls to
+@code{reftex-add-label-environments}, @code{reftex-set-cite-format},
+@code{reftex-add-index-macros}, and @code{reftex-add-section-levels}.
+Settings made with these functions remain local to the current
+document. @xref{AUCTeX}.@refill
+
+@item
+@b{Funny display in selection buffer}@*
+@cindex @code{x-symbol}, Emacs package
+@cindex Emacs packages, @code{x-symbol}
+@cindex @code{isotex}, Emacs package
+@cindex Emacs packages, @code{isotex}
+@cindex @code{iso-cvt}, Emacs package
+@cindex Emacs packages, @code{iso-cvt}
+When using packages which make the buffer representation of a file
+different from its disk representation (e.g. x-symbol, isotex,
+iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes
+reflects the disk state of a file. This happens only in @emph{unvisited}
+parts of a multifile document, because @b{Ref@TeX{}} visits these files
+literally for speed reasons. Then both short context and section
+headings may look different from what you usually see on your screen.
+In rare cases @code{reftex-toc} may have problems to jump to an affected
+section heading. There are three possible ways to deal with
+this:@refill
+@itemize @minus
+@item
+@vindex reftex-keep-temporary-buffers
+@code{(setq reftex-keep-temporary-buffers t)}@*
+This implies that @b{Ref@TeX{}} will load all parts of a multifile
+document into Emacs (i.e. there won't be any temporary buffers).@refill
+@item
+@vindex reftex-initialize-temporary-buffers
+@code{(setq reftex-initialize-temporary-buffers t)}@*
+This means full initialization of temporary buffers. It involves
+a penalty when the same unvisited file is used for lookup often.@refill
+@item
+Set @code{reftex-initialize-temporary-buffers} to a list of hook
+functions doing a minimal initialization.@refill
+@end itemize
+@vindex reftex-refontify-context
+See also the variable @code{reftex-refontify-context}.
+
+@item
+@b{Labels as arguments to \begin}@*
+@cindex @code{pf}, LaTeX package
+@cindex LaTeX packages, @code{pf}
+Some packages use an additional argument to a @code{\begin} macro
+to specify a label. E.g. Lamport's @file{pf.sty} uses both
+@example
+\step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@}
+ @var{claim}
+ \end@{step+@}
+@end example
+
+@noindent
+We need to trick @b{Ref@TeX{}} into swallowing this:
+
+@lisp
+@group
+;; Configuration for Lamport's pf.sty
+(setq reftex-label-alist
+ '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St."))
+ ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000)))
+@end group
+@end lisp
+
+@noindent
+The first line is just a normal configuration for a macro. For the
+@code{step+} environment we actually tell @b{Ref@TeX{}} to look for the
+@emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first}
+argument (which really is a second argument to the macro @code{\begin})
+as a label of type @code{?p}. Argument count for this macro starts only
+after the @samp{@{step+@}}, also when specifying how to get
+context.@refill
+
+@item
+@b{Idle timers in XEmacs}@*
+@cindex Idle timer restart
+@vindex reftex-use-itimer-in-xemacs
+In XEmacs, idle timer restart does not work reliably after fast
+keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command
+hook to start the timer used for automatic crossref information. When
+this bug gets fixed, a real idle timer can be requested with
+@lisp
+(setq reftex-use-itimer-in-xemacs t)
+@end lisp
+
+@item
+@b{Viper mode}@*
+@cindex Viper mode
+@cindex Keybindings, problems with Viper mode
+@findex viper-harness-minor-mode
+With @i{Viper} mode prior to Vipers version 3.01, you need to protect
+@b{Ref@TeX{}}'s keymaps with@refill
+
+@lisp
+(viper-harness-minor-mode "reftex")
+@end lisp
+
+@end itemize
+
+@page
+@node Imprint, Commands, Problems and Work-Arounds, Top
+@section Imprint
+@cindex Imprint
+@cindex Maintainer
+@cindex Acknowledgments
+@cindex Thanks
+@cindex Bug reports
+@cindex @code{http}, @b{Ref@TeX{}} home page
+@cindex @code{ftp}, @b{Ref@TeX{}} site
+
+@b{Ref@TeX{}} was written by @i{@value{AUTHOR}}
+@email{@value{AUTHOR-EMAIL}}, with contributions by @i{Stephen
+Eglen}. @b{Ref@TeX{}} is currently maintained by @refill
+
+@noindent
+@value{MAINTAINER} @email{@value{MAINTAINER-EMAIL}}
+
+If you have questions about @b{Ref@TeX{}}, there are several Usenet
+groups which have competent readers: @code{comp.emacs},
+@code{gnu.emacs.help}, @code{comp.emacs.xemacs}, @code{comp.text.tex}.
+You can also write directly to the maintainer.
+
+If you find a bug in @b{Ref@TeX{}} or its documentation, or if you want
+to contribute code or ideas, please
+@uref{mailto:@value{MAINTAINER-EMAIL},contact the maintainer}. Remember
+to provide all necessary information such as version numbers of Emacs
+and @b{Ref@TeX{}}, and the relevant part of your configuration in
+@file{.emacs}. When reporting a bug which throws an exception, please
+include a backtrace if you know how to produce one.
+
+@b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2.
+It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs
+21.x users want to install the corresponding plugin package which is
+available from the XEmacs @code{ftp} site. See the XEmacs 21.x
+documentation on package installation for details.@refill
+
+Users of earlier Emacs distributions (including Emacs 19) can get a
+@b{Ref@TeX{}} distribution from the
+@uref{http://www.strw.leidenuniv.nl/~dominik/Tools/,maintainers
+webpage}. Note that the Emacs 19 version supports many but not all
+features described in this manual.@refill
+
+Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped
+developing it with their reports. In particular thanks to
+@i{Fran Burstall, Alastair Burt, Soren Dayton, Stephen Eglen, Karl
+Eichwalder, Peter Galbraith, Kai Grossjohann, Dieter Kraft, Adrian Lanz,
+Rory Molinari, Stefan Monnier, Laurent Mugnier, Sudeep Kumar Palat,
+Daniel Polani, Robin Socha, Richard Stanton, Allan Strand, Jan Vroonhof,
+Christoph Wedler, Alan Williams}.@refill
+
+The @code{view-crossref} feature was inspired by @i{Peter Galbraith's}
+@file{bib-cite.el}.@refill
+
+Finally thanks to @i{Uwe Bolick} who first got me (some years ago) into
+supporting LaTeX labels and references with an editor (which was
+MicroEmacs at the time).@refill
+
+@node Commands, Options, Imprint, Top
+@chapter Commands
+@cindex Commands, list of
+
+Here is a summary of @b{Ref@TeX{}}'s commands. All commands are available
+from the @code{Ref} menu. For keybindings, @pxref{Keybindings}.
+
+@deffn Command reftex-toc
+Show the table of contents for the current document. When called with
+one ore two @kbd{C-u} prefixes, rescan the document first.@refill
+@end deffn
+
+@deffn Command reftex-label
+Insert a unique label. With one or two @kbd{C-u} prefixes, enforce
+document rescan first.
+@end deffn
+
+@deffn Command reftex-reference
+Start a selection process to select a label, and insert a reference to
+it. With one or two @kbd{C-u} prefixes, enforce document rescan first.
+@end deffn
+
+@deffn Command reftex-citation
+Make a citation using BibTeX database files. After prompting for a regular
+expression, scans the buffers with BibTeX entries (taken from the
+@code{\bibliography} command or a @code{thebibliography} environment)
+and offers the matching entries for selection. The selected entry is
+formated according to @code{reftex-cite-format} and inserted into the
+buffer.@refill @*
+When called with one or two @kbd{C-u} prefixes, first rescans the
+document. When called with a numeric prefix, make that many citations.
+When called with point inside the braces of a @code{\cite} command, it
+will add another key, ignoring the value of
+@code{reftex-cite-format}.@refill @*
+The regular expression uses an expanded syntax: @samp{&&} is interpreted
+as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain
+both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion
+on knows citation keys is possible. @samp{=} is a good regular
+expression to match all entries in all files.@refill
+@end deffn
+
+@deffn Command reftex-index
+Query for an index macro and insert it along with its arguments. The
+index macros available are those defined in @code{reftex-index-macro} or
+by a call to @code{reftex-add-index-macros}, typically from an AUCTeX
+style file. @b{Ref@TeX{}} provides completion for the index tag and the
+index key, and will prompt for other arguments.@refill
+@end deffn
+
+@deffn Command reftex-index-selection-or-word
+Put current selection or the word near point into the default index
+macro. This uses the information in @code{reftex-index-default-macro}
+to make an index entry. The phrase indexed is the current selection or
+the word near point. When called with one @kbd{C-u} prefix, let the
+user have a chance to edit the index entry. When called with 2
+@kbd{C-u} as prefix, also ask for the index macro and other stuff. When
+called inside TeX math mode as determined by the @file{texmathp.el}
+library which is part of AUCTeX, the string is first processed with the
+@code{reftex-index-math-format}, which see.@refill
+@end deffn
+
+@deffn Command reftex-display-index
+Display a buffer with an index compiled from the current document.
+When the document has multiple indices, first prompts for the correct one.
+When index support is turned off, offer to turn it on.
+With one or two @kbd{C-u} prefixes, rescan document first.
+With prefix 2, restrict index to current document section.
+With prefix 3, restrict index to active region.@refill
+@end deffn
+
+@deffn Command reftex-index-globally
+Index a word with a global search and replace. This works very much
+like @code{reftex-query-replace-document}, but the defaults for the
+search and replace strings are derived from local context. When there
+is an index entry, we try to index similar words. The word to search
+for is the word in direct contact with the index macro (like
+@samp{\index@{@var{word}@}@var{word}} or
+@samp{@var{word}\index@{@var{word}@}}). If there is no such word, we
+use the the index key. The replacement text is the index macro with all
+its arguments and the attached word. When there is no index entry at
+point, we search for the word near point and propose to index it like
+this: @samp{\index@{@var{word}@}@var{word}}. You get a chance to edit
+the search and replacement strings.@refill
+@end deffn
+
+@deffn Command reftex-view-crossref
+View cross reference of macro at point. Point must be on the @var{key}
+argument. Works with the macros @code{\label}, @code{\ref},
+@code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of
+these. Where it makes sense, subsequent calls show additional
+locations. See also the variable @code{reftex-view-crossref-extra} and
+the command @code{reftex-view-crossref-from-bibtex}. With one or two
+@kbd{C-u} prefixes, enforce rescanning of the document. With argument
+2, select the window showing the cross reference.
+@end deffn
+
+@deffn Command reftex-view-crossref-from-bibtex
+View location in a LaTeX document which cites the BibTeX entry at point.
+Since BibTeX files can be used by many LaTeX documents, this function
+prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this
+link to a document, call the function with with a prefix arg. Calling
+this function several times find successive citation locations.
+@end deffn
+
+@deffn Command reftex-create-tags-file
+Create TAGS file by running @code{etags} on the current document. The
+TAGS file is also immediately visited with
+@code{visit-tags-table}.@refill
+@end deffn
+
+@deffn Command reftex-grep-document
+Run grep query through all files related to this document.
+With prefix arg, force to rescan document.
+No active TAGS table is required.@refill
+@end deffn
+
+@deffn Command reftex-search-document
+Regexp search through all files of the current document.
+Starts always in the master file. Stops when a match is found.
+No active TAGS table is required.@refill
+@end deffn
+
+@deffn Command reftex-query-replace-document
+Run a query-replace-regexp of @var{from} with @var{to} over the entire
+document. With prefix arg, replace only word-delimited matches. No
+active TAGS table is required.@refill
+@end deffn
+
+@deffn Command reftex-change-label
+Query replace @var{from} with @var{to} in all @code{\label} and
+@code{\ref} commands. Works on the entire multifile document. No
+active TAGS table is required.@refill
+@end deffn
+
+@deffn Command reftex-renumber-simple-labels
+Renumber all simple labels in the document to make them sequentially.
+Simple labels are the ones created by RefTeX, consisting only of the
+prefix and a number. After the command completes, all these labels will
+have sequential numbers throughout the document. Any references to the
+labels will be changed as well. For this, @b{Ref@TeX{}} looks at the
+arguments of any macros which either start or end with the string
+@samp{ref}. This command should be used with care, in particular in
+multifile documents. You should not use it if another document refers
+to this one with the @code{xr} package.@refill
+@end deffn
+
+@deffn Command reftex-find-duplicate-labels
+Produce a list of all duplicate labels in the document.@refill
+@end deffn
+
+@deffn Command reftex-customize
+Run the customize browser on the @b{Ref@TeX{}} group.
+@end deffn
+@deffn Command reftex-show-commentary
+Show the commentary section from @file{reftex.el}.
+@end deffn
+@deffn Command reftex-info
+Run info on the top @b{Ref@TeX{}} node.
+@end deffn
+@deffn Command reftex-parse-document
+Parse the entire document in order to update the parsing information.
+@end deffn
+@deffn Command reftex-reset-mode
+Enforce rebuilding of several internal lists and variables. Also
+removes the parse file associated with the current document.
+@end deffn
+
+@node Options, Keymaps and Hooks, Commands, Top
+@chapter Options, Keymaps, Hooks
+@cindex Options, list of
+
+Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All
+variables have customize support - so if you are not familiar with Emacs
+Lisp (and even if you are) you might find it more comfortable to use
+@code{customize} to look at and change these variables. @kbd{M-x
+reftex-customize} will get you there.@refill
+
+@menu
+* Options (Table of Contents)::
+* Options (Defining Label Environments)::
+* Options (Creating Labels)::
+* Options (Referencing Labels)::
+* Options (Creating Citations)::
+* Options (Index Support)::
+* Options (Viewing Cross-References)::
+* Options (Finding Files)::
+* Options (Optimizations)::
+* Options (Fontification)::
+* Options (Misc)::
+@end menu
+
+@node Options (Table of Contents), Options (Defining Label Environments), , Options
+@section Table of Contents
+@cindex Options, table of contents
+@cindex Table of contents, options
+
+@defopt reftex-toc-keep-other-windows
+Non-@code{nil} means, split the selected window to display the
+@file{*toc*} buffer. This helps to keep the window configuration, but
+makes the @file{*toc*} small. When @code{nil}, all other windows except
+the selected one will be deleted, so that the @file{*toc*} window fills
+half the frame.@refill
+@end defopt
+
+@defopt reftex-toc-include-file-boundaries
+Non-@code{nil} means, include file boundaries in @file{*toc*} buffer.
+This flag can be toggled from within the @file{*toc*} buffer with the
+@kbd{i} key.@refill
+@end defopt
+
+@defopt reftex-toc-include-labels
+Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag
+can be toggled from within the @file{*toc*} buffer with the @kbd{l}
+key.@refill
+@end defopt
+
+@defopt reftex-toc-include-index-entries
+Non-@code{nil} means, include index entries in @file{*toc*} buffer.
+This flag can be toggled from within the @file{*toc*} buffer with the
+@kbd{i} key.
+@end defopt
+
+@defopt reftex-toc-include-context
+Non-@code{nil} means, include context with labels in the @file{*toc*}
+buffer. Context will only be shown if the labels are visible as well.
+This flag can be toggled from within the @file{*toc*} buffer with the
+@kbd{c} key.@refill
+@end defopt
+
+@defopt reftex-toc-follow-mode
+Non-@code{nil} means, point in @file{*toc*} buffer (the
+table-of-contents buffer) will cause other window to follow. The other
+window will show the corresponding part of the document. This flag can
+be toggled from within the @file{*toc*} buffer with the @kbd{f}
+key.@refill
+@end defopt
+
+@deffn {Normal Hook} reftex-toc-mode-hook
+Normal hook which is run when a @file{*toc*} buffer is
+created.@refill
+@end deffn
+
+@deffn Keymap reftex-toc-map
+The keymap which is active in the @file{*toc*} buffer.
+(@pxref{Table of Contents}).@refill
+@end deffn
+
+@node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options
+@section Defining Label Environments
+@cindex Options, defining label environments
+@cindex Defining label environments, options
+
+@defopt reftex-default-label-alist-entries
+Default label alist specifications. It is a list of symbols with
+associations in the constant @code{reftex-label-alist-builtin}.
+@code{LaTeX} should always be the last entry.@refill
+@end defopt
+
+@defopt reftex-label-alist
+Set this variable to define additions and changes to the defaults in
+@code{reftex-default-label-alist-entries}. The only things you
+@emph{must not} change is that @code{?s} is the type indicator for
+section labels, and @key{SPC} for the @code{any} label type. These are
+hard-coded at other places in the code.@refill
+
+The value of the variable must be a list of items. Each item is a list
+itself and has the following structure:
+
+@example
+ (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format}
+ @var{context-method} (@var{magic-word} ... ))
+@end example
+
+Each list entry describes either an environment carrying a counter for
+use with @code{\label} and @code{\ref}, or a LaTeX macro defining a
+label as (or inside) one of its arguments. The elements of each list
+entry are:@refill
+
+@table @asis
+@item @var{env-or-macro}
+Name of the environment (like @samp{table}) or macro (like
+@samp{\myfig}). For macros, indicate the arguments, as in
+@samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional
+arguments, a star to mark the label argument, if any. The macro does
+not have to have a label argument - you could also use
+@samp{\label@{...@}} inside one of its arguments.@refill
+
+Special names: @code{section} for section labels, @code{any} to define a
+group which contains all labels.@refill
+
+This may also be a function to do local parsing and identify point to be
+in a a non-standard label environment. The function must take an
+argument @var{bound} and limit backward searches to this value. It
+should return either nil or a cons cell @code{(@var{function}
+. @var{position})} with the function symbol and the position where the
+special environment starts. See the Info documentation for an
+example.@refill
+
+Finally this may also be @code{nil} if the entry is only meant to change
+some settings associated with the type indicator character (see
+below).@refill
+
+@item @var{type-key}
+Type indicator character, like @code{?t}, must be a printable ASCII
+character. The type indicator is a single character which defines a
+label type. Any label inside the environment or macro is assumed to
+belong to this type. The same character may occur several times in this
+list, to cover cases in which different environments carry the same
+label type (like @code{equation} and @code{eqnarray}). If the type
+indicator is @code{nil} and the macro has a label argument @samp{@{*@}},
+the macro defines neutral labels just like @code{\label}. In this case
+the reminder of this entry is ignored.@refill
+
+@item @var{label-prefix}
+Label prefix string, like @samp{tab:}. The prefix is a short string
+used as the start of a label. It may be the empty string. The prefix
+may contain the following @samp{%} escapes:@refill
+
+@example
+%f Current file name, directory and extension stripped.
+%F Current file name relative to master file directory.
+%u User login name, on systems which support this.
+%S A section prefix derived with variable @code{reftex-section-prefixes}.
+@end example
+
+@noindent
+Example: In a file @file{intro.tex}, @samp{eq:%f:} will become
+@samp{eq:intro:}.@refill
+
+@item @var{reference-format}
+Format string for reference insert in buffer. @samp{%s} will be
+replaced by the label. When the format starts with @samp{~}, this
+@samp{~} will only be inserted when the character before point is
+@emph{not} a whitespace.@refill
+
+@item @var{context-method}
+Indication on how to find the short context.
+@itemize @minus
+@item
+If @code{nil}, use the text following the @samp{\label@{...@}} macro.@refill
+@item
+If @code{t}, use
+@itemize @minus
+@item
+the section heading for section labels.
+@item
+text following the @samp{\begin@{...@}} statement of environments (not
+a good choice for environments like eqnarray or enumerate, where one has
+several labels in a single environment).@refill
+@item
+text after the macro name (starting with the first arg) for
+macros.@refill
+@end itemize
+@item
+If an integer, use the nth argument of the macro. As a special case,
+1000 means to get text after the last macro argument.@refill
+@item
+If a string, use as regexp to search @emph{backward} from the label.
+Context is then the text following the end of the match. E.g. putting
+this to @samp{\\caption[[@{]} will use the caption in a figure or table
+environment. @samp{\\begin@{eqnarray@}\|\\\\} works for
+eqnarrays.@refill
+@item
+If any of @code{caption}, @code{item}, @code{eqnarray-like},
+@code{alignat-like}, this symbol will internally be translated into an
+appropriate regexp (see also the variable
+@code{reftex-default-context-regexps}).@refill
+@item
+If a function, call this function with the name of the environment/macro
+as argument. On call, point will be just after the @code{\label} macro.
+The function is expected to return a suitable context string. It should
+throw an exception (error) when failing to find context. As an example,
+here is a function returning the 10 chars following the label macro as
+context:@refill
+
+@example
+(defun my-context-function (env-or-mac)
+ (if (> (point-max) (+ 10 (point)))
+ (buffer-substring (point) (+ 10 (point)))
+ (error "Buffer too small")))
+@end example
+@end itemize
+
+Label context is used in two ways by @b{Ref@TeX{}}: For display in the label
+menu, and to derive a label string. If you want to use a different
+method for each of these, specify them as a dotted pair.
+E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for
+display, and text from the default position (@code{t}) to derive a label
+string. This is actually used for section labels.@refill
+
+@item @var{magic-word-list}
+List of magic words which identify a reference to be of this type. If
+the word before point is equal to one of these words when calling
+@code{reftex-reference}, the label list offered will be automatically
+restricted to labels of the correct type. If the first element of this
+word--list is the symbol `regexp', the strings are interpreted as regular
+expressions@footnote{Careful: @b{Ref@TeX{}} will add stuff to the
+beginning and end of these regular expressions.}.@refill
+@end table
+
+If the type indicator characters of two or more entries are the same,
+@b{Ref@TeX{}} will use@refill
+@itemize @minus
+@item
+the first non-@code{nil} format and prefix
+@item
+the magic words of all involved entries.
+@end itemize
+
+Any list entry may also be a symbol. If that has an association in
+@code{reftex-label-alist-builtin}, the @code{cddr} of that association is
+spliced into the list. However, builtin defaults should normally be set
+with the variable @code{reftex-default-label-alist-entries}.@refill
+@end defopt
+
+@defopt reftex-max-section-depth
+Maximum depth of section levels in document structure.
+Standard LaTeX needs 7, default is 12.
+@end defopt
+
+@defopt reftex-section-levels
+Commands and levels used for defining sections in the document. The
+@code{car} of each cons cell is the name of the section macro. The
+@code{cdr} is a number indicating its level. A negative level means the
+same as the positive value, but the section will never get a
+number. The @code{cdr} amy also be a function which then has to return
+the level.@refill
+@end defopt
+
+@defopt reftex-section-prefixes
+Prefixes for section labels. When the label prefix given in an entry in
+@code{reftex-label-alist} contains @samp{%S}, this list is used to
+determine the correct prefix string depending on the current section
+level. The list is an alist, with each entry of the form
+@w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro
+names like @samp{chapter}, integer section levels (as given in
+@code{reftex-section-levels}), and @code{t} for the default.
+@end defopt
+
+@defopt reftex-default-context-regexps
+Alist with default regular expressions for finding context. The emacs
+lisp form @w{@code{(format regexp (regexp-quote environment))}} is used
+to calculate the final regular expression - so @samp{%s} will be
+replaced with the environment or macro.@refill
+@end defopt
+
+@node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options
+@section Creating Labels
+@cindex Options, creating labels
+@cindex Creating labels, options
+
+@defopt reftex-insert-label-flags
+Flags governing label insertion. The value has the form
+
+@example
+(@var{derive} @var{prompt})
+@end example
+
+If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible
+label from context. A section label for example will be derived from
+the section heading. The conversion of the context to a legal label is
+governed by the specifications given in
+@code{reftex-derive-label-parameters}. If @var{derive} is @code{nil},
+the default label will consist of the prefix and a unique number, like
+@samp{eq:23}.@refill
+
+If @var{prompt} is @code{t}, the user will be prompted for a label
+string. When @var{prompt} is @code{nil}, the default label will be
+inserted without query.@refill
+
+So the combination of @var{derive} and @var{prompt} controls label
+insertion. Here is a table describing all four possibilities:@refill
+
+@example
+@group
+@var{derive} @var{prompt} @var{action}
+-----------------------------------------------------------
+nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.}
+nil t @r{Prompt for label.}
+t nil @r{Derive a label from context and insert. No query.}
+t t @r{Derive a label from context, prompt for confirmation.}
+@end group
+@end example
+
+Each flag may be set to @code{t}, @code{nil}, or a string of label type
+letters indicating the label types for which it should be true. Thus,
+the combination may be set differently for each label type. The default
+settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from
+headings (with confirmation). Prompt for figure and table labels. Use
+simple labels without confirmation for everything else.@refill
+
+The available label types are: @code{s} (section), @code{f} (figure),
+@code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
+(footnote), @code{N} (endnote) plus any definitions in
+@code{reftex-label-alist}.@refill
+@end defopt
+
+@deffn Hook reftex-format-label-function
+If non-@code{nil}, should be a function which produces the string to
+insert as a label definition. The function will be called with two
+arguments, the @var{label} and the @var{default-format} (usually
+@samp{\label@{%s@}}). It should return the string to insert into the
+buffer.@refill
+@end deffn
+
+@deffn Hook reftex-string-to-label-function
+Function to turn an arbitrary string into a legal label.
+@b{Ref@TeX{}}'s default function uses the variable
+@code{reftex-derive-label-parameters}.@refill
+@end deffn
+
+@deffn Hook reftex-translate-to-ascii-function
+Filter function which will process a context string before it is used to
+derive a label from it. The intended application is to convert ISO or
+Mule characters into something legal in labels. The default function
+@code{reftex-latin1-to-ascii} removes the accents from Latin-1
+characters. X-Symbol (>=2.6) sets this variable to the much more
+general @code{x-symbol-translate-to-ascii}.@refill
+@end deffn
+
+@defopt reftex-derive-label-parameters
+Parameters for converting a string into a label. This variable is a
+list of the following items:@refill
+@table @asis
+@item @var{nwords}
+Number of words to use.
+@item @var{maxchar}
+Maximum number of characters in a label string.
+@item @var{illegal}
+@code{nil}: Throw away any words containing characters illegal in labels.@*
+@code{t}: Throw away only the illegal characters, not the whole word.
+@item @var{abbrev}
+@code{nil}: Never abbreviate words.@*
+@code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@*
+@code{1}: Abbreviate words if necessary to shorten label string.
+@item @var{separator}
+String separating different words in the label.
+@item @var{ignorewords}
+List of words which should not be part of labels.
+@item @var{downcase}
+@code{t}: Downcase words before putting them into the label.@*
+@end table
+@end defopt
+
+@defopt reftex-label-illegal-re
+Regexp matching characters not legal in labels.
+@end defopt
+
+@defopt reftex-abbrev-parameters
+Parameters for abbreviation of words. A list of four parameters.@refill
+@table @asis
+@item @var{min-chars}
+Minimum number of characters remaining after abbreviation.
+@item @var{min-kill}
+Minimum number of characters to remove when abbreviating words.@refill
+@item @var{before}
+Character class before abbrev point in word.@refill
+@item @var{after}
+Character class after abbrev point in word.@refill
+@end table
+@end defopt
+
+@node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options
+@section Referencing Labels
+@cindex Options, referencing labels
+@cindex Referencing labels, options
+
+@defopt reftex-label-menu-flags
+List of flags governing the label menu makeup. The flags are:
+@table @asis
+@item @var{table-of-contents}
+Show the labels embedded in a table of context.@refill
+@item @var{section-numbers}
+Include section numbers (like 4.1.3) in table of contents.@refill
+@item @var{counters}
+Show counters. This just numbers the labels in the menu.@refill
+@item @var{no-context}
+Non-@code{nil} means do @emph{not} show the short context.@refill
+@item @var{follow}
+Follow full context in other window.@refill
+@item @var{show-commented}
+Show labels from regions which are commented out.@refill
+@item @var{match-everywhere}
+Obsolete flag.@refill
+@item @var{show-files}
+Show begin and end of included files.@refill
+@end table
+
+Each of these flags can be set to @code{t} or @code{nil}, or to a string
+of type letters indicating the label types for which it should be true.
+These strings work like character classes in regular expressions. Thus,
+setting one of the flags to @samp{"sf"} makes the flag true for section
+and figure labels, @code{nil} for everything else. Setting it to
+@samp{"^sf"} makes it the other way round.@refill
+
+The available label types are: @code{s} (section), @code{f} (figure),
+@code{t} (table), @code{i} (item), @code{e} (equation), @code{n}
+(footnote), plus any definitions in @code{reftex-label-alist}.@refill
+
+Most options can also be switched from the label menu itself - so if you
+decide here to not have a table of contents in the label menu, you can
+still get one interactively during selection from the label menu.@refill
+@end defopt
+
+@defopt reftex-multiref-punctuation
+Punctuation strings for multiple references. When marking is used in
+the selection buffer to select several references, this variable
+associates the 3 marking characters @samp{,-+} with prefix strings to be
+inserted into the buffer before the corresponding @code{\ref} macro.
+This is used to string together whole reference sets, like
+@samp{eqs. 1,2,3-5,6 and 7} in a single call to
+@code{reftex-reference}.@refill
+@end defopt
+
+@defopt reftex-vref-is-default
+Non-@code{nil} means, the varioref macro @code{\vref} is used as
+default. In the selection buffer, the @kbd{v} key toggles the reference
+macro between @code{\ref} and @code{\vref}. The value of this variable
+determines the default which is active when entering the selection
+process. Instead of @code{nil} or @code{t}, this may also be a string
+of type letters indicating the label types for which it should be
+true.@refill
+@end defopt
+
+@defopt reftex-fref-is-default
+Non-@code{nil} means, the fancyref macro @code{\fref} is used as
+default. In the selection buffer, the @kbd{V} key toggles the reference
+macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of
+this variable determines the default which is active when entering the
+selection process. Instead of @code{nil} or @code{t}, this may also be
+a string of type letters indicating the label types for which it should
+be true.
+@end defopt
+
+@deffn Hook reftex-format-ref-function
+If non-@code{nil}, should be a function which produces the string to
+insert as a reference. Note that the insertion format can also be
+changed with @code{reftex-label-alist}. This hook also is used by the
+special commands to insert @code{\vref} and @code{\fref} references, so
+even if you set this, your setting will be ignored by the special
+commands. The function will be called with two arguments, the
+@var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}).
+It should return the string to insert into the buffer.@refill
+@end deffn
+
+@defopt reftex-level-indent
+Number of spaces to be used for indentation per section level.@refill
+@end defopt
+
+@defopt reftex-guess-label-type
+Non-@code{nil} means, @code{reftex-reference} will try to guess the
+label type. To do that, @b{Ref@TeX{}} will look at the word before the
+cursor and compare it with the magic words given in
+@code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will
+immediately offer the correct label menu - otherwise it will prompt you
+for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}}
+will always prompt for a label type.@refill
+@end defopt
+
+@deffn {Normal Hook} reftex-display-copied-context-hook
+Normal Hook which is run before context is displayed anywhere. Designed
+for @w{@code{X-Symbol}}, but may have other uses as well.@refill
+@end deffn
+
+@deffn Hook reftex-pre-refontification-functions
+@code{X-Symbol} specific hook. Probably not useful for other purposes.
+The functions get two arguments, the buffer from where the command
+started and a symbol indicating in what context the hook is
+called.@refill
+@end deffn
+
+@deffn {Normal Hook} reftex-select-label-mode-hook
+Normal hook which is run when a selection buffer enters
+@code{reftex-select-label-mode}.@refill
+@end deffn
+
+@deffn Keymap reftex-select-label-map
+The keymap which is active in the labels selection process
+(@pxref{Referencing Labels}).@refill
+@end deffn
+
+@node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options
+@section Creating Citations
+@cindex Options, creating citations
+@cindex Creating citations, options
+
+@defopt reftex-bibfile-ignore-regexps
+List of regular expressions to exclude files in
+@code{\\bibliography@{..@}}. File names matched by any of these regexps
+will not be parsed. Intended for files which contain only
+@code{@@string} macro definitions and the like, which are ignored by
+@b{Ref@TeX{}} anyway.@refill
+@end defopt
+
+@defopt reftex-default-bibliography
+List of BibTeX database files which should be used if none are specified.
+When @code{reftex-citation} is called from a document with neither
+a @samp{\bibliography@{...@}} statement nor a @code{thebibliography}
+environment, @b{Ref@TeX{}} will scan these files instead. Intended for
+using @code{reftex-citation} in non-LaTeX files. The files will be
+searched along the BIBINPUTS or TEXBIB path.@refill
+@end defopt
+
+@defopt reftex-sort-bibtex-matches
+Sorting of the entries found in BibTeX databases by reftex-citation.
+Possible values:@refill
+@example
+nil @r{Do not sort entries.}
+author @r{Sort entries by author name.}
+year @r{Sort entries by increasing year.}
+reverse-year @r{Sort entries by decreasing year.}
+@end example
+@end defopt
+
+@defopt reftex-cite-format
+The format of citations to be inserted into the buffer. It can be a
+string, an alist or a symbol. In the simplest case this is just the string
+@samp{\cite@{%l@}}, which is also the default. See the definition of
+@code{reftex-cite-format-builtin} for more complex examples.@refill
+
+If @code{reftex-cite-format} is a string, it will be used as the format.
+In the format, the following percent escapes will be expanded.@refill
+
+@table @code
+@item %l
+The BibTeX label of the citation.
+@item %a
+List of author names, see also @code{reftex-cite-punctuation}.
+@item %2a
+Like %a, but abbreviate more than 2 authors like Jones et al.
+@item %A
+First author name only.
+@item %e
+Works like @samp{%a}, but on list of editor names. (@samp{%2e} and
+@samp{%E} work a well).@refill
+@end table
+
+It is also possible to access all other BibTeX database fields:
+
+@example
+%b booktitle %c chapter %d edition %h howpublished
+%i institution %j journal %k key %m month
+%n number %o organization %p pages %P first page
+%r address %s school %u publisher %t title
+%v volume %y year
+%B booktitle, abbreviated %T title, abbreviated
+@end example
+
+@noindent
+Usually, only @samp{%l} is needed. The other stuff is mainly for the
+echo area display, and for @code{(setq reftex-comment-citations t)}.@refill
+
+@samp{%<} as a special operator kills punctuation and space around it
+after the string has been formatted.@refill
+
+Beware that all this only works with BibTeX database files. When
+citations are made from the @code{\bibitems} in an explicit
+@code{thebibliography} environment, only @samp{%l} is available.@refill
+
+If @code{reftex-cite-format} is an alist of characters and strings, the
+user will be prompted for a character to select one of the possible
+format strings.@refill
+
+In order to configure this variable, you can either set
+@code{reftex-cite-format} directly yourself or set it to the
+@emph{symbol} of one of the predefined styles. The predefined symbols
+are those which have an association in the constant
+@code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format
+'natbib)}.@refill
+@end defopt
+
+@deffn Hook reftex-format-cite-function
+
+If non-@code{nil}, should be a function which produces the string to
+insert as a citation. Note that the citation format can also be changed
+with the variable @code{reftex-cite-format}. The function will be
+called with two arguments, the @var{citation-key} and the
+@var{default-format} (taken from @code{reftex-cite-format}). It should
+return the string to insert into the buffer.@refill
+@end deffn
+
+@defopt reftex-comment-citations
+Non-@code{nil} means add a comment for each citation describing the full
+entry. The comment is formatted according to
+@code{reftex-cite-comment-format}.@refill
+@end defopt
+
+@defopt reftex-cite-comment-format
+Citation format used for commented citations. Must @emph{not} contain
+@samp{%l}. See the variable @code{reftex-cite-format} for possible
+percent escapes.@refill
+@end defopt
+
+@defopt reftex-cite-punctuation
+Punctuation for formatting of name lists in citations. This is a list
+of 3 strings.@refill
+@enumerate
+@item
+normal names separator, like @samp{, } in Jones, Brown and Miller
+@item
+final names separator, like @samp{ and } in Jones, Brown and Miller
+@item
+The @samp{et al.} string, like @samp{ @{\it et al.@}} in
+Jones @{\it et al.@}
+@end enumerate
+@end defopt
+
+@deffn {Normal Hook} reftex-select-bib-mode-hook
+Normal hook which is run when a selection buffer enters
+@code{reftex-select-bib-mode}.@refill
+@end deffn
+
+@deffn Keymap reftex-select-bib-map
+The keymap which is active in the citation-key selection process
+(@pxref{Creating Citations}).@refill
+@end deffn
+
+@node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options
+@section Index Support
+@cindex Options, Index support
+@cindex Index support, options
+
+@defopt reftex-support-index
+Non-@code{nil} means, index entries are parsed as well. Index support
+is resource intensive and the internal structure holding the parsed
+information can become quite big. Therefore it can be turned off. When
+this is @code{nil} and you execute a command which requires index
+support, you will be asked for confirmation to turn it on and rescan the
+document.@refill
+@end defopt
+
+@defopt reftex-index-special-chars
+List of special characters in index entries, given as strings. These
+correspond to the @code{MakeIndex} keywords
+@code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}.
+@end defopt
+
+@defopt reftex-index-macros
+List of macros which define index entries. The structure of each entry
+is
+@lisp
+(@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude})
+@end lisp
+
+@var{macro} is the macro. Arguments should be denoted by empty braces,
+as for example in @samp{\index[]@{*@}}. Use square brackets to denote
+optional arguments. The star marks where the index key is.@refill
+
+@var{index-tag} is a short name of the index. @samp{idx} and @samp{glo}
+are reserved for the default index and the glossary. Other indices can
+be defined as well. If this is an integer, the Nth argument of the
+macro holds the index tag.@refill
+
+@var{key} is a character which is used to identify the macro for input
+with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are
+reserved for default index and glossary.@refill
+
+@var{prefix} can be a prefix which is added to the @var{key} part of the
+index entry. If you have a macro
+@code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix
+should be @samp{Molecules!}.@refill
+
+@var{exclude} can be a function. If this function exists and returns a
+non-nil value, the index entry at point is ignored. This was
+implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts
+in the LaTeX2e @code{index} package.@refill
+
+The final entry may also be a symbol. It must have an association in
+the variable @code{reftex-index-macros-builtin} to specify the main
+indexing package you are using. Legal values are currently@refill
+@example
+default @r{The LaTeX default - unnecessary to specify this one}
+multind @r{The multind.sty package}
+index @r{The index.sty package}
+index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.}
+ @r{Should not be used - only for old documents}
+@end example
+Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well,
+so with a sufficiently new version of AUCTeX, you should not set the
+package here.
+@end defopt
+
+@defopt reftex-index-default-macro
+The default index macro for @code{reftex-index-selection-or-word}.
+This is a list with @code{(@var{macro-key} @var{default-tag} @var{repeat-word})}.
+
+@var{macro-key} is a character identifying an index macro - see
+@code{reftex-index-macros}.
+
+@var{default-tag} is the tag to be used if the macro requires a
+@var{tag} argument. When this is @code{nil} and a @var{tag} is needed,
+@b{Ref@TeX{}} will ask for it. When this is the empty string and the
+TAG argument of the index macro is optional, the TAG argument will be
+omitted.
+
+@var{repeat-word}, when non-@code{nil} means, the index macro does not
+typeset the entry in the text, so that the text has to be repeated
+outside the index macro.
+@end defopt
+
+@defopt reftex-index-default-tag
+Default index tag. When working with multiple indexes, RefTeX queries
+for an index tag when creating index entries or displaying a specific
+index. This variable controls the default offered for these queries.
+The default can be selected with @key{RET} during selection or
+completion. Legal values of this variable are:@refill
+@example
+nil @r{Do not provide a default index}
+"tag" @r{The default index tag given as a string, e.g. "idx"}
+last @r{The last used index tag will be offered as default}
+@end example
+@end defopt
+
+@defopt reftex-index-math-format
+Format of index entries when copied from inside math mode. When
+@code{reftex-index-selection-or-word} is executed inside TeX math mode,
+the index key copied from the buffer is processed with this format
+string through the @code{format} function. This can be used to add the
+math delimiters (e.g. @samp{$}) to the string. Requires the
+@file{texmathp.el} library which is part of AUCTeX.@refill
+@end defopt
+
+@defopt reftex-index-section-letters
+The letters which denote sections in the index. Usually these are all
+capital letters. Don't use any downcase letters. Order is not
+significant, the index will be sorted by whatever the sort function
+thinks is correct. In addition to these letters, RefTeX will create a
+group @samp{!} which contains all entries sorted below the lowest
+specified letter. In the @file{*Index*} buffer, pressing any of these
+capital letters or @kbd{!} will jump to that section.@refill
+@end defopt
+
+@defopt reftex-index-include-context
+Non-@code{nil} means, display the index definition context in the
+@file{*Index*} buffer. This flag may also be toggled from the
+@file{*Index*} buffer with the @kbd{c} key.
+@end defopt
+
+@defopt reftex-index-follow-mode
+Non-@code{nil} means, point in @file{*Index*} buffer will cause other
+window to follow. The other window will show the corresponding part of
+the document. This flag can be toggled from within the @file{*Index*}
+buffer with the @kbd{f} key.
+@end defopt
+
+@deffn Keymap reftex-index-map
+The keymap which is active in the @file{*Index*} buffer
+(@pxref{Index Support}).@refill
+@end deffn
+
+@node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options
+@section Viewing Cross-References
+@cindex Options, viewing cross-references
+@cindex Viewing cross-references, options
+
+@defopt reftex-view-crossref-extra
+Macros which can be used for the display of cross references.
+This is used when `reftex-view-crossref' is called with point in an
+argument of a macro. Note that crossref viewing for citations,
+references (both ways) and index entries is hard-coded. This variable
+is only to configure additional structures for which crossreference
+viewing can be useful. Each entry has the structure
+@example
+(@var{macro-re} @var{search-re} @var{highlight}).
+@end example
+@var{macro-re} is matched against the macro. @var{search-re} is the
+regexp used to search for cross references. @samp{%s} in this regexp is
+replaced with with the macro argument at point. @var{highlight} is an
+integer indicating which subgroup of the match should be highlighted.
+@end defopt
+
+@defopt reftex-auto-view-crossref
+Non-@code{nil} means, initially turn automatic viewing of crossref info
+on. Automatic viewing of crossref info normally uses the echo area.
+Whenever point is on the argument of a @code{\ref} or @code{\cite}
+macro, and no other message is being displayed, the echo area will
+display information about that cross reference. You can also set the
+variable to the symbol @code{window}. In this case a small temporary
+window is used for the display. This feature can be turned on and of
+from the menu (Ref->Options).@refill
+@end defopt
+
+@defopt reftex-idle-time
+Time (secs) Emacs has to be idle before automatic crossref display is
+done.@refill
+@end defopt
+
+@defopt reftex-cite-view-format
+Citation format used to display citation info in the message area. See
+the variable @code{reftex-cite-format} for possible percent
+escapes.@refill
+@end defopt
+
+@defopt reftex-revisit-to-echo
+Non-@code{nil} means, automatic citation display will revisit files if
+necessary. When nil, citation display in echo area will only be active
+for cached echo strings (see @code{reftex-cache-cite-echo}), or for
+BibTeX database files which are already visited by a live associated
+buffers.@refill
+@end defopt
+
+@defopt reftex-cache-cite-echo
+Non-@code{nil} means, the information displayed in the echo area for
+cite macros (see variable @code{reftex-auto-view-crossref}) is cached and
+saved along with the parsing information. The cache survives document
+scans. In order to clear it, use @kbd{M-x reftex-reset-mode}.
+@end defopt
+
+@node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options
+@section Finding Files
+@cindex Options, Finding Files
+@cindex Finding files, options
+
+@defopt reftex-texpath-environment-variables
+List of specifications how to retrieve the search path for TeX files.
+Several entries are possible.@refill
+@itemize @minus
+@item
+If an element is the name of an environment variable, its content is
+used.@refill
+@item
+If an element starts with an exclamation mark, it is used as a command
+to retrieve the path. A typical command with the kpathsearch library
+would be @w{@code{"!kpsewhich -show-path=.tex"}}.
+@item
+Otherwise the element itself is interpreted as a path.
+@end itemize
+Multiple directories can be separated by the system dependent
+@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
+be expanded recursively. See also @code{reftex-use-external-file-finders}.
+@end defopt
+
+@defopt reftex-bibpath-environment-variables
+List of specifications how to retrieve the search path for BibTeX
+files. Several entries are possible.@refill
+@itemize @minus
+@item
+If an element is the name of an environment variable, its content is
+used.@refill
+@item
+If an element starts with an exclamation mark, it is used as a command
+to retrieve the path. A typical command with the kpathsearch library
+would be @w{@code{"!kpsewhich -show-path=.bib"}}.
+@item
+Otherwise the element itself is interpreted as a path.
+@end itemize
+Multiple directories can be separated by the system dependent
+@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will
+be expanded recursively. See also @code{reftex-use-external-file-finders}.
+@end defopt
+
+@defopt reftex-file-extensions
+Association list with file extensions for different file types.
+This is a list of items, each item is like:
+@code{(@var{type} . (@var{def-ext} @var{other-ext} ...))}
+@example
+@var{type}: @r{File type like @code{"bib"} or @code{"tex"}.}
+@var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.}
+@var{other-ext}: @r{Any number of other legal extensions for this file type.}
+@end example
+When a files is searched and it does not have any of the legal extensions,
+we try the default extension first, and then the naked file name.@refill
+@end defopt
+
+@defopt reftex-search-unrecursed-path-first
+Non-@code{nil} means, search all specified directories before trying
+recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./},
+then @samp{/tex/}, and then all subdirectories of @samp{./}. If this
+option is @code{nil}, the subdirectories of @samp{./} are searched
+before @samp{/tex/}. This is mainly for speed - most of the time the
+recursive path is for the system files and not for the user files. Set
+this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with
+equal names in wrong sequence.@refill
+@end defopt
+
+@defopt reftex-use-external-file-finders
+Non-@code{nil} means, use external programs to find files. Normally,
+@b{Ref@TeX{}} searches the paths given in the environment variables
+@code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX
+database files. With this option turned on, it calls an external
+program specified in the option @code{reftex-external-file-finders}
+instead. As a side effect, the variables
+@code{reftex-texpath-environment-variables} and
+@code{reftex-bibpath-environment-variables} will be ignored.
+@end defopt
+
+@defopt reftex-external-file-finders
+Association list with external programs to call for finding files. Each
+entry is a cons cell @w{@code{(@var{type} . @var{program})}}.
+@var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a
+string containing the external program to use with any arguments.
+@code{%f} will be replaced by the name of the file to be found. Note
+that these commands will be executed directly, not via a shell. Only
+relevant when @code{reftex-use-external-file-finders} is
+non-@code{nil}.@refill
+@end defopt
+
+@page
+@node Options (Optimizations), Options (Fontification), Options (Finding Files), Options
+@section Optimizations
+@cindex Options, optimizations
+@cindex Optimizations, options
+
+@defopt reftex-keep-temporary-buffers
+Non-@code{nil} means, keep buffers created for parsing and lookup.
+@b{Ref@TeX{}} sometimes needs to visit files related to the current
+document. We distinguish files visited for@refill
+@table @asis
+@item PARSING
+Parts of a multifile document loaded when (re)-parsing the
+document.@refill
+@item LOOKUP
+BibTeX database files and TeX files loaded to find a reference, to
+display label context, etc.@refill
+@end table
+The created buffers can be kept for later use, or be thrown away
+immediately after use, depending on the value of this variable:@refill
+
+@table @code
+@item nil
+Throw away as much as possible.
+@item t
+Keep everything.
+@item 1
+Throw away buffers created for parsing, but keep the ones created for
+lookup.@refill
+@end table
+
+If a buffer is to be kept, the file is visited normally (which is
+potentially slow but will happen only once). If a buffer is to be thrown
+away, the initialization of the buffer depends upon the variable
+@code{reftex-initialize-temporary-buffers}.@refill
+@end defopt
+
+@defopt reftex-initialize-temporary-buffers
+Non-@code{nil} means do initializations even when visiting file
+temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and
+other stuff to briefly visit a file. When @code{t}, the full default
+initializations are done (@code{find-file-hook} etc.). Instead of
+@code{t} or @code{nil}, this variable may also be a list of hook
+functions to do a minimal initialization.@refill
+@end defopt
+
+@defopt reftex-no-include-regexps
+List of regular expressions to exclude certain input files from parsing.
+If the name of a file included via @code{\include} or @code{\input} is
+matched by any of the regular expressions in this list, that file is not
+parsed by @b{Ref@TeX{}}.
+@end defopt
+
+@defopt reftex-enable-partial-scans
+Non-@code{nil} means, re-parse only 1 file when asked to re-parse.
+Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}}
+commands, or with the @kbd{r} key in menus. When this option is
+@code{t} in a multifile document, we will only parse the current buffer,
+or the file associated with the label or section heading near point in a
+menu. Requesting re-parsing of an entire multifile document then
+requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in
+menus.@refill
+@end defopt
+
+@defopt reftex-save-parse-info
+Non-@code{nil} means, save information gathered with parsing in files.
+The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is
+used to save the information. When this variable is @code{t},
+@itemize @minus
+@item
+accessing the parsing information for the first time in an editing
+session will read that file (if available) instead of parsing the
+document.@refill
+@item
+exiting Emacs or killing a buffer in reftex-mode will cause a new
+version of the file to be written.@refill
+@end itemize
+@end defopt
+
+@defopt reftex-allow-automatic-rescan
+Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems
+necessary. Applies (currently) only in rare cases, when a new label
+cannot be placed with certainty into the internal label list.
+@end defopt
+
+@defopt reftex-use-multiple-selection-buffers
+Non-@code{nil} means use a separate selection buffer for each label
+type. These buffers are kept from one selection to the next and need
+not to be created for each use - so the menu generally comes up faster.
+The selection buffers will be erased (and therefore updated)
+automatically when new labels in its category are added. See the
+variable @code{reftex-auto-update-selection-buffers}.@refill
+@end defopt
+
+@defopt reftex-auto-update-selection-buffers
+Non-@code{nil} means, selection buffers will be updated automatically.
+When a new label is defined with @code{reftex-label}, all selection
+buffers associated with that label category are emptied, in order to
+force an update upon next use. When @code{nil}, the buffers are left
+alone and have to be updated by hand, with the @kbd{g} key from the
+label selection process. The value of this variable will only have any
+effect when @code{reftex-use-multiple-selection-buffers} is
+non-@code{nil}.@refill
+@end defopt
+
+@node Options (Fontification), Options (Misc), Options (Optimizations), Options
+@section Fontification
+@cindex Options, fontification
+@cindex Fontification, options
+
+@defopt reftex-use-fonts
+Non-@code{nil} means, use fonts in label menu and on-the-fly help.
+Font-lock must be loaded as well to actually get fontified
+display. After changing this option, a rescan may be necessary to
+activate it.@refill
+@end defopt
+
+@defopt reftex-refontify-context
+Non-@code{nil} means, re-fontify the context in the label menu with
+font-lock. This slightly slows down the creation of the label menu. It
+is only necessary when you definitely want the context fontified.@refill
+
+This option may have 3 different values:
+@table @code
+@item nil
+Never refontify.
+@item t
+Always refontify.
+@item 1
+Refontify when necessary, e.g. with old versions of the x-symbol
+package.@refill
+@end table
+The option is ignored when @code{reftex-use-fonts} is @code{nil}.@refill
+@end defopt
+
+@defopt reftex-highlight-selection
+Non-@code{nil} means, highlight selected text in selection and
+@file{*toc*} buffers. Normally, the text near the cursor is the
+@emph{selected} text, and it is highlighted. This is the entry most
+keys in the selection and @file{*toc*} buffers act on. However, if you
+mainly use the mouse to select an item, you may find it nice to have
+mouse-triggered highlighting @emph{instead} or @emph{as well}. The
+variable may have one of these values:@refill
+
+@example
+nil @r{No highlighting.}
+cursor @r{Highlighting is cursor driven.}
+mouse @r{Highlighting is mouse driven.}
+both @r{Both cursor and mouse trigger highlighting.}
+@end example
+
+Changing this variable requires to rebuild the selection and *toc*
+buffers to become effective (keys @kbd{g} or @kbd{r}).@refill
+@end defopt
+
+@defopt reftex-cursor-selected-face
+Face name to highlight cursor selected item in toc and selection buffers.
+See also the variable @code{reftex-highlight-selection}.@refill
+@end defopt
+@defopt reftex-mouse-selected-face
+Face name to highlight mouse selected item in toc and selection buffers.
+See also the variable @code{reftex-highlight-selection}.@refill
+@end defopt
+@defopt reftex-file-boundary-face
+Face name for file boundaries in selection buffer.
+@end defopt
+@defopt reftex-label-face
+Face name for labels in selection buffer.
+@end defopt
+@defopt reftex-section-heading-face
+Face name for section headings in toc and selection buffers.
+@end defopt
+@defopt reftex-toc-header-face
+Face name for the header of a toc buffer.
+@end defopt
+@defopt reftex-bib-author-face
+Face name for author names in bib selection buffer.
+@end defopt
+@defopt reftex-bib-year-face
+Face name for year in bib selection buffer.
+@end defopt
+@defopt reftex-bib-title-face
+Face name for article title in bib selection buffer.
+@end defopt
+@defopt reftex-bib-extra-face
+Face name for bibliographic information in bib selection buffer.
+@end defopt
+@defopt reftex-select-mark-face
+Face name for marked entries in the selection buffers.
+@end defopt
+@defopt reftex-index-header-face
+Face name for the header of an index buffer.
+@end defopt
+@defopt reftex-index-section-face
+Face name for the start of a new letter section in the index.
+@end defopt
+@defopt reftex-index-tag-face
+Face name for index names (for multiple indices).
+@end defopt
+@defopt reftex-index-face
+Face name for index entries.
+@end defopt
+
+@node Options (Misc), , Options (Fontification), Options
+@section Miscellaneous
+@cindex Options, misc
+
+@defopt reftex-extra-bindings
+Non-@code{nil} means, make additional key bindings on startup. These
+extra bindings are located in the users @samp{C-c letter}
+map. @xref{Keybindings}.@refill
+@end defopt
+
+@defopt reftex-plug-into-AUCTeX
+Plug-in flags for AUCTeX interface. This variable is a list of
+5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}}
+will@refill
+
+@example
+- supply labels in new sections and environments (flag 1)
+- supply arguments for macros like @code{\label} (flag 2)
+- supply arguments for macros like @code{\ref} (flag 3)
+- supply arguments for macros like @code{\cite} (flag 4)
+- supply arguments for macros like @code{\index} (flag 5)
+@end example
+
+You may also set the variable itself to t or nil in order to turn all
+options on or off, respectively.@*
+Supplying labels in new sections and environments applies when creating
+sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@*
+Supplying macro arguments applies when you insert such a macro
+interactively with @kbd{C-c @key{RET}}.@*
+See the AUCTeX documentation for more information.
+@end defopt
+
+@defopt reftex-revisit-to-follow
+Non-@code{nil} means, follow-mode will revisit files if necessary.
+When nil, follow-mode will be suspended for stuff in unvisited files.
+@end defopt
+
+@defopt reftex-allow-detached-macro-args
+Non-@code{nil} means, allow arguments of macros to be detached by
+whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb
+[xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that
+this will be the case even if @code{\bb} is defined with zero or one
+argument.@refill
+@end defopt
+
+@node Keymaps and Hooks, Changes, Options, Top
+@section Keymaps and Hooks
+@cindex Keymaps
+
+@b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook.
+
+@deffn Keymap reftex-mode-map
+The keymap for @b{Ref@TeX{}} mode.
+@end deffn
+
+@deffn {Normal Hook} reftex-load-hook
+Normal hook which is being run when loading @file{reftex.el}.
+@end deffn
+
+@deffn {Normal Hook} reftex-mode-hook
+Normal hook which is being run when turning on @b{Ref@TeX{}} mode.@refill
+@end deffn
+
+Furthermore, the 3 modes used for referencing labels, creating citations
+and for the table of contents buffer have their own keymaps and mode
+hooks. See the respective sections. There are many more hooks which
+are described in the relevant sections about options for a specific part
+of @b{Ref@TeX{}}.@refill
+
+@node Changes, , Keymaps and Hooks, Top
+@chapter Changes
+@cindex Changes
+
+Here is a list of recent changes to @b{Ref@TeX{}}.
+
+@ignore
+@noindent @b{Version 1.00}
+@itemize @bullet
+@item
+released on 7 Jan 1997.
+@end itemize
+
+@noindent @b{Version 1.04}
+@itemize @bullet
+@item
+Macros as wrappers, AMSTeX support, delayed context parsing for
+new labels.@refill
+@end itemize
+
+@noindent @b{Version 1.05}
+@itemize @bullet
+@item
+XEmacs port.
+@end itemize
+
+@noindent @b{Version 1.07}
+@itemize @bullet
+@item
+@b{Ref@TeX{}} gets its own menu.
+@end itemize
+
+@noindent @b{Version 1.09}
+@itemize @bullet
+@item
+Support for @code{tex-main-file}, an analogue for
+@code{TeX-master}.@refill
+@item
+MS-DOS support.
+@end itemize
+
+@noindent @b{Version 2.00}
+@itemize @bullet
+@item
+Labels can be derived from context (default for sections).
+@item
+Configuration of label insertion and label referencing revised.
+@item
+Crossref fields in BibTeX database entries.
+@item
+@code{reftex-toc} introduced (thanks to Stephen Eglen).
+@end itemize
+
+@noindent @b{Version 2.03}
+@itemize @bullet
+@item
+@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to
+default environments.@refill
+@item
+@code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari).
+@item
+New functions @code{reftex-arg-label}, @code{reftex-arg-ref},
+@code{reftex-arg-cite}.@refill
+@item
+Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is
+required.@refill
+@item
+@code{reftex-add-to-label-alist} (to be called from AUCTeX style
+files).@refill
+@item
+Finding context with a hook function.
+@item
+Sorting BibTeX entries (new variable:
+@code{reftex-sort-bibtex-matches}).
+@end itemize
+
+@noindent @b{Version 2.05}
+@itemize @bullet
+@item
+Support for @file{custom.el}.
+@item
+New function @code{reftex-grep-document} (thanks to Stephen Eglen).
+@end itemize
+
+@noindent @b{Version 2.07}
+@itemize @bullet
+@item
+New functions @code{reftex-search-document},
+@code{reftex-query-replace-document}.
+@end itemize
+
+@noindent @b{Version 2.11}
+@itemize @bullet
+@item
+Submitted for inclusion to Emacs and XEmacs.
+@end itemize
+
+@noindent @b{Version 2.14}
+@itemize @bullet
+@item
+Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with
+AUCTeX.@refill
+@end itemize
+
+@noindent @b{Version 2.17}
+@itemize @bullet
+@item
+Label prefix expands % escapes with current file name and other stuff.
+@item
+Citation format now with % escapes. This is not backward
+compatible!@refill
+@item
+TEXINPUTS variable recognized when looking for input files.
+@item
+Context can be the nth argument of a macro.@refill
+@item
+Searching in the select buffer is now possible (@kbd{C-s} and
+@kbd{C-r}).@refill
+@item
+Display and derive-label can use two different context methods.
+@item
+AMSmath @code{xalignat} and @code{xxalignat} added.
+@end itemize
+
+@noindent @b{Version 3.00}
+@itemize @bullet
+@item
+@b{Ref@TeX{}} should work better for very large projects:
+@item
+The new parser works without creating a master buffer.
+@item
+Rescanning can be limited to a part of a multifile document.
+@item
+Information from the parser can be stored in a file.
+@item
+@b{Ref@TeX{}} can deal with macros having a naked label as an argument.
+@item
+Macros may have white space and newlines between arguments.
+@item
+Multiple identical section headings no longer confuse
+@code{reftex-toc}.@refill
+@item
+@b{Ref@TeX{}} should work correctly in combination with buffer-altering
+packages like outline, folding, x-symbol, iso-cvt, isotex, etc.@refill
+@item
+All labeled environments discussed in @emph{The LaTeX Companion} by
+Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of
+@b{Ref@TeX{}}'s defaults.@refill
+@end itemize
+
+@noindent @b{Version 3.03}
+@itemize @bullet
+@item
+Support for the LaTeX package @code{xr}, for inter-document
+references.@refill
+@item
+A few (minor) Mule-related changes.
+@item
+Fixed bug which could cause @emph{huge} @file{.rel} files.
+@item
+Search for input and @file{.bib} files with recursive path definitions.
+@end itemize
+
+@noindent @b{Version 3.04}
+@itemize @bullet
+@item
+Fixed BUG in the @emph{xr} support.
+@end itemize
+
+@noindent @b{Version 3.05}
+@itemize @bullet
+@item
+Compatibility code now first checks for XEmacs feature.
+@end itemize
+
+@noindent @b{Version 3.07}
+@itemize @bullet
+@item
+@code{Ref} menu improved.
+@end itemize
+
+@noindent @b{Version 3.10}
+@itemize @bullet
+@item
+Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19.
+@item
+Removed unimportant code which caused OS/2 Emacs to crash.
+@item
+All customization variables now accessible from menu.
+@end itemize
+
+@noindent @b{Version 3.11}
+@itemize @bullet
+@item
+Fixed bug which led to naked label in (e.g.) footnotes.
+@item
+Added scroll-other-window functions to RefTeX-Select.
+@end itemize
+
+@noindent @b{Version 3.12}
+@itemize @bullet
+@item
+There are 3 new keymaps for customization: @code{reftex-toc-map},
+@code{reftex-select-label-map}, @code{reftex-select-bib-map}.
+@item
+Refontification uses more standard font-lock stuff.
+@item
+When no BibTeX database files are specified, citations can also use
+@code{\bibitem} entries from a @code{thebibliography} environment.@refill
+@end itemize
+
+@noindent @b{Version 3.14}
+@itemize @bullet
+@item
+Selection buffers can be kept between selections: this is faster.
+See new variable @code{reftex-use-multiple-selection-buffers}.@refill
+@item
+Prefix interpretation of reftex-view-crossref changed.
+@item
+Support for the @code{varioref} package (@kbd{v} key in selection
+buffer).@refill
+@end itemize
+
+@noindent @b{Version 3.16}
+@itemize @bullet
+@item
+New hooks @code{reftex-format-label-function},
+@code{reftex-format-ref-function}, @code{reftex-format-cite-function}.@refill
+@item
+TeXInfo documentation completed.
+@item
+Some restrictions in Label inserting and referencing removed.
+@item
+New variable @code{reftex-default-bibliography}.
+@end itemize
+
+@noindent @b{Version 3.17}
+@itemize @bullet
+@item
+Additional bindings in selection and @file{*toc*} buffers. @kbd{g}
+redefined.
+@item
+New command @code{reftex-save-all-document-buffers}.
+@item
+Magic word matching made more intelligent.
+@item
+Selection process can switch to completion (with @key{TAB}).
+@item
+@code{\appendix} is now recognized and influences section numbering.
+@item
+File commentary shortened considerably (use Info documentation).
+@item
+New option @code{reftex-no-include-regexps} to skip some include files.
+@item
+New option @code{reftex-revisit-to-follow}.
+@end itemize
+
+@noindent @b{Version 3.18}
+@itemize @bullet
+@item
+The selection now uses a recursive edit, much like minibuffer input.
+This removes all restrictions during selection. E.g. you can now
+switch buffers at will, use the mouse etc.@refill
+@item
+New option @code{reftex-highlight-selection}.
+@item
+@kbd{mouse-2} can be used to select in selection and @file{*toc*}
+buffers.@refill
+@item
+Fixed some problems regarding the interaction with VIPER mode.
+@item
+Follow-mode is now only used after point motion.
+@item
+@b{Ref@TeX{}} now finally does not fontify temporary files anymore.
+@end itemize
+
+@noindent @b{Version 3.19}
+@itemize @bullet
+@item
+Fixed bug with AUCTeX @code{TeX-master}.
+@end itemize
+
+@noindent @b{Version 3.21}
+@itemize @bullet
+@item
+New options for all faces used by @b{Ref@TeX{}}. They're in the
+customization group @code{reftex-fontification-configurations}.@refill
+@end itemize
+
+@noindent @b{Version 3.22}
+@itemize @bullet
+@item
+Fixed bug with empty context strings.
+@item
+@code{reftex-mouse-view-crossref} is now bound by default at
+@kbd{S-mouse-2}.@refill
+@end itemize
+
+@noindent @b{Version 3.23}
+@itemize @bullet
+@item
+Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs.
+@item
+@code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse
+file.
+@item
+The cursor inside a @code{\ref} or @code{\cite} macro can now trigger
+automatic display of crossref information in the echo area. See
+variable @code{reftex-auto-view-crossref}.
+@item
+AUCTeX interface updates:
+@itemize @minus
+@item
+AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections.
+@item
+@b{Ref@TeX{}} notifies AUCTeX about new labels.
+@item
+@code{TeX-arg-ref} no longer used (introduction was unnecessary).
+@item
+@code{reftex-arg-label} and @code{reftex-arg-cite} fixed up.
+@item
+Settings added to @b{Ref@TeX{}} via style files remain local.
+@end itemize
+@item
+Fixed bug with @code{reftex-citation} in non-latex buffers.
+@item
+Fixed bug with syntax table and context refontification.
+@item
+Safety-net for name change of @code{font-lock-reference-face}.
+@end itemize
+
+@noindent @b{Version 3.24}
+@itemize @bullet
+@item
+New option @code{reftex-revisit-to-echo}.
+@item
+Interface with X-Symbol (>=2.6) is now complete and stable.
+@item
+Adapted to new outline, which uses overlays.
+@item
+File names in @code{\bibliography} may now have the @code{.bib}
+extension.@refill
+@item
+Fixed Bug with parsing "single file" from master file buffer.
+@end itemize
+
+@noindent @b{Version 3.25}
+@itemize @bullet
+@item
+Echoing of citation info caches the info for displayed entries.
+New option @code{reftex-cache-cite-echo}.@refill
+@item
+@kbd{M-x reftex-reset-mode} now also removes the file with parsing
+info.@refill
+@item
+Default of @code{reftex-revisit-to-follow} changed to nil.
+@end itemize
+
+@noindent @b{Version 3.26}
+@itemize @bullet
+@item
+[X]Emacs 19 no longer supported. Use 3.22 for Emacs 19.
+@item
+New hooks @code{reftex-translate-to-ascii-function},
+@code{reftex-string-to-label-function}.@refill
+@item
+Made sure automatic crossref display will not visit/scan files.
+@end itemize
+
+@noindent @b{Version 3.27}
+@itemize @bullet
+@item
+Macros can define @emph{neutral} labels, just like @code{\label}
+itself.@refill
+@item
+New option @code{reftex-allow-detached-macro-args}, default @code{nil}!
+@end itemize
+
+@noindent @b{Version 3.28}
+@itemize @bullet
+@item
+Auto view crossref for XEmacs uses @code{post-command-hook} to restart the
+timer, since itimer restart is not reliable.@refill
+@item
+Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}.
+@item
+Expansion of recursive tex and bib path rewritten.
+@item
+Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers.
+@item
+Fixed bug with section numbering after *-red sections.
+@end itemize
+
+@noindent @b{Version 3.30}
+@itemize @bullet
+@item
+In @code{reftex-citation}, the regular expression used to scan BibTeX
+files can be specified using completion on known citation keys.
+@item
+New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all}
+entries.
+@item
+New command @code{reftex-renumber-simple-labels} to renumber simple
+labels like @samp{eq:13} sequentially through a document.
+@end itemize
+@noindent @b{Version 3.33}
+@itemize @bullet
+@item
+Multiple selection buffers are now hidden buffers (they start with a
+SPACE).
+@item
+Fixed bug with file search when TEXINPUTS environment variable is empty.
+@end itemize
+@noindent @b{Version 3.34}
+@itemize @bullet
+@item
+Additional flag in @code{reftex-derive-label-parameters} do make only
+lowercase labels (default @code{t}).
+@item
+All @file{.rel} files have a final newline to avoid queries.
+@item
+Single byte representations of accented European letters (ISO-8859-1)
+are now legal in labels.
+@end itemize
+@noindent @b{Version 3.35}
+@itemize @bullet
+@item
+ISO 8859 Latin-1 chars are converted to ASCII to derive better labels.
+This takes back the related changes in 3.34 for safety reasons.@refill
+@end itemize
+@noindent @b{Version 3.36}
+@itemize @bullet
+@item
+New value @code{window} for option @code{reftex-auto-view-crossref}.
+@end itemize
+@noindent @b{Version 3.38}
+@itemize @bullet
+@item
+@code{reftex-view-crossref} no longer moves to find a macro. Point has
+to be on the macro argument.
+@end itemize
+@noindent @b{Version 3.41}
+@itemize @bullet
+@item
+New options @code{reftex-texpath-environment-variables},
+@code{reftex-use-external-file-finders},
+@code{reftex-external-file-finders},
+@code{reftex-search-unrecursed-path-first}.
+@item
+@emph{kpathsearch} support. See new options and
+@code{reftex-bibpath-environment-variables}.
+@end itemize
+@end ignore
+@noindent @b{Version 3.42}
+@itemize @bullet
+@item
+File search further refined. New option @code{reftex-file-extensions}.
+@item
+@file{*toc*} buffer can show the file boundaries of a multifile
+document, all labels and associated context. New keys @kbd{i}, @kbd{l},
+and @kbd{c}. New options @code{reftex-toc-include-labels},
+@code{reftex-toc-include-context},
+@code{reftex-toc-include-file-boundaries}. @refill
+@end itemize
+@noindent @b{Version 3.43}
+@itemize @bullet
+@item
+Viewing cross-references generalized. Now works on @code{\label},
+@code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of
+these, and from BibTeX buffers.@refill
+@item
+New option @code{reftex-view-crossref-extra}.@refill
+@item
+Support for the additional sectioning commands @code{\addchap} and
+@code{\addsec} which are defined in the LaTeX KOMA-Script classes.@refill
+@item
+Files in @code{reftex-default-bibliography} will be searched along
+@code{BIBINPUTS} path.@refill
+@item
+Reading a parse file now checks consistency.
+@end itemize
+@noindent @b{Version 4.00}
+@itemize @bullet
+@item
+RefTeX has been split into several smaller files which are autoloaded on
+demand.
+@item
+Index support, along with many new options.
+@item
+The selection of keys for @code{\ref} and @code{\cite} now allows to
+select multiple items by marking entries with the @kbd{m} key.
+@item
+Fancyref support.
+@end itemize
+@noindent @b{Version 4.01}
+@itemize @bullet
+@item
+New command @code{reftex-index-globally} to index a word in many
+places in the document. Also available from the index buffer with
+@kbd{&}.
+@item
+The first item in a @code{reftex-label-alist} entry may now also be a parser
+function to do non-standard parsing.
+@item
+@code{reftex-auto-view-crossref} no longer interferes with
+@code{pop-up-frames} (patch from Stefan Monnier).
+@end itemize
+@noindent @b{Version 4.02}
+@itemize @bullet
+@item
+macros ending in @samp{refrange} are considered to contain references.
+@item
+Index entries made with @code{reftex-index-selection-or-word} in TeX
+math mode automatically get enclosing @samp{$} to preserve math mode. See
+new option @code{reftex-index-math-format}. Requires AUCTeX.
+@end itemize
+@noindent @b{Version 4.04}
+@itemize @bullet
+@item
+New option @code{reftex-index-default-tag} implements a default for queries.
+@end itemize
+@noindent @b{Version 4.06}
+@itemize @bullet
+@item
+@code{reftex-section-levels} can contain a function to compute the level
+of a sectioning command.
+@item
+Multiple @code{thebibliography} environments recognized.
+@end itemize
+
+
+@node Index, , , Top
+@unnumbered Index
+@printindex cp
+
+@summarycontents
+@contents
+@bye
+
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Registers, Display, Rectangles, Top
+@chapter Registers
+@cindex registers
+
+ Emacs @dfn{registers} are places you can save text or positions for
+later use. Once you save text or a rectangle in a register, you can
+copy it into the buffer once or many times; you can move point to a
+position saved in a register once or many times.
+
+@findex view-register
+ Each register has a name which is a single character. A register can
+store a piece of text, a rectangle, a position, a window configuration,
+or a file name, but only one thing at any given time. Whatever you
+store in a register remains there until you store something else in that
+register. To see what a register @var{r} contains, use @kbd{M-x
+view-register}.
+
+@table @kbd
+@item M-x view-register @key{RET} @var{r}
+Display a description of what register @var{r} contains.
+@end table
+
+@menu
+* Position: RegPos. Saving positions in registers.
+* Text: RegText. Saving text in registers.
+* Rectangle: RegRect. Saving rectangles in registers.
+* Configurations: RegConfig. Saving window configurations in registers.
+* Files: RegFiles. File names in registers.
+* Numbers: RegNumbers. Numbers in registers.
+* Bookmarks:: Bookmarks are like registers, but persistent.
+@end menu
+
+@node RegPos
+@section Saving Positions in Registers
+
+ Saving a position records a place in a buffer so that you can move
+back there later. Moving to a saved position switches to that buffer
+and moves point to that place in it.
+
+@table @kbd
+@item C-x r @key{SPC} @var{r}
+Save position of point in register @var{r} (@code{point-to-register}).
+@item C-x r j @var{r}
+Jump to the position saved in register @var{r} (@code{jump-to-register}).
+@end table
+
+@kindex C-x r SPC
+@findex point-to-register
+ To save the current position of point in a register, choose a name
+@var{r} and type @kbd{C-x r @key{SPC} @var{r}}. The register @var{r}
+retains the position thus saved until you store something else in that
+register.
+
+@kindex C-x r j
+@findex jump-to-register
+ The command @kbd{C-x r j @var{r}} moves point to the position recorded
+in register @var{r}. The register is not affected; it continues to
+record the same position. You can jump to the saved position any number
+of times.
+
+ If you use @kbd{C-x r j} to go to a saved position, but the buffer it
+was saved from has been killed, @kbd{C-x r j} tries to create the buffer
+again by visiting the same file. Of course, this works only for buffers
+that were visiting files.
+
+@node RegText
+@section Saving Text in Registers
+
+ When you want to insert a copy of the same piece of text several
+times, it may be inconvenient to yank it from the kill ring, since each
+subsequent kill moves that entry further down the ring. An alternative
+is to store the text in a register and later retrieve it.
+
+@table @kbd
+@item C-x r s @var{r}
+Copy region into register @var{r} (@code{copy-to-register}).
+@item C-x r i @var{r}
+Insert text from register @var{r} (@code{insert-register}).
+@end table
+
+@kindex C-x r s
+@kindex C-x r i
+@findex copy-to-register
+@findex insert-register
+ @kbd{C-x r s @var{r}} stores a copy of the text of the region into the
+register named @var{r}. Given a numeric argument, @kbd{C-x r s @var{r}}
+deletes the text from the buffer as well.
+
+ @kbd{C-x r i @var{r}} inserts in the buffer the text from register
+@var{r}. Normally it leaves point before the text and places the mark
+after, but with a numeric argument (@kbd{C-u}) it puts point after the
+text and the mark before.
+
+@node RegRect
+@section Saving Rectangles in Registers
+
+ A register can contain a rectangle instead of linear text. The
+rectangle is represented as a list of strings. @xref{Rectangles}, for
+basic information on how to specify a rectangle in the buffer.
+
+@table @kbd
+@findex copy-rectangle-to-register
+@kindex C-x r r
+@item C-x r r @var{r}
+Copy the region-rectangle into register @var{r}
+(@code{copy-rectangle-to-register}). With numeric argument, delete it as
+well.
+@item C-x r i @var{r}
+Insert the rectangle stored in register @var{r} (if it contains a
+rectangle) (@code{insert-register}).
+@end table
+
+ The @kbd{C-x r i @var{r}} command inserts a text string if the
+register contains one, and inserts a rectangle if the register contains
+one.
+
+ See also the command @code{sort-columns}, which you can think of
+as sorting a rectangle. @xref{Sorting}.
+
+@node RegConfig
+@section Saving Window Configurations in Registers
+
+@findex window-configuration-to-register
+@findex frame-configuration-to-register
+@kindex C-x r w
+@kindex C-x r f
+ You can save the window configuration of the selected frame in a
+register, or even the configuration of all windows in all frames, and
+restore the configuration later.
+
+@table @kbd
+@item C-x r w @var{r}
+Save the state of the selected frame's windows in register @var{r}
+(@code{window-configuration-to-register}).
+@item C-x r f @var{r}
+Save the state of all frames, including all their windows, in register
+@var{r} (@code{frame-configuration-to-register}).
+@end table
+
+ Use @kbd{C-x r j @var{r}} to restore a window or frame configuration.
+This is the same command used to restore a cursor position. When you
+restore a frame configuration, any existing frames not included in the
+configuration become invisible. If you wish to delete these frames
+instead, use @kbd{C-u C-x r j @var{r}}.
+
+@node RegNumbers
+@section Keeping Numbers in Registers
+
+ There are commands to store a number in a register, to insert
+the number in the buffer in decimal, and to increment it. These commands
+can be useful in keyboard macros (@pxref{Keyboard Macros}).
+
+@table @kbd
+@item C-u @var{number} C-x r n @var{reg}
+@kindex C-x r n
+@findex number-to-register
+Store @var{number} into register @var{reg} (@code{number-to-register}).
+@item C-u @var{number} C-x r + @var{reg}
+@kindex C-x r +
+@findex increment-register
+Increment the number in register @var{reg} by @var{number}
+(@code{increment-register}).
+@item C-x r g @var{reg}
+Insert the number from register @var{reg} into the buffer.
+@end table
+
+ @kbd{C-x r g} is the same command used to insert any other
+sort of register contents into the buffer.
+
+@node RegFiles
+@section Keeping File Names in Registers
+
+ If you visit certain file names frequently, you can visit them more
+conveniently if you put their names in registers. Here's the Lisp code
+used to put a file name in a register:
+
+@smallexample
+(set-register ?@var{r} '(file . @var{name}))
+@end smallexample
+
+@need 3000
+@noindent
+For example,
+
+@smallexample
+(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
+@end smallexample
+
+@noindent
+puts the file name shown in register @samp{z}.
+
+ To visit the file whose name is in register @var{r}, type @kbd{C-x r j
+@var{r}}. (This is the same command used to jump to a position or
+restore a frame configuration.)
+
+@node Bookmarks
+@section Bookmarks
+@cindex bookmarks
+
+ @dfn{Bookmarks} are somewhat like registers in that they record
+positions you can jump to. Unlike registers, they have long names, and
+they persist automatically from one Emacs session to the next. The
+prototypical use of bookmarks is to record ``where you were reading'' in
+various files.
+
+@table @kbd
+@item C-x r m @key{RET}
+Set the bookmark for the visited file, at point.
+
+@item C-x r m @var{bookmark} @key{RET}
+@findex bookmark-set
+Set the bookmark named @var{bookmark} at point (@code{bookmark-set}).
+
+@item C-x r b @var{bookmark} @key{RET}
+@findex bookmark-jump
+Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}).
+
+@item C-x r l
+@findex list-bookmarks
+List all bookmarks (@code{list-bookmarks}).
+
+@item M-x bookmark-save
+@findex bookmark-save
+Save all the current bookmark values in the default bookmark file.
+@end table
+
+@kindex C-x r m
+@findex bookmark-set
+@kindex C-x r b
+@findex bookmark-jump
+ The prototypical use for bookmarks is to record one current position
+in each of several files. So the command @kbd{C-x r m}, which sets a
+bookmark, uses the visited file name as the default for the bookmark
+name. If you name each bookmark after the file it points to, then you
+can conveniently revisit any of those files with @kbd{C-x r b}, and move
+to the position of the bookmark at the same time.
+
+@kindex C-x r l
+ To display a list of all your bookmarks in a separate buffer, type
+@kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer,
+you can use it to edit your bookmark definitions or annotate the
+bookmarks. Type @kbd{C-h m} in that buffer for more information about
+its special editing commands.
+
+ When you kill Emacs, Emacs offers to save your bookmark values in your
+default bookmark file, @file{~/.emacs.bmk}, if you have changed any
+bookmark values. You can also save the bookmarks at any time with the
+@kbd{M-x bookmark-save} command. The bookmark commands load your
+default bookmark file automatically. This saving and loading is how
+bookmarks persist from one Emacs session to the next.
+
+@vindex bookmark-save-flag
+ If you set the variable @code{bookmark-save-flag} to 1, then each
+command that sets a bookmark will also save your bookmarks; this way,
+you don't lose any bookmark values even if Emacs crashes. (The value,
+if a number, says how many bookmark modifications should go by between
+saving.)
+
+@vindex bookmark-search-size
+ Bookmark position values are saved with surrounding context, so that
+@code{bookmark-jump} can find the proper position even if the file is
+modified slightly. The variable @code{bookmark-search-size} says how
+many characters of context to record, on each side of the bookmark's
+position.
+
+ Here are some additional commands for working with bookmarks:
+
+@table @kbd
+@item M-x bookmark-load @key{RET} @var{filename} @key{RET}
+@findex bookmark-load
+Load a file named @var{filename} that contains a list of bookmark
+values. You can use this command, as well as @code{bookmark-write}, to
+work with other files of bookmark values in addition to your default
+bookmark file.
+
+@item M-x bookmark-write @key{RET} @var{filename} @key{RET}
+@findex bookmark-write
+Save all the current bookmark values in the file @var{filename}.
+
+@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET}
+@findex bookmark-delete
+Delete the bookmark named @var{bookmark}.
+
+@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET}
+@findex bookmark-insert-location
+Insert in the buffer the name of the file that bookmark @var{bookmark}
+points to.
+
+@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET}
+@findex bookmark-insert
+Insert in the buffer the @emph{contents} of the file that bookmark
+@var{bookmark} points to.
+@end table
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Rmail, Dired, Sending Mail, Top
+@chapter Reading Mail with Rmail
+@cindex Rmail
+@cindex reading mail
+@findex rmail
+@findex rmail-mode
+@vindex rmail-mode-hook
+
+ Rmail is an Emacs subsystem for reading and disposing of mail that you
+receive. Rmail stores mail messages in files called Rmail files.
+Reading the message in an Rmail file is done in a special major mode,
+Rmail mode, which redefines most letters to run commands for managing
+mail. The command @code{rmail-mode} is used to switch into Rmail mode,
+and it runs the hook @code{rmail-mode-hook} as usual, but don't run this
+command by hand; it can't do a reasonable job unless the buffer is
+visiting a proper Rmail file.
+
+@menu
+* Basic: Rmail Basics. Basic concepts of Rmail, and simple use.
+* Scroll: Rmail Scrolling. Scrolling through a message.
+* Motion: Rmail Motion. Moving to another message.
+* Deletion: Rmail Deletion. Deleting and expunging messages.
+* Inbox: Rmail Inbox. How mail gets into the Rmail file.
+* Files: Rmail Files. Using multiple Rmail files.
+* Output: Rmail Output. Copying message out to files.
+* Labels: Rmail Labels. Classifying messages by labeling them.
+* Attrs: Rmail Attributes. Certain standard labels, called attributes.
+* Reply: Rmail Reply. Sending replies to messages you are viewing.
+* Summary: Rmail Summary. Summaries show brief info on many messages.
+* Sort: Rmail Sorting. Sorting messages in Rmail.
+* Display: Rmail Display. How Rmail displays a message; customization.
+* Editing: Rmail Editing. Editing message text and headers in Rmail.
+* Digest: Rmail Digest. Extracting the messages from a digest message.
+* Out of Rmail:: Converting an Rmail file to mailbox format.
+* Rot13: Rmail Rot13. Reading messages encoded in the rot13 code.
+* Movemail: Movemail. More details of fetching new mail.
+@end menu
+
+@node Rmail Basics
+@section Basic Concepts of Rmail
+
+@cindex primary Rmail file
+@vindex rmail-file-name
+ Using Rmail in the simplest fashion, you have one Rmail file
+@file{~/RMAIL} in which all of your mail is saved. It is called your
+@dfn{primary Rmail file}. The command @kbd{M-x rmail} reads your primary
+Rmail file, merges new mail in from your inboxes, displays the first
+message you haven't read yet, and lets you begin reading. The variable
+@code{rmail-file-name} specifies the name of the primary Rmail file.
+
+ Rmail uses narrowing to hide all but one message in the Rmail file.
+The message that is shown is called the @dfn{current message}. Rmail
+mode's special commands can do such things as delete the current
+message, copy it into another file, send a reply, or move to another
+message. You can also create multiple Rmail files and use Rmail to move
+messages between them.
+
+@cindex message number
+ Within the Rmail file, messages are normally arranged sequentially in
+order of receipt; you can specify other ways to sort them. Messages are
+assigned consecutive integers as their @dfn{message numbers}. The
+number of the current message is displayed in Rmail's mode line,
+followed by the total number of messages in the file. You can move to a
+message by specifying its message number with the @kbd{j} key
+(@pxref{Rmail Motion}).
+
+@kindex s @r{(Rmail)}
+@findex rmail-save
+ Following the usual conventions of Emacs, changes in an Rmail file
+become permanent only when the file is saved. You can save it with
+@kbd{s} (@code{rmail-save}), which also expunges deleted messages from
+the file first (@pxref{Rmail Deletion}). To save the file without
+expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail file after
+merging new mail from an inbox file (@pxref{Rmail Inbox}).
+
+@kindex q @r{(Rmail)}
+@findex rmail-quit
+@kindex b @r{(Rmail)}
+@findex rmail-bury
+ You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and
+saves the Rmail file and then switches to another buffer. But there is
+no need to `exit' formally. If you switch from Rmail to editing in
+other buffers, and never happen to switch back, you have exited. (The
+Rmail command @kbd{b}, @code{rmail-bury}, does this for you.) Just make
+sure to save the Rmail file eventually (like any other file you have
+changed). @kbd{C-x s} is a good enough way to do this
+(@pxref{Saving}).
+
+@node Rmail Scrolling
+@section Scrolling Within a Message
+
+ When Rmail displays a message that does not fit on the screen, you
+must scroll through it to read the rest. You could do this with
+@kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so
+frequent that it deserves to be easier to type.
+
+@table @kbd
+@item @key{SPC}
+Scroll forward (@code{scroll-up}).
+@item @key{DEL}
+Scroll backward (@code{scroll-down}).
+@item .
+Scroll to start of message (@code{rmail-beginning-of-message}).
+@end table
+
+@kindex SPC @r{(Rmail)}
+@kindex DEL @r{(Rmail)}
+ Since the most common thing to do while reading a message is to scroll
+through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
+@kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down})
+
+@kindex . @r{(Rmail)}
+@findex rmail-beginning-of-message
+ The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
+beginning of the selected message. This is not quite the same as @kbd{M-<}:
+for one thing, it does not set the mark; for another, it resets the buffer
+boundaries to the current message if you have changed them.
+
+@node Rmail Motion
+@section Moving Among Messages
+
+ The most basic thing to do with a message is to read it. The way to
+do this in Rmail is to make the message current. The usual practice is
+to move sequentially through the file, since this is the order of
+receipt of messages. When you enter Rmail, you are positioned at the
+first message that you have not yet made current (that is, the first one
+that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move
+forward to see the other new messages; move backward to reexamine old
+messages.
+
+@table @kbd
+@item n
+Move to the next nondeleted message, skipping any intervening deleted
+messages (@code{rmail-next-undeleted-message}).
+@item p
+Move to the previous nondeleted message
+(@code{rmail-previous-undeleted-message}).
+@item M-n
+Move to the next message, including deleted messages
+(@code{rmail-next-message}).
+@item M-p
+Move to the previous message, including deleted messages
+(@code{rmail-previous-message}).
+@item j
+Move to the first message. With argument @var{n}, move to
+message number @var{n} (@code{rmail-show-message}).
+@item >
+Move to the last message (@code{rmail-last-message}).
+@item <
+Move to the first message (@code{rmail-first-message}).
+
+@item M-s @var{regexp} @key{RET}
+Move to the next message containing a match for @var{regexp}
+(@code{rmail-search}).
+
+@item - M-s @var{regexp} @key{RET}
+Move to the previous message containing a match for @var{regexp}.
+@end table
+
+@kindex n @r{(Rmail)}
+@kindex p @r{(Rmail)}
+@kindex M-n @r{(Rmail)}
+@kindex M-p @r{(Rmail)}
+@findex rmail-next-undeleted-message
+@findex rmail-previous-undeleted-message
+@findex rmail-next-message
+@findex rmail-previous-message
+ @kbd{n} and @kbd{p} are the usual way of moving among messages in
+Rmail. They move through the messages sequentially, but skip over
+deleted messages, which is usually what you want to do. Their command
+definitions are named @code{rmail-next-undeleted-message} and
+@code{rmail-previous-undeleted-message}. If you do not want to skip
+deleted messages---for example, if you want to move to a message to
+undelete it---use the variants @kbd{M-n} and @kbd{M-p}
+(@code{rmail-next-message} and @code{rmail-previous-message}). A
+numeric argument to any of these commands serves as a repeat
+count.@refill
+
+ In Rmail, you can specify a numeric argument by typing just the
+digits. You don't need to type @kbd{C-u} first.
+
+@kindex M-s @r{(Rmail)}
+@findex rmail-search
+@cindex searching in Rmail
+ The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of
+search. The usual incremental search command @kbd{C-s} works in Rmail,
+but it searches only within the current message. The purpose of
+@kbd{M-s} is to search for another message. It reads a regular
+expression (@pxref{Regexps}) nonincrementally, then searches starting at
+the beginning of the following message for a match. It then selects
+that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp
+used the previous time.
+
+ To search backward in the file for another message, give @kbd{M-s} a
+negative argument. In Rmail you can do this with @kbd{- M-s}.
+
+ It is also possible to search for a message based on labels.
+@xref{Rmail Labels}.
+
+@kindex j @r{(Rmail)}
+@kindex > @r{(Rmail)}
+@kindex < @r{(Rmail)}
+@findex rmail-show-message
+@findex rmail-last-message
+@findex rmail-first-message
+ To move to a message specified by absolute message number, use @kbd{j}
+(@code{rmail-show-message}) with the message number as argument. With
+no argument, @kbd{j} selects the first message. @kbd{<}
+(@code{rmail-first-message}) also selects the first message. @kbd{>}
+(@code{rmail-last-message}) selects the last message.
+
+@node Rmail Deletion
+@section Deleting Messages
+
+@cindex deletion (Rmail)
+ When you no longer need to keep a message, you can @dfn{delete} it. This
+flags it as ignorable, and some Rmail commands pretend it is no longer
+present; but it still has its place in the Rmail file, and still has its
+message number.
+
+@cindex expunging (Rmail)
+ @dfn{Expunging} the Rmail file actually removes the deleted messages.
+The remaining messages are renumbered consecutively. Expunging is the only
+action that changes the message number of any message, except for
+undigestifying (@pxref{Rmail Digest}).
+
+@table @kbd
+@item d
+Delete the current message, and move to the next nondeleted message
+(@code{rmail-delete-forward}).
+@item C-d
+Delete the current message, and move to the previous nondeleted
+message (@code{rmail-delete-backward}).
+@item u
+Undelete the current message, or move back to a deleted message and
+undelete it (@code{rmail-undelete-previous-message}).
+@item x
+Expunge the Rmail file (@code{rmail-expunge}).
+@end table
+
+@kindex d @r{(Rmail)}
+@kindex C-d @r{(Rmail)}
+@findex rmail-delete-forward
+@findex rmail-delete-backward
+ There are two Rmail commands for deleting messages. Both delete the
+current message and select another message. @kbd{d}
+(@code{rmail-delete-forward}) moves to the following message, skipping
+messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward})
+moves to the previous nondeleted message. If there is no nondeleted
+message to move to in the specified direction, the message that was just
+deleted remains current. A numeric argument to either command reverses
+the direction of motion after deletion.
+
+@vindex rmail-delete-message-hook
+ Whenever Rmail deletes a message, it invokes the function(s) listed in
+@code{rmail-delete-message-hook}. When the hook functions are invoked,
+the message has been marked deleted, but it is still the current message
+in the Rmail buffer.
+
+@cindex undeletion (Rmail)
+@kindex x @r{(Rmail)}
+@findex rmail-expunge
+@kindex u @r{(Rmail)}
+@findex rmail-undelete-previous-message
+ To make all the deleted messages finally vanish from the Rmail file,
+type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still
+@dfn{undelete} the deleted messages. The undeletion command, @kbd{u}
+(@code{rmail-undelete-previous-message}), is designed to cancel the
+effect of a @kbd{d} command in most cases. It undeletes the current
+message if the current message is deleted. Otherwise it moves backward
+to previous messages until a deleted message is found, and undeletes
+that message.
+
+ You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u}
+moves back to and undeletes the message that the @kbd{d} deleted. But
+this does not work when the @kbd{d} skips a few already-deleted messages
+that follow the message being deleted; then the @kbd{u} command
+undeletes the last of the messages that were skipped. There is no clean
+way to avoid this problem. However, by repeating the @kbd{u} command,
+you can eventually get back to the message that you intend to
+undelete. You can also select a particular deleted message with
+the @kbd{M-p} command, then type @kbd{u} to undelete it.
+
+ A deleted message has the @samp{deleted} attribute, and as a result
+@samp{deleted} appears in the mode line when the current message is
+deleted. In fact, deleting or undeleting a message is nothing more than
+adding or removing this attribute. @xref{Rmail Attributes}.
+
+@node Rmail Inbox
+@section Rmail Files and Inboxes
+@cindex inbox file
+
+ The operating system places incoming mail for you in a file that we
+call your @dfn{inbox}. When you start up Rmail, it runs a C program
+called @code{movemail} to copy the new messages from your inbox into
+your primary Rmail file, which also contains other messages saved from
+previous Rmail sessions. It is in this file that you actually read the
+mail with Rmail. This operation is called @dfn{getting new mail}. You
+can get new mail at any time in Rmail by typing @kbd{g}.
+
+@vindex rmail-primary-inbox-list
+@cindex @code{MAIL} environment variable
+ The variable @code{rmail-primary-inbox-list} contains a list of the
+files which are inboxes for your primary Rmail file. If you don't set
+this variable explicitly, it is initialized from the @code{MAIL}
+environment variable, or, as a last resort, set to @code{nil}, which
+means to use the default inbox. The default inbox is
+@file{/var/mail/@var{username}}, @file{/usr/spool/mail/@var{username}},
+or @file{/usr/mail/@var{username}}, depending on your operating system.
+
+ To see what the default is on your system, use @kbd{C-h v
+rmail-primary-inbox @key{RET}}. You can specify the inbox file(s) for
+any Rmail file with the command @code{set-rmail-inbox-list}; see
+@ref{Rmail Files}.
+
+ There are two reasons for having separate Rmail files and inboxes.
+
+@enumerate
+@item
+The inbox file format varies between operating systems and according to
+the other mail software in use. Only one part of Rmail needs to know
+about the alternatives, and it need only understand how to convert all
+of them to Rmail's own format.
+
+@item
+It is very cumbersome to access an inbox file without danger of losing
+mail, because it is necessary to interlock with mail delivery.
+Moreover, different operating systems use different interlocking
+techniques. The strategy of moving mail out of the inbox once and for
+all into a separate Rmail file avoids the need for interlocking in all
+the rest of Rmail, since only Rmail operates on the Rmail file.
+@end enumerate
+
+ Rmail was written to use Babyl format as its internal format. Since
+then, we have recognized that the usual inbox format on Unix and GNU
+systems is adequate for the job, and we plan to change Rmail to use that
+as its internal format. However, the Rmail file will still be separate
+from the inbox file, even on systems where their format is the same.
+
+@node Rmail Files
+@section Multiple Rmail Files
+
+ Rmail operates by default on your @dfn{primary Rmail file}, which is named
+@file{~/RMAIL} and receives your incoming mail from your system inbox file.
+But you can also have other Rmail files and edit them with Rmail. These
+files can receive mail through their own inboxes, or you can move messages
+into them with explicit Rmail commands (@pxref{Rmail Output}).
+
+@table @kbd
+@item i @var{file} @key{RET}
+Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
+
+@item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
+Specify inbox file names for current Rmail file to get mail from.
+
+@item g
+Merge new mail from current Rmail file's inboxes
+(@code{rmail-get-new-mail}).
+
+@item C-u g @var{file} @key{RET}
+Merge new mail from inbox file @var{file}.
+@end table
+
+@kindex i @r{(Rmail)}
+@findex rmail-input
+ To run Rmail on a file other than your primary Rmail file, you may use
+the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file
+in Rmail mode. You can use @kbd{M-x rmail-input} even when not in
+Rmail.
+
+ The file you read with @kbd{i} should normally be a valid Rmail file.
+If it is not, Rmail tries to decompose it into a stream of messages in
+various known formats. If it succeeds, it converts the whole file to an
+Rmail file. If you specify a file name that doesn't exist, @kbd{i}
+initializes a new buffer for creating a new Rmail file.
+
+@vindex rmail-secondary-file-directory
+@vindex rmail-secondary-file-regexp
+ You can also select an Rmail file from a menu. Choose first the menu
+bar Classify item, then from the Classify menu choose the Input Rmail
+File item; then choose the Rmail file you want. The variables
+@code{rmail-secondary-file-directory} and
+@code{rmail-secondary-file-regexp} specify which files to offer in the
+menu: the first variable says which directory to find them in; the
+second says which files in that directory to offer (all those that match
+the regular expression). These variables also apply to choosing a file
+for output (@pxref{Rmail Output}).
+
+@findex set-rmail-inbox-list
+ Each Rmail file can contain a list of inbox file names; you can specify
+this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
+@key{RET}}. The argument can contain any number of file names, separated
+by commas. It can also be empty, which specifies that this file should
+have no inboxes. Once a list of inboxes is specified, the Rmail file
+remembers it permanently until you specify a different list.
+
+ As a special exception, if your primary Rmail file does not specify any
+inbox files, it uses your standard system inbox.
+
+@kindex g @r{(Rmail)}
+@findex rmail-get-new-mail
+ The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the
+current Rmail file from its specified inboxes. If the Rmail file
+has no inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail}
+also merges new mail into your primary Rmail file.
+
+ To merge mail from a file that is not the usual inbox, give the
+@kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file
+name and merges mail from that file. The inbox file is not deleted or
+changed in any way when @kbd{g} with an argument is used. This is,
+therefore, a general way of merging one file of messages into another.
+
+@node Rmail Output
+@section Copying Messages Out to Files
+
+ These commands copy messages from an Rmail file into another file.
+
+@table @kbd
+@item o @var{file} @key{RET}
+Append a copy of the current message to the file @var{file}, using Rmail
+file format by default (@code{rmail-output-to-rmail-file}).
+
+@item C-o @var{file} @key{RET}
+Append a copy of the current message to the file @var{file}, using
+system inbox file format by default (@code{rmail-output}).
+
+@item w @var{file} @key{RET}
+Output just the message body to the file @var{file}, taking the default
+file name from the message @samp{Subject} header.
+@end table
+
+@kindex o @r{(Rmail)}
+@findex rmail-output-to-rmail-file
+@kindex C-o @r{(Rmail)}
+@findex rmail-output
+ The commands @kbd{o} and @kbd{C-o} copy the current message into a
+specified file. This file may be an Rmail file or it may be in system
+inbox format; the output commands ascertain the file's format and write
+the copied message in that format.
+
+ When copying a message to a file in Unix mail file format, these
+commands include whichever header fields are currently visible. Use the
+@kbd{t} command first, if you wish, to specify which headers to show
+(and copy).
+
+ The @kbd{o} and @kbd{C-o} commands differ in two ways: each has its
+own separate default file name, and each specifies a choice of format to
+use when the file does not already exist. The @kbd{o} command uses
+Rmail format when it creates a new file, while @kbd{C-o} uses system
+inbox format for a new file. The default file name for @kbd{o} is the
+file name used last with @kbd{o}, and the default file name for
+@kbd{C-o} is the file name used last with @kbd{C-o}.
+
+ If the output file is an Rmail file currently visited in an Emacs buffer,
+the output commands copy the message into that buffer. It is up to you
+to save the buffer eventually in its file.
+
+@kindex w @r{(Rmail)}
+@findex rmail-output-body-to-file
+ Sometimes you may receive a message whose body holds the contents of a
+file. You can save the body to a file (excluding the message header)
+with the @kbd{w} command (@code{rmail-output-body-to-file}). Often
+these messages contain the intended file name in the @samp{Subject}
+field, so the @kbd{w} command uses the @samp{Subject} field as the
+default for the output file name. However, the file name is read using
+the minibuffer, so you can specify a different name if you wish.
+
+ You can also output a message to an Rmail file chosen with a menu.
+Choose first the menu bar Classify item, then from the Classify menu
+choose the Output Rmail File menu item; then choose the Rmail file you want.
+This outputs the current message to that file, like the @kbd{o} command.
+The variables @code{rmail-secondary-file-directory} and
+@code{rmail-secondary-file-regexp} specify which files to offer in the
+menu: the first variable says which directory to find them in; the
+second says which files in that directory to offer (all those that match
+the regular expression).
+
+@vindex rmail-delete-after-output
+ Copying a message gives the original copy of the message the
+@samp{filed} attribute, so that @samp{filed} appears in the mode line
+when such a message is current. If you like to keep just a single copy
+of every mail message, set the variable @code{rmail-delete-after-output}
+to @code{t}; then the @kbd{o} and @kbd{C-o} commands delete the original
+message after copying it. (You can undelete the original afterward if
+you wish.)
+
+ Copying messages into files in system inbox format uses the header
+fields that are displayed in Rmail at the time. Thus, if you use the
+@kbd{t} command to view the entire header and then copy the message, the
+entire header is copied. @xref{Rmail Display}.
+
+@vindex rmail-output-file-alist
+ The variable @code{rmail-output-file-alist} lets you specify
+intelligent defaults for the output file, based on the contents of the
+current message. The value should be a list whose elements have this
+form:
+
+@example
+(@var{regexp} . @var{name-exp})
+@end example
+
+@noindent
+If there's a match for @var{regexp} in the current message, then the
+default file name for output is @var{name-exp}. If multiple elements
+match the message, the first matching element decides the default file
+name. The subexpression @var{name-exp} may be a string constant giving
+the file name to use, or more generally it may be any Lisp expression
+that returns a file name as a string. @code{rmail-output-file-alist}
+applies to both @kbd{o} and @kbd{C-o}.
+
+@node Rmail Labels
+@section Labels
+@cindex label (Rmail)
+@cindex attribute (Rmail)
+
+ Each message can have various @dfn{labels} assigned to it as a means
+of classification. Each label has a name; different names are different
+labels. Any given label is either present or absent on a particular
+message. A few label names have standard meanings and are given to
+messages automatically by Rmail when appropriate; these special labels
+are called @dfn{attributes}.
+@ifinfo
+(@xref{Rmail Attributes}.)
+@end ifinfo
+All other labels are assigned only by users.
+
+@table @kbd
+@item a @var{label} @key{RET}
+Assign the label @var{label} to the current message (@code{rmail-add-label}).
+@item k @var{label} @key{RET}
+Remove the label @var{label} from the current message (@code{rmail-kill-label}).
+@item C-M-n @var{labels} @key{RET}
+Move to the next message that has one of the labels @var{labels}
+(@code{rmail-next-labeled-message}).
+@item C-M-p @var{labels} @key{RET}
+Move to the previous message that has one of the labels @var{labels}
+(@code{rmail-previous-labeled-message}).
+@item C-M-l @var{labels} @key{RET}
+Make a summary of all messages containing any of the labels @var{labels}
+(@code{rmail-summary-by-labels}).
+@end table
+
+@kindex a @r{(Rmail)}
+@kindex k @r{(Rmail)}
+@findex rmail-add-label
+@findex rmail-kill-label
+ The @kbd{a} (@code{rmail-add-label}) and @kbd{k}
+(@code{rmail-kill-label}) commands allow you to assign or remove any
+label on the current message. If the @var{label} argument is empty, it
+means to assign or remove the same label most recently assigned or
+removed.
+
+ Once you have given messages labels to classify them as you wish, there
+are two ways to use the labels: in moving and in summaries.
+
+@kindex C-M-n @r{(Rmail)}
+@kindex C-M-p @r{(Rmail)}
+@findex rmail-next-labeled-message
+@findex rmail-previous-labeled-message
+ The command @kbd{C-M-n @var{labels} @key{RET}}
+(@code{rmail-next-labeled-message}) moves to the next message that has
+one of the labels @var{labels}. The argument @var{labels} specifies one
+or more label names, separated by commas. @kbd{C-M-p}
+(@code{rmail-previous-labeled-message}) is similar, but moves backwards
+to previous messages. A numeric argument to either command serves as a
+repeat count.
+
+ The command @kbd{C-M-l @var{labels} @key{RET}}
+(@code{rmail-summary-by-labels}) displays a summary containing only the
+messages that have at least one of a specified set of labels. The
+argument @var{labels} is one or more label names, separated by commas.
+@xref{Rmail Summary}, for information on summaries.@refill
+
+ If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or
+@kbd{C-M-l} is empty, it means to use the last set of labels specified
+for any of these commands.
+
+@node Rmail Attributes
+@section Rmail Attributes
+
+ Some labels such as @samp{deleted} and @samp{filed} have built-in
+meanings and are assigned to or removed from messages automatically at
+appropriate times; these labels are called @dfn{attributes}. Here is a
+list of Rmail attributes:
+
+@table @samp
+@item unseen
+Means the message has never been current. Assigned to messages when
+they come from an inbox file, and removed when a message is made
+current. When you start Rmail, it initially shows the first message
+that has this attribute.
+@item deleted
+Means the message is deleted. Assigned by deletion commands and
+removed by undeletion commands (@pxref{Rmail Deletion}).
+@item filed
+Means the message has been copied to some other file. Assigned by the
+file output commands (@pxref{Rmail Files}).
+@item answered
+Means you have mailed an answer to the message. Assigned by the @kbd{r}
+command (@code{rmail-reply}). @xref{Rmail Reply}.
+@item forwarded
+Means you have forwarded the message. Assigned by the @kbd{f} command
+(@code{rmail-forward}). @xref{Rmail Reply}.
+@item edited
+Means you have edited the text of the message within Rmail.
+@xref{Rmail Editing}.
+@item resent
+Means you have resent the message. Assigned by the command @kbd{M-x
+rmail-resend}. @xref{Rmail Reply}.
+@end table
+
+ All other labels are assigned or removed only by the user, and have no
+standard meaning.
+
+@node Rmail Reply
+@section Sending Replies
+
+ Rmail has several commands that use Mail mode to send outgoing mail.
+@xref{Sending Mail}, for information on using Mail mode, including
+certain features meant to work with Rmail. What this section documents
+are the special commands of Rmail for entering Mail mode. Note that the
+usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and @kbd{C-x 5
+m}---are available in Rmail mode and work just as they usually do.
+
+@table @kbd
+@item m
+Send a message (@code{rmail-mail}).
+@item c
+Continue editing the already started outgoing message (@code{rmail-continue}).
+@item r
+Send a reply to the current Rmail message (@code{rmail-reply}).
+@item f
+Forward the current message to other users (@code{rmail-forward}).
+@item C-u f
+Resend the current message to other users (@code{rmail-resend}).
+@item M-m
+Try sending a bounced message a second time (@code{rmail-retry-failure}).
+@end table
+
+@kindex r @r{(Rmail)}
+@findex rmail-reply
+@cindex reply to a message
+ The most common reason to send a message while in Rmail is to reply to
+the message you are reading. To do this, type @kbd{r}
+(@code{rmail-reply}). This displays the @samp{*mail*} buffer in another
+window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject},
+@samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the
+message you are replying to. The @samp{To} field starts out as the
+address of the person who sent the message you received, and the
+@samp{CC} field starts out with all the other recipients of that
+message.
+
+@vindex rmail-dont-reply-to-names
+ You can exclude certain recipients from being placed automatically in
+the @samp{CC}, using the variable @code{rmail-dont-reply-to-names}. Its
+value should be a regular expression (as a string); any recipient that
+the regular expression matches, is excluded from the @samp{CC} field.
+The default value matches your own name, and any name starting with
+@samp{info-}. (Those names are excluded because there is a convention
+of using them for large mailing lists to broadcast announcements.)
+
+ To omit the @samp{CC} field completely for a particular reply, enter
+the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}.
+
+ Once the @samp{*mail*} buffer has been initialized, editing and
+sending the mail goes as usual (@pxref{Sending Mail}). You can edit the
+presupplied header fields if they are not right for you. You can also
+use the commands of Mail mode (@pxref{Mail Mode}), including @kbd{C-c
+C-y} which yanks in the message that you are replying to. You can
+switch to the Rmail buffer, select a different message there, switch
+back, and yank the new current message.
+
+@kindex M-m @r{(Rmail)}
+@findex rmail-retry-failure
+@cindex retrying a failed message
+@vindex rmail-retry-ignored-headers
+ Sometimes a message does not reach its destination. Mailers usually
+send the failed message back to you, enclosed in a @dfn{failure
+message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure})
+prepares to send the same message a second time: it sets up a
+@samp{*mail*} buffer with the same text and header fields as before. If
+you type @kbd{C-c C-c} right away, you send the message again exactly
+the same as the first time. Alternatively, you can edit the text or
+headers and then send it. The variable
+@code{rmail-retry-ignored-headers}, in the same format as
+@code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which
+headers are stripped from the failed message when retrying it; it
+defaults to @code{nil}.
+
+@kindex f @r{(Rmail)}
+@findex rmail-forward
+@cindex forwarding a message
+ Another frequent reason to send mail in Rmail is to @dfn{forward} the
+current message to other users. @kbd{f} (@code{rmail-forward}) makes
+this easy by preinitializing the @samp{*mail*} buffer with the current
+message as the text, and a subject designating a forwarded message. All
+you have to do is fill in the recipients and send. When you forward a
+message, recipients get a message which is ``from'' you, and which has
+the original message in its contents.
+
+@findex unforward-rmail-message
+ Forwarding a message encloses it between two delimiter lines. It also
+modifies every line that starts with a dash, by inserting @w{@samp{- }}
+at the start of the line. When you receive a forwarded message, if it
+contains something besides ordinary text---for example, program source
+code---you might find it useful to undo that transformation. You can do
+this by selecting the forwarded message and typing @kbd{M-x
+unforward-rmail-message}. This command extracts the original forwarded
+message, deleting the inserted @w{@samp{- }} strings, and inserts it
+into the Rmail file as a separate message immediately following the
+current one.
+
+@findex rmail-resend
+ @dfn{Resending} is an alternative similar to forwarding; the
+difference is that resending sends a message that is ``from'' the
+original sender, just as it reached you---with a few added header fields
+@samp{Resent-from} and @samp{Resent-to} to indicate that it came via
+you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs
+@code{rmail-forward}, which is programmed to invoke @code{rmail-resend}
+if you provide a numeric argument.)
+
+@kindex m @r{(Rmail)}
+@findex rmail-mail
+ The @kbd{m} (@code{rmail-mail}) command is used to start editing an
+outgoing message that is not a reply. It leaves the header fields empty.
+Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
+accessible for @kbd{C-c C-y}, just as @kbd{r} does. Thus, @kbd{m} can be
+used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
+can do.@refill
+
+@kindex c @r{(Rmail)}
+@findex rmail-continue
+ The @kbd{c} (@code{rmail-continue}) command resumes editing the
+@samp{*mail*} buffer, to finish editing an outgoing message you were
+already composing, or to alter a message you have sent.@refill
+
+@vindex rmail-mail-new-frame
+ If you set the variable @code{rmail-mail-new-frame} to a
+non-@code{nil} value, then all the Rmail commands to start sending a
+message create a new frame to edit it in. This frame is deleted when
+you send the message, or when you use the @samp{Don't Send} item in the
+@samp{Mail} menu.
+
+ All the Rmail commands to send a message use the mail-composition
+method that you have chosen (@pxref{Mail Methods}).
+
+@node Rmail Summary
+@section Summaries
+@cindex summary (Rmail)
+
+ A @dfn{summary} is a buffer containing one line per message to give
+you an overview of the mail in an Rmail file. Each line shows the
+message number, the sender, the labels, and the subject. Almost all
+Rmail commands are valid in the summary buffer also; these apply to the
+message described by the current line of the summary. Moving point in
+the summary buffer selects messages as you move to their summary lines.
+
+ A summary buffer applies to a single Rmail file only; if you are
+editing multiple Rmail files, each one can have its own summary buffer.
+The summary buffer name is made by appending @samp{-summary} to the
+Rmail buffer's name. Normally only one summary buffer is displayed at a
+time.
+
+@menu
+* Rmail Make Summary:: Making various sorts of summaries.
+* Rmail Summary Edit:: Manipulating messages from the summary.
+@end menu
+
+@node Rmail Make Summary
+@subsection Making Summaries
+
+ Here are the commands to create a summary for the current Rmail file.
+Once the Rmail file has a summary buffer, changes in the Rmail file
+(such as deleting or expunging messages, and getting new mail)
+automatically update the summary.
+
+@table @kbd
+@item h
+@itemx C-M-h
+Summarize all messages (@code{rmail-summary}).
+@item l @var{labels} @key{RET}
+@itemx C-M-l @var{labels} @key{RET}
+Summarize messages that have one or more of the specified labels
+(@code{rmail-summary-by-labels}).
+@item C-M-r @var{rcpts} @key{RET}
+Summarize messages that have one or more of the specified recipients
+(@code{rmail-summary-by-recipients}).
+@item C-M-t @var{topic} @key{RET}
+Summarize messages that have a match for the specified regexp
+@var{topic} in their subjects (@code{rmail-summary-by-topic}).
+@end table
+
+@kindex h @r{(Rmail)}
+@findex rmail-summary
+ The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
+for the current Rmail file with a summary of all the messages in the file.
+It then displays and selects the summary buffer in another window.
+
+@kindex l @r{(Rmail)}
+@kindex C-M-l @r{(Rmail)}
+@findex rmail-summary-by-labels
+ @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
+a partial summary mentioning only the messages that have one or more of the
+labels @var{labels}. @var{labels} should contain label names separated by
+commas.@refill
+
+@kindex C-M-r @r{(Rmail)}
+@findex rmail-summary-by-recipients
+ @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
+makes a partial summary mentioning only the messages that have one or more
+of the recipients @var{rcpts}. @var{rcpts} should contain mailing
+addresses separated by commas.@refill
+
+@kindex C-M-t @r{(Rmail)}
+@findex rmail-summary-by-topic
+ @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic})
+makes a partial summary mentioning only the messages whose subjects have
+a match for the regular expression @var{topic}.
+
+ Note that there is only one summary buffer for any Rmail file; making one
+kind of summary discards any previously made summary.
+
+@vindex rmail-summary-window-size
+@vindex rmail-summary-line-count-flag
+ The variable @code{rmail-summary-window-size} says how many lines to
+use for the summary window. The variable
+@code{rmail-summary-line-count-flag} controls whether the summary line
+for a message should include the line count of the message.
+
+@node Rmail Summary Edit
+@subsection Editing in Summaries
+
+ You can use the Rmail summary buffer to do almost anything you can do
+in the Rmail buffer itself. In fact, once you have a summary buffer,
+there's no need to switch back to the Rmail buffer.
+
+ You can select and display various messages in the Rmail buffer, from
+the summary buffer, just by moving point in the summary buffer to
+different lines. It doesn't matter what Emacs command you use to move
+point; whichever line point is on at the end of the command, that
+message is selected in the Rmail buffer.
+
+ Almost all Rmail commands work in the summary buffer as well as in the
+Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current
+message, @kbd{u} undeletes, and @kbd{x} expunges. @kbd{o} and @kbd{C-o}
+output the current message to a file; @kbd{r} starts a reply to it. You
+can scroll the current message while remaining in the summary buffer
+using @key{SPC} and @key{DEL}.
+
+ The Rmail commands to move between messages also work in the summary
+buffer, but with a twist: they move through the set of messages included
+in the summary. They also ensure the Rmail buffer appears on the screen
+(unlike cursor motion commands, which update the contents of the Rmail
+buffer but don't display it in a window unless it already appears).
+Here is a list of these commands:
+
+@table @kbd
+@item n
+Move to next line, skipping lines saying `deleted', and select its
+message.
+@item p
+Move to previous line, skipping lines saying `deleted', and select
+its message.
+@item M-n
+Move to next line and select its message.
+@item M-p
+Move to previous line and select its message.
+@item >
+Move to the last line, and select its message.
+@item <
+Move to the first line, and select its message.
+@item M-s @var{pattern} @key{RET}
+Search through messages for @var{pattern} starting with the current
+message; select the message found, and move point in the summary buffer
+to that message's line.
+@end table
+
+@vindex rmail-redisplay-summary
+ Deletion, undeletion, and getting new mail, and even selection of a
+different message all update the summary buffer when you do them in the
+Rmail buffer. If the variable @code{rmail-redisplay-summary} is
+non-@code{nil}, these actions also bring the summary buffer back onto
+the screen.
+
+@kindex Q @r{(Rmail summary)}
+@findex rmail-summary-wipe
+@kindex q @r{(Rmail summary)}
+@findex rmail-summary-quit
+ When you are finished using the summary, type @kbd{Q}
+(@code{rmail-summary-wipe}) to delete the summary buffer's window. You
+can also exit Rmail while in the summary: @kbd{q}
+(@code{rmail-summary-quit}) deletes the summary window, then exits from
+Rmail by saving the Rmail file and switching to another buffer.
+
+@node Rmail Sorting
+@section Sorting the Rmail File
+
+@table @kbd
+@item M-x rmail-sort-by-date
+Sort messages of current Rmail file by date.
+
+@item M-x rmail-sort-by-subject
+Sort messages of current Rmail file by subject.
+
+@item M-x rmail-sort-by-author
+Sort messages of current Rmail file by author's name.
+
+@item M-x rmail-sort-by-recipient
+Sort messages of current Rmail file by recipient's names.
+
+@item M-x rmail-sort-by-correspondent
+Sort messages of current Rmail file by the name of the other
+correspondent.
+
+@item M-x rmail-sort-by-lines
+Sort messages of current Rmail file by size (number of lines).
+
+@item M-x rmail-sort-by-keywords @key{RET} @var{labels} @key{RET}
+Sort messages of current Rmail file by labels. The argument
+@var{labels} should be a comma-separated list of labels. The order of
+these labels specifies the order of messages; messages with the first
+label come first, messages with the second label come second, and so on.
+Messages which have none of these labels come last.
+@end table
+
+ The Rmail sort commands perform a @emph{stable sort}: if there is no
+reason to prefer either one of two messages, their order remains
+unchanged. You can use this to sort by more than one criterion. For
+example, if you use @code{rmail-sort-by-date} and then
+@code{rmail-sort-by-author}, messages from the same author appear in
+order by date.
+
+ With a numeric argument, all these commands reverse the order of
+comparison. This means they sort messages from newest to oldest, from
+biggest to smallest, or in reverse alphabetical order.
+
+@node Rmail Display
+@section Display of Messages
+
+ Rmail reformats the header of each message before displaying it for
+the first time. Reformatting hides uninteresting header fields to
+reduce clutter. You can use the @kbd{t} command to show the entire
+header or to repeat the header reformatting operation.
+
+@table @kbd
+@item t
+Toggle display of complete header (@code{rmail-toggle-header}).
+@end table
+
+@vindex rmail-ignored-headers
+ Reformatting the header involves deleting most header fields, on the
+grounds that they are not interesting. The variable
+@code{rmail-ignored-headers} holds a regular expression that specifies
+which header fields to hide in this way---if it matches the beginning of
+a header field, that whole field is hidden.
+
+@kindex t @r{(Rmail)}
+@findex rmail-toggle-header
+ Rmail saves the complete original header before reformatting; to see
+it, use the @kbd{t} command (@code{rmail-toggle-header}). This
+discards the reformatted headers of the current message and displays it
+with the original header. Repeating @kbd{t} reformats the message
+again. Selecting the message again also reformats.
+
+ One consequence of this is that if you edit the reformatted header
+(using @kbd{e}; @pxref{Rmail Editing}), subsequent use of @kbd{t} will
+discard your edits. On the other hand, if you use @kbd{e} after
+@kbd{t}, to edit the original (unreformatted) header, those changes are
+permanent.
+
+ When the @kbd{t} command has a prefix argument, a positive argument
+means to show the reformatted header, and a zero or negative argument
+means to show the full header.
+
+@vindex rmail-highlighted-headers
+ When used with a window system that supports multiple fonts, Rmail
+highlights certain header fields that are especially interesting---by
+default, the @samp{From} and @samp{Subject} fields. The variable
+@code{rmail-highlighted-headers} holds a regular expression that
+specifies the header fields to highlight; if it matches the beginning of
+a header field, that whole field is highlighted.
+
+ If you specify unusual colors for your text foreground and background,
+the colors used for highlighting may not go well with them. If so,
+specify different colors for the @code{highlight} face. That is worth
+doing because the @code{highlight} face is used for other kinds of
+highlighting as well. @xref{Faces}, for how to do this.
+
+ To turn off highlighting entirely in Rmail, set
+@code{rmail-highlighted-headers} to @code{nil}.
+
+@node Rmail Editing
+@section Editing Within a Message
+
+ Most of the usual Emacs commands are available in Rmail mode, though a
+few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for
+other purposes. However, the Rmail buffer is normally read only, and
+most of the letters are redefined as Rmail commands. If you want to
+edit the text of a message, you must use the Rmail command @kbd{e}.
+
+@table @kbd
+@item e
+Edit the current message as ordinary text.
+@end table
+
+@kindex e @r{(Rmail)}
+@findex rmail-edit-current-message
+ The @kbd{e} command (@code{rmail-edit-current-message}) switches from
+Rmail mode into Rmail Edit mode, another major mode which is nearly the
+same as Text mode. The mode line indicates this change.
+
+ In Rmail Edit mode, letters insert themselves as usual and the Rmail
+commands are not available. When you are finished editing the message and
+are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to
+Rmail mode. Alternatively, you can return to Rmail mode but cancel all the
+editing that you have done, by typing @kbd{C-c C-]}.
+
+@vindex rmail-edit-mode-hook
+ Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then it
+runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}). It adds the
+attribute @samp{edited} to the message. It also displays the full
+headers of the message, so that you can edit the headers as well as the
+body of the message, and your changes in the the headers will be
+permanent.
+
+@node Rmail Digest
+@section Digest Messages
+@cindex digest message
+@cindex undigestify
+
+ A @dfn{digest message} is a message which exists to contain and carry
+several other messages. Digests are used on some moderated mailing
+lists; all the messages that arrive for the list during a period of time
+such as one day are put inside a single digest which is then sent to the
+subscribers. Transmitting the single digest uses much less computer
+time than transmitting the individual messages even though the total
+size is the same, because the per-message overhead in network mail
+transmission is considerable.
+
+@findex undigestify-rmail-message
+ When you receive a digest message, the most convenient way to read it is
+to @dfn{undigestify} it: to turn it back into many individual messages.
+Then you can read and delete the individual messages as it suits you.
+
+ To do this, select the digest message and type the command @kbd{M-x
+undigestify-rmail-message}. This extracts the submessages as separate
+Rmail messages, and inserts them following the digest. The digest
+message itself is flagged as deleted.
+
+@node Out of Rmail
+@section Converting an Rmail File to Inbox Format
+
+@findex unrmail
+ The command @kbd{M-x unrmail} converts a file in Rmail format to inbox
+format (also known as the system mailbox format), so that you can use it
+with other mail-editing tools. You must specify two arguments, the name
+of the Rmail file and the name to use for the converted file. @kbd{M-x
+unrmail} does not alter the Rmail file itself.
+
+@node Rmail Rot13
+@section Reading Rot13 Messages
+@cindex rot13 code
+
+ Mailing list messages that might offend some readers are sometimes
+encoded in a simple code called @dfn{rot13}---so named because it
+rotates the alphabet by 13 letters. This code is not for secrecy, as it
+provides none; rather, it enables those who might be offended to avoid
+ever seeing the real text of the message.
+
+@findex rot13-other-window
+ To view a buffer using the rot13 code, use the command @kbd{M-x
+rot13-other-window}. This displays the current buffer in another window
+which applies the code when displaying the text.
+
+@node Movemail
+@section @code{movemail} and POP
+@cindex @code{movemail} program
+
+@vindex rmail-preserve-inbox
+ When getting new mail, Rmail first copies the new mail from the inbox
+file to the Rmail file; then it saves the Rmail file; then it truncates
+the inbox file. This way, a system crash may cause duplication of mail
+between the inbox and the Rmail file, but cannot lose mail. If
+@code{rmail-preserve-inbox} is non-@code{nil}, then Rmail will copy new
+mail from the inbox file to the Rmail file without truncating the inbox
+file. You may wish to set this, for example, on a portable computer you
+use to check your mail via POP while traveling, so that your mail will
+remain on the server and you can save it later on your workstation.
+
+ In some cases, Rmail copies the new mail from the inbox file
+indirectly. First it runs the @code{movemail} program to move the mail
+from the inbox to an intermediate file called
+@file{~/.newmail-@var{inboxname}}. Then Rmail merges the new mail from
+that file, saves the Rmail file, and only then deletes the intermediate
+file. If there is a crash at the wrong time, this file continues to
+exist, and Rmail will use it again the next time it gets new mail from
+that inbox.
+
+@pindex movemail
+ If Rmail is unable to convert the data in
+@file{~/.newmail-@var{inboxname}} into Babyl format, it renames the file
+to @file{~/RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the
+name unique) so that Rmail will not have trouble with the data again.
+You should look at the file, find whatever message confuses Rmail
+(probably one that includes the control-underscore character, octal code
+037), and delete it. Then you can use @kbd{1 g} to get new mail from
+the corrected file.
+
+ Some sites use a method called POP for accessing users' inbox data
+instead of storing the data in inbox files. @code{movemail} can work
+with POP if you compile it with the macro @code{MAIL_USE_POP} defined.
+(You can achieve that by specifying @samp{--with-pop} when you run
+@code{configure} during the installation of Emacs.)
+@code{movemail} only works with POP3, not with older
+versions of POP.
+
+@cindex @code{MAILHOST} environment variable
+@cindex POP inboxes
+ Assuming you have compiled and installed @code{movemail}
+appropriately, you can specify a POP inbox by using a ``file name'' of
+the form @samp{po:@var{username}}, in the inbox list of an Rmail file.
+@code{movemail} handles such a name by opening a connection to the POP
+server. The @code{MAILHOST} environment variable specifies the machine
+to look for the server on.
+
+@vindex rmail-pop-password
+@vindex rmail-pop-password-required
+ Accessing mail via POP may require a password. If the variable
+@code{rmail-pop-password} is non-@code{nil}, it specifies the password
+to use for POP. Alternatively, if @code{rmail-pop-password-required} is
+non-@code{nil}, then Rmail asks you for the password to use.
+
+@vindex rmail-movemail-flags
+ If you need to pass additional command-line flags to @code{movemail},
+set the variable @code{rmail-movemail-flags} a list of the flags you
+wish to use. Do not use this variable to pass the @samp{-p} flag to
+preserve your inbox contents; use @code{rmail-preserve-inbox} instead.
+
+@cindex Kerberos POP authentication
+ The @code{movemail} program installed at your site may support
+Kerberos authentication. If it is
+supported, it is used by default whenever you attempt to retrieve
+POP mail when @code{rmail-pop-password} and
+@code{rmail-pop-password-required} are unset.
+
+@cindex POP inboxes in reverse order
+ Some POP servers store messages in reverse order. If your server does
+this, and you would rather read your mail in the order in which it was
+received, you can tell @code{movemail} to reverse the order of
+downloaded messages by adding the @samp{-r} flag to
+@code{rmail-movemail-flags}.
--- /dev/null
+\input texinfo @comment -*-texinfo-*-
+@comment 3.47
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename ../info/sc
+@settitle Supercite Version 3.1 User's Manual
+@iftex
+@finalout
+@end iftex
+
+@dircategory Editors
+@direntry
+* SC: (sc). Supercite lets you cite parts of messages you're
+ replying to, in flexible ways.
+@end direntry
+
+@c @setchapternewpage odd % For book style double sided manual.
+@comment %**end of header (This is for running Texinfo on a region.)
+@c @smallbook
+@tex
+\overfullrule=0pt
+%\global\baselineskip 30pt % For printing in double spaces
+@end tex
+@ifinfo
+This document describes the Supercite Version 3.1 package for citing and
+attributing the replies for various GNU Emacs mail and news reading
+subsystems.
+
+Copyright @copyright{} 1993 Barry A@. Warsaw
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+@end ifinfo
+@c
+@titlepage
+@sp 6
+@center @titlefont{Supercite User's Manual}
+@sp 2
+@center @titlefont{Supercite Version 3.1}
+@sp 4
+@center Manual Revision: 3.47
+@center August 1993
+@sp 5
+@center Barry A@. Warsaw
+@center @t{bwarsaw@@cen.com}
+@center @t{@dots{}!uunet!cen.com!bwarsaw}
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1993 Barry A@. Warsaw
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@end titlepage
+@page
+@ifinfo
+@node Top, Introduction, (dir), (dir)
+@comment node-name, next, previous, up
+
+This document describes the Supercite Version 3.1 package for citing and
+attributing the replies for various GNU Emacs mail and news reading
+subsystems. The manual is divided into the following chapters.
+
+@menu
+* Introduction::
+* Citations::
+* Getting Connected::
+* Replying and Yanking::
+* Selecting an Attribution::
+* Configuring the Citation Engine::
+* Post-yank Formatting Commands::
+* Information Keys and the Info Alist::
+* Reference Headers::
+* Hints to MUA Authors::
+* Version 3 Changes::
+* Thanks and History::
+* The Supercite Mailing List::
+
+* Concept Index::
+* Command Index::
+* Key Index::
+* Variable Index::
+@end menu
+@end ifinfo
+
+@node Introduction, Usage Overview, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+@ifinfo
+
+@end ifinfo
+Supercite version 3.1 is a GNU Emacs package written entirely in Emacs
+Lisp. It interfaces to most of the commonly used Emacs mail user agents
+(@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides
+sophisticated facilities for the citing and attributing of message
+replies. Supercite has a very specific and limited role in the process
+of composing replies to both USENET network news and electronic mail.
+
+The preferred way to spell Supercite is with a capital @samp{S},
+lowercase @samp{upercite}. There are a few alternate spellings out there
+and I won't be terribly offended if you use them. People often ask
+though@dots{}
+
+@ifinfo
+@menu
+* Usage Overview::
+* What Supercite Does Not Do::
+* What Supercite Does::
+@end menu
+@end ifinfo
+
+@cindex MUA
+@cindex NUA
+Supercite is only useful in conjunction with MUAs and NUAs such as VM,
+GNUS, RMAIL, etc@. (hereafter referred to collectively as MUAs).
+Supercite is typically called by the MUA after a reply buffer has been
+setup. Thereafter, Supercite's many commands and formatting styles are
+available in that reply buffer until the reply is sent. Supercite is
+re-initialized in each new reply buffer.
+
+Supercite is currently at major revision 3.1, and is known to work in the
+following environments:
+
+@table @asis
+@item Emacs versions:
+ GNU Emacs 18.57 through 18.59, all Emacs 19,
+ all current Lucid Emacs, and Epoch 4.@refill
+
+@item MUAs:
+ VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and
+ beyond, PCMAIL.@refill
+
+@item NUAs:
+ RNEWS, GNUS 3.12 and beyond, GNEWS.@refill
+
+@end table
+For systems with version numbers, all known subsequent versions also
+work with Supercite. For those systems without version numbers,
+Supercite probably works with any recently released version. Note that
+only some of these systems will work with Supercite ``out of the box.''
+All others must overload interfacing routines to supply the necessary
+glue. @xref{Getting Connected}, for more details.@refill
+
+
+@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction
+@comment node-name, next, previous, up
+@kindex r
+@kindex f
+@kindex C-c C-y
+@cindex yank
+@cindex cite, citing
+@cindex attribute, attributing
+@comment
+@section Usage Overview
+@ifinfo
+
+@end ifinfo
+Typical usage is as follows. You want to reply or followup to a message
+in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f}
+(i.e., ``forward'') to begin composing the reply. In response, the MUA
+will create a reply buffer and initialize the outgoing mail headers
+appropriately. The body of the reply will usually be empty at this
+point. You now decide that you would like to include part of the
+original message in your reply. To do this, you @dfn{yank} the original
+message into the reply buffer, typically with a key stroke such as
+@kbd{C-c C-y}. This sequence will invoke an MUA-specific function which
+fills the body of the reply with the original message and then
+@dfn{attributes} this text to its author. This is called @dfn{citing}
+and its effect is to prefix every line from the original message with a
+special text tag. Most MUAs provide some default style of citing; by
+using Supercite you gain a wider flexibility in the look and style of
+citations. Supercite's only job is to cite the original message.
+
+@node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction
+@comment node-name, next, previous, up
+@section What Supercite Doesn't Do
+@ifinfo
+
+@end ifinfo
+Because of this clear division of labor, there are useful features which
+are the sole responsibility of the MUA, even though it might seem that
+Supercite should provide them. For example, many people would like to
+be able to yank (and cite) only a portion of the original message.
+Since Supercite only modifies the text it finds in the reply buffer as
+set up by the MUA, it is the MUA's responsibility to do partial yanking.
+@xref{Reply Buffer Initialization}.@refill
+
+@vindex mail-header-separator
+@comment
+Another potentially useful thing would be for Supercite to set up the
+outgoing mail headers with information it gleans from the reply buffer.
+But by previously agreed upon convention, any text above the
+@code{mail-header-separator} which separates mail headers from message
+bodies cannot be modified by Supercite. Supercite, in fact, doesn't
+know anything about the meaning of these headers, and never ventures
+outside the designated region. @xref{Hints to MUA Authors}, for more
+details.@refill
+
+@node What Supercite Does, Citations, What Supercite Does Not Do, Introduction
+@comment node-name, next, previous, up
+@findex sc-cite-original
+@section What Supercite Does
+@ifinfo
+
+@end ifinfo
+Supercite is invoked for the first time on a reply buffer via your MUA's
+reply or forward command. This command will actually perform citations
+by calling a hook variable to which Supercite's top-level function
+@code{sc-cite-original} has been added. When @code{sc-cite-original} is
+executed, the original message must be set up in a very specific way,
+but this is handled automatically by the MUA. @xref{Hints to MUA
+Authors}.@refill
+
+@cindex info alist
+The first thing Supercite does, via @code{sc-cite-original}, is to parse
+through the original message's mail headers. It saves this data in an
+@dfn{information association list}, or @dfn{info alist}. The information
+in this list is used in a number of places throughout Supercite.
+@xref{Information Keys and the Info Alist}.@refill
+
+@cindex nuking mail headers
+@cindex reference header
+After the mail header info is extracted, the headers are optionally
+removed (@dfn{nuked}) from the reply. Supercite then writes a
+@dfn{reference header} into the buffer. This reference header is a
+string carrying details about the citation it is about to perform.
+
+@cindex modeline
+Next, Supercite visits each line in the reply, transforming the line
+according to a customizable ``script''. Lines which were not previously
+cited in the original message are given a citation, while already cited
+lines remain untouched, or are coerced to your preferred style.
+Finally, Supercite installs a keymap into the reply buffer so that you
+have access to Supercite's post-yank formatting and reciting commands as
+you subsequently edit your reply. You can tell that Supercite has been
+installed into the reply buffer because that buffer's modeline will
+display the minor mode string @samp{SC}.
+
+@cindex filladapt
+@cindex gin-mode
+@vindex fill-prefix
+@findex fill-paragraph
+@comment
+When the original message is cited by @code{sc-cite-original}, it will
+(optionally) be filled by Supercite. However, if you manually edit the
+cited text and want to re-fill it, you must use an add-on package such
+as @cite{filladapt} or @cite{gin-mode}. These packages can recognize
+Supercited text and will fill them appropriately. Emacs' built-in
+filling routines, e.g@. @code{fill-paragraph}, do not recognize cited
+text and will not re-fill them properly because it cannot guess the
+@code{fill-prefix} being used.
+@xref{Post-yank Formatting Commands}, for details.@refill
+
+As mentioned above, Supercite provides commands to recite or uncite
+regions of text in the reply buffer, and commands to perform other
+beautifications on the cited original text, maintaining consistent and
+informative citations throughout. Supercite tries to be as configurable
+as possible to allow for a wide range of personalized citation styles,
+but it is also immediately useful with the default configuration, once
+it has been properly connected to your MUA. @xref{Getting Connected},
+for more details.@refill
+
+@node Citations, Citation Elements, What Supercite Does, Top
+@comment node-name, next, previous, up
+@cindex nested citations
+@cindex citation
+@comment
+@chapter Citations
+@ifinfo
+
+@end ifinfo
+A @dfn{citation} is the acknowledgement of the original author of a mail
+message in the body of the reply. There are two basic citation styles
+which Supercite supports. The first, called @dfn{nested citations} is
+an anonymous form of citation; in other words, an indication is made
+that the cited line was written by someone @emph{other} that the current
+message author (i.e., other than you, the person composing the reply),
+but no reference is made as to the identity of the original author.
+This style should look familiar since its use on the net is widespread.
+Here's an example of what a message buffer would look like using nested
+citations after multiple replies:
+
+@example
+>> John originally wrote this
+>> and this as well
+> Jane said that John didn't know
+> what he was talking about
+And that's what I think too.
+@end example
+
+@ifinfo
+@menu
+* Citation Elements::
+* Recognizing Citations::
+@end menu
+@end ifinfo
+
+Note that multiple inclusions of the original messages result in a
+nesting of the @samp{@code{>}} characters. This can sometimes be quite
+confusing when many levels of citations are included since it may be
+difficult or impossible to figure out who actually participated in the
+thread, and multiple nesting of @samp{@code{>}} characters can sometimes
+make the message very difficult for the eye to scan.
+
+@cindex non-nested citations
+In @dfn{non-nested citations}, each cited line begins with an
+informative string attributing that line to the original author. Only
+the first level of attribution will be shown; subsequent citations don't
+nest the citation strings. The above dialog might look like this when
+non-nested citations are used:
+
+@example
+John> John originally wrote this
+John> and this as well
+Jane> Jane said that John didn't know
+Jane> what he was talking about
+And that's what I think too.
+@end example
+
+Notice here that my inclusion of Jane's inclusion of John's original
+message did not result in a line cited with @samp{Jane>John>}.
+
+@vindex sc-nested-citation-p
+@vindex nested-citation-p (sc-)
+Supercite supports both styles of citation, and the variable
+@code{sc-nested-citation-p} controls which style it will use when citing
+previously uncited text. When this variable is @code{nil} (the default),
+non-nested citations are used. When non-@code{nil}, nested citations
+are used.
+
+
+@node Citation Elements, Recognizing Citations, Citations, Citations
+@comment node-name, next, previous, up
+@cindex citation string
+@comment
+@section Citation Elements
+@ifinfo
+
+@end ifinfo
+@dfn{Citation strings} are composed of one or more elements. Non-nested
+citations are composed of four elements, three of which are directly
+user definable. The elements are concatenated together, in this order:
+
+@cindex citation leader
+@vindex citation-leader (sc-)
+@vindex sc-citation-leader
+@enumerate
+@item
+The @dfn{citation leader}. The citation leader is contained in the
+variable @code{sc-citation-leader}, and has the default value of a
+string containing four spaces.
+
+@cindex attribution string
+@item
+The @dfn{attribution string}. This element is supplied automatically by
+Supercite, based on your preferences and the original message's mail
+headers, though you may be asked to confirm Supercite's choice.
+@xref{Selecting an Attribution}, for more details.@refill
+
+@cindex citation delimiter
+@vindex sc-citation-delimiter
+@vindex citation-delimiter (sc-)
+@item
+The @dfn{citation delimiter}. This string, contained in the variable
+@code{sc-citation-delimiter} visually separates the citation from the
+text of the line. This variable has a default value of @code{">"} and
+for best results, the string should consist of only a single character.
+
+@cindex citation separator
+@vindex citation-separator (sc-)
+@vindex sc-citation-separator
+@item
+The @dfn{citation separator}. The citation separator is contained in
+the variable @code{sc-citation-separator}, and has the default value of
+a string containing a single space.
+@end enumerate
+
+For example, suppose you were using the default values for the above
+variables, and Supercite provided the attribution string @samp{Jane}.
+In this case, the composed, non-nested citation string used might be
+something like
+@code{@asis{" Jane> "}}.
+This citation string will be inserted in front of
+every line in the original message that is not already cited.@refill
+
+Nested citations, being simpler than non-nested citations, are composed
+of the same elements, sans the attribution string. Supercite is smart
+enough to not put additional spaces between citation delimiters for
+multi-level nested citations.
+
+@node Recognizing Citations, Getting Connected, Citation Elements, Citations
+@comment node-name, next, previous, up
+@section Recognizing Citations
+@ifinfo
+
+@end ifinfo
+Supercite also recognizes citations in the original article, and can
+transform these already cited lines in a number of ways. This is how
+Supercite suppresses the multiple citing of non-nested citations.
+Recognition of cited lines is controlled by variables analogous to those
+that make up the citation string as mentioned previously.
+
+@vindex sc-citation-leader-regexp
+@vindex citation-leader-regexp (sc-)
+@vindex sc-citation-delimiter-regexp
+@vindex citation-delimiter-regexp (sc-)
+@vindex sc-citation-separator-regexp
+@vindex citation-separator-regexp (sc-)
+@vindex sc-citation-root-regexp
+@vindex citation-root-regexp (sc-)
+@vindex sc-citation-nonnested-root-regexp
+@vindex citation-nonnested-root-regexp (sc-)
+
+The variable @code{sc-citation-leader-regexp} describes how citation
+leaders can look, by default it matches any number of spaces or tabs.
+Note that since the lisp function @code{looking-at} is used to do the
+matching, if you change this variable it need not start with a leading
+@code{"^"}.
+
+Similarly, the variables @code{sc-citation-delimiter-regexp} and
+@code{sc-citation-separator-regexp} respectively describe how citation
+delimiters and separators can look. They follow the same rule as
+@code{sc-citation-leader-regexp} above.
+
+When Supercite composes a citation string, it provides the attribution
+automatically. The analogous variable which handles recognition of the
+attribution part of citation strings is @code{sc-citation-root-regexp}.
+This variable describes the attribution root for both nested and
+non-nested citations. By default it can match zero-to-many alphanumeric
+characters (also ``.'', ``-'', and ``_''). But in some situations,
+Supercite has to determine whether it is looking at a nested or
+non-nested citation. Thus the variable
+@code{sc-citation-nonnested-root-regexp} is used to describe only
+non-nested citation roots. It is important to remember that if you
+change @code{sc-citation-root-regexp} you should always also change
+@code{sc-citation-nonnested-root-regexp}.@refill
+
+Nemacs users:@: For best results, try setting
+@code{sc-citation-root-regexp} to:@refill
+
+@example
+"\\([-._a-zA-Z0-9]\\|\\cc\\|\\cC\\|\\ch\\|\\cH\\|\\ck\\|\\cK\\|\\ca\\|\\cg\\|\\cr\\|\\cu\\)*"
+@end example
+
+Mule users:@: For best results, try setting
+@code{sc-citation-root-regexp} to:@refill
+
+@example
+"\\([-._a-zA-Z0-9]\\|\\cj\\)*"
+@end example
+
+@node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top
+@comment node-name, next, previous, up
+@cindex information keys
+@cindex Info Alist
+@cindex information extracted from mail fields
+@findex sc-mail-field
+@findex mail-field (sc-)
+@comment
+@chapter Information Keys and the Info Alist
+@ifinfo
+
+@end ifinfo
+@dfn{Mail header information keys} are nuggets of information that
+Supercite extracts from the various mail headers of the original
+message, placed in the reply buffer by the MUA. Information is kept in
+the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in
+various places within Supercite, such as in header rewrite functions and
+attribution selection. Other bits of data, composed and created by
+Supercite, are also kept as key-value pairs in this alist. In the case
+of mail fields, the key is the name of the field, omitting the trailing
+colon. Info keys are always case insensitive (as are mail headers), and
+the value for a corresponding key can be retrieved from the alist with
+the @code{sc-mail-field} function. Thus, if the following fields were
+present in the original article:@refill
+
+@example
+Date:@: 08 April 1991, 17:32:09 EST
+Subject:@: Better get out your asbestos suit
+@end example
+
+@vindex sc-mumble
+@vindex mumble (sc-)
+@noindent
+then, the following lisp constructs return:
+
+@example
+(sc-mail-field "date")
+==> "08 April 1991, 17:32:09 EST"
+
+(sc-mail-field "subject")
+==> "Better get out your asbestos suit"
+@end example
+
+Since the argument to @code{sc-mail-field} can be any string, it is
+possible that the mail field will not be present on the info alist
+(possibly because the mail header was not present in the original
+message). In this case, @code{sc-mail-field} will return the value of
+the variable @code{sc-mumble}.
+
+Supercite always places all mail fields found in the yanked original
+article into the info alist. If possible, Supercite will also places
+the following keys into the info alist:
+
+@table @code
+@cindex sc-attribution info field
+@cindex attribution info field (sc-)
+@item "sc-attribution"
+the selected attribution string.
+
+@cindex sc-citation info field
+@cindex citation info field (sc-)
+@item "sc-citation"
+the non-nested citation string.
+
+@cindex sc-from-address info field
+@cindex from-address info field (sc-)
+@item "sc-from-address"
+email address extracted from the @samp{From:@:} field.
+
+@cindex sc-reply-address info field
+@cindex reply-address info field (sc-)
+@item "sc-reply-address"
+email address extracted from the @samp{Reply-To:@:} field.
+
+@cindex sc-sender-address info field
+@cindex sender-address info field (sc-)
+@item "sc-sender-address"
+email address extracted from the @samp{Sender:@:} field.
+
+@cindex sc-emailname info field
+@cindex emailname info field (sc-)
+@item "sc-emailname"
+email terminus extracted from the @samp{From:@:} field.
+
+@cindex sc-initials info field
+@cindex initials info field (sc-)
+@item "sc-initials"
+the author's initials.
+
+@cindex sc-author info field
+@cindex author info field (sc-)
+@item "sc-author"
+the author's full name.
+
+@cindex sc-firstname info field
+@cindex firstname info field (sc-)
+@item "sc-firstname"
+the author's first name.
+
+@cindex sc-lastname info field
+@cindex lastname info field (sc-)
+@item "sc-lastname"
+the author's last name.
+
+@cindex sc-middlename-1 info field
+@cindex middlename-1 info field (sc-)
+@item "sc-middlename-1"
+the author's first middle name.
+@end table
+
+If the author's name has more than one middle name, they will appear as
+info keys with the appropriate index (e.g., @code{"sc-middlename-2"},
+@dots{}). @xref{Selecting an Attribution}.@refill
+
+@node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top
+@comment node-name, next, previous, up
+@cindex reference headers
+@chapter Reference Headers
+@ifinfo
+
+@end ifinfo
+Supercite will insert an informative @dfn{reference header} at the
+beginning of the cited body of text, which display more detail about the
+original article and provides the mapping between the attribution and
+the original author in non-nested citations. Whereas the citation
+string usually only contains a portion of the original author's name,
+the reference header can contain such information as the author's full
+name, email address, the original article's subject, etc. In fact any
+information contained in the info alist can be inserted into a reference
+header.
+
+@ifinfo
+@menu
+* The Built-in Header Rewrite Functions::
+* Electric References::
+@end menu
+@end ifinfo
+
+@cindex header rewrite functions
+@vindex sc-rewrite-header-list
+@vindex rewrite-header-list (sc-)
+There are a number of built-in @dfn{header rewrite functions} supplied
+by Supercite, but you can write your own custom header rewrite functions
+(perhaps using the built-in ones as examples). The variable
+@code{sc-rewrite-header-list} contains the list of such header rewrite
+functions. This list is consulted both when inserting the initial
+reference header, and when displaying @dfn{electric references}.
+@xref{Electric References}.
+
+@vindex sc-preferred-header-style
+@vindex preferred-header-style (sc-)
+When Supercite is initially run on a reply buffer (via
+@code{sc-cite-original}), it will automatically call one of these
+functions. The one it uses is defined in the variable
+@code{sc-preferred-header-style}. The value of this variable is an
+integer which is an index into the @code{sc-rewrite-header-list},
+beginning at zero.
+
+@node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers
+@comment node-name, next, previous, up
+@cindex header rewrite functions, built-in
+@comment
+@section The Built-in Header Rewrite Functions
+@ifinfo
+
+@end ifinfo
+Below are examples of the various built-in header rewrite functions.
+Please note the following:@: first, the text which appears in the
+examples below as @var{infokey} indicates that the corresponding value
+of the info key from the info alist will be inserted there.
+(@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said}
+below, @var{date} and @var{from} correspond to the values of the
+@samp{Date:@:} and @samp{From:@:} mail headers respectively.@refill
+
+@vindex sc-reference-tag-string
+@vindex reference-tag-string (sc-)
+Also, the string @code{">>>>>"} below is really the value of the
+variable @code{sc-reference-tag-string}. This variable is used in all
+built-in header rewrite functions, and you can customize its value to
+change the tag string globally.
+
+Finally, the references headers actually written may omit certain parts
+of the header if the info key associated with @var{infokey} is not
+present in the info alist. In fact, for all built-in headers, if the
+@samp{From:@:} field is not present in the mail headers, the entire
+reference header will be omitted (but this usually signals a serious
+problem either in your MUA or in Supercite's installation).
+
+@table @code
+@findex sc-no-header
+@findex no-header (sc-)
+@item sc-no-header
+This function produces no header. It should be used instead of
+@code{nil} to produce a blank header. This header can possibly contain
+a blank line after the @code{mail-header-separator} line.
+
+@item sc-no-blank-line-or-header
+@findex sc-no-blank-line-or-header
+@findex no-blank-line-or-header (sc-)
+This function is similar to @code{sc-no-header} except that any blank
+line after the @code{mail-header-separator} line will be removed.
+
+@item sc-header-on-said
+@findex sc-header-on-said
+@findex header-on-said (sc-)
+@code{>>>>> On @var{date}, @var{from} said:}
+
+@item sc-header-inarticle-writes
+@findex sc-header-inarticle-writes
+@findex header-inarticle-writes (sc-)
+@code{>>>>> In article @var{message-id}, @var{from} writes:}
+
+@item sc-header-regarding-adds
+@findex sc-header-regarding-adds
+@findex header-regarding-adds (sc-)
+@code{>>>>> Regarding @var{subject}; @var{from} adds:}
+
+@item sc-header-attributed-writes
+@findex sc-header-attributed-writes
+@findex header-attributed-writes (sc-)
+@code{>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:}
+
+@item sc-header-author-writes
+@findex sc-header-author-writes
+@findex header-author-writes (sc-)
+@code{>>>>> @var{sc-author} writes:}
+
+@item sc-header-verbose
+@findex sc-header-verbose
+@findex header-verbose (sc-)
+@code{>>>>> On @var{date},}@*
+@code{>>>>> @var{sc-author}}@*
+@code{>>>>> from the organization of @var{organization}}@*
+@code{>>>>> who can be reached at:@: @var{sc-reply-address}}@*
+@code{>>>>> (whose comments are cited below with:@: "@var{sc-cite}")}@*
+@code{>>>>> had this to say in article @var{message-id}}@*
+@code{>>>>> in newsgroups @var{newsgroups}}@*
+@code{>>>>> concerning the subject of @var{subject}}@*
+@code{>>>>> see @var{references} for more details}
+@end table
+
+@node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers
+@comment node-name, next, previous, up
+@cindex electric references
+@section Electric References
+@ifinfo
+
+@end ifinfo
+By default, when Supercite cites the original message for the first
+time, it just goes ahead and inserts the reference header indexed by
+@code{sc-preferred-header-style}. However, you may want to select
+different reference headers based on the type of reply or forwarding you
+are doing. You may also want to preview the reference header before
+deciding whether to insert it into the reply buffer or not. Supercite
+provides an optional @dfn{electric reference} mode which you can drop
+into to give you this functionality.
+
+@vindex sc-electric-references-p
+@vindex electric-references-p (sc-)
+If the variable @code{sc-electric-references-p} is non-@code{nil},
+Supercite will bring up an electric reference mode buffer and place you
+into a recursive edit. The electric reference buffer is read-only, so
+you cannot directly modify the reference text until you exit electric
+references and insert the text into the reply buffer. But you can cycle
+through all the reference header rewrite functions in your
+@code{sc-rewrite-header-list}.
+
+You can also set a new preferred header style, jump to any header, or
+jump to the preferred header. The header will be shown in the electric
+reference buffer and the header index and function name will appear in
+the echo area.
+
+The following commands are available while in electric reference mode
+(shown here with their default key bindings):
+
+@table @asis
+@item @code{sc-eref-next} (@kbd{n})
+@findex sc-eref-next
+@findex eref-next (sc-)
+@kindex n
+@vindex sc-electric-circular-p
+@vindex electric-circular-p (sc-)
+Displays the next reference header in the electric reference buffer. If
+the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking
+@code{sc-eref-next} while viewing the last reference header in the list
+will wrap around to the first header.@refill
+
+@item @code{sc-eref-prev} (@kbd{p})
+@findex sc-eref-prev
+@findex eref-prev (sc-)
+@kindex p
+Displays the previous reference header in the electric reference buffer.
+If the variable @code{sc-electric-circular-p} is non-@code{nil},
+invoking @code{sc-eref-prev} will wrap around to the last header.@refill
+
+@item @code{sc-eref-goto} (@kbd{g})
+@findex sc-eref-goto
+@findex eref-goto (sc-)
+@kindex g
+Goes to a specified reference header. The index (into the
+@code{sc-rewrite-header-list}) can be specified as a numeric argument to
+the command. Otherwise, Supercite will query you for the index in the
+minibuffer.@refill
+
+@item @code{sc-eref-jump} (@kbd{j})
+@findex sc-eref-jump
+@findex eref-jump (sc-)
+@kindex j
+Display the preferred reference header, i.e., the one indexed by the current
+value of @code{sc-preferred-header-style}.
+
+@item @code{sc-eref-setn} (@kbd{s})
+@findex sc-eref-setn
+@findex eref-setn (sc-)
+@kindex s
+Set the preferred reference header (i.e.,
+@code{sc-preferred-header-style}) to the currently displayed header.@refill
+
+@item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c})
+@kindex RET
+@kindex C-j
+@kindex q
+@findex sc-eref-exit
+@findex eref-exit (sc-)
+Exit from electric reference mode and insert the current header into the
+reply buffer.@refill
+
+@item @code{sc-eref-abort} (@kbd{q}, @kbd{x})
+@findex sc-eref-abort
+@findex eref-abort (sc-)
+@kindex x
+Exit from electric reference mode without inserting the current header.
+@end table
+
+@vindex sc-electric-mode-hook
+@vindex electric-mode-hook (sc-)
+@noindent
+Supercite will execute the hook @code{sc-electric-mode-hook} before
+entering electric reference mode.
+
+@node Getting Connected, Emacs 19 MUAs, Recognizing Citations, Top
+@comment node-name, next, previous, up
+@cindex citation interface specification
+@chapter Getting Connected
+@ifinfo
+
+@end ifinfo
+Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the
+original message into the reply buffer. In reality, the citation of the
+original message is performed via a call through a configurable hook
+variable. The name of this variable has been agreed to in advance as
+part of the @dfn{citation interface specification}. By default this
+hook variable has a @code{nil} value, which the MUA recognizes to mean,
+``use your default citation function''. When you add Supercite's
+citation function to the hook, thereby giving the variable a
+non-@code{nil} value, it tells the MUA to run the hook via
+@code{run-hooks} instead of using the default citation.@refill
+
+@ifinfo
+@menu
+* Emacs 19 MUAs::
+* Emacs 18 MUAs::
+* MH-E with any Emacsen::
+* VM with any Emacsen::
+* GNEWS with any Emacsen::
+* Overloading for Non-conforming MUAs::
+@end menu
+@end ifinfo
+
+Early in Supercite's development, the Supercite author, a few MUA
+authors, and some early Supercite users got together and agreed upon a
+standard interface between MUAs and citation packages (of which
+Supercite is currently the only known add-on @t{:-)}. With the recent
+release of the Free Software Foundation's GNU Emacs 19, the interface
+has undergone some modification and it is possible that not all MUAs
+support the new interface yet. Some support only the old interface and
+some do not support the interface at all. Still, it is possible for all
+known MUAs to use Supercite, and the following sections will outline the
+procedures you need to follow.
+
+To learn exactly how to connect Supercite to the software systems you
+are using, read the appropriate following sections. For details on the
+interface specifications, or if you are writing or maintaining an MUA,
+@pxref{Hints to MUA Authors}.
+
+@cindex autoload
+@cindex .emacs file
+@findex sc-cite-original
+@findex cite-original (sc-)
+@findex sc-submit-bug-report
+@findex submit-bug-report (sc-)
+The first thing that everyone should do, regardless of the MUA you are
+using is to set up Emacs so it will load Supercite at the appropriate
+time. You can either dump Supercite into your Emacs binary (ask your
+local Emacs guru how to do this if you don't know), or you can set up an
+@dfn{autoload} for Supercite. To do the latter, put the following in
+your @file{.emacs} file:
+
+@example
+(autoload 'sc-cite-original "supercite" "Supercite 3.1" t)
+(autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" t)
+@end example
+
+@cindex point
+@cindex mark
+The function @code{sc-cite-original} is the top-level Supercite function
+designed to be run from the citation hook. It expects
+@samp{point} and @samp{mark} to be set around the region to cite, and it
+expects the original article's mail headers to be present within this
+region. Note that Supercite @emph{never} touches any text outside this
+region. Note further that for Emacs 19, the region need not be active
+for @code{sc-cite-original} to do its job.
+@xref{Hints to MUA Authors}.@refill
+
+The other step in the getting connected process is to make sure your
+MUA calls @code{sc-cite-original} at the right time. As mentioned
+above, some MUAs handle this differently. Read the sections that follow
+pertaining to the MUAs you are using.
+
+@vindex sc-load-hook
+@vindex load-hook (sc-)
+@vindex sc-pre-hook
+@vindex pre-hook (sc-)
+One final note. After Supercite is loaded into your Emacs session, it
+runs the hook @code{sc-load-hook}. You can put any customizations into
+this hook since it is only run once. This will not work, however, if
+your Emacs maintainer has put Supercite into your dumped Emacs' image.
+In that case, you can use the @code{sc-pre-hook} variable, but this will
+get executed every time @code{sc-cite-original} is called. @xref{Reply
+Buffer Initialization}.@refill
+
+@node Emacs 19 MUAs, Emacs 18 MUAs, Getting Connected, Getting Connected
+@comment node-name, next, previous, up
+@vindex mail-citation-hook
+@cindex .emacs file
+@section GNUS, RMAIL, or RNEWS with any Emacs 19
+@ifinfo
+
+@end ifinfo
+These MUAs, distributed with Emacs and with Lucid Emacs, use Emacs's
+built-in yanking facility, which provides the citing hook variable
+@code{mail-citation-hook}. By default, this hook's value is @code{nil},
+but by adding the following to your @file{.emacs} file, you can tell
+these MUAs to use Supercite to perform the citing of the original
+message:
+
+@example
+(add-hook 'mail-citation-hook 'sc-cite-original)
+@end example
+
+GNUS users may also want to add the following bit of lisp as well. This
+prevents GNUS from inserting its default attribution header. Otherwise,
+both GNUS and Supercite will insert an attribution header:
+
+@example
+(setq news-reply-header-hook nil)
+@end example
+
+@node Emacs 18 MUAs, MH-E with any Emacsen, Emacs 19 MUAs, Getting Connected
+@comment node-name, next, previous, up
+@vindex mail-citation-hook
+@cindex .emacs file
+@cindex overloading
+@cindex sendmail.el file
+@section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4
+@ifinfo
+
+@end ifinfo
+These MUAs use Emacs' built-in yanking and citing routines, contained in
+the @file{sendmail.el} file. @file{sendmail.el} for Emacs 18, and its
+derivative Epoch 4, do not know anything about the citation interface
+required by Supercite. To connect Supercite to any of these MUAs under
+Emacs 18 or Epoch 4, you should first
+@pxref{Overloading for Non-conforming MUAs}. Then follow the directions
+for using these MUAs under Emacs 19.
+@xref{Emacs 19 MUAs}.@refill
+
+@cindex add-hook substitute
+@cindex setq as a substitute for add-hook
+@findex setq
+@findex add-hook
+@cindex sc-unsupp.el file
+Note that those instructions will tell you to use the function
+@code{add-hook}. This function is new with Emacs 19 and you will not
+have it by default if you are running Emacs 18 or Epoch 4. You can
+either substitute the appropriate call to @code{setq}, or you can use
+the @code{add-hook} function that is provided in the @file{sc-unsupp.el}
+file of unsupported Supercite hacks and ideas. Or you can upgrade to
+some Emacs 19 variant! @t{:-)}@refill
+
+To use @code{setq} instead of @code{add-hook}, you would, for example,
+change this:
+
+@example
+(add-hook 'mail-citation-hook 'sc-cite-original)
+@end example
+
+to:
+
+@example
+(setq mail-citation-hook 'sc-cite-original)
+@end example
+
+Note the lack of of a single quote on the first argument to @code{setq}.
+
+@node MH-E with any Emacsen, VM with any Emacsen, Emacs 18 MUAs, Getting Connected
+@comment node-name, next, previous, up
+@cindex .emacs file
+@vindex mh-yank-hooks
+@findex add-hook
+@cindex mail-citation-hook
+@section MH-E with any Emacsen
+@ifinfo
+
+@end ifinfo
+MH-E 4.x conforms to the @code{mail-citation-hook} interface supported
+by other MUAs. At the time of this writing, MH-E 4.0 has not been
+released, but if you have it, put this in your @file{.emacs} file to
+connect Supercite and MH-E 4.x:
+
+@example
+(add-hook 'mail-citation-hook 'sc-cite-original)
+@end example
+
+Note that if you are using Emacs 18 or Epoch 4, you will not have the
+@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to
+proceed without @code{add-hook}.
+
+MH-E version 3.x uses a slightly different interface than other MUAs.
+MH-E provides a hook variable @code{mh-yank-hooks}, but it doesn't act
+like a hook, and doing an @code{add-hook} will not work.
+
+To connect Supercite to MH-E 3.x, you should instead add the following
+to your @code{.emacs} file:
+
+@example
+(add-hook 'mh-yank-hooks 'sc-cite-original)
+@end example
+
+@vindex mh-yank-from-start-of-msg
+You also need to make sure that MH-E includes all the original mail
+headers in the yanked message. The variable that controls this is
+@code{mh-yank-from-start-of-msg}. By default, this variable has the
+value @code{t}, which tells MH-E to include all the mail headers when
+yanking the original message. Before you switched to using Supercite,
+you may have set this variable to other values so as not to include the
+mail headers in the yanked message. Since Supercite requires these
+headers (and cleans them out for you), you need to make sure the value
+is @code{t}. This lisp, in your @file{.emacs} file will do the trick:
+
+@example
+(setq mh-yank-from-start-of-msg t)
+@end example
+
+Note that versions of MH-E before 3.7 did not provide the
+@code{mh-yank-hooks} variable. Your only option is to upgrade to MH-E
+version 3.7 or later.
+
+@node VM with any Emacsen, GNEWS with any Emacsen, MH-E with any Emacsen, Getting Connected
+@comment node-name, next, previous, up
+@cindex .emacs file
+@vindex mail-citation-hook
+@vindex mail-yank-hooks
+@section VM with any Emacsen
+@ifinfo
+
+@end ifinfo
+Since release 4.40, VM has supported the citation interface required by
+Supercite. But since the interface has changed recently the details of
+getting connected differ with the version of VM you are using.
+
+If you are running any release of VM after 4.40, you can add the
+following to your @file{.emacs} to connect Supercite with VM:
+
+@example
+(add-hook 'mail-yank-hooks 'sc-cite-original)
+@end example
+
+Note that if you are using Emacs 18 or Epoch 4, you will not have the
+@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to
+proceed without @code{add-hook}.
+
+Since version 5.34, VM has supported the newer @code{mail-citation-hook}
+interface, but @code{mail-yank-hooks} is still being supported for
+backward compatibility. If you are running a newer version of VM and
+you want to maintain consistency with other MUAs, use this bit of code
+instead:
+
+@example
+(add-hook 'mail-citation-hook 'sc-cite-original)
+@end example
+
+@node GNEWS with any Emacsen, Overloading for Non-conforming MUAs, VM with any Emacsen, Getting Connected
+@comment node-name, next, previous, up@cindex .emacs file
+@vindex news-reply-mode-hook
+@findex sc-perform-overloads
+@findex perform-overloads (sc-)
+@vindex gnews-ready-hook
+@section GNEWS with any Emacsen
+@ifinfo
+
+@end ifinfo
+As far as I know, no version of GNEWS supports the citation interface
+required by Supercite. To connect Supercite with GNEWS, please first
+@pxref{Overloading for Non-conforming MUAs}.
+
+After you have followed the directions in that section. You should add
+the following lisp code to your @file{.emacs} file:
+
+@example
+(add-hook 'mail-citation-hook 'sc-cite-original)
+@end example
+
+Note that if you are using Emacs 18 or Epoch 4, you will not have the
+@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to
+proceed without @code{add-hook}.
+
+@node Overloading for Non-conforming MUAs, Replying and Yanking, GNEWS with any Emacsen, Getting Connected
+@comment node-name, next, previous, up
+@cindex overloading
+@cindex sc-oloads.el
+@vindex mail-citation-hook
+@findex sc-perform-overloads
+@cindex .emacs file
+@section Overloading for Non-conforming MUAs
+@ifinfo
+
+@end ifinfo
+As mentioned elsewhere, some MUAs do not provide the necessary hooks to
+connect with Supercite. Supercite version 3.1 provides an unsupported
+mechanism, called @dfn{overloading} which redefines certain key
+functions in the MUA, so that it will call the @code{mail-citation-hook}
+variable instead of the MUA's default hard-coded citing routines. Since
+most newer versions of the known MUAs support the
+@code{mail-citation-hook} variable, it is recommended that you upgrade
+if at all possible. But if you can't upgrade, at least you're not out
+of luck! Once you set up overloading properly, you should follow the
+directions for connecting Supercite to the Emacs 19 MUAs.
+@xref{Emacs 19 MUAs}.@refill
+
+@cindex Hyperbole
+@vindex hyperb:version
+Users of Bob Weiner's Hyperbole package take note. Hyperbole provides
+the necessary overloads (and a whole lot more!) and you can potentially
+clobber it if you were to load Supercite's overloading after
+Hyperbole's. For this reason, Supercite will @emph{not} perform any
+overloading if it finds the variable @code{hyperb:version} is
+@code{boundp} (i.e. it exists because Hyperbole has been loaded into
+your Emacs session). If this is the case, Supercite will display a
+warning message in the minibuffer. You should consult the Hyperbole
+manual for further details.
+
+Overloading involves the re-definition of the citing function with the
+new, @code{mail-citation-hook} savvy version. The function in
+@file{sc-oloads.el} that does this is @code{sc-perform-overloads}. This
+function is smart enough to only overload the MUA functions when it is
+absolutely necessary, based on the version numbers it can figure out.
+Also, @code{sc-perform-overloads} will only install the new functions
+once. It is also smart enough to do nothing if the MUA is not yet
+loaded.@refill
+
+The tricky part is finding the right time and place to perform the
+overloading. It must be done after the MUA has been loaded into your
+Emacs session, but before the first time you try to yank in a message.
+Fortunately, this has been figured out for you.
+
+If you must overload, you should put the following lisp code in your
+@file{.emacs} file, to make sure the @file{sc-oloads.el} file gets
+loaded at the right time:
+
+@example
+(autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t)
+@end example
+
+Then you must make sure that the function @code{sc-perform-overloads}
+gets run at the right time. For GNUS, put this in your @file{.emacs}
+file:
+
+@example
+(setq news-reply-mode-hook 'sc-perform-overloads)
+(setq mail-setup-hook 'sc-perform-overloads)
+@end example
+
+If you are using RNEWS, put this in your @file{.emacs} file:
+
+@vindex news-reply-mode-hook
+@example
+(setq news-reply-mode-hook 'sc-perform-overloads)
+@end example
+
+If you are using RMAIL or PCMAIL, put this in your @file{.emacs} file:
+
+@example
+(setq mail-setup-hook 'sc-perform-overloads)
+@end example
+
+If you are using GNEWS, put this in your @file{.emacs} file:
+
+@example
+(setq news-reply-mode-hook 'sc-perform-overloads)
+(setq gnews-ready-hook 'sc-perform-overloads)
+@end example
+
+Now go back and follow the directions for getting the Emacs 19 MUAs
+connected to Supercite. Be sure to @pxref{Emacs 18 MUAs} on substitutes
+for Emacs 19's @code{add-hook} function.@refill
+
+@node Replying and Yanking, Reply Buffer Initialization, Overloading for Non-conforming MUAs, Top
+@comment node-name, next, previous, up
+@chapter Replying and Yanking
+@ifinfo
+
+This chapter explains what happens when you reply and yank an original
+message from an MUA.
+
+@menu
+* Reply Buffer Initialization::
+* Filling Cited Text::
+@end menu
+@end ifinfo
+@node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking
+@comment node-name, next, previous, up
+@findex sc-cite-original
+@findex cite-original (sc-)
+@comment
+@section Reply Buffer Initialization
+@ifinfo
+
+@end ifinfo
+Executing @code{sc-cite-original} performs the following steps as it
+initializes the reply buffer:
+
+@enumerate
+@item
+@vindex sc-pre-hook
+@vindex pre-hook (sc-)
+@emph{Runs @code{sc-pre-hook}.}
+This hook variable is run before @code{sc-cite-original} does any other
+work. You could conceivably use this hook to set certain Supercite
+variables based on the reply buffer's mode or name (i.e., to do
+something different based on whether you are replying or following up to
+an article).@refill
+
+@item
+@emph{Inserts Supercite's keymap.}
+@vindex sc-mode-map-prefix
+@vindex mode-map-prefix (sc-)
+@kindex C-c C-p
+@cindex keymap prefix
+Supercite provides a number of commands for performing post-yank
+modifications to the reply buffer. These commands are installed on
+Supercite's top-level keymap. Since Supercite has to interface with a
+wide variety of MUAs, it does not install all of its commands directly
+into the reply buffer's keymap. Instead, it puts its commands on a
+keymap prefix, then installs this prefix onto the buffer's keymap. What
+this means is that you typically have to type more characters to invoke
+a Supercite command, but Supercite's keybindings can be made much more
+consistent across MUAs.
+
+You can control what key Supercite uses as its keymap prefix by changing
+the variable @code{sc-mode-map-prefix}. By default, this variable is
+set to @code{C-c C-p}; a finger twister perhaps, but unfortunately the
+best default due to the scarcity of available keybindings in many MUAs.
+
+@item
+@emph{Turns on Supercite minor mode.}
+@cindex modeline
+The modeline of the reply buffer should indicate that Supercite is
+active in that buffer by displaying the string @samp{SC}.
+
+@item
+@emph{Sets the ``Undo Boundary''.}
+@cindex undo boundary
+Supercite sets an undo boundary before it begins to modify the original
+yanked text. This allows you to easily undo Supercite's changes to
+affect alternative citing styles.
+
+@item
+@emph{Processes the mail headers.}
+@vindex sc-confirm-always-p
+@vindex confirm-always-p (sc-)
+@vindex sc-mail-warn-if-non-rfc822-p
+@vindex mail-warn-if-non-rfc822-p (sc-)
+All previously retrieved info key-value pairs are deleted from the info
+alist, then the mail headers in the body of the yanked message are
+scanned. Info key-value pairs are created for each header found. Also,
+such useful information as the author's name and email address are
+extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is
+non-@code{nil}, then Supercite will warn you if it finds a mail header
+that does not conform to RFC822. This is rare and indicates a problem
+either with your MUA or the original author's MUA, or some MTA (mail
+transport agent) along the way.
+
+@vindex sc-nuke-mail-headers
+@vindex sc-nuke-mail-header-list
+@vindex nuke-mail-headers (sc-)
+@vindex nuke-mail-header-list (sc-)
+Once the info keys have been extracted from the mail headers, the
+headers are nuked from the reply buffer. You can control exactly which
+headers are removed or kept, but by default, all headers are removed.
+
+There are two variables which control mail header nuking. The variable
+@code{sc-nuke-mail-headers} controls the overall behavior of the header
+nuking routines. By setting this variable to @code{'all}, you
+automatically nuke all mail headers. Likewise, setting this variable to
+@code{'none} inhibits nuking of any mail headers. In between these
+extremes, you can tell Supercite to nuke only a specified list of mail
+headers by setting this variable to @code{'specified}, or to keep only a
+specified list of headers by setting it to @code{'keep}.
+
+If @code{sc-nuke-mail-headers} is set to @code{'specified} or
+@code{'keep}, then the variable @code{sc-nuke-mail-header-list} is
+consulted for the list of headers to nuke or keep. This variable
+contains a list of regular expressions. If the mail header line matches
+a regular expression in this list, the header will be nuked or kept.
+The line is matched against the regexp using @code{looking-at} rooted at
+the beginning of the line.
+
+@vindex sc-blank-lines-after-headers
+@vindex blank-lines-after-headers (sc-)
+If the variable @code{sc-blank-lines-after-headers} is non-@code{nil},
+it contains the number of blank lines remaining in the buffer after mail
+headers are nuked. By default, only one blank line is left in the buffer.
+
+@item
+@emph{Selects the attribution and citation strings.}
+Once the mail headers have been processed, Supercite selects a
+attribution string and a citation string which it will use to cite the
+original message. @xref{Selecting an Attribution}, for details.
+
+@item
+@emph{Cites the message body.}
+@vindex sc-cite-region-limit
+@vindex cite-region-limit (sc-)b
+After the selection of the attribution and citation strings, Supercite
+cites the original message by inserting the citation string prefix in
+front of every uncited line. You may not want Supercite to
+automatically cite very long messages however. For example, some email
+could contain a smaller header section followed by a huge uuencoded
+message. It wouldn't make sense to cite the uuencoded message part when
+responding to the original author's short preface. For this reason,
+Supercite provides a variable which limits the automatic citation of
+long messages to a certain maximum number of lines. The variable is
+called @code{sc-cite-region-limit}. If this variable contains an
+integer, messages with more lines that this will not be cited at all,
+and a warning message will be displayed. Supercite has performed
+everything necessary, though, for you to manually cite only the small
+portion of the original message that you want to use.
+
+If @code{sc-cite-region-limit} contains a non-@code{nil} value, the
+original message will always be cited, regardless of its size. If the
+variable contains the value @code{nil}, the region will never be cited
+automatically. Use this if you always want to be able to edit and cite
+the message manually.
+
+@vindex sc-cite-blank-lines-p
+@vindex cite-blank-lines-p (sc-)
+The variable @code{sc-cite-blank-lines-p} controls whether blank lines
+in the original message should be cited or not. If this variable is
+non-@code{nil}, blank lines will be cited just like non-blank lines.
+Otherwise, blank lines will be treated as paragraph separators.
+
+Citing of the original message is highly configurable. Supercite's
+default setup does a pretty good job of citing many common forms of
+previously cited messages. But there are as many citation styles out
+there as people on the net, or just about! It would be impossible for
+Supercite to anticipate every style in existence, and you probably
+wouldn't encounter them all anyway. But you can configure Supercite to
+recognize those styles you see often.
+@xref{Configuring the Citation Engine}, for details.@refill
+
+@item
+@emph{Runs @code{sc-post-hook}.}
+@vindex sc-post-hook
+@vindex post-hook (sc-)
+This variable is very similar to @code{sc-pre-hook}, except that it runs
+after @code{sc-cite-original} is finished. This hook is provided mostly
+for completeness and backward compatibility. Perhaps it could be used to
+reset certain variables set in @code{sc-pre-hook}.@refill
+@end enumerate
+
+@node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking
+@comment node-name, next, previous, up
+@cindex filling paragraphs
+@vindex sc-auto-fill-region-p
+@vindex auto-fill-region-p (sc-)
+@cindex filladapt
+@cindex gin-mode
+@findex sc-setup-filladapt
+@findex setup-filladapt (sc-)
+@vindex sc-load-hook
+@vindex load-hook (sc-)
+@section Filling Cited Text
+@ifinfo
+
+@end ifinfo
+Supercite will automatically fill newly cited text from the original
+message unless the variable @code{sc-auto-fill-region-p} has a
+@code{nil} value. Supercite will also re-fill paragraphs when you
+manually cite or re-cite text.
+
+However, during normal editing, Supercite itself cannot be used to fill
+paragraphs. This is a change from version 2. There are other add-on
+lisp packages which do filling much better than Supercite ever did. The
+two best known are @dfn{filladapt} and @dfn{gin-mode}. Both work well
+with Supercite and both are available at the normal Emacs Lisp archive
+sites. @dfn{gin-mode} works pretty well out of the box, but if you use
+@dfn{filladapt}, you may want to run the function
+@code{sc-setup-filladapt} from your @code{sc-load-hook}. This simply
+makes @dfn{filladapt} a little more Supercite savvy than its default
+setup.
+
+@vindex sc-fixup-whitespace-p
+@vindex fixup-whitespace-p (sc-)
+Also, Supercite will collapse leading whitespace between the citation
+string and the text on a line when the variable
+@code{sc-fixup-whitespace-p} is non-@code{nil}. The default value for
+this variable is @code{nil}.@refill
+
+@vindex fill-prefix
+Its important to understand that Supercite's automatic filling (during
+the initial citation of the reply) is very fragile. That is because
+figuring out the @code{fill-prefix} for a particular paragraph is a
+really hard thing to do automatically. This is especially the case when
+the original message contains code or some other text where leading
+whitespace is important to preserve. For this reason, many Supercite
+users typically run with @code{sc-auto-fill-region-p} (and possibly also
+@code{sc-fixup-whitespace-p}) set to @code{nil}. They then manually
+fill each cited paragraph in the reply buffer.
+
+I usually run with both these variables containing their default values.
+When Supercite's automatic filling breaks on a particular message, I
+will use Emacs' undo feature to undo back before the citation was
+applied to the original message. Then I'll toggle the variables and
+manually cite those paragraphs that I don't want to fill or collapse
+whitespace on. @xref{Variable Toggling Shortcuts}.@refill
+
+@kindex C-c C-p C-p
+If you find that Supercite's automatic filling is just too fragile for
+your tastes, you might consider one of these alternate approaches.
+Also, to make life easier, a shortcut function to toggle the state of
+both of these variables is provided on the key binding
+@kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix};
+@pxref{Post-yank Formatting Commands}).@refill
+
+You will noticed that the minor mode string will
+show the state of these variables as qualifier characters. When both
+variables are @code{nil}, the Supercite minor mode string will display
+@samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the
+string will display @samp{SC:f}, and when just
+@code{sc-fixup-whitespace-p} is non-@code{nil}, the string will display
+@samp{SC:w}. When both variables are non-@code{nil}, the string will
+display @samp{SC:fw}. Note that the qualifiers chosen are mnemonics for
+the default bindings of the toggling function for each respective
+variable.
+@xref{Variable Toggling Shortcuts}.@refill
+
+Why are these variables not set to @code{nil} by default? It is because
+many users won't manually fill paragraphs that are Supercited, and there
+have been widespread complaints on the net about mail and news messages
+containing lines greater than about 72 characters. So the default is to
+fill cited text.
+
+@node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top
+@comment node-name, next, previous, up
+@cindex attribution list
+@vindex sc-preferred-attribution-list
+@vindex preferred-attribution-list (sc-)
+@comment
+@chapter Selecting an Attribution
+@ifinfo
+
+@end ifinfo
+As you know, the attribution string is the part of the author's name
+that will be used to composed a non-nested citation string. Supercite
+scans the various mail headers present in the original article and uses
+a number of heuristics to extract strings which it puts into the
+@dfn{attribution association list} or @dfn{attribution alist}. This is
+analogous, but different than, the info alist previously mentioned. Each
+element in the attribution alist is a key-value pair containing such
+information as the author's first name, middle names, and last name, the
+author's initials, and the author's email terminus.
+
+@ifinfo
+@menu
+* Attribution Preferences::
+* Anonymous Attributions::
+* Author Names::
+@end menu
+@end ifinfo
+
+@node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution
+@comment node-name, next, previous, up
+@section Attribution Preferences
+@ifinfo
+
+@end ifinfo
+When you cite an original message, you can tell Supercite which part of
+the author's name you would prefer it to use as the attribution. The
+variable @code{sc-preferred-attribution-list} controls this; it contains
+keys which are matched against the attribution alist in the given order.
+The first value of a key that produces a non-@code{nil}, non-empty
+string match is used as the attribution string, and if no keys match, a
+secondary mechanism is used to generate the attribution.
+@xref{Anonymous Attributions}.
+
+The following preferences are always available in the attribution alist
+(barring error):
+
+@table @code
+@item "emailname"
+the author's email terminus.
+
+@item "initials"
+the author's initials.
+
+@item "firstname"
+the author's first name.
+
+@item "lastname"
+the author's last name.
+
+@item "middlename-1"
+the author's first middle name.
+
+@item "sc-lastchoice"
+the last attribution string you have selected. This is useful when you
+recite paragraphs in the reply.@refill
+
+@item "sc-consult"
+@vindex sc-attrib-selection-list
+@vindex attrib-selection-list (sc-)
+consults the customizable list @code{sc-attrib-selection-list} which can
+be used to select special attributions based on the value of any info
+key. See below for details.
+
+@item "x-attribution"
+the original author's suggestion for attribution string choice. See below
+for details.@refill
+@end table
+
+Middle name indexes can be any positive integer greater than zero,
+though it is unlikely that many authors will have more than one middle
+name, if that many.
+
+At this point, let me digress into a discussion of etiquette. It is my
+belief that while the style of the citations is a reflection of the
+personal tastes of the replier (i.e., you), the attribution selection is
+ultimately the personal choice of the original author. In a sense it is
+his or her ``net nickname'', and therefore the author should have some
+say in the selection of attribution string. Imagine how you would feel
+if someone gave you a nickname that you didn't like?
+
+For this reason, Supercite recognizes a special mail header,
+@samp{X-Attribution:}, which if present, tells Supercite the attribution
+string preferred by the original author. It is the value of this header
+that is associated with the @code{"x-attribution"} key in the
+attribution alist. Currently, you can override the preference of this
+key by changing @code{sc-preferred-attribution-list}, but that isn't
+polite, and in the future Supercite may hard-code this. For now, it is
+suggested that if you change the order of the keys in this list, that
+@code{"x-attribution"} always be first, or possible second behind only
+@code{"sc-lastchoice"}. This latter is the default.
+
+@vindex sc-attrib-selection-list
+@vindex attrib-selection-list (sc-)
+The value @code{"sc-consult"} in @code{sc-preferred-attribution-list}
+has a special meaning during attribution selection. When Supercite
+encounters this preference, it begins processing a customizable list of
+attributions, contained in the variable @code{sc-attrib-selection-list}.
+Each element in this list contains lists of the following form:
+
+@example
+@group
+(@var{infokey} ((@var{regexp} @. @var{attribution})
+ (@var{regexp} @. @var{attribution})
+ (@dots{})))
+@end group
+@end example
+
+@noindent
+@findex sc-mail-field
+@findex mail-field (sc-)
+where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp}
+is a regular expression to match against the @var{infokey}'s value. If
+@var{regexp} matches the @var{infokey}'s value, the @var{attribution} is
+used as the attribution string. Actually, @var{attribution} can be a
+string or a list; if it is a list, it is @code{eval}uated and the return
+value (which must be a string), is used as the attribution.
+
+This can be very useful for when you are replying to net acquaintances
+who do not use the @samp{X-Attribution:@:} mail header. You may know
+what nickname they would prefer to use, and you can set up this list to
+match against a specific mail field, e.g., @samp{From:@:}, allowing you
+to cite your friend's message with the appropriate attribution.
+
+@node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution
+@comment node-name, next, previous, up
+@vindex sc-default-author-name
+@vindex default-author-name (sc-)
+@vindex sc-default-attribution
+@vindex default-attribution (sc-)
+@comment
+@section Anonymous Attributions
+@ifinfo
+
+@end ifinfo
+When the author's name cannot be found in the @samp{From:@:} mail
+header, a fallback author name and attribution string must be supplied.
+The fallback author name is contained in the variable
+@code{sc-default-author-name} and the fallback attribution string is
+contained in the variable @code{sc-default-attribution}. Default values
+for these variables are @code{"Anonymous"} and @code{"Anon"},
+respectively. Note that in most circumstances, getting the default
+author name or attribution is a sign that something is set up
+incorrectly.
+
+@vindex sc-use-only-preference-p
+@vindex use-only-preference-p (sc-)
+Also, if the preferred attribution, which you specified in your
+@code{sc-preferred-attribution-alist} variable cannot be found, a
+secondary method can be employed to find a valid attribution string. The
+variable @code{sc-use-only-preference-p} controls what happens in this
+case. If the variable's value is non-@code{nil}, then
+@code{sc-default-author-name} and @code{sc-default-attribution} are
+used, otherwise, the following steps are taken to find a valid
+attribution string, and the first step to return a non-@code{nil},
+non-empty string becomes the attribution:@refill
+
+@enumerate
+@item
+Use the last selected attribution, if there is one.
+
+@item
+Use the value of the @code{"x-attribution"} key.
+
+@item
+Use the author's first name.
+
+@item
+Use the author's last name.
+
+@item
+Use the author's initials.
+
+@item
+Find the first non-@code{nil}, non-empty attribution string in the
+attribution alist.
+
+@item
+@code{sc-default-attribution} is used.
+@end enumerate
+
+@vindex sc-confirm-always-p
+@vindex confirm-always-p (sc-)
+Once the attribution string has been automatically selected, a number of
+things can happen. If the variable @code{sc-confirm-always-p} is
+non-@code{nil}, you are queried for confirmation of the chosen
+attribution string. The possible values for completion are those strings
+in the attribution alist, however you are not limited to these choices.
+You can type any arbitrary string at the confirmation prompt. The string
+you enter becomes the value associated with the @code{"sc-lastchoice"}
+key in the attribution alist.
+
+@vindex sc-downcase-p
+@vindex downcase-p (sc-)
+Once an attribution string has been selected, Supercite will force the
+string to lower case if the variable @code{sc-downcase-p} is
+non-@code{nil}.
+
+@vindex sc-attribs-preselect-hook
+@vindex attribs-preselect-hook (sc-)
+@vindex sc-attribs-postselect-hook
+@vindex attribs-postselect-hook (sc-)
+
+Two hook variables provide even greater control of the attribution
+selection process. The hook @code{sc-attribs-preselect-hook} is run
+before any attribution is selected. Likewise, the hook
+@code{sc-attribs-postselect-hook} is run after the attribution is
+selected (and the corresponding citation string is built), but before
+these values are committed for use by Supercite. During the
+post-selection hook, the local variables @code{attribution} and
+@code{citation} are bound to the appropriate strings. By changing these
+variables in your hook functions, you change the attribution and
+citation strings used by Supercite. One possible use of this would be
+to override any automatically derived attribution string when it is only
+one character long; e.g. you prefer to use @code{"initials"} but the
+author only has one name.@refill
+
+@node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution
+@comment node-name, next, previous, up
+@cindex author names
+@section Author Names
+@ifinfo
+
+@end ifinfo
+Supercite employs a number of heuristics to decipher the author's name
+based on value of the @samp{From:@:} mail field of the original message.
+Supercite can recognize almost all of the common @samp{From:@:} field
+formats in use. If you encounter a @samp{From:@:} field that Supercite
+cannot parse, please report this bug.
+@xref{The Supercite Mailing List}.@refill
+
+@vindex sc-titlecue-regexp
+@vindex titlecue-regexp (sc-)
+There are a number of Supercite variables that control how author names
+are extracted from the @samp{From:@:} header. Some headers may contain a
+descriptive title as in:
+
+@example
+From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker)
+@end example
+
+Supercite knows which part of the @samp{From:@:} header is email address
+and which part is author name, but in this case the string @code{"Decent
+Hacker"} is not part of the author's name. You can tell Supercite to
+ignore the title, while still recognizing hyphenated names through the
+use of a regular expression in the variable @code{sc-titlecue-regexp}.
+This variable has the default value of @code{"\\\\s +-+\\\\s +"}. Any
+text after this regexp is encountered is ignored as noise.
+
+@vindex sc-name-filter-alist
+@vindex name-filter-alist (sc-)
+Some @samp{From:@:} headers may contain extra titles in the name fields
+not separated by a title cue, but which are nonetheless not part of the
+author's name proper. Examples include the titles ``Dr.'', ``Mr.'',
+``Ms.'', ``Jr.'', ``Sr.'', and ``III'' (e.g., Thurston Howe, the Third).
+Also, some companies prepend or append the name of the division,
+organization, or project on the author's name. All of these titles are
+noise which should be ignored. The variable @code{sc-name-filter-alist}
+is used for this purpose. As implied by its name, this variable is an
+association list, where each element is a cons cell of the form:
+
+@example
+(@var{regexp} @. @var{position})
+@end example
+
+@noindent
+where @var{regexp} is a regular expression that is matched (using
+@code{string-match}) against each element of the @samp{From:@:} field's
+author name. @var{position} is a position indicator, starting at zero.
+Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name,
+@code{sc-name-filter-alist} would have an entry such as:
+
+@example
+("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0)
+@end example
+
+@noindent
+which only removes them if they appear as the first word in the name.
+The position indicator is an integer, or one of the two special symbols
+@code{last} or @code{any}. @code{last} always matches against the last
+word in the name field, while @code{any} matches against every word in
+the name field.
+
+@node Configuring the Citation Engine, Using Regi, Author Names, Top
+@comment node-name, next, previous, up
+@cindex Regi
+@cindex frames (Regi)
+@cindex entries (Regi)
+@chapter Configuring the Citation Engine
+@ifinfo
+
+@end ifinfo
+At the heart of Supercite is a regular expression interpreting engine
+called @dfn{Regi}. Regi operates by interpreting a data structure
+called a Regi-frame (or just @dfn{frame}), which is a list of
+Regi-entries (or just @dfn{entry}). Each entry contains a predicate,
+typically a regular expression, which is matched against a line of text
+in the current buffer. If the predicate matches true, an associated
+expression is @code{eval}uated. In this way, an entire region of text
+can be transformed in an @emph{awk}-like manner. Regi is used
+throughout Supercite, from mail header information extraction, to header
+nuking, to citing text.
+
+@ifinfo
+@menu
+* Using Regi::
+* Frames You Can Customize::
+@end menu
+@end ifinfo
+
+While the details of Regi are discussed below (@pxref{Using Regi}), only
+those who wish to customize certain aspects of Supercite need concern
+themselves with it. It is important to understand though, that any
+conceivable citation style that can be described by a regular expression
+can be recognized by Supercite. This leads to some interesting
+applications. For example, if you regularly receive email from a
+co-worker that uses an uncommon citation style (say one that employs a
+@samp{|} or @samp{@}} character at the front of the line), it is
+possible for Supercite to recognize this and @emph{coerce} the citation
+to your preferred style, for consistency. In theory, it is possible for
+Supercite to recognize such things as uuencoded messages or C code and
+cite or fill those differently than normal text. None of this is
+currently part of Supercite, but contributions are welcome!
+
+@node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine
+@comment node-name, next, previous, up
+@findex regi-interpret
+@findex eval
+@findex looking-at
+@section Using Regi
+@ifinfo
+
+@end ifinfo
+Regi works by interpreting frames with the function
+@code{regi-interpret}. A frame is a list of arbitrary size where each
+element is a entry of the following form:
+
+@example
+(@var{pred} @var{func} [@var{negate-p} [@var{case-fold-search}]])
+@end example
+
+Regi starts with the first entry in a frame, evaluating the @var{pred}
+of that entry against the beginning of the line that @samp{point} is on.
+If the @var{pred} evaluates to true (or false if the optional
+@var{negate-p} is non-@code{nil}), then the @var{func} for that entry is
+@code{eval}uated. How processing continues is determined by the return
+value for @var{func}, and is described below. If @var{pred} was false
+the next entry in the frame is checked until all entries have been
+matched against the current line. If no entry matches, @samp{point} is
+moved forward one line and the frame is reset to the first entry.
+
+@var{pred} can be a string, a variable, a list or one of the following
+symbols: @code{t}, @code{begin}, @code{end}, or @code{every}. If
+@var{pred} is a string, or a variable or list that @code{eval}uates to a
+string, it is interpreted as a regular expression. This regexp is
+matched against the current line, from the beginning, using
+@code{looking-at}. This match folds case if the optional
+@var{case-fold-search} is non-@code{nil}. If @var{pred} is not a
+string, or does not @code{eval}uate to a string, it is interpreted as a
+binary value (@code{nil} or non-@code{nil}).@refill
+
+The four special symbol values for @var{pred} are recognized:
+
+@table @code
+@item t
+Always produces a true outcome.
+@item begin
+Always executed before the frame is interpreted. This can be used to
+initialize some global variables for example.
+@item end
+Always executed after frame interpreting is completed. This can be used
+to perform any necessary post-processing.
+@item every
+Executes whenever the frame is reset, usually after the entire frame has
+been matched against the current line.
+@end table
+
+Note that @var{negate-p} and @var{case-fold-search} are ignored if
+@var{pred} is one of these special symbols. Only the first occurrence of
+each symbol in a frame is used; any duplicates are ignored. Also
+note that for performance reasons, the entries associated with these
+symbols are removed from the frame during the main interpreting loop.
+
+Your @var{func} can return certain values which control continued Regi
+processing. By default, if your @var{func} returns @code{nil} (as it
+should be careful to do explicitly), Regi will reset the frame to the
+first entry, and advance @samp{point} to the beginning of the next line.
+If a list is returned from your function, it can contain any combination
+of the following elements:@refill
+
+@table @asis
+@item the symbol @code{continue}
+This tells Regi to continue processing entries after a match, instead of
+reseting the frame and moving @samp{point}. In this way, lines of text
+can have multiple matches, but you have to be careful to avoid entering
+infinite loops.
+
+@item the symbol @code{abort}
+This tells Regi to terminate frame processing. However, any @code{end}
+entry is still processed.
+
+@item the list @code{(frame . @var{newframe})}
+This tells Regi to substitute @var{newframe} as the frame it is
+interpreting. In other words, your @var{func} can modify the Regi frame
+on the fly. @var{newframe} can be a variable containing a frame, or it
+can be the frame in-lined.@refill
+
+@item the list @code{(step . @var{step})}
+Tells Regi to move @var{step} number of lines forward as it continues
+processing. By default, Regi moves forward one line. @var{step} can be
+zero or negative of course, but watch out for infinite loops.@refill
+@end table
+
+During execution of your @var{func}, the following variables will be
+temporarily bound to some useful information:@refill
+
+@table @code
+@item curline
+The current line in the buffer that Regi is @code{looking-at}, as a string.
+@item curframe
+The current frame being interpreted.
+@item curentry
+The current frame entry being interpreted.
+@end table
+
+@node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine
+@comment node-name, next, previous, up
+@vindex sc-nuke-mail-header
+@section Frames You Can Customize
+@ifinfo
+
+@end ifinfo
+As mentioned earlier, Supercite uses various frames to perform
+certain jobs such as mail header information extraction and mail header
+nuking. However, these frames are not available for you to customize,
+except through abstract interfaces such as @code{sc-nuke-mail-header},
+et al.
+
+@vindex sc-default-cite-frame
+However, the citation frames Supercite uses provide a lot of customizing
+power and are thus available to you to change to suit your needs. The
+workhorse of citation is the frame contained in the variable
+@code{sc-default-cite-frame}. This frame recognizes many situations,
+such as blank lines, which it interprets as paragraph separators. It
+also recognizes previously cited nested and non-nested citations in the
+original message. By default it will coerce non-nested citations into
+your preferred citation style, and it will add a level of citation to
+nested citations. It will also simply cite uncited lines in your
+preferred style.
+
+@cindex unciting
+@cindex reciting
+@vindex sc-default-uncite-frame
+@vindex sc-default-recite-frame
+In a similar vein, there are default frames for @dfn{unciting} and
+@dfn{reciting}, contained in the variables
+@code{sc-default-uncite-frame} and @code{sc-default-recite-frame}
+respectively.@refill
+
+As mentioned earlier (@pxref{Recognizing Citations}), citations are
+recognized through the values of the regular expressions
+@code{sc-citation-root-regexp}, et al. To recognize odd styles, you
+could modify these variables, or you could modify the default citing
+frame. Alternatively, you could set up association lists of frames for
+recognizing specific alternative forms.
+
+@vindex sc-cite-frame-alist
+@vindex sc-uncite-frame-alist
+@vindex sc-recite-frame-alist
+For each of the actions -- citing, unciting, and reciting -- an alist is
+consulted to find the frame to use (@code{sc-cite-frame-alist},
+@code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist}
+respectively). These frames can contain alists of the form:
+
+@example
+((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
+ (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
+ (@dots{}))
+@end example
+
+@vindex sc-mail-field
+@findex string-match
+Where @var{infokey} is a key suitable for @code{sc-mail-field},
+@var{regexp} is a regular expression which is @code{string-match}'d
+against the value of the @code{sc-mail-field} key, and @var{frame} is
+the frame to use if a match occurred. @var{frame} can be a variable
+containing a frame or a frame in-lined.@refill
+
+When Supercite is about to cite, uncite, or recite a region, it consults
+the appropriate alist and attempts to find a frame to use. If one
+is not found from the alist, then the appropriate default frame is used.
+
+@node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top
+@comment node-name, next, previous, up
+@vindex sc-mode-map-prefix
+@vindex mode-map-prefix (sc-)
+@kindex C-c C-p
+@chapter Post-yank Formatting Commands
+@ifinfo
+
+@end ifinfo
+Once the original message has been yanked into the reply buffer, and
+@code{sc-cite-original} has had a chance to do its thing, a number of
+useful Supercite commands will be available to you. Since there is wide
+variety in the keymaps that MUAs set up in their reply buffers, it is
+next to impossible for Supercite to properly sprinkle its commands into
+the existing keymap. For this reason Supercite places its commands on a
+separate keymap, putting this keymap onto a prefix key in the reply
+buffer. You can customize the prefix key Supercite uses by changing the
+variable @code{sc-mode-map-prefix}. By default, the
+@code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice,
+but unfortunately the best general solution so far. In the rest of this
+chapter, we'll assume you've installed Supercite's keymap on the default
+prefix.@refill
+
+@ifinfo
+@menu
+* Citing Commands::
+* Insertion Commands::
+* Variable Toggling Shortcuts::
+* Mail Field Commands::
+* Miscellaneous Commands::
+@end menu
+@end ifinfo
+
+@node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands
+@comment node-name, next, previous, up
+@vindex sc-cite-region-limit
+@section Commands to Manually Cite, Recite, and Uncite
+@ifinfo
+
+@end ifinfo
+Probably the three most common post-yank formatting operations that you
+will perform will be the manual citing, reciting, and unciting of
+regions of text in the reply buffer. Often you may want to recite a
+paragraph to use a nickname, or manually cite a message when setting
+@code{sc-cite-region-limit} to @code{nil}. The following commands
+perform these functions on the region of text between @samp{point} and
+@samp{mark}. Each of them sets the @dfn{undo boundary} before modifying
+the region so that the command can be undone in the standard Emacs
+way.@refill
+
+A quick note about Emacs 19. Unlike in Emacs 18, the region delimited
+by @samp{point} and @samp{mark} can have two states. It can be
+@dfn{active} or @dfn{inactive}. Although Emacs 19 and Lucid Emacs 19
+use different terminology and functions, both employ the same convention
+such that when the region is inactive, commands that modify the region
+should generate an error. The user needs to explicitly activate the
+region before successfully executing the command. All Supercite
+commands conform to this convention.
+
+Here is the list of Supercite citing commands:
+
+@table @asis
+@findex sc-cite-region
+@findex cite-region (sc-)
+@kindex C-c C-p c
+@vindex sc-pre-cite-hook
+@vindex pre-cite-hook (sc-)
+@vindex sc-confirm-always-p
+@vindex confirm-always-p
+@kindex C-u
+@item @code{sc-cite-region} (@kbd{C-c C-p c})
+@comment
+This command cites each line in the region of text by interpreting the
+selected frame from @code{sc-cite-frame-alist}, or the default citing
+frame @code{sc-default-cite-frame}. It runs the hook
+@code{sc-pre-cite-hook} before interpreting the frame. With an optional
+universal argument (@kbd{C-u}), it temporarily sets
+@code{sc-confirm-always-p} to @code{t} so you can confirm the
+attribution string for a single manual citing.
+@xref{Configuring the Citation Engine}.@refill
+
+@findex sc-uncite-region
+@findex uncite-region (sc-)
+@kindex C-c C-p u
+@item @code{sc-uncite-region} (@kbd{C-c C-p u})
+@comment
+This command removes any citation strings from the beginning of each
+cited line in the region by interpreting the selected frame from
+@code{sc-uncite-frame-alist}, or the default unciting frame
+@code{sc-default-uncite-frame}. It runs the hook
+@code{sc-pre-uncite-hook} before interpreting the frame.
+@xref{Configuring the Citation Engine}.@refill
+
+@findex sc-recite-region
+@findex recite-region (sc-)
+@kindex C-c C-p r
+@item @code{sc-recite-region} (@kbd{C-c C-p r})
+@comment
+This command recites each line the region by interpreting the selected
+frame from @code{sc-recite-frame-alist}, or the default reciting frame
+@code{sc-default-recite-frame}. It runs the hook
+@code{sc-pre-recite-hook} before interpreting the frame.
+@xref{Configuring the Citation Engine}.@refill
+
+@vindex sc-confirm-always-p
+@vindex confirm-always-p (sc-)
+Supercite will always ask you to confirm the attribution when reciting a
+region, regardless of the value of @code{sc-confirm-always-p}.
+@end table
+
+@node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands
+@comment node-name, next, previous, up
+@section Insertion Commands
+@ifinfo
+
+@end ifinfo
+These two functions insert various strings into the reply buffer.
+
+@table @asis
+@findex sc-insert-reference
+@findex insert-reference (sc-)
+@kindex C-c C-p w
+@item @code{sc-insert-reference} (@kbd{C-c C-p w})
+@comment
+@vindex sc-preferred-header-style
+@vindex preferred-header-style (sc-)
+Inserts a reference header into the reply buffer at @samp{point}. With
+no arguments, the header indexed by @code{sc-preferred-header-style} is
+inserted. An optional numeric argument is the index into
+@code{sc-rewrite-header-list} indicating which reference header to
+write.@refill
+
+With just the universal argument (@kbd{C-u}), electric reference mode is
+entered, regardless of the value of @code{sc-electric-references-p}.
+
+@findex sc-insert-citation
+@findex insert-citation (sc-)
+@kindex C-c C-p i
+@item @code{sc-insert-citation} (@kbd{C-c C-p i})
+@comment
+Inserts the current citation string at the beginning of the line that
+@samp{point} is on. If the line is already cited, Supercite will issue
+an error and will not cite the line.
+@end table
+
+@node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands
+@comment node-name, next, previous, up
+@cindex toggling variables
+@section Variable Toggling Shortcuts
+@ifinfo
+
+@end ifinfo
+Supercite defines a number of commands that make it easier for you to
+toggle and set various Supercite variables as you are editing the reply
+buffer. For example, you may want to turn off filling or whitespace
+cleanup, but only temporarily. These toggling shortcut commands make
+this easy to do.
+
+@kindex C-c C-p C-t
+Like Supercite commands in general, the toggling commands are placed on
+a keymap prefix within the greater Supercite keymap. For the default
+value of @code{sc-mode-map-prefix}, this will be
+@kbd{C-c C-p C-t}.@refill
+
+The following commands toggle the value of certain Supercite variables
+which take only a binary value:
+
+@table @kbd
+@item C-c C-p C-t b
+Toggles the variable @code{sc-mail-nuke-blank-lines-p}.
+
+@item C-c C-p C-t c
+Toggles the variable @code{sc-confirm-always-p}.
+
+@item C-c C-p C-t d
+Toggles the variable @code{sc-downcase-p}.
+
+@item C-c C-p C-t e
+Toggles the variable @code{sc-electric-references-p}.
+
+@item C-c C-p C-t f
+Toggles the variable @code{sc-auto-fill-region-p}.
+
+@item C-c C-p C-t o
+Toggles the variable @code{sc-electric-circular-p}.
+
+@item C-c C-p C-t s
+Toggles the variable @code{sc-nested-citation-p}.
+
+@item C-c C-p C-t u
+Toggles the variable @code{sc-use-only-preferences-p}.
+
+@item C-c C-p C-t w
+Toggles the variable @code{sc-fixup-whitespace-p}.
+@end table
+
+@findex set-variable
+The following commands let you set the value of multi-value variables,
+in the same way that Emacs' @code{set-variable} does:
+
+@table @kbd
+@item C-c C-p C-t a
+Sets the value of the variable @code{sc-preferred-attribution-list}.
+
+@item C-c C-p C-t l
+Sets the value of the variable @code{sc-cite-region-limit}.
+
+@item C-c C-p C-t n
+Sets the value of the variable @code{sc-mail-nuke-mail-headers}.
+
+@item C-c C-p C-t N
+Sets the value of the variable @code{sc-mail-header-nuke-list}.
+
+@item C-c C-p C-t p
+Sets the value of the variable @code{sc-preferred-header-style}.
+@end table
+
+@kindex C-c C-p C-p
+One special command is provided to toggle both
+@code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together.
+This is because you typically want to run Supercite with either variable
+as @code{nil} or non-@code{nil}. The command to toggle these variables
+together is bound on @kbd{C-c C-p C-p}.@refill
+
+Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?})
+brings up a Help message on the toggling keymap.
+
+
+@node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands
+@comment node-name, next, previous, up
+@section Mail Field Commands
+@ifinfo
+
+@end ifinfo
+These commands allow you to view, modify, add, and delete various bits
+of information from the info alist.
+@xref{Information Keys and the Info Alist}.@refill
+
+@table @asis
+@kindex C-c C-p f
+@findex sc-mail-field-query
+@findex mail-field-query (sc-)
+@kindex C-c C-p f
+@item @code{sc-mail-field-query} (@kbd{C-c C-p f})
+@comment
+Allows you to interactively view, modify, add, and delete info alist
+key-value pairs. With no argument, you are prompted (with completion)
+for a info key. The value associated with that key is displayed in the
+minibuffer. With an argument, this command will first ask if you want
+to view, modify, add, or delete an info key. Viewing is identical to
+running the command with no arguments.
+
+If you want to modify the value of a key, Supercite will first prompt
+you (with completion) for the key of the value you want to change. It
+will then put you in the minibuffer with the key's current value so you
+can edit the value as you wish. When you hit @key{RET}, the key's value
+is changed. For those of you running Emacs 19, minibuffer history is
+kept for the values.
+
+If you choose to delete a key-value pair, Supercite will prompt you (with
+completion) for the key to delete.
+
+If you choose to add a new key-value pair, Supercite firsts prompts you
+for the key to add. Note that completion is turned on for this prompt,
+but you can type any key name here, even one that does not yet exist.
+After entering the key, Supercite prompts you for the key's value. It
+is not an error to enter a key that already exists, but the new value
+will override any old value. It will not replace it though; if you
+subsequently delete the key-value pair, the old value will reappear.
+
+@findex sc-mail-process-headers
+@findex mail-process-headers (sc-)
+@kindex C-c C-p g
+@item @code{sc-mail-process-headers} (@kbd{C-c C-p g})
+@comment
+This command lets you re-initialize Supercite's info alist from any set
+of mail headers in the region between @samp{point} and @samp{mark}.
+This function is especially useful for replying to digest messages where
+Supercite will initially set up its information for the digest
+originator, but you want to cite each component article with the real
+message author. Note that unless an error during processing occurs, any
+old information is lost.@refill
+@end table
+
+@node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands
+@comment node-name, next, previous, up
+@section Miscellaneous Commands
+@ifinfo
+
+@end ifinfo
+@table @asis
+@findex sc-open-line
+@findex open-line (sc-)
+@findex open-line
+@kindex C-c C-p o
+@item @code{sc-open-line} (@kbd{C-c C-p o})
+@comment
+Similar to Emacs' standard @code{open-line} commands, but inserts the
+citation string in front of the new line. As with @code{open-line},
+an optional numeric argument inserts that many new lines.@refill
+
+@findex sc-describe
+@findex describe (sc-)
+@kindex C-c C-p ?
+@kindex C-c C-p h
+@item @code{sc-describe} (@kbd{C-c C-p h} and @kbd{C-c C-p ?})
+@comment
+This function has been obsoleted by the @TeX{}info manual you are now
+reading. It is still provided for compatibility, but it will eventually
+go away.
+
+@findex sc-version
+@findex version (sc-)
+@kindex C-c C-p v
+@item @code{sc-version} (@kbd{C-c C-p v})
+@comment
+Echos the version of Supercite you are using. With the optional
+universal argument (@kbd{C-u}), this command inserts the version
+information into the current buffer.
+
+@findex sc-submit-bug-report
+@findex submit-bug-report (sc-)
+@kindex C-c C-p C-b
+@item @code{sc-submit-bug-report} (@kbd{C-c C-p C-b})
+@comment
+If you encounter a bug, or wish to suggest an enhancement, use this
+command to set up an outgoing mail buffer, with the proper address to
+the Supercite maintainer automatically inserted in the @samp{To:@:}
+field. This command also inserts information that the Supercite
+maintainer can use to recreate your exact setup, making it easier to
+verify your bug.
+@end table
+
+@node Hints to MUA Authors, Version 3 Changes, Electric References, Top
+@comment node-name, next, previous, up
+@chapter Hints to MUA Authors
+@ifinfo
+
+@end ifinfo
+In June of 1989, some discussion was held between the various MUA
+authors, the Supercite author, and other Supercite users. These
+discussions centered around the need for a standard interface between
+MUAs and Supercite (or any future Supercite-like packages). This
+interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in
+a mail message to the Supercite mailing list:
+
+@example
+ Martin> Each news/mail-reader should provide a form of
+ Martin> mail-yank-original that
+
+ Martin> 1: inserts the original message incl. header into the
+ Martin> reply buffer; no indentation/prefixing is done, the header
+ Martin> tends to be a "full blown" version rather than to be
+ Martin> stripped down.
+
+ Martin> 2: `point' is at the start of the header, `mark' at the
+ Martin> end of the message body.
+
+ Martin> 3: (run-hooks 'mail-yank-hooks)
+
+ Martin> [Supercite] should be run as such a hook and merely
+ Martin> rewrite the message. This way it isn't anymore
+ Martin> [Supercite]'s job to gather the original from obscure
+ Martin> sources. [@dots{}]
+@end example
+
+@vindex mail-citation-hook
+@vindex mail-yank-hooks
+@cindex sendmail.el
+@findex mail-yank-original
+@findex defvar
+This specification was adopted, but with the recent release of
+Emacs 19, it has undergone a slight modification. Instead of the
+variable @code{mail-yank-hooks}, the new preferred hook variable that
+the MUA should provide is @code{mail-citation-hook}.
+@code{mail-yank-hooks} can be provided for backward compatibility, but
+@code{mail-citation-hook} should always take precedence. Richard
+Stallman (of the FSF) suggests that the MUAs should @code{defvar}
+@code{mail-citation-hook} to @code{nil} and perform some default citing
+when that is the case. Take a look at Emacs 19's @file{sendmail.el}
+file, specifically the @code{mail-yank-original} defun for
+details.@refill
+
+If you are writing a new MUA package, or maintaining an existing MUA
+package, you should make it conform to this interface so that your users
+will be able to link Supercite easily and seamlessly. To do this, when
+setting up a reply or forward buffer, your MUA should follow these
+steps:
+
+@enumerate
+@item
+Insert the original message, including the mail headers into the reply
+buffer. At this point you should not modify the raw text in any way, and
+you should place all the original headers into the body of the reply.
+This means that many of the mail headers will be duplicated, one copy
+above the @code{mail-header-separator} line and one copy below,
+however there will probably be more headers below this line.@refill
+
+@item
+Set @samp{point} to the beginning of the line containing the first mail
+header in the body of the reply. Set @samp{mark} at the end of the
+message text. It is very important that the region be set around the
+text Supercite is to modify and that the mail headers are within this
+region. Supercite will not venture outside the region for any reason,
+and anything within the region is fair game, so don't put anything that
+@strong{must} remain unchanged inside the region. Further note that for
+Emacs 19, the region need not be set active. Supercite will work
+properly when the region is inactive, as should any other like-minded
+package.@refill
+
+@item
+Run the hook @code{mail-citation-hook}. You will probably want to
+provide some kind of default citation functions in cases where the user
+does not have Supercite installed. By default, your MUA should
+@code{defvar} @code{mail-citation-hook} to @code{nil}, and in your
+yanking function, check its value. If it finds
+@code{mail-citation-hook} to be @code{nil}, it should perform some
+default citing behavior. User who want to connect to Supercite then
+need only add @code{sc-cite-original} to this list of hooks using
+@code{add-hook}.@refill
+@end enumerate
+
+If you do all this, your users will not need to overload your routines
+to use Supercite, and your MUA will join the ranks of those that conform
+to this interface ``out of the box.''
+
+@node Version 3 Changes, Thanks and History, Hints to MUA Authors, Top
+@comment node-name, next, previous, up
+@chapter Version 3 Changes
+@ifinfo
+
+@end ifinfo
+@cindex sc-unsupp.el file
+With version 3, Supercite has undergone an almost complete rewrite, and
+has hopefully benefited in a number of ways, including vast
+improvements in the speed of performance, a big reduction in size of the
+code and in the use of Emacs resources, and a much cleaner and flexible
+internal architecture. The central construct of the info alist, and its
+role in Supercite has been expanded, and the other central concept, the
+general package Regi, was developed to provide a theoretically unlimited
+flexibility.
+
+But most of this work is internal and not of very great importance to the
+casual user. There have been some changes at the user-visible level,
+but for the most part, the Supercite configuration variables from
+version 2 should still be relevant to version 3. Below, I briefly
+outline those user-visible things that have changed since version 2. For
+details, look to other sections of this manual.
+
+@enumerate
+@item
+@cindex supercite.el file
+@cindex reporter.el file
+@cindex regi.el file
+@cindex sc.el from version 2
+@cindex sc-elec.el from version 2
+Supercite proper now comes in a single file, @file{supercite.el}, which
+contains everything except the unsupported noodlings, overloading (which
+should be more or less obsolete with the release of Emacs 19), and the
+general lisp packages @file{reporter.el} and @file{regi.el}. Finally,
+the @TeX{}info manual comes in its own file as well. In particular, the
+file @file{sc.el} from the version 2 distribution is obsolete, as is the
+file @file{sc-elec.el}.
+
+@item
+@code{sc-spacify-name-chars} is gone in version 3.
+
+@item
+@vindex sc-attrib-selection-list
+@vindex attrib-selection-list
+@code{sc-nickname-alist} is gone in version 3. The
+@code{sc-attrib-selection-list} is a more general construct supporting
+the same basic feature.
+
+@item
+The version 2 variable @code{sc-preferred-attribution} has been changed
+to @code{sc-preferred-attribution-list}, and has been expanded upon to
+allow you to specify an ordered list of preferred attributions.
+
+@item
+@code{sc-mail-fields-list} has been removed, and header nuking in
+general has been greatly improved, giving you wider flexibility in
+specifying which headers to keep and remove while presenting a
+simplified interface to commonly chosen defaults.
+
+@item
+Post-yank paragraph filling has been completely removed from Supercite,
+other packages just do it better than Supercite ever would. Supercite
+will still fill newly cited paragraphs.
+
+@item
+@vindex sc-cite-region-limit
+@vindex cite-region-limit
+The variable @code{sc-all-but-cite-p} has been replaced by
+@code{sc-cite-region-limit}.
+
+@item
+Keymap hacking in the reply buffer has been greatly simplified, with, I
+believe, little reduction in functionality.
+
+@item
+Hacking of the reply buffer's docstring has been completely eliminated.
+@end enumerate
+
+@node Thanks and History, The Supercite Mailing List, Version 3 Changes, Top
+@comment node-name, next, previous, up
+@chapter Thanks and History
+@ifinfo
+
+@end ifinfo
+The Supercite package was derived from its predecessor Superyank 1.11
+which was inspired by various bits of code and ideas from Martin Neitzel
+and Ashwin Ram. They were the folks who came up with the idea of
+non-nested citations and implemented some rough code to provide this
+style. Superyank and Supercite version 2 evolved to the point where much
+of the attribution selection mechanism was automatic, and features have
+been continuously added through the comments and suggestions of the
+Supercite mailing list participants. Supercite version 3 represents a
+nearly complete rewrite with many of the algorithms and coding styles
+being vastly improved. Hopefully Supercite version 3 is faster,
+smaller, and much more flexible than its predecessors.
+
+In the version 2 manual I thanked some specific people for their help in
+developing Supercite 2. You folks know who you are and your continued
+support is greatly appreciated. I wish to thank everyone on the
+Supercite mailing list, especially the brave alpha testers, who helped
+considerably in testing out the concepts and implementation of Supercite
+version 3. Special thanks go out to the MUA and Emacs authors Kyle
+Jones, Stephen Gildea, Richard Stallman, and Jamie Zawinski for coming
+to a quick agreement on the new @code{mail-citation-hook} interface, and
+for adding the magic lisp to their code to support this.
+
+All who have helped and contributed have been greatly appreciated.
+
+@node The Supercite Mailing List, Concept Index, Thanks and History, Top
+@comment node-name, next, previous, up
+@cindex supercite mailing list address
+@cindex mailing list address
+@chapter The Supercite Mailing List
+@ifinfo
+
+@end ifinfo
+The author runs a simple mail expanding mailing list for discussion of
+issues related to Supercite. This includes enhancement requests, bug
+reports, general help questions, etc. To subscribe or unsubscribe to
+the mailing list, send a request to the administrative address:
+
+@example
+supercite-request@@python.org
+@end example
+
+Please be sure to include the most reliable and shortest (preferably
+Internet) address back to you. To post articles to the list, send your
+message to this address (you do not need to be a member to post, but be
+sure to indicate this in your article or replies may not be CC'd to
+you):
+
+@example
+supercite@@python.org
+@end example
+
+If you are sending bug reports, they should go to the following address,
+but @emph{please}! use the command @code{sc-submit-bug-report} since it
+will be much easier for me to duplicate your problem if you do so. It
+will set up a mail buffer automatically with this address on the
+@samp{To:@:} line:
+
+@example
+supercite-help@@python.org
+@end example
+
+@node Concept Index, Command Index, The Supercite Mailing List, Top
+@comment node-name, next, previous, up
+@unnumbered Concept Index
+@printindex cp
+
+@node Command Index, Key Index, Concept Index, Top
+@comment node-name, next, previous, up
+@unnumbered Command Index
+@ifinfo
+
+@end ifinfo
+Since all supercite commands are prepended with the string
+``@code{sc-}'', each appears under its @code{sc-}@var{command} name and
+its @var{command} name.
+@iftex
+@sp 2
+@end iftex
+@printindex fn
+
+@node Key Index, Variable Index, Command Index, Top
+@comment node-name, next, previous, up
+@unnumbered Key Index
+@printindex ky
+
+@node Variable Index, , Key Index, Top
+@comment node-name, next, previous, up
+@unnumbered Variable Index
+@ifinfo
+
+@end ifinfo
+Since all supercite variables are prepended with the string
+``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and
+its @var{variable} name.
+@iftex
+@sp 2
+@end iftex
+@printindex vr
+@summarycontents
+@contents
+@bye
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Screen, User Input, Acknowledgments, Top
+@chapter The Organization of the Screen
+@cindex screen
+@cindex parts of the screen
+@c
+
+ On a text-only terminal, the Emacs display occupies the whole screen.
+On the X Window System, Emacs creates its own X windows to use. We use
+the term @dfn{frame} to mean an entire text-only screen or an entire X
+window used by Emacs. Emacs uses both kinds of frames in the same way
+to display your editing. Emacs normally starts out with just one frame,
+but you can create additional frames if you wish. @xref{Frames}.
+
+ When you start Emacs, the entire frame except for the first and last
+lines is devoted to the text you are editing. This area is called the
+@dfn{window}. The first line is a @dfn{menu bar}, and the last line is
+a special @dfn{echo area} or @dfn{minibuffer window} where prompts
+appear and where you can enter responses. See below for more
+information about these special lines.
+
+ You can subdivide the large text window horizontally or vertically
+into multiple text windows, each of which can be used for a different
+file (@pxref{Windows}). In this manual, the word ``window'' always
+refers to the subdivisions of a frame within Emacs.
+
+ The window that the cursor is in is the @dfn{selected window}, in
+which editing takes place. Most Emacs commands implicitly apply to the
+text in the selected window (though mouse commands generally operate on
+whatever window you click them in, whether selected or not). The other
+windows display text for reference only, unless/until you select them.
+If you use multiple frames under the X Window System, then giving the
+input focus to a particular frame selects a window in that frame.
+
+ Each window's last line is a @dfn{mode line}, which describes what is
+going on in that window. It appears in inverse video, if the terminal
+supports that, and its contents begin with @w{@samp{--:-- @ *scratch*}}
+when Emacs starts. The mode line displays status information such as
+what buffer is being displayed above it in the window, what major and
+minor modes are in use, and whether the buffer contains unsaved changes.
+
+@menu
+* Point:: The place in the text where editing commands operate.
+* Echo Area:: Short messages appear at the bottom of the screen.
+* Mode Line:: Interpreting the mode line.
+* Menu Bar:: How to use the menu bar.
+@end menu
+
+@node Point
+@section Point
+@cindex point
+@cindex cursor
+
+ Within Emacs, the terminal's cursor shows the location at which
+editing commands will take effect. This location is called @dfn{point}.
+Many Emacs commands move point through the text, so that you can edit at
+different places in it. You can also place point by clicking mouse
+button 1.
+
+ While the cursor appears to point @emph{at} a character, you should
+think of point as @emph{between} two characters; it points @emph{before}
+the character that appears under the cursor. For example, if your text
+looks like @samp{frob} with the cursor over the @samp{b}, then point is
+between the @samp{o} and the @samp{b}. If you insert the character
+@samp{!} at that position, the result is @samp{fro!b}, with point
+between the @samp{!} and the @samp{b}. Thus, the cursor remains over
+the @samp{b}, as before.
+
+ Sometimes people speak of ``the cursor'' when they mean ``point,'' or
+speak of commands that move point as ``cursor motion'' commands.
+
+ Terminals have only one cursor, and when output is in progress it must
+appear where the typing is being done. This does not mean that point is
+moving. It is only that Emacs has no way to show you the location of point
+except when the terminal is idle.
+
+ If you are editing several files in Emacs, each in its own buffer,
+each buffer has its own point location. A buffer that is not currently
+displayed remembers where point is in case you display it again later.
+
+ When there are multiple windows in a frame, each window has its own
+point location. The cursor shows the location of point in the selected
+window. This also is how you can tell which window is selected. If the
+same buffer appears in more than one window, each window has its own
+position for point in that buffer.
+
+ When there are multiple frames, each frame can display one cursor.
+The cursor in the selected frame is solid; the cursor in other frames is
+a hollow box, and appears in the window that would be selected if you
+give the input focus to that frame.
+
+ The term `point' comes from the character @samp{.}, which was the
+command in TECO (the language in which the original Emacs was written)
+for accessing the value now called `point'.
+
+@node Echo Area
+@section The Echo Area
+@cindex echo area
+@c
+
+ The line at the bottom of the frame (below the mode line) is the
+@dfn{echo area}. It is used to display small amounts of text for
+several purposes.
+
+ @dfn{Echoing} means displaying the characters that you type. Outside
+Emacs, the operating system normally echoes all your input. Emacs
+handles echoing differently.
+
+ Single-character commands do not echo in Emacs, and multi-character
+commands echo only if you pause while typing them. As soon as you pause
+for more than a second in the middle of a command, Emacs echoes all the
+characters of the command so far. This is to @dfn{prompt} you for the
+rest of the command. Once echoing has started, the rest of the command
+echoes immediately as you type it. This behavior is designed to give
+confident users fast response, while giving hesitant users maximum
+feedback. You can change this behavior by setting a variable
+(@pxref{Display Vars}).
+
+@cindex error message in the echo area
+ If a command cannot be executed, it may print an @dfn{error message} in
+the echo area. Error messages are accompanied by a beep or by flashing the
+screen. Also, any input you have typed ahead is thrown away when an error
+happens.
+
+ Some commands print informative messages in the echo area. These
+messages look much like error messages, but they are not announced with
+a beep and do not throw away input. Sometimes the message tells you
+what the command has done, when this is not obvious from looking at the
+text being edited. Sometimes the sole purpose of a command is to print
+a message giving you specific information---for example, @kbd{C-x =}
+prints a message describing the character position of point in the text
+and its current column in the window. Commands that take a long time
+often display messages ending in @samp{...} while they are working, and
+add @samp{done} at the end when they are finished.
+
+@cindex @samp{*Messages*} buffer
+@cindex saved echo area messages
+@cindex messages saved from echo area
+ Echo-area informative messages are saved in an editor buffer named
+@samp{*Messages*}. (We have not explained buffers yet; see
+@ref{Buffers}, for more information about them.) If you miss a message
+that appears briefly on the screen, you can switch to the
+@samp{*Messages*} buffer to see it again. (Successive progress messages
+are often collapsed into one in that buffer.)
+
+@vindex message-log-max
+ The size of @samp{*Messages*} is limited to a certain number of lines.
+The variable @code{message-log-max} specifies how many lines. Once the
+buffer has that many lines, each line added at the end deletes one line
+from the beginning. @xref{Variables}, for how to set variables such as
+@code{message-log-max}.
+
+ The echo area is also used to display the @dfn{minibuffer}, a window that
+is used for reading arguments to commands, such as the name of a file to be
+edited. When the minibuffer is in use, the echo area begins with a prompt
+string that usually ends with a colon; also, the cursor appears in that line
+because it is the selected window. You can always get out of the
+minibuffer by typing @kbd{C-g}. @xref{Minibuffer}.
+
+@node Mode Line
+@section The Mode Line
+@cindex mode line
+@cindex top level
+@c
+
+ Each text window's last line is a @dfn{mode line}, which describes what
+is going on in that window. When there is only one text window, the
+mode line appears right above the echo area; it is the next-to-last line
+on the frame. The mode line is in inverse video if the terminal
+supports that, and it starts and ends with dashes.
+
+ Normally, the mode line looks like this:
+
+@example
+-@var{cs}:@var{ch} @var{buf} (@var{major} @var{minor})--@var{line}--@var{pos}------
+@end example
+
+@noindent
+This gives information about the buffer being displayed in the window: the
+buffer's name, what major and minor modes are in use, whether the buffer's
+text has been changed, and how far down the buffer you are currently
+looking.
+
+ @var{ch} contains two stars @samp{**} if the text in the buffer has
+been edited (the buffer is ``modified''), or @samp{--} if the buffer has
+not been edited. For a read-only buffer, it is @samp{%*} if the buffer
+is modified, and @samp{%%} otherwise.
+
+ @var{buf} is the name of the window's @dfn{buffer}. In most cases
+this is the same as the name of a file you are editing. @xref{Buffers}.
+
+ The buffer displayed in the selected window (the window that the
+cursor is in) is also Emacs's selected buffer, the one that editing
+takes place in. When we speak of what some command does to ``the
+buffer,'' we are talking about the currently selected buffer.
+
+ @var{line} is @samp{L} followed by the current line number of point.
+This is present when Line Number mode is enabled (which it normally is).
+You can optionally display the current column number too, by turning on
+Column Number mode (which is not enabled by default because it is
+somewhat slower). @xref{Optional Mode Line}.
+
+ @var{pos} tells you whether there is additional text above the top of
+the window, or below the bottom. If your buffer is small and it is all
+visible in the window, @var{pos} is @samp{All}. Otherwise, it is
+@samp{Top} if you are looking at the beginning of the buffer, @samp{Bot}
+if you are looking at the end of the buffer, or @samp{@var{nn}%}, where
+@var{nn} is the percentage of the buffer above the top of the
+window.@refill
+
+ @var{major} is the name of the @dfn{major mode} in effect in the
+buffer. At any time, each buffer is in one and only one of the possible
+major modes. The major modes available include Fundamental mode (the
+least specialized), Text mode, Lisp mode, C mode, Texinfo mode, and many
+others. @xref{Major Modes}, for details of how the modes differ and how
+to select one.@refill
+
+ Some major modes display additional information after the major mode
+name. For example, Rmail buffers display the current message number and
+the total number of messages. Compilation buffers and Shell buffers
+display the status of the subprocess.
+
+ @var{minor} is a list of some of the @dfn{minor modes} that are turned
+on at the moment in the window's chosen buffer. For example,
+@samp{Fill} means that Auto Fill mode is on. @samp{Abbrev} means that
+Word Abbrev mode is on. @samp{Ovwrt} means that Overwrite mode is on.
+@xref{Minor Modes}, for more information. @samp{Narrow} means that the
+buffer being displayed has editing restricted to only a portion of its
+text. This is not really a minor mode, but is like one.
+@xref{Narrowing}. @samp{Def} means that a keyboard macro is being
+defined. @xref{Keyboard Macros}.
+
+ In addition, if Emacs is currently inside a recursive editing level,
+square brackets (@samp{[@dots{}]}) appear around the parentheses that
+surround the modes. If Emacs is in one recursive editing level within
+another, double square brackets appear, and so on. Since recursive
+editing levels affect Emacs globally, not just one buffer, the square
+brackets appear in every window's mode line or not in any of them.
+@xref{Recursive Edit}.@refill
+
+ Non-windowing terminals can only show a single Emacs frame at a time
+(@pxref{Frames}). On such terminals, the mode line displays the name of
+the selected frame, after @var{ch}. The initial frame's name is
+@samp{F1}.
+
+ @var{cs} states the coding system used for the file you are editing.
+A dash indicates the default state of affairs: no code conversion,
+except for end-of-line translation if the file contents call for that.
+@samp{=} means no conversion whatsoever. Nontrivial code conversions
+are represented by various letters---for example, @samp{1} refers to ISO
+Latin-1. @xref{Coding Systems}, for more information. If you are using
+an input method, a string of the form @samp{@var{i}>} is added to the
+beginning of @var{cs}; @var{i} identifies the input method. (Some input
+methods show @samp{+} or @samp{@@} instead of @samp{>}.) @xref{Input
+Methods}.
+
+ When you are using a character-only terminal (not a window system),
+@var{cs} uses three characters to describe, respectively, the coding
+system for keyboard input, the coding system for terminal output, and
+the coding system used for the file you are editing.
+
+ When multibyte characters are not enabled, @var{cs} does not appear at
+all. @xref{Enabling Multibyte}.
+
+@cindex end-of-line conversion, mode-line indication
+ The colon after @var{cs} can change to another string in certain
+circumstances. Emacs uses newline to separate lines in the buffer.
+Some files use different conventions for separating lines: either
+carriage-return linefeed (the MS-DOS convention) or just carriage-return
+(the Macintosh convention). If the buffer's file uses carriage-return
+linefeed, the colon changes to either a backslash (@samp{\}) or
+@samp{(DOS)}, depending on the operating system. If the file uses just
+carriage-return, the colon indicator changes to either a forward slash
+(@samp{/}) or @samp{(Mac)}. On some systems, Emacs displays
+@samp{(Unix)} instead of the colon even for files that use newline to
+separate lines.
+
+@vindex eol-mnemonic-unix
+@vindex eol-mnemonic-dos
+@vindex eol-mnemonic-mac
+@vindex eol-mnemonic-undecided
+ You can customize the mode line display for each of the end-of-line
+formats by setting each of the variables @code{eol-mnemonic-unix},
+@code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and
+@code{eol-mnemonic-undecided} to any string you find appropriate.
+@xref{Variables}, for an explanation how to set variables.
+
+ @xref{Optional Mode Line}, for features that add other handy
+information to the mode line, such as the current column number of
+point, the current time, and whether new mail for you has arrived.
+
+@node Menu Bar
+@section The Menu Bar
+@cindex menu bar
+
+ Each Emacs frame normally has a @dfn{menu bar} at the top which you
+can use to perform certain common operations. There's no need to list
+them here, as you can more easily see for yourself.
+
+@kindex M-`
+@kindex F10
+@findex tmm-menubar
+ When you are using a window system, you can use the mouse to choose a
+command from the menu bar. An arrow pointing right, after the menu
+item, indicates that the item leads to a subsidiary menu; @samp{...} at
+the end means that the command will read arguments from the keyboard
+before it actually does anything.
+
+ To view the full command name and documentation for a menu item, type
+@kbd{C-h k}, and then select the menu bar with the mouse in the usual
+way (@pxref{Key Help}).
+
+ On text-only terminals with no mouse, you can use the menu bar by
+typing @kbd{M-`} or @key{F10} (these run the command
+@code{tmm-menubar}). This command enters a mode in which you can select
+a menu item from the keyboard. A provisional choice appears in the echo
+area. You can use the left and right arrow keys to move through the
+menu to different choices. When you have found the choice you want,
+type @key{RET} to select it.
+
+ Each menu item also has an assigned letter or digit which designates
+that item; it is usually the initial of some word in the item's name.
+This letter or digit is separated from the item name by @samp{=>}. You
+can type the item's letter or digit to select the item.
+
+ Some of the commands in the menu bar have ordinary key bindings as
+well; if so, the menu lists one equivalent key binding in parentheses
+after the item itself.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Search, Fixit, Display, Top
+@chapter Searching and Replacement
+@cindex searching
+@cindex finding strings within text
+
+ Like other editors, Emacs has commands for searching for occurrences of
+a string. The principal search command is unusual in that it is
+@dfn{incremental}; it begins to search before you have finished typing the
+search string. There are also nonincremental search commands more like
+those of other editors.
+
+ Besides the usual @code{replace-string} command that finds all
+occurrences of one string and replaces them with another, Emacs has a fancy
+replacement command called @code{query-replace} which asks interactively
+which occurrences to replace.
+
+@menu
+* Incremental Search:: Search happens as you type the string.
+* Nonincremental Search:: Specify entire string and then search.
+* Word Search:: Search for sequence of words.
+* Regexp Search:: Search for match for a regexp.
+* Regexps:: Syntax of regular expressions.
+* Search Case:: To ignore case while searching, or not.
+* Replace:: Search, and replace some or all matches.
+* Other Repeating Search:: Operating on all matches for some regexp.
+@end menu
+
+@node Incremental Search, Nonincremental Search, Search, Search
+@section Incremental Search
+
+@cindex incremental search
+ An incremental search begins searching as soon as you type the first
+character of the search string. As you type in the search string, Emacs
+shows you where the string (as you have typed it so far) would be
+found. When you have typed enough characters to identify the place you
+want, you can stop. Depending on what you plan to do next, you may or
+may not need to terminate the search explicitly with @key{RET}.
+
+@c WideCommands
+@table @kbd
+@item C-s
+Incremental search forward (@code{isearch-forward}).
+@item C-r
+Incremental search backward (@code{isearch-backward}).
+@end table
+
+@kindex C-s
+@findex isearch-forward
+ @kbd{C-s} starts an incremental search. @kbd{C-s} reads characters from
+the keyboard and positions the cursor at the first occurrence of the
+characters that you have typed. If you type @kbd{C-s} and then @kbd{F},
+the cursor moves right after the first @samp{F}. Type an @kbd{O}, and see
+the cursor move to after the first @samp{FO}. After another @kbd{O}, the
+cursor is after the first @samp{FOO} after the place where you started the
+search. At each step, the buffer text that matches the search string is
+highlighted, if the terminal can do that; at each step, the current search
+string is updated in the echo area.
+
+ If you make a mistake in typing the search string, you can cancel
+characters with @key{DEL}. Each @key{DEL} cancels the last character of
+search string. This does not happen until Emacs is ready to read another
+input character; first it must either find, or fail to find, the character
+you want to erase. If you do not want to wait for this to happen, use
+@kbd{C-g} as described below.
+
+ When you are satisfied with the place you have reached, you can type
+@key{RET}, which stops searching, leaving the cursor where the search
+brought it. Also, any command not specially meaningful in searches
+stops the searching and is then executed. Thus, typing @kbd{C-a} would
+exit the search and then move to the beginning of the line. @key{RET}
+is necessary only if the next command you want to type is a printing
+character, @key{DEL}, @key{RET}, or another control character that is
+special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s},
+@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, or @kbd{M-s}).
+
+ Sometimes you search for @samp{FOO} and find it, but not the one you
+expected to find. There was a second @samp{FOO} that you forgot about,
+before the one you were aiming for. In this event, type another @kbd{C-s}
+to move to the next occurrence of the search string. This can be done any
+number of times. If you overshoot, you can cancel some @kbd{C-s}
+characters with @key{DEL}.
+
+ After you exit a search, you can search for the same string again by
+typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
+incremental search, and the second @kbd{C-s} means ``search again.''
+
+ To reuse earlier search strings, use the @dfn{search ring}. The
+commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search
+string to reuse. These commands leave the selected search ring element
+in the minibuffer, where you can edit it. Type @kbd{C-s} or @kbd{C-r}
+to terminate editing the string and search for it.
+
+ If your string is not found at all, the echo area says @samp{Failing
+I-Search}. The cursor is after the place where Emacs found as much of your
+string as it could. Thus, if you search for @samp{FOOT}, and there is no
+@samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
+At this point there are several things you can do. If your string was
+mistyped, you can rub some of it out and correct it. If you like the place
+you have found, you can type @key{RET} or some other Emacs command to
+``accept what the search offered.'' Or you can type @kbd{C-g}, which
+removes from the search string the characters that could not be found (the
+@samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
+@samp{FOOT}). A second @kbd{C-g} at that point cancels the search
+entirely, returning point to where it was when the search started.
+
+ An upper-case letter in the search string makes the search
+case-sensitive. If you delete the upper-case character from the search
+string, it ceases to have this effect. @xref{Search Case}.
+
+ If a search is failing and you ask to repeat it by typing another
+@kbd{C-s}, it starts again from the beginning of the buffer. Repeating
+a failing reverse search with @kbd{C-r} starts again from the end. This
+is called @dfn{wrapping around}. @samp{Wrapped} appears in the search
+prompt once this has happened. If you keep on going past the original
+starting point of the search, it changes to @samp{Overwrapped}, which
+means that you are revisiting matches that you have already seen.
+
+@cindex quitting (in search)
+ The @kbd{C-g} ``quit'' character does special things during searches;
+just what it does depends on the status of the search. If the search has
+found what you specified and is waiting for input, @kbd{C-g} cancels the
+entire search. The cursor moves back to where you started the search. If
+@kbd{C-g} is typed when there are characters in the search string that have
+not been found---because Emacs is still searching for them, or because it
+has failed to find them---then the search string characters which have not
+been found are discarded from the search string. With them gone, the
+search is now successful and waiting for more input, so a second @kbd{C-g}
+will cancel the entire search.
+
+ To search for a newline, type @kbd{C-j}. To search for another
+control character, such as control-S or carriage return, you must quote
+it by typing @kbd{C-q} first. This function of @kbd{C-q} is analogous
+to its use for insertion (@pxref{Inserting Text}): it causes the
+following character to be treated the way any ``ordinary'' character is
+treated in the same context. You can also specify a character by its
+octal code: enter @kbd{C-q} followed by a sequence of octal digits.
+
+ You can change to searching backwards with @kbd{C-r}. If a search fails
+because the place you started was too late in the file, you should do this.
+Repeated @kbd{C-r} keeps looking for more occurrences backwards. A
+@kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be canceled
+with @key{DEL}.
+
+@kindex C-r
+@findex isearch-backward
+ If you know initially that you want to search backwards, you can use
+@kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} as
+a key runs a command (@code{isearch-backward}) to search backward. A
+backward search finds matches that are entirely before the starting
+point, just as a forward search finds matches that begin after it.
+
+ The characters @kbd{C-y} and @kbd{C-w} can be used in incremental
+search to grab text from the buffer into the search string. This makes
+it convenient to search for another occurrence of text at point.
+@kbd{C-w} copies the word after point as part of the search string,
+advancing point over that word. Another @kbd{C-s} to repeat the search
+will then search for a string including that word. @kbd{C-y} is similar
+to @kbd{C-w} but copies all the rest of the current line into the search
+string. Both @kbd{C-y} and @kbd{C-w} convert the text they copy to
+lower case if the search is currently not case-sensitive; this is so the
+search remains case-insensitive.
+
+ The character @kbd{M-y} copies text from the kill ring into the search
+string. It uses the same text that @kbd{C-y} as a command would yank.
+@xref{Yanking}.
+
+ When you exit the incremental search, it sets the mark to where point
+@emph{was}, before the search. That is convenient for moving back
+there. In Transient Mark mode, incremental search sets the mark without
+activating it, and does so only if the mark is not already active.
+
+@vindex isearch-mode-map
+ To customize the special characters that incremental search understands,
+alter their bindings in the keymap @code{isearch-mode-map}. For a list
+of bindings, look at the documentation of @code{isearch-mode} with
+@kbd{C-h f isearch-mode @key{RET}}.
+
+@subsection Slow Terminal Incremental Search
+
+ Incremental search on a slow terminal uses a modified style of display
+that is designed to take less time. Instead of redisplaying the buffer at
+each place the search gets to, it creates a new single-line window and uses
+that to display the line that the search has found. The single-line window
+comes into play as soon as point gets outside of the text that is already
+on the screen.
+
+ When you terminate the search, the single-line window is removed.
+Then Emacs redisplays the window in which the search was done, to show
+its new position of point.
+
+@ignore
+ The three dots at the end of the search string, normally used to indicate
+that searching is going on, are not displayed in slow style display.
+@end ignore
+
+@vindex search-slow-speed
+ The slow terminal style of display is used when the terminal baud rate is
+less than or equal to the value of the variable @code{search-slow-speed},
+initially 1200.
+
+@vindex search-slow-window-lines
+ The number of lines to use in slow terminal search display is controlled
+by the variable @code{search-slow-window-lines}. Its normal value is 1.
+
+@node Nonincremental Search, Word Search, Incremental Search, Search
+@section Nonincremental Search
+@cindex nonincremental search
+
+ Emacs also has conventional nonincremental search commands, which require
+you to type the entire search string before searching begins.
+
+@table @kbd
+@item C-s @key{RET} @var{string} @key{RET}
+Search for @var{string}.
+@item C-r @key{RET} @var{string} @key{RET}
+Search backward for @var{string}.
+@end table
+
+ To do a nonincremental search, first type @kbd{C-s @key{RET}}. This
+enters the minibuffer to read the search string; terminate the string
+with @key{RET}, and then the search takes place. If the string is not
+found, the search command gets an error.
+
+ The way @kbd{C-s @key{RET}} works is that the @kbd{C-s} invokes
+incremental search, which is specially programmed to invoke nonincremental
+search if the argument you give it is empty. (Such an empty argument would
+otherwise be useless.) @kbd{C-r @key{RET}} also works this way.
+
+ However, nonincremental searches performed using @kbd{C-s @key{RET}} do
+not call @code{search-forward} right away. The first thing done is to see
+if the next character is @kbd{C-w}, which requests a word search.
+@ifinfo
+@xref{Word Search}.
+@end ifinfo
+
+@findex search-forward
+@findex search-backward
+ Forward and backward nonincremental searches are implemented by the
+commands @code{search-forward} and @code{search-backward}. These
+commands may be bound to keys in the usual manner. The feature that you
+can get to them via the incremental search commands exists for
+historical reasons, and to avoid the need to find suitable key sequences
+for them.
+
+@node Word Search, Regexp Search, Nonincremental Search, Search
+@section Word Search
+@cindex word search
+
+ Word search searches for a sequence of words without regard to how the
+words are separated. More precisely, you type a string of many words,
+using single spaces to separate them, and the string can be found even if
+there are multiple spaces, newlines or other punctuation between the words.
+
+ Word search is useful for editing a printed document made with a text
+formatter. If you edit while looking at the printed, formatted version,
+you can't tell where the line breaks are in the source file. With word
+search, you can search without having to know them.
+
+@table @kbd
+@item C-s @key{RET} C-w @var{words} @key{RET}
+Search for @var{words}, ignoring details of punctuation.
+@item C-r @key{RET} C-w @var{words} @key{RET}
+Search backward for @var{words}, ignoring details of punctuation.
+@end table
+
+ Word search is a special case of nonincremental search and is invoked
+with @kbd{C-s @key{RET} C-w}. This is followed by the search string,
+which must always be terminated with @key{RET}. Being nonincremental,
+this search does not start until the argument is terminated. It works
+by constructing a regular expression and searching for that; see
+@ref{Regexp Search}.
+
+ Use @kbd{C-r @key{RET} C-w} to do backward word search.
+
+@findex word-search-forward
+@findex word-search-backward
+ Forward and backward word searches are implemented by the commands
+@code{word-search-forward} and @code{word-search-backward}. These
+commands may be bound to keys in the usual manner. The feature that you
+can get to them via the incremental search commands exists for historical
+reasons, and to avoid the need to find suitable key sequences for them.
+
+@node Regexp Search, Regexps, Word Search, Search
+@section Regular Expression Search
+@cindex regular expression
+@cindex regexp
+
+ A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
+denotes a class of alternative strings to match, possibly infinitely
+many. In GNU Emacs, you can search for the next match for a regexp
+either incrementally or not.
+
+@kindex C-M-s
+@findex isearch-forward-regexp
+@kindex C-M-r
+@findex isearch-backward-regexp
+ Incremental search for a regexp is done by typing @kbd{C-M-s}
+(@code{isearch-forward-regexp}). This command reads a search string
+incrementally just like @kbd{C-s}, but it treats the search string as a
+regexp rather than looking for an exact match against the text in the
+buffer. Each time you add text to the search string, you make the
+regexp longer, and the new regexp is searched for. Invoking @kbd{C-s}
+with a prefix argument (its value does not matter) is another way to do
+a forward incremental regexp search. To search backward for a regexp,
+use @kbd{C-M-r} (@code{isearch-backward-regexp}), or @kbd{C-r} with a
+prefix argument.
+
+ All of the control characters that do special things within an
+ordinary incremental search have the same function in incremental regexp
+search. Typing @kbd{C-s} or @kbd{C-r} immediately after starting the
+search retrieves the last incremental search regexp used; that is to
+say, incremental regexp and non-regexp searches have independent
+defaults. They also have separate search rings that you can access with
+@kbd{M-p} and @kbd{M-n}.
+
+ If you type @key{SPC} in incremental regexp search, it matches any
+sequence of whitespace characters, including newlines. If you want
+to match just a space, type @kbd{C-q @key{SPC}}.
+
+ Note that adding characters to the regexp in an incremental regexp
+search can make the cursor move back and start again. For example, if
+you have searched for @samp{foo} and you add @samp{\|bar}, the cursor
+backs up in case the first @samp{bar} precedes the first @samp{foo}.
+
+@findex re-search-forward
+@findex re-search-backward
+ Nonincremental search for a regexp is done by the functions
+@code{re-search-forward} and @code{re-search-backward}. You can invoke
+these with @kbd{M-x}, or bind them to keys, or invoke them by way of
+incremental regexp search with @kbd{C-M-s @key{RET}} and @kbd{C-M-r
+@key{RET}}.
+
+ If you use the incremental regexp search commands with a prefix
+argument, they perform ordinary string search, like
+@code{isearch-forward} and @code{isearch-backward}. @xref{Incremental
+Search}.
+
+@node Regexps, Search Case, Regexp Search, Search
+@section Syntax of Regular Expressions
+@cindex regexp syntax
+
+ Regular expressions have a syntax in which a few characters are
+special constructs and the rest are @dfn{ordinary}. An ordinary
+character is a simple regular expression which matches that same
+character and nothing else. The special characters are @samp{$},
+@samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, @samp{]} and
+@samp{\}. Any other character appearing in a regular expression is
+ordinary, unless a @samp{\} precedes it.
+
+ For example, @samp{f} is not a special character, so it is ordinary, and
+therefore @samp{f} is a regular expression that matches the string
+@samp{f} and no other string. (It does @emph{not} match the string
+@samp{ff}.) Likewise, @samp{o} is a regular expression that matches
+only @samp{o}. (When case distinctions are being ignored, these regexps
+also match @samp{F} and @samp{O}, but we consider this a generalization
+of ``the same string,'' rather than an exception.)
+
+ Any two regular expressions @var{a} and @var{b} can be concatenated. The
+result is a regular expression which matches a string if @var{a} matches
+some amount of the beginning of that string and @var{b} matches the rest of
+the string.@refill
+
+ As a simple example, we can concatenate the regular expressions @samp{f}
+and @samp{o} to get the regular expression @samp{fo}, which matches only
+the string @samp{fo}. Still trivial. To do something nontrivial, you
+need to use one of the special characters. Here is a list of them.
+
+@table @kbd
+@item .@: @r{(Period)}
+is a special character that matches any single character except a newline.
+Using concatenation, we can make regular expressions like @samp{a.b}, which
+matches any three-character string that begins with @samp{a} and ends with
+@samp{b}.@refill
+
+@item *
+is not a construct by itself; it is a postfix operator that means to
+match the preceding regular expression repetitively as many times as
+possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
+@samp{o}s).
+
+@samp{*} always applies to the @emph{smallest} possible preceding
+expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
+@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
+
+The matcher processes a @samp{*} construct by matching, immediately,
+as many repetitions as can be found. Then it continues with the rest
+of the pattern. If that fails, backtracking occurs, discarding some
+of the matches of the @samp{*}-modified construct in case that makes
+it possible to match the rest of the pattern. For example, in matching
+@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
+tries to match all three @samp{a}s; but the rest of the pattern is
+@samp{ar} and there is only @samp{r} left to match, so this try fails.
+The next alternative is for @samp{a*} to match only two @samp{a}s.
+With this choice, the rest of the regexp matches successfully.@refill
+
+@item +
+is a postfix operator, similar to @samp{*} except that it must match
+the preceding expression at least once. So, for example, @samp{ca+r}
+matches the strings @samp{car} and @samp{caaaar} but not the string
+@samp{cr}, whereas @samp{ca*r} matches all three strings.
+
+@item ?
+is a postfix operator, similar to @samp{*} except that it can match the
+preceding expression either once or not at all. For example,
+@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
+
+@item [ @dots{} ]
+is a @dfn{character set}, which begins with @samp{[} and is terminated
+by @samp{]}. In the simplest case, the characters between the two
+brackets are what this set can match.
+
+Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
+@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
+(including the empty string), from which it follows that @samp{c[ad]*r}
+matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
+
+You can also include character ranges in a character set, by writing the
+starting and ending characters with a @samp{-} between them. Thus,
+@samp{[a-z]} matches any lower-case ASCII letter. Ranges may be
+intermixed freely with individual characters, as in @samp{[a-z$%.]},
+which matches any lower-case ASCII letter or @samp{$}, @samp{%} or
+period.
+
+Note that the usual regexp special characters are not special inside a
+character set. A completely different set of special characters exists
+inside character sets: @samp{]}, @samp{-} and @samp{^}.
+
+To include a @samp{]} in a character set, you must make it the first
+character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
+include a @samp{-}, write @samp{-} as the first or last character of the
+set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]}
+and @samp{-}.
+
+To include @samp{^} in a set, put it anywhere but at the beginning of
+the set.
+
+When you use a range in case-insensitive search, you should write both
+ends of the range in upper case, or both in lower case, or both should
+be non-letters. The behavior of a mixed-case range such as @samp{A-z}
+is somewhat ill-defined, and it may change in future Emacs versions.
+
+@item [^ @dots{} ]
+@samp{[^} begins a @dfn{complemented character set}, which matches any
+character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches
+all characters @emph{except} letters and digits.
+
+@samp{^} is not special in a character set unless it is the first
+character. The character following the @samp{^} is treated as if it
+were first (in other words, @samp{-} and @samp{]} are not special there).
+
+A complemented character set can match a newline, unless newline is
+mentioned as one of the characters not to match. This is in contrast to
+the handling of regexps in programs such as @code{grep}.
+
+@item ^
+is a special character that matches the empty string, but only at the
+beginning of a line in the text being matched. Otherwise it fails to
+match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
+the beginning of a line.
+
+@item $
+is similar to @samp{^} but matches only at the end of a line. Thus,
+@samp{x+$} matches a string of one @samp{x} or more at the end of a line.
+
+@item \
+has two functions: it quotes the special characters (including
+@samp{\}), and it introduces additional special constructs.
+
+Because @samp{\} quotes special characters, @samp{\$} is a regular
+expression that matches only @samp{$}, and @samp{\[} is a regular
+expression that matches only @samp{[}, and so on.
+@end table
+
+Note: for historical compatibility, special characters are treated as
+ordinary ones if they are in contexts where their special meanings make no
+sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is
+no preceding expression on which the @samp{*} can act. It is poor practice
+to depend on this behavior; it is better to quote the special character anyway,
+regardless of where it appears.@refill
+
+For the most part, @samp{\} followed by any character matches only that
+character. However, there are several exceptions: two-character
+sequences starting with @samp{\} that have special meanings. The second
+character in the sequence is always an ordinary character when used on
+its own. Here is a table of @samp{\} constructs.
+
+@table @kbd
+@item \|
+specifies an alternative. Two regular expressions @var{a} and @var{b}
+with @samp{\|} in between form an expression that matches some text if
+either @var{a} matches it or @var{b} matches it. It works by trying to
+match @var{a}, and if that fails, by trying to match @var{b}.
+
+Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
+but no other string.@refill
+
+@samp{\|} applies to the largest possible surrounding expressions. Only a
+surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
+@samp{\|}.@refill
+
+Full backtracking capability exists to handle multiple uses of @samp{\|}.
+
+@item \( @dots{} \)
+is a grouping construct that serves three purposes:
+
+@enumerate
+@item
+To enclose a set of @samp{\|} alternatives for other operations.
+Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
+
+@item
+To enclose a complicated expression for the postfix operators @samp{*},
+@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
+@samp{bananana}, etc., with any (zero or more) number of @samp{na}
+strings.@refill
+
+@item
+To record a matched substring for future reference.
+@end enumerate
+
+This last application is not a consequence of the idea of a
+parenthetical grouping; it is a separate feature that is assigned as a
+second meaning to the same @samp{\( @dots{} \)} construct. In practice
+there is no conflict between the two meanings.
+
+@item \@var{d}
+matches the same text that matched the @var{d}th occurrence of a
+@samp{\( @dots{} \)} construct.
+
+After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
+the beginning and end of the text matched by that construct. Then,
+later on in the regular expression, you can use @samp{\} followed by the
+digit @var{d} to mean ``match the same text matched the @var{d}th time
+by the @samp{\( @dots{} \)} construct.''
+
+The strings matching the first nine @samp{\( @dots{} \)} constructs
+appearing in a regular expression are assigned numbers 1 through 9 in
+the order that the open-parentheses appear in the regular expression.
+So you can use @samp{\1} through @samp{\9} to refer to the text matched
+by the corresponding @samp{\( @dots{} \)} constructs.
+
+For example, @samp{\(.*\)\1} matches any newline-free string that is
+composed of two identical halves. The @samp{\(.*\)} matches the first
+half, which may be anything, but the @samp{\1} that follows must match
+the same exact text.
+
+If a particular @samp{\( @dots{} \)} construct matches more than once
+(which can easily happen if it is followed by @samp{*}), only the last
+match is recorded.
+
+@item \`
+matches the empty string, but only at the beginning
+of the buffer or string being matched against.
+
+@item \'
+matches the empty string, but only at the end of
+the buffer or string being matched against.
+
+@item \=
+matches the empty string, but only at point.
+
+@item \b
+matches the empty string, but only at the beginning or
+end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
+@samp{foo} as a separate word. @samp{\bballs?\b} matches
+@samp{ball} or @samp{balls} as a separate word.@refill
+
+@samp{\b} matches at the beginning or end of the buffer
+regardless of what text appears next to it.
+
+@item \B
+matches the empty string, but @emph{not} at the beginning or
+end of a word.
+
+@item \<
+matches the empty string, but only at the beginning of a word.
+@samp{\<} matches at the beginning of the buffer only if a
+word-constituent character follows.
+
+@item \>
+matches the empty string, but only at the end of a word. @samp{\>}
+matches at the end of the buffer only if the contents end with a
+word-constituent character.
+
+@item \w
+matches any word-constituent character. The syntax table
+determines which characters these are. @xref{Syntax}.
+
+@item \W
+matches any character that is not a word-constituent.
+
+@item \s@var{c}
+matches any character whose syntax is @var{c}. Here @var{c} is a
+character that represents a syntax code: thus, @samp{w} for word
+constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
+etc. Represent a character of whitespace (which can be a newline) by
+either @samp{-} or a space character.
+
+@item \S@var{c}
+matches any character whose syntax is not @var{c}.
+@end table
+
+ The constructs that pertain to words and syntax are controlled by the
+setting of the syntax table (@pxref{Syntax}).
+
+ Here is a complicated regexp, used by Emacs to recognize the end of a
+sentence together with any whitespace that follows. It is given in Lisp
+syntax to enable you to distinguish the spaces from the tab characters. In
+Lisp syntax, the string constant begins and ends with a double-quote.
+@samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a
+backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a
+newline.
+
+@example
+"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
+@end example
+
+@noindent
+This contains four parts in succession: a character set matching period,
+@samp{?}, or @samp{!}; a character set matching close-brackets, quotes,
+or parentheses, repeated any number of times; an alternative in
+backslash-parentheses that matches end-of-line, a tab, or two spaces;
+and a character set matching whitespace characters, repeated any number
+of times.
+
+ To enter the same regexp interactively, you would type @key{TAB} to
+enter a tab, and @kbd{C-j} to enter a newline. You would also type
+single backslashes as themselves, instead of doubling them for Lisp syntax.
+
+@node Search Case, Replace, Regexps, Search
+@section Searching and Case
+
+@vindex case-fold-search
+ Incremental searches in Emacs normally ignore the case of the text
+they are searching through, if you specify the text in lower case.
+Thus, if you specify searching for @samp{foo}, then @samp{Foo} and
+@samp{foo} are also considered a match. Regexps, and in particular
+character sets, are included: @samp{[ab]} would match @samp{a} or
+@samp{A} or @samp{b} or @samp{B}.@refill
+
+ An upper-case letter anywhere in the incremental search string makes
+the search case-sensitive. Thus, searching for @samp{Foo} does not find
+@samp{foo} or @samp{FOO}. This applies to regular expression search as
+well as to string search. The effect ceases if you delete the
+upper-case letter from the search string.
+
+ If you set the variable @code{case-fold-search} to @code{nil}, then
+all letters must match exactly, including case. This is a per-buffer
+variable; altering the variable affects only the current buffer, but
+there is a default value which you can change as well. @xref{Locals}.
+This variable applies to nonincremental searches also, including those
+performed by the replace commands (@pxref{Replace}) and the minibuffer
+history matching commands (@pxref{Minibuffer History}).
+
+@node Replace, Other Repeating Search, Search Case, Search
+@section Replacement Commands
+@cindex replacement
+@cindex search-and-replace commands
+@cindex string substitution
+@cindex global substitution
+
+ Global search-and-replace operations are not needed as often in Emacs
+as they are in other editors@footnote{In some editors,
+search-and-replace operations are the only convenient way to make a
+single change in the text.}, but they are available. In addition to the
+simple @kbd{M-x replace-string} command which is like that found in most
+editors, there is a @kbd{M-x query-replace} command which asks you, for
+each occurrence of the pattern, whether to replace it.
+
+ The replace commands normally operate on the text from point to the
+end of the buffer; however, in Transient Mark mode, when the mark is
+active, they operate on the region. The replace commands all replace
+one string (or regexp) with one replacement string. It is possible to
+perform several replacements in parallel using the command
+@code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
+
+@menu
+* Unconditional Replace:: Replacing all matches for a string.
+* Regexp Replace:: Replacing all matches for a regexp.
+* Replacement and Case:: How replacements preserve case of letters.
+* Query Replace:: How to use querying.
+@end menu
+
+@node Unconditional Replace, Regexp Replace, Replace, Replace
+@subsection Unconditional Replacement
+@findex replace-string
+@findex replace-regexp
+
+@table @kbd
+@item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
+Replace every occurrence of @var{string} with @var{newstring}.
+@item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
+Replace every match for @var{regexp} with @var{newstring}.
+@end table
+
+ To replace every instance of @samp{foo} after point with @samp{bar},
+use the command @kbd{M-x replace-string} with the two arguments
+@samp{foo} and @samp{bar}. Replacement happens only in the text after
+point, so if you want to cover the whole buffer you must go to the
+beginning first. All occurrences up to the end of the buffer are
+replaced; to limit replacement to part of the buffer, narrow to that
+part of the buffer before doing the replacement (@pxref{Narrowing}).
+In Transient Mark mode, when the region is active, replacement is
+limited to the region (@pxref{Transient Mark}).
+
+ When @code{replace-string} exits, it leaves point at the last
+occurrence replaced. It sets the mark to the prior position of point
+(where the @code{replace-string} command was issued); use @kbd{C-u
+C-@key{SPC}} to move back there.
+
+ A numeric argument restricts replacement to matches that are surrounded
+by word boundaries. The argument's value doesn't matter.
+
+@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
+@subsection Regexp Replacement
+
+ The @kbd{M-x replace-string} command replaces exact matches for a
+single string. The similar command @kbd{M-x replace-regexp} replaces
+any match for a specified pattern.
+
+ In @code{replace-regexp}, the @var{newstring} need not be constant: it
+can refer to all or part of what is matched by the @var{regexp}.
+@samp{\&} in @var{newstring} stands for the entire match being replaced.
+@samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for
+whatever matched the @var{d}th parenthesized grouping in @var{regexp}.
+To include a @samp{\} in the text to replace with, you must enter
+@samp{\\}. For example,
+
+@example
+M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
+@end example
+
+@noindent
+replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
+with @samp{cddr-safe}.
+
+@example
+M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
+@end example
+
+@noindent
+performs the inverse transformation.
+
+@node Replacement and Case, Query Replace, Regexp Replace, Replace
+@subsection Replace Commands and Case
+
+ If the first argument of a replace command is all lower case, the
+commands ignores case while searching for occurrences to
+replace---provided @code{case-fold-search} is non-@code{nil}. If
+@code{case-fold-search} is set to @code{nil}, case is always significant
+in all searches.
+
+@vindex case-replace
+ In addition, when the @var{newstring} argument is all or partly lower
+case, replacement commands try to preserve the case pattern of each
+occurrence. Thus, the command
+
+@example
+M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
+@end example
+
+@noindent
+replaces a lower case @samp{foo} with a lower case @samp{bar}, an
+all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with
+@samp{Bar}. (These three alternatives---lower case, all caps, and
+capitalized, are the only ones that @code{replace-string} can
+distinguish.)
+
+ If upper-case letters are used in the replacement string, they remain
+upper case every time that text is inserted. If upper-case letters are
+used in the first argument, the second argument is always substituted
+exactly as given, with no case conversion. Likewise, if either
+@code{case-replace} or @code{case-fold-search} is set to @code{nil},
+replacement is done without case conversion.
+
+@node Query Replace,, Replacement and Case, Replace
+@subsection Query Replace
+@cindex query replace
+
+@table @kbd
+@item M-% @var{string} @key{RET} @var{newstring} @key{RET}
+@itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
+Replace some occurrences of @var{string} with @var{newstring}.
+@item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
+@itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
+Replace some matches for @var{regexp} with @var{newstring}.
+@end table
+
+@kindex M-%
+@findex query-replace
+ If you want to change only some of the occurrences of @samp{foo} to
+@samp{bar}, not all of them, then you cannot use an ordinary
+@code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}).
+This command finds occurrences of @samp{foo} one by one, displays each
+occurrence and asks you whether to replace it. A numeric argument to
+@code{query-replace} tells it to consider only occurrences that are
+bounded by word-delimiter characters. This preserves case, just like
+@code{replace-string}, provided @code{case-replace} is non-@code{nil},
+as it normally is.
+
+@kindex C-M-%
+@findex query-replace-regexp
+ Aside from querying, @code{query-replace} works just like
+@code{replace-string}, and @code{query-replace-regexp} works just like
+@code{replace-regexp}. This command is run by @kbd{C-M-%}.
+
+ The things you can type when you are shown an occurrence of @var{string}
+or a match for @var{regexp} are:
+
+@ignore @c Not worth it.
+@kindex SPC @r{(query-replace)}
+@kindex DEL @r{(query-replace)}
+@kindex , @r{(query-replace)}
+@kindex RET @r{(query-replace)}
+@kindex . @r{(query-replace)}
+@kindex ! @r{(query-replace)}
+@kindex ^ @r{(query-replace)}
+@kindex C-r @r{(query-replace)}
+@kindex C-w @r{(query-replace)}
+@kindex C-l @r{(query-replace)}
+@end ignore
+
+@c WideCommands
+@table @kbd
+@item @key{SPC}
+to replace the occurrence with @var{newstring}.
+
+@item @key{DEL}
+to skip to the next occurrence without replacing this one.
+
+@item , @r{(Comma)}
+to replace this occurrence and display the result. You are then asked
+for another input character to say what to do next. Since the
+replacement has already been made, @key{DEL} and @key{SPC} are
+equivalent in this situation; both move to the next occurrence.
+
+You can type @kbd{C-r} at this point (see below) to alter the replaced
+text. You can also type @kbd{C-x u} to undo the replacement; this exits
+the @code{query-replace}, so if you want to do further replacement you
+must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart
+(@pxref{Repetition}).
+
+@item @key{RET}
+to exit without doing any more replacements.
+
+@item .@: @r{(Period)}
+to replace this occurrence and then exit without searching for more
+occurrences.
+
+@item !
+to replace all remaining occurrences without asking again.
+
+@item ^
+to go back to the position of the previous occurrence (or what used to
+be an occurrence), in case you changed it by mistake. This works by
+popping the mark ring. Only one @kbd{^} in a row is meaningful, because
+only one previous replacement position is kept during @code{query-replace}.
+
+@item C-r
+to enter a recursive editing level, in case the occurrence needs to be
+edited rather than just replaced with @var{newstring}. When you are
+done, exit the recursive editing level with @kbd{C-M-c} to proceed to
+the next occurrence. @xref{Recursive Edit}.
+
+@item C-w
+to delete the occurrence, and then enter a recursive editing level as in
+@kbd{C-r}. Use the recursive edit to insert text to replace the deleted
+occurrence of @var{string}. When done, exit the recursive editing level
+with @kbd{C-M-c} to proceed to the next occurrence.
+
+@item C-l
+to redisplay the screen. Then you must type another character to
+specify what to do with this occurrence.
+
+@item C-h
+to display a message summarizing these options. Then you must type
+another character to specify what to do with this occurrence.
+@end table
+
+ Some other characters are aliases for the ones listed above: @kbd{y},
+@kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and
+@key{RET}.
+
+ Aside from this, any other character exits the @code{query-replace},
+and is then reread as part of a key sequence. Thus, if you type
+@kbd{C-k}, it exits the @code{query-replace} and then kills to end of
+line.
+
+ To restart a @code{query-replace} once it is exited, use @kbd{C-x
+@key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it
+used the minibuffer to read its arguments. @xref{Repetition, C-x ESC
+ESC}.
+
+ See also @ref{Transforming File Names}, for Dired commands to rename,
+copy, or link files by replacing regexp matches in file names.
+
+@node Other Repeating Search,, Replace, Search
+@section Other Search-and-Loop Commands
+
+ Here are some other commands that find matches for a regular
+expression. They all operate from point to the end of the buffer, and
+all ignore case in matching, if the pattern contains no upper-case
+letters and @code{case-fold-search} is non-@code{nil}.
+
+@findex list-matching-lines
+@findex occur
+@findex count-matches
+@findex delete-non-matching-lines
+@findex delete-matching-lines
+@findex flush-lines
+@findex keep-lines
+
+@table @kbd
+@item M-x occur @key{RET} @var{regexp} @key{RET}
+Display a list showing each line in the buffer that contains a match for
+@var{regexp}. A numeric argument specifies the number of context lines
+to print before and after each matching line; the default is none.
+To limit the search to part of the buffer, narrow to that part
+(@pxref{Narrowing}).
+
+@kindex RET @r{(Occur mode)}
+The buffer @samp{*Occur*} containing the output serves as a menu for
+finding the occurrences in their original context. Click @kbd{Mouse-2}
+on an occurrence listed in @samp{*Occur*}, or position point there and
+type @key{RET}; this switches to the buffer that was searched and
+moves point to the original of the chosen occurrence.
+
+@item M-x list-matching-lines
+Synonym for @kbd{M-x occur}.
+
+@item M-x count-matches @key{RET} @var{regexp} @key{RET}
+Print the number of matches for @var{regexp} after point.
+
+@item M-x flush-lines @key{RET} @var{regexp} @key{RET}
+Delete each line that follows point and contains a match for
+@var{regexp}.
+
+@item M-x keep-lines @key{RET} @var{regexp} @key{RET}
+Delete each line that follows point and @emph{does not} contain a match
+for @var{regexp}.
+@end table
+
+ In addition, you can use @code{grep} from Emacs to search a collection
+of files for matches for a regular expression, then visit the matches
+either sequentially or in arbitrary order. @xref{Grep Searching}.
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Sending Mail, Rmail, Picture, Top
+@chapter Sending Mail
+@cindex sending mail
+@cindex mail
+@cindex message
+
+ To send a message in Emacs, you start by typing a command (@kbd{C-x m})
+to select and initialize the @samp{*mail*} buffer. Then you edit the text
+and headers of the message in this buffer, and type another command
+(@kbd{C-c C-s} or @kbd{C-c C-c}) to send the message.
+
+@table @kbd
+@item C-x m
+Begin composing a message to send (@code{compose-mail}).
+@item C-x 4 m
+Likewise, but display the message in another window
+(@code{compose-mail-other-window}).
+@item C-x 5 m
+Likewise, but make a new frame (@code{compose-mail-other-frame}).
+@item C-c C-s
+In Mail mode, send the message (@code{mail-send}).
+@item C-c C-c
+Send the message and bury the mail buffer (@code{mail-send-and-exit}).
+@end table
+
+@kindex C-x m
+@findex compose-mail
+@kindex C-x 4 m
+@findex compose-mail-other-window
+@kindex C-x 5 m
+@findex compose-mail-other-frame
+ The command @kbd{C-x m} (@code{compose-mail}) selects a buffer named
+@samp{*mail*} and initializes it with the skeleton of an outgoing
+message. @kbd{C-x 4 m} (@code{compose-mail-other-window}) selects the
+@samp{*mail*} buffer in a different window, leaving the previous current
+buffer visible. @kbd{C-x 5 m} (@code{compose-mail-other-frame}) creates
+a new frame to select the @samp{*mail*} buffer.
+
+ Because the mail-composition buffer is an ordinary Emacs buffer, you can
+switch to other buffers while in the middle of composing mail, and switch
+back later (or never). If you use the @kbd{C-x m} command again when you
+have been composing another message but have not sent it, you are asked to
+confirm before the old message is erased. If you answer @kbd{n}, the
+@samp{*mail*} buffer is left selected with its old contents, so you can
+finish the old message and send it. @kbd{C-u C-x m} is another way to do
+this. Sending the message marks the @samp{*mail*} buffer ``unmodified,''
+which avoids the need for confirmation when @kbd{C-x m} is next used.
+
+ If you are composing a message in the @samp{*mail*} buffer and want to
+send another message before finishing the first, rename the
+@samp{*mail*} buffer using @kbd{M-x rename-uniquely} (@pxref{Misc
+Buffer}). Then you can use @kbd{C-x m} or its variants described above
+to make a new @samp{*mail*} buffer. Once you've done that, you can work
+with each mail buffer independently.
+
+@menu
+* Format: Mail Format. Format of the mail being composed.
+* Headers: Mail Headers. Details of permitted mail header fields.
+* Aliases: Mail Aliases. Abbreviating and grouping mail addresses.
+* Mode: Mail Mode. Special commands for editing mail being composed.
+* Spook: Distracting NSA. How to distract the NSA's attention.
+* Mail Methods:: Using alternative mail-composition methods.
+@end menu
+
+@node Mail Format
+@section The Format of the Mail Buffer
+
+ In addition to the @dfn{text} or @dfn{body}, a message has @dfn{header
+fields} which say who sent it, when, to whom, why, and so on. Some
+header fields, such as @samp{Date} and @samp{Sender}, are created
+automatically when you send the message. Others, such as the recipient
+names, must be specified by you in order to send the message properly.
+
+ Mail mode provides a few commands to help you edit some header fields,
+and some are preinitialized in the buffer automatically at times. You can
+insert and edit header fields using ordinary editing commands.
+
+ The line in the buffer that says
+
+@example
+--text follows this line--
+@end example
+
+@noindent
+is a special delimiter that separates the headers you have specified from
+the text. Whatever follows this line is the text of the message; the
+headers precede it. The delimiter line itself does not appear in the
+message actually sent. The text used for the delimiter line is controlled
+by the variable @code{mail-header-separator}.
+
+Here is an example of what the headers and text in the mail buffer
+might look like.
+
+@example
+To: gnu@@gnu.org
+CC: lungfish@@spam.org, byob@@spam.org
+Subject: The Emacs Manual
+--Text follows this line--
+Please ignore this message.
+@end example
+
+@node Mail Headers
+@section Mail Header Fields
+@cindex headers (of mail message)
+
+ A header field in the mail buffer starts with a field name at the
+beginning of a line, terminated by a colon. Upper and lower case are
+equivalent in field names (and in mailing addresses also). After the
+colon and optional whitespace comes the contents of the field.
+
+ You can use any name you like for a header field, but normally people
+use only standard field names with accepted meanings. Here is a table
+of fields commonly used in outgoing messages.
+
+@table @samp
+@item To
+This field contains the mailing addresses to which the message is
+addressed. If you list more than one address, use commas, not spaces,
+to separate them.
+
+@item Subject
+The contents of the @samp{Subject} field should be a piece of text
+that says what the message is about. The reason @samp{Subject} fields
+are useful is that most mail-reading programs can provide a summary of
+messages, listing the subject of each message but not its text.
+
+@item CC
+This field contains additional mailing addresses to send the message to,
+like @samp{To} except that these readers should not regard the message
+as directed at them.
+
+@item BCC
+This field contains additional mailing addresses to send the message to,
+which should not appear in the header of the message actually sent.
+Copies sent this way are called @dfn{blind carbon copies}.
+
+@vindex mail-self-blind
+To send a blind carbon copy of every outgoing message to yourself, set
+the variable @code{mail-self-blind} to @code{t}.
+
+@item FCC
+This field contains the name of one file and directs Emacs to append a
+copy of the message to that file when you send the message. If the file
+is in Rmail format, Emacs writes the message in Rmail format; otherwise,
+Emacs writes the message in system mail file format.
+
+@vindex mail-archive-file-name
+To put a fixed file name in the @samp{FCC} field each time you start
+editing an outgoing message, set the variable
+@code{mail-archive-file-name} to that file name. Unless you remove the
+@samp{FCC} field before sending, the message will be written into that
+file when it is sent.
+
+@item From
+Use the @samp{From} field to say who you are, when the account you are
+using to send the mail is not your own. The contents of the @samp{From}
+field should be a valid mailing address, since replies will normally go
+there. If you don't specify the @samp{From} field yourself, Emacs uses
+the value of @code{user-mail-address} as the default.
+
+@item Reply-to
+Use this field to direct replies to a different address. Most
+mail-reading programs (including Rmail) automatically send replies to
+the @samp{Reply-to} address in preference to the @samp{From} address.
+By adding a @samp{Reply-to} field to your header, you can work around
+any problems your @samp{From} address may cause for replies.
+
+@cindex @code{REPLYTO} environment variable
+@vindex mail-default-reply-to
+To put a fixed @samp{Reply-to} address into every outgoing message, set
+the variable @code{mail-default-reply-to} to that address (as a string).
+Then @code{mail} initializes the message with a @samp{Reply-to} field as
+specified. You can delete or alter that header field before you send
+the message, if you wish. When Emacs starts up, if the environment
+variable @code{REPLYTO} is set, @code{mail-default-reply-to} is
+initialized from that environment variable.
+
+@item In-reply-to
+This field contains a piece of text describing a message you are
+replying to. Some mail systems can use this information to correlate
+related pieces of mail. Normally this field is filled in by Rmail
+when you reply to a message in Rmail, and you never need to
+think about it (@pxref{Rmail}).
+
+@item References
+This field lists the message IDs of related previous messages. Rmail
+sets up this field automatically when you reply to a message.
+@end table
+
+ The @samp{To}, @samp{CC}, @samp{BCC} and @samp{FCC} header fields can
+appear any number of times, and each such header field can contain
+multiple addresses, separated by commas. This way, you can specify any
+number of places to send the message. A @samp{To}, @samp{CC}, or
+@samp{BCC} field can also have continuation lines: one or more lines
+starting with whitespace, following the starting line of the field, are
+considered part of the field. Here's an example of a @samp{To} field
+with a continuation line:@refill
+
+@example
+@group
+To: foo@@here.net, this@@there.net,
+ me@@gnu.cambridge.mass.usa.earth.spiral3281
+@end group
+@end example
+
+@vindex mail-from-style
+ When you send the message, if you didn't write a @samp{From} field
+yourself, Emacs puts in one for you. The variable
+@code{mail-from-style} controls the format:
+
+@table @code
+@item nil
+Use just the email address, as in @samp{king@@grassland.com}.
+@item parens
+Use both email address and full name, as in @samp{king@@grassland.com (Elvis
+Parsley)}.
+@item angles
+Use both email address and full name, as in @samp{Elvis Parsley
+<king@@grassland.com>}.
+@item system-default
+Allow the system to insert the @samp{From} field.
+@end table
+
+@node Mail Aliases
+@section Mail Aliases
+@cindex mail aliases
+@cindex @file{.mailrc} file
+@cindex mailrc file
+
+ You can define @dfn{mail aliases} in a file named @file{~/.mailrc}.
+These are short mnemonic names which stand for mail addresses or groups of
+mail addresses. Like many other mail programs, Emacs expands aliases
+when they occur in the @samp{To}, @samp{From}, @samp{CC}, @samp{BCC}, and
+@samp{Reply-to} fields, plus their @samp{Resent-} variants.
+
+ To define an alias in @file{~/.mailrc}, write a line in the following
+format:
+
+@example
+alias @var{shortaddress} @var{fulladdresses}
+@end example
+
+@noindent
+Here @var{fulladdresses} stands for one or more mail addresses for
+@var{shortaddress} to expand into. Separate multiple addresses with
+spaces; if an address contains a space, quote the whole address with a
+pair of double-quotes.
+
+For instance, to make @code{maingnu} stand for
+@code{gnu@@gnu.org} plus a local address of your own, put in
+this line:@refill
+
+@example
+alias maingnu gnu@@gnu.org local-gnu
+@end example
+
+ Emacs also recognizes include commands in @samp{.mailrc} files.
+They look like this:
+
+@example
+source @var{filename}
+@end example
+
+@noindent
+The file @file{~/.mailrc} is used primarily by other mail-reading
+programs; it can contain various other commands. Emacs ignores
+everything in it except for alias definitions and include commands.
+
+@findex define-mail-alias
+ Another way to define a mail alias, within Emacs alone, is with the
+@code{define-mail-alias} command. It prompts for the alias and then the
+full address. You can use it to define aliases in your @file{.emacs}
+file, like this:
+
+@example
+(define-mail-alias "maingnu" "gnu@@gnu.org")
+@end example
+
+@vindex mail-aliases
+ @code{define-mail-alias} records aliases by adding them to a
+variable named @code{mail-aliases}. If you are comfortable with
+manipulating Lisp lists, you can set @code{mail-aliases} directly. The
+initial value of @code{mail-aliases} is @code{t}, which means that
+Emacs should read @file{.mailrc} to get the proper value.
+
+@vindex mail-personal-alias-file
+ You can specify a different file name to use instead of
+@file{~/.mailrc} by setting the variable
+@code{mail-personal-alias-file}.
+
+@findex expand-mail-aliases
+ Normally, Emacs expands aliases when you send the message. You do not
+need to expand mail aliases before sending the message, but you can
+expand them if you want to see where the mail will actually go. To do
+this, use the command @kbd{M-x expand-mail-aliases}; it expands all mail
+aliases currently present in the mail headers that hold addresses.
+
+ If you like, you can have mail aliases expand as abbrevs, as soon as
+you type them in (@pxref{Abbrevs}). To enable this feature, execute the
+following:
+
+@example
+(add-hook 'mail-setup-hook 'mail-abbrevs-setup)
+@end example
+
+@noindent
+@findex define-mail-abbrev
+@vindex mail-abbrevs
+This can go in your @file{.emacs} file. @xref{Hooks}. If you use this
+feature, you must use @code{define-mail-abbrev} instead of
+@code{define-mail-alias}; the latter does not work with this package.
+Note that the mail abbreviation package uses the variable
+@code{mail-abbrevs} instead of @code{mail-aliases}, and that all alias
+names are converted to lower case.
+
+@kindex C-c C-a @r{(Mail mode)}
+@findex mail-interactive-insert-alias
+ The mail abbreviation package also provides the @kbd{C-c C-a}
+(@code{mail-interactive-insert-alias}) command, which reads an alias
+name (with completion) and inserts its definition at point. This is
+useful when editing the message text itself or a header field such as
+@samp{Subject} in which Emacs does not normally expand aliases.
+
+ Note that abbrevs expand only if you insert a word-separator character
+afterward. However, you can rebind @kbd{C-n} and @kbd{M->} to cause
+expansion as well. Here's how to do that:
+
+@smallexample
+(add-hook 'mail-setup-hook
+ '(lambda ()
+ (substitute-key-definition
+ 'next-line 'mail-abbrev-next-line
+ mail-mode-map global-map)
+ (substitute-key-definition
+ 'end-of-buffer 'mail-abbrev-end-of-buffer
+ mail-mode-map global-map)))
+@end smallexample
+
+@node Mail Mode
+@section Mail Mode
+@cindex Mail mode
+@cindex mode, Mail
+
+ The major mode used in the mail buffer is Mail mode, which is much
+like Text mode except that various special commands are provided on the
+@kbd{C-c} prefix. These commands all have to do specifically with
+editing or sending the message. In addition, Mail mode defines the
+character @samp{%} as a word separator; this is helpful for using the
+word commands to edit mail addresses.
+
+ Mail mode is normally used in buffers set up automatically by the
+@code{mail} command and related commands. However, you can also switch
+to Mail mode in a file-visiting buffer. That is a useful thing to do if
+you have saved draft message text in a file.
+
+@menu
+* Mail Sending:: Commands to send the message.
+* Header Editing:: Commands to move to header fields and edit them.
+* Citing Mail:: Copying all or part of a message you are replying to.
+* Mail Mode Misc:: Spell checking, signatures, etc.
+@end menu
+
+@node Mail Sending
+@subsection Mail Sending
+
+ Mail mode has two commands for sending the message you have been
+editing:
+
+@table @kbd
+@item C-c C-s
+Send the message, and leave the mail buffer selected (@code{mail-send}).
+@item C-c C-c
+Send the message, and select some other buffer (@code{mail-send-and-exit}).
+@end table
+
+@kindex C-c C-s @r{(Mail mode)}
+@kindex C-c C-c @r{(Mail mode)}
+@findex mail-send
+@findex mail-send-and-exit
+ @kbd{C-c C-s} (@code{mail-send}) sends the message and marks the mail
+buffer unmodified, but leaves that buffer selected so that you can
+modify the message (perhaps with new recipients) and send it again.
+@kbd{C-c C-c} (@code{mail-send-and-exit}) sends and then deletes the
+window or switches to another buffer. It puts the mail buffer at the
+lowest priority for reselection by default, since you are finished with
+using it. This is the usual way to send the message.
+
+ In a file-visiting buffer, sending the message does not clear the
+modified flag, because only saving the file should do that. As a
+result, you don't get a warning if you try to send the same message
+twice.
+
+@vindex sendmail-coding-system
+ When you send a message that contains non-ASCII characters, they need
+to be encoded with a coding system (@pxref{Coding Systems}). Usually
+the coding system is specified automatically by your chosen language
+environment (@pxref{Language Environments}). You can explicitly specify
+the coding system for outgoing mail by setting the variable
+@code{sendmail-coding-system}.
+
+ If the coding system thus determined does not handle the characters in
+a particular message, Emacs asks you to select the coding system to use,
+showing a list of possible coding systems.
+
+@node Header Editing
+@subsection Mail Header Editing
+
+ Mail mode provides special commands to move to particular header
+fields and to complete addresses in headers.
+
+@table @kbd
+@item C-c C-f C-t
+Move to the @samp{To} header field, creating one if there is none
+(@code{mail-to}).
+@item C-c C-f C-s
+Move to the @samp{Subject} header field, creating one if there is
+none (@code{mail-subject}).
+@item C-c C-f C-c
+Move to the @samp{CC} header field, creating one if there is none
+(@code{mail-cc}).
+@item C-c C-f C-b
+Move to the @samp{BCC} header field, creating one if there is none
+(@code{mail-bcc}).
+@item C-c C-f C-f
+Move to the @samp{FCC} header field, creating one if there is none
+(@code{mail-fcc}).
+@item M-@key{TAB}
+Complete a mailing address (@code{mail-complete}).
+@end table
+
+@kindex C-c C-f C-t @r{(Mail mode)}
+@findex mail-to
+@kindex C-c C-f C-s @r{(Mail mode)}
+@findex mail-subject
+@kindex C-c C-f C-c @r{(Mail mode)}
+@findex mail-cc
+@kindex C-c C-f C-b @r{(Mail mode)}
+@findex mail-bcc
+@kindex C-c C-f C-f @r{(Mail mode)}
+@findex mail-fcc
+ There are five commands to move point to particular header fields, all
+based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). They
+are listed in the table above. If the field in question does not exist,
+these commands create one. We provide special motion commands for these
+particular fields because they are the fields users most often want to
+edit.
+
+@findex mail-complete
+@kindex M-TAB @r{(Mail mode)}
+ While editing a header field that contains mailing addresses, such as
+@samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete a mailing
+address by typing @kbd{M-@key{TAB}} (@code{mail-complete}). It inserts
+the full name corresponding to the address, if it can determine the full
+name. The variable @code{mail-complete-style} controls whether to insert
+the full name, and what style to use, as in @code{mail-from-style}
+(@pxref{Mail Headers}).
+
+ For completion purposes, the valid mailing addresses are taken to be
+the local users' names plus your personal mail aliases. You can specify
+additional sources of valid addresses; use the customization buffer
+to see the options for this.
+
+ If you type @kbd{M-@key{TAB}} in the body of the message, it invokes
+@code{ispell-complete-word}, as in Text mode.
+
+@node Citing Mail
+@subsection Citing Mail
+@cindex citing mail
+
+ Mail mode also has commands for yanking or @dfn{citing} all or part of
+a message that you are replying to. These commands are active only when
+you started sending a message using an Rmail command.
+
+@table @kbd
+@item C-c C-y
+Yank the selected message from Rmail (@code{mail-yank-original}).
+@item C-c C-r
+Yank the region from the Rmail buffer (@code{mail-yank-region}).
+@item C-c C-q
+Fill each paragraph cited from another message
+(@code{mail-fill-yanked-message}).
+@end table
+
+@kindex C-c C-y @r{(Mail mode)}
+@findex mail-yank-original
+ When mail sending is invoked from the Rmail mail reader using an Rmail
+command, @kbd{C-c C-y} can be used inside the mail buffer to insert
+the text of the message you are replying to. Normally it indents each line
+of that message three spaces and eliminates most header fields. A numeric
+argument specifies the number of spaces to indent. An argument of just
+@kbd{C-u} says not to indent at all and not to eliminate anything.
+@kbd{C-c C-y} always uses the current message from the Rmail buffer,
+so you can insert several old messages by selecting one in Rmail,
+switching to @samp{*mail*} and yanking it, then switching back to
+Rmail to select another.
+
+@vindex mail-yank-prefix
+ You can specify the text for @kbd{C-c C-y} to insert at the beginning
+of each line: set @code{mail-yank-prefix} to the desired string. (A
+value of @code{nil} means to use indentation; this is the default.)
+However, @kbd{C-u C-c C-y} never adds anything at the beginning of the
+inserted lines, regardless of the value of @code{mail-yank-prefix}.
+
+@kindex C-c C-r @r{(Mail mode)}
+@findex mail-yank-region
+ To yank just a part of an incoming message, set the region in Rmail to
+the part you want; then go to the @samp{*Mail*} message and type
+@kbd{C-c C-r} (@code{mail-yank-region}). Each line that is copied is
+indented or prefixed according to @code{mail-yank-prefix}.
+
+@kindex C-c C-q @r{(Mail mode)}
+@findex mail-fill-yanked-message
+ After using @kbd{C-c C-y} or @kbd{C-c C-r}, you can type @kbd{C-c C-q}
+(@code{mail-fill-yanked-message}) to fill the paragraphs of the yanked
+old message or messages. One use of @kbd{C-c C-q} fills all such
+paragraphs, each one individually. To fill a single paragraph of the
+quoted message, use @kbd{M-q}. If filling does not automatically
+handle the type of citation prefix you use, try setting the fill prefix
+explicitly. @xref{Filling}.
+
+@node Mail Mode Misc
+@subsection Mail Mode Miscellany
+
+@table @kbd
+@item C-c C-t
+Move to the beginning of the message body text (@code{mail-text}).
+@item C-c C-w
+Insert the file @file{~/.signature} at the end of the message text
+(@code{mail-signature}).
+@item C-c C-i @var{file} @key{RET}
+Insert the contents of @var{file} at the end of the outgoing message
+(@code{mail-attach-file}).
+@item M-x ispell-message
+Do spelling correction on the message text, but not on citations from
+other messages.
+@end table
+
+@kindex C-c C-t @r{(Mail mode)}
+@findex mail-text
+ @kbd{C-c C-t} (@code{mail-text}) moves point to just after the header
+separator line---that is, to the beginning of the message body text.
+
+@kindex C-c C-w @r{(Mail mode)}
+@findex mail-signature
+@vindex mail-signature
+ @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece of text at
+the end of the message to say more about who you are. The text comes
+from the file @file{~/.signature} in your home directory. To insert
+your signature automatically, set the variable @code{mail-signature} to
+@code{t}; then starting a mail message automatically inserts the
+contents of your @file{~/.signature} file. If you want to omit your
+signature from a particular message, delete it from the buffer before
+you send the message.
+
+ You can also set @code{mail-signature} to a string; then that string
+is inserted automatically as your signature when you start editing a
+message to send. If you set it to some other Lisp expression, the
+expression is evaluated each time, and its value (which should be a
+string) specifies the signature.
+
+@findex ispell-message
+ You can do spelling correction on the message text you have written
+with the command @kbd{M-x ispell-message}. If you have yanked an
+incoming message into the outgoing draft, this command skips what was
+yanked, but it checks the text that you yourself inserted. (It looks
+for indentation or @code{mail-yank-prefix} to distinguish the cited
+lines from your input.) @xref{Spelling}.
+
+@kindex C-c C-i @r{(Mail mode)}
+@findex mail-attach-file
+ To include a file in the outgoing message, you can use @kbd{C-x i},
+the usual command to insert a file in the current buffer. But it is
+often more convenient to use a special command, @kbd{C-c C-i}
+(@code{mail-attach-file}). This command inserts the file contents at
+the end of the buffer, after your signature if any, with a delimiter
+line that includes the file name.
+
+@vindex mail-mode-hook
+@vindex mail-setup-hook
+ Turning on Mail mode (which @kbd{C-x m} does automatically) runs the
+normal hooks @code{text-mode-hook} and @code{mail-mode-hook}.
+Initializing a new outgoing message runs the normal hook
+@code{mail-setup-hook}; if you want to add special fields to your mail
+header or make other changes to the appearance of the mail buffer, use
+that hook. @xref{Hooks}.
+
+ The main difference between these hooks is just when they are
+invoked. Whenever you type @kbd{M-x mail}, @code{mail-mode-hook} runs
+as soon as the @samp{*mail*} buffer is created. Then the
+@code{mail-setup} function puts in the default contents of the buffer.
+After these default contents are inserted, @code{mail-setup-hook} runs.
+
+@node Distracting NSA
+@section Distracting the NSA
+
+@findex spook
+@cindex NSA
+ @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing
+mail message. The keywords are chosen from a list of words that suggest
+you are discussing something subversive.
+
+ The idea behind this feature is the suspicion that the NSA snoops on
+all electronic mail messages that contain keywords suggesting they might
+find them interesting. (The NSA says they don't, but that's what they
+@emph{would} say.) The idea is that if lots of people add suspicious
+words to their messages, the NSA will get so busy with spurious input
+that they will have to give up reading it all.
+
+ Here's how to insert spook keywords automatically whenever you start
+entering an outgoing message:
+
+@example
+(add-hook 'mail-setup-hook 'spook)
+@end example
+
+ Whether or not this confuses the NSA, it at least amuses people.
+
+@node Mail Methods
+@section Mail-Composition Methods
+@cindex mail-composition methods
+
+ This chapter describes the usual Emacs mode for editing and sending
+mail---Mail mode. Emacs has alternative facilities for editing and
+sending mail, including MH-E and Message mode, not documented in this
+manual. You can choose any of them as your preferred method. The
+commands @code{C-x m}, @code{C-x 4 m} and @code{C-x 5 m} use whichever
+agent you have specified. So do various other Emacs commands and
+facilities that send mail.
+
+@vindex mail-user-agent
+ To specify your mail-composition method, set the variable
+@code{mail-user-agent}. Currently legitimate values include
+@code{sendmail-user-agent}, @code{mh-e-user-agent}, and
+@code{message-user-agent}.
+
+ If you select a different mail-composition method, the information in
+this chapter about the @samp{*mail*} buffer and Mail mode does not
+apply; other methods may use completely different commands with a
+different format in a differently named buffer.
+
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Text, Programs, Indentation, Top
+@chapter Commands for Human Languages
+@cindex text
+@cindex manipulating text
+
+ The term @dfn{text} has two widespread meanings in our area of the
+computer field. One is data that is a sequence of characters. Any file
+that you edit with Emacs is text, in this sense of the word. The other
+meaning is more restrictive: a sequence of characters in a human language
+for humans to read (possibly after processing by a text formatter), as
+opposed to a program or commands for a program.
+
+ Human languages have syntactic/stylistic conventions that can be
+supported or used to advantage by editor commands: conventions involving
+words, sentences, paragraphs, and capital letters. This chapter
+describes Emacs commands for all of these things. There are also
+commands for @dfn{filling}, which means rearranging the lines of a
+paragraph to be approximately equal in length. The commands for moving
+over and killing words, sentences and paragraphs, while intended
+primarily for editing text, are also often useful for editing programs.
+
+ Emacs has several major modes for editing human-language text. If the
+file contains text pure and simple, use Text mode, which customizes
+Emacs in small ways for the syntactic conventions of text. Outline mode
+provides special commands for operating on text with an outline
+structure.
+@iftex
+@xref{Outline Mode}.
+@end iftex
+
+ For text which contains embedded commands for text formatters, Emacs
+has other major modes, each for a particular text formatter. Thus, for
+input to @TeX{}, you would use @TeX{}
+@iftex
+mode (@pxref{TeX Mode}).
+@end iftex
+@ifinfo
+mode.
+@end ifinfo
+For input to nroff, use Nroff mode.
+
+ Instead of using a text formatter, you can edit formatted text in
+WYSIWYG style (``what you see is what you get''), with Enriched mode.
+Then the formatting appears on the screen in Emacs while you edit.
+@iftex
+@xref{Formatted Text}.
+@end iftex
+
+@menu
+* Words:: Moving over and killing words.
+* Sentences:: Moving over and killing sentences.
+* Paragraphs:: Moving over paragraphs.
+* Pages:: Moving over pages.
+* Filling:: Filling or justifying text.
+* Case:: Changing the case of text.
+* Text Mode:: The major modes for editing text files.
+* Outline Mode:: Editing outlines.
+* TeX Mode:: Editing input to the formatter TeX.
+* Nroff Mode:: Editing input to the formatter nroff.
+* Formatted Text:: Editing formatted text directly in WYSIWYG fashion.
+@end menu
+
+@node Words
+@section Words
+@cindex words
+@cindex Meta commands and words
+
+ Emacs has commands for moving over or operating on words. By convention,
+the keys for them are all Meta characters.
+
+@c widecommands
+@table @kbd
+@item M-f
+Move forward over a word (@code{forward-word}).
+@item M-b
+Move backward over a word (@code{backward-word}).
+@item M-d
+Kill up to the end of a word (@code{kill-word}).
+@item M-@key{DEL}
+Kill back to the beginning of a word (@code{backward-kill-word}).
+@item M-@@
+Mark the end of the next word (@code{mark-word}).
+@item M-t
+Transpose two words or drag a word across other words
+(@code{transpose-words}).
+@end table
+
+ Notice how these keys form a series that parallels the character-based
+@kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is
+cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}.
+
+@kindex M-f
+@kindex M-b
+@findex forward-word
+@findex backward-word
+ The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b}
+(@code{backward-word}) move forward and backward over words. These
+Meta characters are thus analogous to the corresponding control
+characters, @kbd{C-f} and @kbd{C-b}, which move over single characters
+in the text. The analogy extends to numeric arguments, which serve as
+repeat counts. @kbd{M-f} with a negative argument moves backward, and
+@kbd{M-b} with a negative argument moves forward. Forward motion
+stops right after the last letter of the word, while backward motion
+stops right before the first letter.@refill
+
+@kindex M-d
+@findex kill-word
+ @kbd{M-d} (@code{kill-word}) kills the word after point. To be
+precise, it kills everything from point to the place @kbd{M-f} would
+move to. Thus, if point is in the middle of a word, @kbd{M-d} kills
+just the part after point. If some punctuation comes between point and the
+next word, it is killed along with the word. (If you wish to kill only the
+next word but not the punctuation before it, simply do @kbd{M-f} to get
+the end, and kill the word backwards with @kbd{M-@key{DEL}}.)
+@kbd{M-d} takes arguments just like @kbd{M-f}.
+
+@findex backward-kill-word
+@kindex M-DEL
+ @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before
+point. It kills everything from point back to where @kbd{M-b} would
+move to. If point is after the space in @w{@samp{FOO, BAR}}, then
+@w{@samp{FOO, }} is killed. (If you wish to kill just @samp{FOO}, and
+not the comma and the space, use @kbd{M-b M-d} instead of
+@kbd{M-@key{DEL}}.)
+
+@kindex M-t
+@findex transpose-words
+ @kbd{M-t} (@code{transpose-words}) exchanges the word before or
+containing point with the following word. The delimiter characters between
+the words do not move. For example, @w{@samp{FOO, BAR}} transposes into
+@w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for
+more on transposition and on arguments to transposition commands.
+
+@kindex M-@@
+@findex mark-word
+ To operate on the next @var{n} words with an operation which applies
+between point and mark, you can either set the mark at point and then move
+over the words, or you can use the command @kbd{M-@@} (@code{mark-word})
+which does not move point, but sets the mark where @kbd{M-f} would move
+to. @kbd{M-@@} accepts a numeric argument that says how many words to
+scan for the place to put the mark. In Transient Mark mode, this command
+activates the mark.
+
+ The word commands' understanding of syntax is completely controlled by
+the syntax table. Any character can, for example, be declared to be a word
+delimiter. @xref{Syntax}.
+
+@node Sentences
+@section Sentences
+@cindex sentences
+@cindex manipulating sentences
+
+ The Emacs commands for manipulating sentences and paragraphs are mostly
+on Meta keys, so as to be like the word-handling commands.
+
+@table @kbd
+@item M-a
+Move back to the beginning of the sentence (@code{backward-sentence}).
+@item M-e
+Move forward to the end of the sentence (@code{forward-sentence}).
+@item M-k
+Kill forward to the end of the sentence (@code{kill-sentence}).
+@item C-x @key{DEL}
+Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
+@end table
+
+@kindex M-a
+@kindex M-e
+@findex backward-sentence
+@findex forward-sentence
+ The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and
+@code{forward-sentence}) move to the beginning and end of the current
+sentence, respectively. They were chosen to resemble @kbd{C-a} and
+@kbd{C-e}, which move to the beginning and end of a line. Unlike them,
+@kbd{M-a} and @kbd{M-e} if repeated or given numeric arguments move over
+successive sentences.
+
+ Moving backward over a sentence places point just before the first
+character of the sentence; moving forward places point right after the
+punctuation that ends the sentence. Neither one moves over the
+whitespace at the sentence boundary.
+
+@kindex M-k
+@kindex C-x DEL
+@findex kill-sentence
+@findex backward-kill-sentence
+ Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go
+with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command
+@kbd{M-k} (@code{kill-sentence}) which kills from point to the end of
+the sentence. With minus one as an argument it kills back to the
+beginning of the sentence. Larger arguments serve as a repeat count.
+There is also a command, @kbd{C-x @key{DEL}}
+(@code{backward-kill-sentence}), for killing back to the beginning of a
+sentence. This command is useful when you change your mind in the
+middle of composing text.@refill
+
+ The sentence commands assume that you follow the American typist's
+convention of putting two spaces at the end of a sentence; they consider
+a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!}
+followed by the end of a line or two spaces, with any number of
+@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between.
+A sentence also begins or ends wherever a paragraph begins or ends.
+
+@vindex sentence-end
+ The variable @code{sentence-end} controls recognition of the end of a
+sentence. It is a regexp that matches the last few characters of a
+sentence, together with the whitespace following the sentence. Its
+normal value is
+
+@example
+"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
+@end example
+
+@noindent
+This example is explained in the section on regexps. @xref{Regexps}.
+
+ If you want to use just one space between sentences, you should
+set @code{sentence-end} to this value:
+
+@example
+"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
+@end example
+
+@noindent
+You should also set the variable @code{sentence-end-double-space} to
+@code{nil} so that the fill commands expect and leave just one space at
+the end of a sentence. Note that this makes it impossible to
+distinguish between periods that end sentences and those that indicate
+abbreviations.
+
+@node Paragraphs
+@section Paragraphs
+@cindex paragraphs
+@cindex manipulating paragraphs
+@kindex M-@{
+@kindex M-@}
+@findex backward-paragraph
+@findex forward-paragraph
+
+ The Emacs commands for manipulating paragraphs are also Meta keys.
+
+@table @kbd
+@item M-@{
+Move back to previous paragraph beginning (@code{backward-paragraph}).
+@item M-@}
+Move forward to next paragraph end (@code{forward-paragraph}).
+@item M-h
+Put point and mark around this or next paragraph (@code{mark-paragraph}).
+@end table
+
+ @kbd{M-@{} moves to the beginning of the current or previous
+paragraph, while @kbd{M-@}} moves to the end of the current or next
+paragraph. Blank lines and text-formatter command lines separate
+paragraphs and are not considered part of any paragraph. In Fundamental
+mode, but not in Text mode, an indented line also starts a new
+paragraph. (If a paragraph is preceded by a blank line, these commands
+treat that blank line as the beginning of the paragraph.)
+
+ In major modes for programs, paragraphs begin and end only at blank
+lines. This makes the paragraph commands continue to be useful even
+though there are no paragraphs per se.
+
+ When there is a fill prefix, then paragraphs are delimited by all lines
+which don't start with the fill prefix. @xref{Filling}.
+
+@kindex M-h
+@findex mark-paragraph
+ When you wish to operate on a paragraph, you can use the command
+@kbd{M-h} (@code{mark-paragraph}) to set the region around it. Thus,
+for example, @kbd{M-h C-w} kills the paragraph around or after point.
+The @kbd{M-h} command puts point at the beginning and mark at the end of
+the paragraph point was in. In Transient Mark mode, it activates the
+mark. If point is between paragraphs (in a run of blank lines, or at a
+boundary), the paragraph following point is surrounded by point and
+mark. If there are blank lines preceding the first line of the
+paragraph, one of these blank lines is included in the region.
+
+@vindex paragraph-start
+@vindex paragraph-separate
+ The precise definition of a paragraph boundary is controlled by the
+variables @code{paragraph-separate} and @code{paragraph-start}. The
+value of @code{paragraph-start} is a regexp that should match any line
+that either starts or separates paragraphs. The value of
+@code{paragraph-separate} is another regexp that should match only lines
+that separate paragraphs without being part of any paragraph (for
+example, blank lines). Lines that start a new paragraph and are
+contained in it must match only @code{paragraph-start}, not
+@code{paragraph-separate}. For example, in Fundamental mode,
+@code{paragraph-start} is @code{"[ @t{\}t@t{\}n@t{\}f]"} and
+@code{paragraph-separate} is @code{"[ @t{\}t@t{\}f]*$"}.@refill
+
+ Normally it is desirable for page boundaries to separate paragraphs.
+The default values of these variables recognize the usual separator for
+pages.
+
+@node Pages
+@section Pages
+
+@cindex pages
+@cindex formfeed
+ Files are often thought of as divided into @dfn{pages} by the
+@dfn{formfeed} character (ASCII control-L, octal code 014). When you
+print hardcopy for a file, this character forces a page break; thus,
+each page of the file goes on a separate page on paper. Most Emacs
+commands treat the page-separator character just like any other
+character: you can insert it with @kbd{C-q C-l}, and delete it with
+@key{DEL}. Thus, you are free to paginate your file or not. However,
+since pages are often meaningful divisions of the file, Emacs provides
+commands to move over them and operate on them.
+
+@c WideCommands
+@table @kbd
+@item C-x [
+Move point to previous page boundary (@code{backward-page}).
+@item C-x ]
+Move point to next page boundary (@code{forward-page}).
+@item C-x C-p
+Put point and mark around this page (or another page) (@code{mark-page}).
+@item C-x l
+Count the lines in this page (@code{count-lines-page}).
+@end table
+
+@kindex C-x [
+@kindex C-x ]
+@findex forward-page
+@findex backward-page
+ The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
+after the previous page delimiter. If point is already right after a page
+delimiter, it skips that one and stops at the previous one. A numeric
+argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page})
+command moves forward past the next page delimiter.
+
+@kindex C-x C-p
+@findex mark-page
+ The @kbd{C-x C-p} command (@code{mark-page}) puts point at the
+beginning of the current page and the mark at the end. The page
+delimiter at the end is included (the mark follows it). The page
+delimiter at the front is excluded (point follows it). @kbd{C-x C-p
+C-w} is a handy way to kill a page to move it elsewhere. If you move to
+another page delimiter with @kbd{C-x [} and @kbd{C-x ]}, then yank the
+killed page, all the pages will be properly delimited once again. The
+reason @kbd{C-x C-p} includes only the following page delimiter in the
+region is to ensure that.
+
+ A numeric argument to @kbd{C-x C-p} is used to specify which page to go
+to, relative to the current one. Zero means the current page. One means
+the next page, and @minus{}1 means the previous one.
+
+@kindex C-x l
+@findex count-lines-page
+ The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
+where to break a page in two. It prints in the echo area the total number
+of lines in the current page, and then divides it up into those preceding
+the current line and those following, as in
+
+@example
+Page has 96 (72+25) lines
+@end example
+
+@noindent
+ Notice that the sum is off by one; this is correct if point is not at the
+beginning of a line.
+
+@vindex page-delimiter
+ The variable @code{page-delimiter} controls where pages begin. Its
+value is a regexp that matches the beginning of a line that separates
+pages. The normal value of this variable is @code{"^@t{\}f"}, which
+matches a formfeed character at the beginning of a line.
+
+@node Filling
+@section Filling Text
+@cindex filling text
+
+ @dfn{Filling} text means breaking it up into lines that fit a
+specified width. Emacs does filling in two ways. In Auto Fill mode,
+inserting text with self-inserting characters also automatically fills
+it. There are also explicit fill commands that you can use when editing
+text leaves it unfilled. When you edit formatted text, you can specify
+a style of filling for each portion of the text (@pxref{Formatted
+Text}).
+
+@menu
+* Auto Fill:: Auto Fill mode breaks long lines automatically.
+* Fill Commands:: Commands to refill paragraphs and center lines.
+* Fill Prefix:: Filling paragraphs that are indented
+ or in a comment, etc.
+* Adaptive Fill:: How Emacs can determine the fill prefix automatically.
+@end menu
+
+@node Auto Fill
+@subsection Auto Fill Mode
+@cindex Auto Fill mode
+@cindex mode, Auto Fill
+@cindex word wrap
+
+ @dfn{Auto Fill} mode is a minor mode in which lines are broken
+automatically when they become too wide. Breaking happens only when
+you type a @key{SPC} or @key{RET}.
+
+@table @kbd
+@item M-x auto-fill-mode
+Enable or disable Auto Fill mode.
+@item @key{SPC}
+@itemx @key{RET}
+In Auto Fill mode, break lines when appropriate.
+@end table
+
+@findex auto-fill-mode
+ @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off
+if it was on. With a positive numeric argument it always turns Auto
+Fill mode on, and with a negative argument always turns it off. You can
+see when Auto Fill mode is in effect by the presence of the word
+@samp{Fill} in the mode line, inside the parentheses. Auto Fill mode is
+a minor mode which is enabled or disabled for each buffer individually.
+@xref{Minor Modes}.
+
+ In Auto Fill mode, lines are broken automatically at spaces when they
+get longer than the desired width. Line breaking and rearrangement
+takes place only when you type @key{SPC} or @key{RET}. If you wish to
+insert a space or newline without permitting line-breaking, type
+@kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a
+control-J). Also, @kbd{C-o} inserts a newline without line breaking.
+
+ Auto Fill mode works well with programming-language modes, because it
+indents new lines with @key{TAB}. If a line ending in a comment gets
+too long, the text of the comment is split into two comment lines.
+Optionally, new comment delimiters are inserted at the end of the first
+line and the beginning of the second so that each line is a separate
+comment; the variable @code{comment-multi-line} controls the choice
+(@pxref{Comments}).
+
+ Adaptive filling (see the following section) works for Auto Filling as
+well as for explicit fill commands. It takes a fill prefix
+automatically from the second or first line of a paragraph.
+
+ Auto Fill mode does not refill entire paragraphs; it can break lines but
+cannot merge lines. So editing in the middle of a paragraph can result in
+a paragraph that is not correctly filled. The easiest way to make the
+paragraph properly filled again is usually with the explicit fill commands.
+@ifinfo
+@xref{Fill Commands}.
+@end ifinfo
+
+ Many users like Auto Fill mode and want to use it in all text files.
+The section on init files says how to arrange this permanently for yourself.
+@xref{Init File}.
+
+@node Fill Commands
+@subsection Explicit Fill Commands
+
+@table @kbd
+@item M-q
+Fill current paragraph (@code{fill-paragraph}).
+@item C-x f
+Set the fill column (@code{set-fill-column}).
+@item M-x fill-region
+Fill each paragraph in the region (@code{fill-region}).
+@item M-x fill-region-as-paragraph
+Fill the region, considering it as one paragraph.
+@item M-s
+Center a line.
+@end table
+
+@kindex M-q
+@findex fill-paragraph
+ To refill a paragraph, use the command @kbd{M-q}
+(@code{fill-paragraph}). This operates on the paragraph that point is
+inside, or the one after point if point is between paragraphs.
+Refilling works by removing all the line-breaks, then inserting new ones
+where necessary.
+
+@findex fill-region
+ To refill many paragraphs, use @kbd{M-x fill-region}, which
+divides the region into paragraphs and fills each of them.
+
+@findex fill-region-as-paragraph
+ @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h}
+for finding paragraph boundaries (@pxref{Paragraphs}). For more
+control, you can use @kbd{M-x fill-region-as-paragraph}, which refills
+everything between point and mark. This command deletes any blank lines
+within the region, so separate blocks of text end up combined into one
+block.@refill
+
+@cindex justification
+ A numeric argument to @kbd{M-q} causes it to @dfn{justify} the text as
+well as filling it. This means that extra spaces are inserted to make
+the right margin line up exactly at the fill column. To remove the
+extra spaces, use @kbd{M-q} with no argument. (Likewise for
+@code{fill-region}.) Another way to control justification, and choose
+other styles of filling, is with the @code{justification} text property;
+see @ref{Format Justification}.
+
+@kindex M-s @r{(Text mode)}
+@cindex centering
+@findex center-line
+ The command @kbd{M-s} (@code{center-line}) centers the current line
+within the current fill column. With an argument @var{n}, it centers
+@var{n} lines individually and moves past them.
+
+@vindex fill-column
+@kindex C-x f
+@findex set-fill-column
+ The maximum line width for filling is in the variable
+@code{fill-column}. Altering the value of @code{fill-column} makes it
+local to the current buffer; until that time, the default value is in
+effect. The default is initially 70. @xref{Locals}. The easiest way
+to set @code{fill-column} is to use the command @kbd{C-x f}
+(@code{set-fill-column}). With a numeric argument, it uses that as the
+new fill column. With just @kbd{C-u} as argument, it sets
+@code{fill-column} to the current horizontal position of point.
+
+ Emacs commands normally consider a period followed by two spaces or by
+a newline as the end of a sentence; a period followed by just one space
+indicates an abbreviation and not the end of a sentence. To preserve
+the distinction between these two ways of using a period, the fill
+commands do not break a line after a period followed by just one space.
+
+@vindex sentence-end-double-space
+ If the variable @code{sentence-end-double-space} is @code{nil}, the
+fill commands expect and leave just one space at the end of a sentence.
+Ordinarily this variable is @code{t}, so the fill commands insist on
+two spaces for the end of a sentence, as explained above. @xref{Sentences}.
+
+@vindex colon-double-space
+ If the variable @code{colon-double-space} is non-@code{nil}, the
+fill commands put two spaces after a colon.
+
+@node Fill Prefix
+@subsection The Fill Prefix
+
+@cindex fill prefix
+ To fill a paragraph in which each line starts with a special marker
+(which might be a few spaces, giving an indented paragraph), you can use
+the @dfn{fill prefix} feature. The fill prefix is a string that Emacs
+expects every line to start with, and which is not included in filling.
+You can specify a fill prefix explicitly; Emacs can also deduce the
+fill prefix automatically (@pxref{Adaptive Fill}).
+
+@table @kbd
+@item C-x .
+Set the fill prefix (@code{set-fill-prefix}).
+@item M-q
+Fill a paragraph using current fill prefix (@code{fill-paragraph}).
+@item M-x fill-individual-paragraphs
+Fill the region, considering each change of indentation as starting a
+new paragraph.
+@item M-x fill-nonuniform-paragraphs
+Fill the region, considering only paragraph-separator lines as starting
+a new paragraph.
+@end table
+
+@kindex C-x .
+@findex set-fill-prefix
+ To specify a fill prefix, move to a line that starts with the desired
+prefix, put point at the end of the prefix, and give the command
+@w{@kbd{C-x .}}@: (@code{set-fill-prefix}). That's a period after the
+@kbd{C-x}. To turn off the fill prefix, specify an empty prefix: type
+@w{@kbd{C-x .}}@: with point at the beginning of a line.@refill
+
+ When a fill prefix is in effect, the fill commands remove the fill
+prefix from each line before filling and insert it on each line after
+filling. Auto Fill mode also inserts the fill prefix automatically when
+it makes a new line. The @kbd{C-o} command inserts the fill prefix on
+new lines it creates, when you use it at the beginning of a line
+(@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes the
+prefix (if it occurs) after the newline that it deletes
+(@pxref{Indentation}).
+
+ For example, if @code{fill-column} is 40 and you set the fill prefix
+to @samp{;; }, then @kbd{M-q} in the following text
+
+@example
+;; This is an
+;; example of a paragraph
+;; inside a Lisp-style comment.
+@end example
+
+@noindent
+produces this:
+
+@example
+;; This is an example of a paragraph
+;; inside a Lisp-style comment.
+@end example
+
+ Lines that do not start with the fill prefix are considered to start
+paragraphs, both in @kbd{M-q} and the paragraph commands; this gives
+good results for paragraphs with hanging indentation (every line
+indented except the first one). Lines which are blank or indented once
+the prefix is removed also separate or start paragraphs; this is what
+you want if you are writing multi-paragraph comments with a comment
+delimiter on each line.
+
+@findex fill-individual-paragraphs
+ You can use @kbd{M-x fill-individual-paragraphs} to set the fill
+prefix for each paragraph automatically. This command divides the
+region into paragraphs, treating every change in the amount of
+indentation as the start of a new paragraph, and fills each of these
+paragraphs. Thus, all the lines in one ``paragraph'' have the same
+amount of indentation. That indentation serves as the fill prefix for
+that paragraph.
+
+@findex fill-nonuniform-paragraphs
+ @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides
+the region into paragraphs in a different way. It considers only
+paragraph-separating lines (as defined by @code{paragraph-separate}) as
+starting a new paragraph. Since this means that the lines of one
+paragraph may have different amounts of indentation, the fill prefix
+used is the smallest amount of indentation of any of the lines of the
+paragraph. This gives good results with styles that indent a paragraph's
+first line more or less that the rest of the paragraph.
+
+@vindex fill-prefix
+ The fill prefix is stored in the variable @code{fill-prefix}. Its value
+is a string, or @code{nil} when there is no fill prefix. This is a
+per-buffer variable; altering the variable affects only the current buffer,
+but there is a default value which you can change as well. @xref{Locals}.
+
+ The @code{indentation} text property provides another way to control
+the amount of indentation paragraphs receive. @xref{Format Indentation}.
+
+@node Adaptive Fill
+@subsection Adaptive Filling
+
+@cindex adaptive filling
+ The fill commands can deduce the proper fill prefix for a paragraph
+automatically in certain cases: either whitespace or certain punctuation
+characters at the beginning of a line are propagated to all lines of the
+paragraph.
+
+ If the paragraph has two or more lines, the fill prefix is taken from
+the paragraph's second line, but only if it appears on the first line as
+well.
+
+ If a paragraph has just one line, fill commands @emph{may} take a
+prefix from that line. The decision is complicated because there are
+three reasonable things to do in such a case:
+
+@itemize @bullet
+@item
+Use the first line's prefix on all the lines of the paragraph.
+
+@item
+Indent subsequent lines with whitespace, so that they line up under the
+text that follows the prefix on the first line, but don't actually copy
+the prefix from the first line.
+
+@item
+Don't do anything special with the second and following lines.
+@end itemize
+
+ All three of these styles of formatting are commonly used. So the
+fill commands try to determine what you would like, based on the prefix
+that appears and on the major mode. Here is how.
+
+@vindex adaptive-fill-first-line-regexp
+ If the prefix found on the first line matches
+@code{adaptive-fill-first-line-regexp}, or if it appears to be a
+comment-starting sequence (this depends on the major mode), then the
+prefix found is used for filling the paragraph, provided it would not
+act as a paragraph starter on subsequent lines.
+
+ Otherwise, the prefix found is converted to an equivalent number of
+spaces, and those spaces are used as the fill prefix for the rest of the
+lines, provided they would not act as a paragraph starter on subsequent
+lines.
+
+ In Text mode, and other modes where only blank lines and page
+delimiters separate paragraphs, the prefix chosen by adaptive filling
+never acts as a paragraph starter, so it can always be used for filling.
+
+@vindex adaptive-fill-mode
+@vindex adaptive-fill-regexp
+ The variable @code{adaptive-fill-regexp} determines what kinds of line
+beginnings can serve as a fill prefix: any characters at the start of
+the line that match this regular expression are used. If you set the
+variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is
+never chosen automatically.
+
+@vindex adaptive-fill-function
+ You can specify more complex ways of choosing a fill prefix
+automatically by setting the variable @code{adaptive-fill-function} to a
+function. This function is called with point after the left margin of a
+line, and it should return the appropriate fill prefix based on that
+line. If it returns @code{nil}, that means it sees no fill prefix in
+that line.
+
+@node Case
+@section Case Conversion Commands
+@cindex case conversion
+
+ Emacs has commands for converting either a single word or any arbitrary
+range of text to upper case or to lower case.
+
+@c WideCommands
+@table @kbd
+@item M-l
+Convert following word to lower case (@code{downcase-word}).
+@item M-u
+Convert following word to upper case (@code{upcase-word}).
+@item M-c
+Capitalize the following word (@code{capitalize-word}).
+@item C-x C-l
+Convert region to lower case (@code{downcase-region}).
+@item C-x C-u
+Convert region to upper case (@code{upcase-region}).
+@end table
+
+@kindex M-l
+@kindex M-u
+@kindex M-c
+@cindex words, case conversion
+@cindex converting text to upper or lower case
+@cindex capitalizing words
+@findex downcase-word
+@findex upcase-word
+@findex capitalize-word
+ The word conversion commands are the most useful. @kbd{M-l}
+(@code{downcase-word}) converts the word after point to lower case, moving
+past it. Thus, repeating @kbd{M-l} converts successive words.
+@kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while
+@kbd{M-c} (@code{capitalize-word}) puts the first letter of the word
+into upper case and the rest into lower case. All these commands convert
+several words at once if given an argument. They are especially convenient
+for converting a large amount of text from all upper case to mixed case,
+because you can move through the text using @kbd{M-l}, @kbd{M-u} or
+@kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead
+to skip a word.
+
+ When given a negative argument, the word case conversion commands apply
+to the appropriate number of words before point, but do not move point.
+This is convenient when you have just typed a word in the wrong case: you
+can give the case conversion command and continue typing.
+
+ If a word case conversion command is given in the middle of a word, it
+applies only to the part of the word which follows point. This is just
+like what @kbd{M-d} (@code{kill-word}) does. With a negative argument,
+case conversion applies only to the part of the word before point.
+
+@kindex C-x C-l
+@kindex C-x C-u
+@findex downcase-region
+@findex upcase-region
+ The other case conversion commands are @kbd{C-x C-u}
+(@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
+convert everything between point and mark to the specified case. Point and
+mark do not move.
+
+ The region case conversion commands @code{upcase-region} and
+@code{downcase-region} are normally disabled. This means that they ask
+for confirmation if you try to use them. When you confirm, you may
+enable the command, which means it will not ask for confirmation again.
+@xref{Disabling}.
+
+@node Text Mode
+@section Text Mode
+@cindex Text mode
+@cindex mode, Text
+@findex text-mode
+
+ When you edit files of text in a human language, it's more convenient
+to use Text mode rather than Fundamental mode. To enter Text mode, type
+@kbd{M-x text-mode}.
+
+ In Text mode, only blank lines and page delimiters separate
+paragraphs. As a result, paragraphs can be indented, and adaptive
+filling determines what indentation to use when filling a paragraph.
+@xref{Adaptive Fill}.
+
+@kindex TAB @r{(Text mode)}
+ Text mode defines @key{TAB} to run @code{indent-relative}
+(@pxref{Indentation}), so that you can conveniently indent a line like
+the previous line. When the previous line is not indented,
+@code{indent-relative} runs @code{tab-to-tab-stop}, which uses Emacs tab
+stops that you can set (@pxref{Tab Stops}).
+
+ Text mode turns off the features concerned with comments except when
+you explicitly invoke them. It changes the syntax table so that periods
+are not considered part of a word, while apostrophes, backspaces and
+underlines are considered part of words.
+
+@cindex Paragraph-Indent Text mode
+@cindex mode, Paragraph-Indent Text
+@findex paragraph-indent-text-mode
+ If you indent the first lines of paragraphs, then you should use
+Paragraph-Indent Text mode rather than Text mode. In this mode, you do
+not need to have blank lines between paragraphs, because the first-line
+indentation is sufficient to start a paragraph; however paragraphs in
+which every line is indented are not supported. Use @kbd{M-x
+paragraph-indent-text-mode} to enter this mode.
+
+@kindex M-TAB @r{(Text mode)}
+ Text mode, and all the modes based on it, define @kbd{M-@key{TAB}} as
+the command @code{ispell-complete-word}, which performs completion of
+the partial word in the buffer before point, using the spelling
+dictionary as the space of possible words. @xref{Spelling}.
+
+@vindex text-mode-hook
+ Entering Text mode runs the hook @code{text-mode-hook}. Other major
+modes related to Text mode also run this hook, followed by hooks of
+their own; this includes Paragraph-Indent Text mode, Nroff mode, @TeX{}
+mode, Outline mode, and Mail mode. Hook functions on
+@code{text-mode-hook} can look at the value of @code{major-mode} to see
+which of these modes is actually being entered. @xref{Hooks}.
+
+@ifinfo
+ Emacs provides two other modes for editing text that is to be passed
+through a text formatter to produce fancy formatted printed output.
+@xref{Nroff Mode}, for editing input to the formatter nroff.
+@xref{TeX Mode}, for editing input to the formatter TeX.
+
+ Another mode is used for editing outlines. It allows you to view the
+text at various levels of detail. You can view either the outline
+headings alone or both headings and text; you can also hide some of the
+headings at lower levels from view to make the high level structure more
+visible. @xref{Outline Mode}.
+@end ifinfo
+
+@node Outline Mode
+@section Outline Mode
+@cindex Outline mode
+@cindex mode, Outline
+@cindex selective display
+@cindex invisible lines
+
+@findex outline-mode
+@findex outline-minor-mode
+@vindex outline-minor-mode-prefix
+ Outline mode is a major mode much like Text mode but intended for
+editing outlines. It allows you to make parts of the text temporarily
+invisible so that you can see the outline structure. Type @kbd{M-x
+outline-mode} to switch to Outline mode as the major mode of the current
+buffer.
+
+ When Outline mode makes a line invisible, the line does not appear on
+the screen. The screen appears exactly as if the invisible line were
+deleted, except that an ellipsis (three periods in a row) appears at the
+end of the previous visible line (only one ellipsis no matter how many
+invisible lines follow).
+
+ Editing commands that operate on lines, such as @kbd{C-n} and
+@kbd{C-p}, treat the text of the invisible line as part of the previous
+visible line. Killing an entire visible line, including its terminating
+newline, really kills all the following invisible lines along with it.
+
+ Outline minor mode provides the same commands as the major mode,
+Outline mode, but you can use it in conjunction with other major modes.
+Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in
+the current buffer. You can also specify this in the text of a file,
+with a file local variable of the form @samp{mode: outline-minor}
+(@pxref{File Variables}).
+
+@kindex C-c @@ @r{(Outline minor mode)}
+ The major mode, Outline mode, provides special key bindings on the
+@kbd{C-c} prefix. Outline minor mode provides similar bindings with
+@kbd{C-c @@} as the prefix; this is to reduce the conflicts with the
+major mode's special commands. (The variable
+@code{outline-minor-mode-prefix} controls the prefix used.)
+
+@vindex outline-mode-hook
+ Entering Outline mode runs the hook @code{text-mode-hook} followed by
+the hook @code{outline-mode-hook} (@pxref{Hooks}).
+
+@menu
+* Format: Outline Format. What the text of an outline looks like.
+* Motion: Outline Motion. Special commands for moving through
+ outlines.
+* Visibility: Outline Visibility. Commands to control what is visible.
+* Views: Outline Views. Outlines and multiple views.
+@end menu
+
+@node Outline Format
+@subsection Format of Outlines
+
+@cindex heading lines (Outline mode)
+@cindex body lines (Outline mode)
+ Outline mode assumes that the lines in the buffer are of two types:
+@dfn{heading lines} and @dfn{body lines}. A heading line represents a
+topic in the outline. Heading lines start with one or more stars; the
+number of stars determines the depth of the heading in the outline
+structure. Thus, a heading line with one star is a major topic; all the
+heading lines with two stars between it and the next one-star heading
+are its subtopics; and so on. Any line that is not a heading line is a
+body line. Body lines belong with the preceding heading line. Here is
+an example:
+
+@example
+* Food
+This is the body,
+which says something about the topic of food.
+
+** Delicious Food
+This is the body of the second-level header.
+
+** Distasteful Food
+This could have
+a body too, with
+several lines.
+
+*** Dormitory Food
+
+* Shelter
+Another first-level topic with its header line.
+@end example
+
+ A heading line together with all following body lines is called
+collectively an @dfn{entry}. A heading line together with all following
+deeper heading lines and their body lines is called a @dfn{subtree}.
+
+@vindex outline-regexp
+ You can customize the criterion for distinguishing heading lines
+by setting the variable @code{outline-regexp}. Any line whose
+beginning has a match for this regexp is considered a heading line.
+Matches that start within a line (not at the left margin) do not count.
+The length of the matching text determines the level of the heading;
+longer matches make a more deeply nested level. Thus, for example,
+if a text formatter has commands @samp{@@chapter}, @samp{@@section}
+and @samp{@@subsection} to divide the document into chapters and
+sections, you could make those lines count as heading lines by
+setting @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}.
+Note the trick: the two words @samp{chapter} and @samp{section} are equally
+long, but by defining the regexp to match only @samp{chap} we ensure
+that the length of the text matched on a chapter heading is shorter,
+so that Outline mode will know that sections are contained in chapters.
+This works as long as no other command starts with @samp{@@chap}.
+
+@vindex outline-level
+ It is possible to change the rule for calculating the level of a
+heading line by setting the variable @code{outline-level}. The value of
+@code{outline-level} should be a function that takes no arguments and
+returns the level of the current heading. Some major modes such as C,
+Nroff, and Emacs Lisp mode set this variable and/or
+@code{outline-regexp} in order to work with Outline minor mode.
+
+@node Outline Motion
+@subsection Outline Motion Commands
+
+ Outline mode provides special motion commands that move backward and
+forward to heading lines.
+
+@table @kbd
+@item C-c C-n
+Move point to the next visible heading line
+(@code{outline-next-visible-heading}).
+@item C-c C-p
+Move point to the previous visible heading line
+(@code{outline-previous-visible-heading}).
+@item C-c C-f
+Move point to the next visible heading line at the same level
+as the one point is on (@code{outline-forward-same-level}).
+@item C-c C-b
+Move point to the previous visible heading line at the same level
+(@code{outline-backward-same-level}).
+@item C-c C-u
+Move point up to a lower-level (more inclusive) visible heading line
+(@code{outline-up-heading}).
+@end table
+
+@findex outline-next-visible-heading
+@findex outline-previous-visible-heading
+@kindex C-c C-n @r{(Outline mode)}
+@kindex C-c C-p @r{(Outline mode)}
+ @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next
+heading line. @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves
+similarly backward. Both accept numeric arguments as repeat counts. The
+names emphasize that invisible headings are skipped, but this is not really
+a special feature. All editing commands that look for lines ignore the
+invisible lines automatically.@refill
+
+@findex outline-up-heading
+@findex outline-forward-same-level
+@findex outline-backward-same-level
+@kindex C-c C-f @r{(Outline mode)}
+@kindex C-c C-b @r{(Outline mode)}
+@kindex C-c C-u @r{(Outline mode)}
+ More powerful motion commands understand the level structure of headings.
+@kbd{C-c C-f} (@code{outline-forward-same-level}) and
+@kbd{C-c C-b} (@code{outline-backward-same-level}) move from one
+heading line to another visible heading at the same depth in
+the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves
+backward to another heading that is less deeply nested.
+
+@node Outline Visibility
+@subsection Outline Visibility Commands
+
+ The other special commands of outline mode are used to make lines visible
+or invisible. Their names all start with @code{hide} or @code{show}.
+Most of them fall into pairs of opposites. They are not undoable; instead,
+you can undo right past them. Making lines visible or invisible is simply
+not recorded by the undo mechanism.
+
+@table @kbd
+@item C-c C-t
+Make all body lines in the buffer invisible (@code{hide-body}).
+@item C-c C-a
+Make all lines in the buffer visible (@code{show-all}).
+@item C-c C-d
+Make everything under this heading invisible, not including this
+heading itself (@code{hide-subtree}).
+@item C-c C-s
+Make everything under this heading visible, including body,
+subheadings, and their bodies (@code{show-subtree}).
+@item C-c C-l
+Make the body of this heading line, and of all its subheadings,
+invisible (@code{hide-leaves}).
+@item C-c C-k
+Make all subheadings of this heading line, at all levels, visible
+(@code{show-branches}).
+@item C-c C-i
+Make immediate subheadings (one level down) of this heading line
+visible (@code{show-children}).
+@item C-c C-c
+Make this heading line's body invisible (@code{hide-entry}).
+@item C-c C-e
+Make this heading line's body visible (@code{show-entry}).
+@item C-c C-q
+Hide everything except the top @var{n} levels of heading lines
+(@code{hide-sublevels}).
+@item C-c C-o
+Hide everything except for the heading or body that point is in, plus
+the headings leading up from there to the top level of the outline
+(@code{hide-other}).
+@end table
+
+@findex hide-entry
+@findex show-entry
+@kindex C-c C-c @r{(Outline mode)}
+@kindex C-c C-e @r{(Outline mode)}
+ Two commands that are exact opposites are @kbd{C-c C-c}
+(@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They are
+used with point on a heading line, and apply only to the body lines of
+that heading. Subheadings and their bodies are not affected.
+
+@findex hide-subtree
+@findex show-subtree
+@kindex C-c C-s @r{(Outline mode)}
+@kindex C-c C-d @r{(Outline mode)}
+@cindex subtree (Outline mode)
+ Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) and
+@kbd{C-c C-s} (@code{show-subtree}). Both expect to be used when point is
+on a heading line, and both apply to all the lines of that heading's
+@dfn{subtree}: its body, all its subheadings, both direct and indirect, and
+all of their bodies. In other words, the subtree contains everything
+following this heading line, up to and not including the next heading of
+the same or higher rank.@refill
+
+@findex hide-leaves
+@findex show-branches
+@kindex C-c C-l @r{(Outline mode)}
+@kindex C-c C-k @r{(Outline mode)}
+ Intermediate between a visible subtree and an invisible one is having
+all the subheadings visible but none of the body. There are two
+commands for doing this, depending on whether you want to hide the
+bodies or make the subheadings visible. They are @kbd{C-c C-l}
+(@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}).
+
+@kindex C-c C-i @r{(Outline mode)}
+@findex show-children
+ A little weaker than @code{show-branches} is @kbd{C-c C-i}
+(@code{show-children}). It makes just the direct subheadings
+visible---those one level down. Deeper subheadings remain invisible, if
+they were invisible.@refill
+
+@findex hide-body
+@findex show-all
+@kindex C-c C-t @r{(Outline mode)}
+@kindex C-c C-a @r{(Outline mode)}
+ Two commands have a blanket effect on the whole file. @kbd{C-c C-t}
+(@code{hide-body}) makes all body lines invisible, so that you see just
+the outline structure. @kbd{C-c C-a} (@code{show-all}) makes all lines
+visible. These commands can be thought of as a pair of opposites even
+though @kbd{C-c C-a} applies to more than just body lines.
+
+@findex hide-sublevels
+@kindex C-c C-q @r{(Outline mode)}
+ The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the
+top level headings. With a numeric argument @var{n}, it hides everything
+except the top @var{n} levels of heading lines.
+
+@findex hide-other
+@kindex C-c C-o @r{(Outline mode)}
+ The command @kbd{C-c C-o} (@code{hide-other}) hides everything except
+the heading or body text that point is in, plus its parents (the headers
+leading up from there to top level in the outline).
+
+ You can turn off the use of ellipses at the ends of visible lines by
+setting @code{selective-display-ellipses} to @code{nil}. Then there is
+no visible indication of the presence of invisible lines.
+
+ When incremental search finds text that is hidden by Outline mode,
+it makes that part of the buffer visible. If you exit the search
+at that position, the text remains visible.
+
+@node Outline Views
+@subsection Viewing One Outline in Multiple Views
+
+@cindex multiple views of outline
+@cindex views of an outline
+@cindex outline with multiple views
+@cindex indirect buffers and outlines
+ You can display two views of a single outline at the same time, in
+different windows. To do this, you must create an indirect buffer using
+@kbd{M-x make-indirect-buffer}. The first argument of this command is
+the existing outline buffer name, and its second argument is the name to
+use for the new indirect buffer. @xref{Indirect Buffers}.
+
+ Once the indirect buffer exists, you can display it in a window in the
+normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline
+mode commands to show and hide parts of the text operate on each buffer
+independently; as a result, each buffer can have its own view. If you
+want more than two views on the same outline, create additional indirect
+buffers.
+
+@node TeX Mode
+@section @TeX{} Mode
+@cindex @TeX{} mode
+@cindex La@TeX{} mode
+@cindex Sli@TeX{} mode
+@cindex mode, @TeX{}
+@cindex mode, La@TeX{}
+@cindex mode, Sli@TeX{}
+@findex tex-mode
+@findex plain-tex-mode
+@findex latex-mode
+@findex slitex-mode
+
+ @TeX{} is a powerful text formatter written by Donald Knuth; it is also
+free, like GNU Emacs. La@TeX{} is a simplified input format for @TeX{},
+implemented by @TeX{} macros; it comes with @TeX{}. Sli@TeX{} is a special
+form of La@TeX{}.@refill
+
+ Emacs has a special @TeX{} mode for editing @TeX{} input files.
+It provides facilities for checking the balance of delimiters and for
+invoking @TeX{} on all or part of the file.
+
+@vindex tex-default-mode
+ @TeX{} mode has three variants, Plain @TeX{} mode, La@TeX{} mode, and
+Sli@TeX{} mode (these three distinct major modes differ only slightly).
+They are designed for editing the three different formats. The command
+@kbd{M-x tex-mode} looks at the contents of the buffer to determine
+whether the contents appear to be either La@TeX{} input or Sli@TeX{}
+input; if so, it selects the appropriate mode. If the file contents do
+not appear to be La@TeX{} or Sli@TeX{}, it selects Plain @TeX{} mode.
+If the contents are insufficient to determine this, the variable
+@code{tex-default-mode} controls which mode is used.
+
+ When @kbd{M-x tex-mode} does not guess right, you can use the commands
+@kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, and @kbd{M-x
+slitex-mode} to select explicitly the particular variants of @TeX{}
+mode.
+
+@vindex tex-shell-hook
+@vindex tex-mode-hook
+@vindex latex-mode-hook
+@vindex slitex-mode-hook
+@vindex plain-tex-mode-hook
+ Entering any kind of @TeX{} mode runs the hooks @code{text-mode-hook}
+and @code{tex-mode-hook}. Then it runs either
+@code{plain-tex-mode-hook} or @code{latex-mode-hook}, whichever is
+appropriate. For Sli@TeX{} files, it calls @code{slitex-mode-hook}.
+Starting the @TeX{} shell runs the hook @code{tex-shell-hook}.
+@xref{Hooks}.
+
+@menu
+* Editing: TeX Editing. Special commands for editing in TeX mode.
+* LaTeX: LaTeX Editing. Additional commands for LaTeX input files.
+* Printing: TeX Print. Commands for printing part of a file with TeX.
+@end menu
+
+@node TeX Editing
+@subsection @TeX{} Editing Commands
+
+ Here are the special commands provided in @TeX{} mode for editing the
+text of the file.
+
+@table @kbd
+@item "
+Insert, according to context, either @samp{``} or @samp{"} or
+@samp{''} (@code{tex-insert-quote}).
+@item C-j
+Insert a paragraph break (two newlines) and check the previous
+paragraph for unbalanced braces or dollar signs
+(@code{tex-terminate-paragraph}).
+@item M-x tex-validate-region
+Check each paragraph in the region for unbalanced braces or dollar signs.
+@item C-c @{
+Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}).
+@item C-c @}
+Move forward past the next unmatched close brace (@code{up-list}).
+@end table
+
+@findex tex-insert-quote
+@kindex " @r{(@TeX{} mode)}
+ In @TeX{}, the character @samp{"} is not normally used; we use
+@samp{``} to start a quotation and @samp{''} to end one. To make
+editing easier under this formatting convention, @TeX{} mode overrides
+the normal meaning of the key @kbd{"} with a command that inserts a pair
+of single-quotes or backquotes (@code{tex-insert-quote}). To be
+precise, this command inserts @samp{``} after whitespace or an open
+brace, @samp{"} after a backslash, and @samp{''} after any other
+character.
+
+ If you need the character @samp{"} itself in unusual contexts, use
+@kbd{C-q} to insert it. Also, @kbd{"} with a numeric argument always
+inserts that number of @samp{"} characters. You can turn off the
+feature of @kbd{"} expansion by eliminating that binding in the local
+map (@pxref{Key Bindings}).
+
+ In @TeX{} mode, @samp{$} has a special syntax code which attempts to
+understand the way @TeX{} math mode delimiters match. When you insert a
+@samp{$} that is meant to exit math mode, the position of the matching
+@samp{$} that entered math mode is displayed for a second. This is the
+same feature that displays the open brace that matches a close brace that
+is inserted. However, there is no way to tell whether a @samp{$} enters
+math mode or leaves it; so when you insert a @samp{$} that enters math
+mode, the previous @samp{$} position is shown as if it were a match, even
+though they are actually unrelated.
+
+@findex tex-insert-braces
+@kindex C-c @{ @r{(@TeX{} mode)}
+@findex up-list
+@kindex C-c @} @r{(@TeX{} mode)}
+ @TeX{} uses braces as delimiters that must match. Some users prefer
+to keep braces balanced at all times, rather than inserting them
+singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of
+braces. It leaves point between the two braces so you can insert the
+text that belongs inside. Afterward, use the command @kbd{C-c @}}
+(@code{up-list}) to move forward past the close brace.
+
+@findex tex-validate-region
+@findex tex-terminate-paragraph
+@kindex C-j @r{(@TeX{} mode)}
+ There are two commands for checking the matching of braces. @kbd{C-j}
+(@code{tex-terminate-paragraph}) checks the paragraph before point, and
+inserts two newlines to start a new paragraph. It prints a message in
+the echo area if any mismatch is found. @kbd{M-x tex-validate-region}
+checks a region, paragraph by paragraph. The errors are listed in the
+@samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in
+that buffer to go to a particular mismatch.
+
+ Note that Emacs commands count square brackets and parentheses in
+@TeX{} mode, not just braces. This is not strictly correct for the
+purpose of checking @TeX{} syntax. However, parentheses and square
+brackets are likely to be used in text as matching delimiters and it is
+useful for the various motion commands and automatic match display to
+work with them.
+
+@node LaTeX Editing
+@subsection La@TeX{} Editing Commands
+
+ La@TeX{} mode, and its variant, Sli@TeX{} mode, provide a few extra
+features not applicable to plain @TeX{}.
+
+@table @kbd
+@item C-c C-o
+Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position
+point on a line between them (@code{tex-latex-block}).
+@item C-c C-e
+Close the innermost La@TeX{} block not yet closed
+(@code{tex-close-latex-block}).
+@end table
+
+@findex tex-latex-block
+@kindex C-c C-o @r{(La@TeX{} mode)}
+@vindex latex-block-names
+ In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to
+group blocks of text. To insert a @samp{\begin} and a matching
+@samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c
+C-o} (@code{tex-latex-block}). A blank line is inserted between the
+two, and point is left there. You can use completion when you enter the
+block type; to specify additional block type names beyond the standard
+list, set the variable @code{latex-block-names}. For example, here's
+how to add @samp{theorem}, @samp{corollary}, and @samp{proof}:
+
+@example
+(setq latex-block-names '("theorem" "corollary" "proof"))
+@end example
+
+@findex tex-close-latex-block
+@kindex C-c C-e @r{(La@TeX{} mode)}
+ In La@TeX{} input, @samp{\begin} and @samp{\end} commands must
+balance. You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to
+insert automatically a matching @samp{\end} to match the last unmatched
+@samp{\begin}. It indents the @samp{\end} to match the corresponding
+@samp{\begin}. It inserts a newline after @samp{\end} if point is at
+the beginning of a line.
+
+@node TeX Print
+@subsection @TeX{} Printing Commands
+
+ You can invoke @TeX{} as an inferior of Emacs on either the entire
+contents of the buffer or just a region at a time. Running @TeX{} in
+this way on just one chapter is a good way to see what your changes
+look like without taking the time to format the entire file.
+
+@table @kbd
+@item C-c C-r
+Invoke @TeX{} on the current region, together with the buffer's header
+(@code{tex-region}).
+@item C-c C-b
+Invoke @TeX{} on the entire current buffer (@code{tex-buffer}).
+@item C-c @key{TAB}
+Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}).
+@item C-c C-f
+Invoke @TeX{} on the current file (@code{tex-file}).
+@item C-c C-l
+Recenter the window showing output from the inferior @TeX{} so that
+the last line can be seen (@code{tex-recenter-output-buffer}).
+@item C-c C-k
+Kill the @TeX{} subprocess (@code{tex-kill-job}).
+@item C-c C-p
+Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
+C-f} command (@code{tex-print}).
+@item C-c C-v
+Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c
+C-f} command (@code{tex-view}).
+@item C-c C-q
+Show the printer queue (@code{tex-show-print-queue}).
+@end table
+
+@findex tex-buffer
+@kindex C-c C-b @r{(@TeX{} mode)}
+@findex tex-print
+@kindex C-c C-p @r{(@TeX{} mode)}
+@findex tex-view
+@kindex C-c C-v @r{(@TeX{} mode)}
+@findex tex-show-print-queue
+@kindex C-c C-q @r{(@TeX{} mode)}
+ You can pass the current buffer through an inferior @TeX{} by means of
+@kbd{C-c C-b} (@code{tex-buffer}). The formatted output appears in a
+temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}).
+Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to
+view the progress of your output towards being printed. If your terminal
+has the ability to display @TeX{} output files, you can preview the
+output on the terminal with @kbd{C-c C-v} (@code{tex-view}).
+
+@cindex @code{TEXINPUTS} environment variable
+@vindex tex-directory
+ You can specify the directory to use for running @TeX{} by setting the
+variable @code{tex-directory}. @code{"."} is the default value. If
+your environment variable @code{TEXINPUTS} contains relative directory
+names, or if your files contains @samp{\input} commands with relative
+file names, then @code{tex-directory} @emph{must} be @code{"."} or you
+will get the wrong results. Otherwise, it is safe to specify some other
+directory, such as @code{"/tmp"}.
+
+@vindex tex-run-command
+@vindex latex-run-command
+@vindex slitex-run-command
+@vindex tex-dvi-print-command
+@vindex tex-dvi-view-command
+@vindex tex-show-queue-command
+ If you want to specify which shell commands are used in the inferior @TeX{},
+you can do so by setting the values of the variables @code{tex-run-command},
+@code{latex-run-command}, @code{slitex-run-command},
+@code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and
+@code{tex-show-queue-command}. You @emph{must} set the value of
+@code{tex-dvi-view-command} for your particular terminal; this variable
+has no default value. The other variables have default values that may
+(or may not) be appropriate for your system.
+
+ Normally, the file name given to these commands comes at the end of
+the command string; for example, @samp{latex @var{filename}}. In some
+cases, however, the file name needs to be embedded in the command; an
+example is when you need to provide the file name as an argument to one
+command whose output is piped to another. You can specify where to put
+the file name with @samp{*} in the command string. For example,
+
+@example
+(setq tex-dvi-print-command "dvips -f * | lpr")
+@end example
+
+@findex tex-kill-job
+@kindex C-c C-k @r{(@TeX{} mode)}
+@findex tex-recenter-output-buffer
+@kindex C-c C-l @r{(@TeX{} mode)}
+ The terminal output from @TeX{}, including any error messages, appears
+in a buffer called @samp{*tex-shell*}. If @TeX{} gets an error, you can
+switch to this buffer and feed it input (this works as in Shell mode;
+@pxref{Interactive Shell}). Without switching to this buffer you can
+scroll it so that its last line is visible by typing @kbd{C-c
+C-l}.
+
+ Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if
+you see that its output is no longer useful. Using @kbd{C-c C-b} or
+@kbd{C-c C-r} also kills any @TeX{} process still running.@refill
+
+@findex tex-region
+@kindex C-c C-r @r{(@TeX{} mode)}
+ You can also pass an arbitrary region through an inferior @TeX{} by typing
+@kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because most files
+of @TeX{} input contain commands at the beginning to set parameters and
+define macros, without which no later part of the file will format
+correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a
+part of the file as containing essential commands; it is included before
+the specified region as part of the input to @TeX{}. The designated part
+of the file is called the @dfn{header}.
+
+@cindex header (@TeX{} mode)
+ To indicate the bounds of the header in Plain @TeX{} mode, you insert two
+special strings in the file. Insert @samp{%**start of header} before the
+header, and @samp{%**end of header} after it. Each string must appear
+entirely on one line, but there may be other text on the line before or
+after. The lines containing the two strings are included in the header.
+If @samp{%**start of header} does not appear within the first 100 lines of
+the buffer, @kbd{C-c C-r} assumes that there is no header.
+
+ In La@TeX{} mode, the header begins with @samp{\documentclass} or
+@samp{\documentstyle} and ends with @samp{\begin@{document@}}. These
+are commands that La@TeX{} requires you to use in any case, so nothing
+special needs to be done to identify the header.
+
+@findex tex-file
+@kindex C-c C-f @r{(@TeX{} mode)}
+ The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their
+work in a temporary directory, and do not have available any of the auxiliary
+files needed by @TeX{} for cross-references; these commands are generally
+not suitable for running the final copy in which all of the cross-references
+need to be correct.
+
+ When you want the auxiliary files for cross references, use @kbd{C-c
+C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file,
+in that file's directory. Before running @TeX{}, it offers to save any
+modified buffers. Generally, you need to use (@code{tex-file}) twice to
+get the cross-references right.
+
+@vindex tex-start-options-string
+ The value of the variable @code{tex-start-options-string} specifies
+options for the @TeX{} run. The default value causes @TeX{} to run in
+nonstopmode. To run @TeX{} interactively, set the variable to @code{""}.
+
+@vindex tex-main-file
+ Large @TeX{} documents are often split into several files---one main
+file, plus subfiles. Running @TeX{} on a subfile typically does not
+work; you have to run it on the main file. In order to make
+@code{tex-file} useful when you are editing a subfile, you can set the
+variable @code{tex-main-file} to the name of the main file. Then
+@code{tex-file} runs @TeX{} on that file.
+
+ The most convenient way to use @code{tex-main-file} is to specify it
+in a local variable list in each of the subfiles. @xref{File
+Variables}.
+
+@findex tex-bibtex-file
+@kindex C-c TAB @r{(@TeX{} mode)}
+@vindex tex-bibtex-command
+ For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary
+file for the current buffer's file. Bib@TeX{} looks up bibliographic
+citations in a data base and prepares the cited references for the
+bibliography section. The command @kbd{C-c TAB}
+(@code{tex-bibtex-file}) runs the shell command
+(@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the
+current buffer's file. Generally, you need to do @kbd{C-c C-f}
+(@code{tex-file}) once to generate the @samp{.aux} file, then do
+@kbd{C-c TAB} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f}
+(@code{tex-file}) twice more to get the cross-references correct.
+
+ For managing all kinds of references, you can use Ref@TeX{}.
+@xref{Top, , RefTeX, reftex}.
+
+@node Nroff Mode
+@section Nroff Mode
+
+@cindex nroff
+@findex nroff-mode
+ Nroff mode is a mode like Text mode but modified to handle nroff commands
+present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It
+differs from Text mode in only a few ways. All nroff command lines are
+considered paragraph separators, so that filling will never garble the
+nroff commands. Pages are separated by @samp{.bp} commands. Comments
+start with backslash-doublequote. Also, three special commands are
+provided that are not in Text mode:
+
+@findex forward-text-line
+@findex backward-text-line
+@findex count-text-lines
+@kindex M-n @r{(Nroff mode)}
+@kindex M-p @r{(Nroff mode)}
+@kindex M-? @r{(Nroff mode)}
+@table @kbd
+@item M-n
+Move to the beginning of the next line that isn't an nroff command
+(@code{forward-text-line}). An argument is a repeat count.
+@item M-p
+Like @kbd{M-n} but move up (@code{backward-text-line}).
+@item M-?
+Prints in the echo area the number of text lines (lines that are not
+nroff commands) in the region (@code{count-text-lines}).
+@end table
+
+@findex electric-nroff-mode
+ The other feature of Nroff mode is that you can turn on Electric Nroff
+mode. This is a minor mode that you can turn on or off with @kbd{M-x
+electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each
+time you use @key{RET} to end a line that contains an nroff command that
+opens a kind of grouping, the matching nroff command to close that
+grouping is automatically inserted on the following line. For example,
+if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}},
+this inserts the matching command @samp{.)b} on a new line following
+point.
+
+ If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}),
+heading lines are lines of the form @samp{.H} followed by a number (the
+header level).
+
+@vindex nroff-mode-hook
+ Entering Nroff mode runs the hook @code{text-mode-hook}, followed by
+the hook @code{nroff-mode-hook} (@pxref{Hooks}).
+
+@node Formatted Text
+@section Editing Formatted Text
+
+@cindex Enriched mode
+@cindex mode, Enriched
+@cindex formatted text
+@cindex WYSIWYG
+@cindex word processing
+ @dfn{Enriched mode} is a minor mode for editing files that contain
+formatted text in WYSIWYG fashion, as in a word processor. Currently,
+formatted text in Enriched mode can specify fonts, colors, underlining,
+margins, and types of filling and justification. In the future, we plan
+to implement other formatting features as well.
+
+ Enriched mode is a minor mode (@pxref{Minor Modes}). Typically it is
+used in conjunction with Text mode (@pxref{Text Mode}). However, you
+can also use it with other major modes such as Outline mode and
+Paragraph-Indent Text mode.
+
+ Potentially, Emacs can store formatted text files in various file
+formats. Currently, only one format is implemented: @dfn{text/enriched}
+format, which is defined by the MIME protocol. @xref{Format
+Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual},
+for details of how Emacs recognizes and converts file formats.
+
+ The Emacs distribution contains a formatted text file that can serve as
+an example. Its name is @file{etc/enriched.doc}. It contains samples
+illustrating all the features described in this section. It also
+contains a list of ideas for future enhancements.
+
+@menu
+* Requesting Formatted Text:: Entering and exiting Enriched mode.
+* Hard and Soft Newlines:: There are two different kinds of newlines.
+* Editing Format Info:: How to edit text properties.
+* Faces: Format Faces. Bold, italic, underline, etc.
+* Color: Format Colors. Changing the color of text.
+* Indent: Format Indentation. Changing the left and right margins.
+* Justification: Format Justification.
+ Centering, setting text flush with the
+ left or right margin, etc.
+* Other: Format Properties. The "special" text properties submenu.
+* Forcing Enriched Mode:: How to force use of Enriched mode.
+@end menu
+
+@node Requesting Formatted Text
+@subsection Requesting to Edit Formatted Text
+
+ Whenever you visit a file that Emacs saved in the text/enriched format,
+Emacs automatically converts the formatting information in the file into
+Emacs's own internal format (text properties), and turns on Enriched
+mode.
+
+@findex enriched-mode
+ To create a new file of formatted text, first visit the nonexistent
+file, then type @kbd{M-x enriched-mode} before you start inserting text.
+This command turns on Enriched mode. Do this before you begin inserting
+text, to ensure that the text you insert is handled properly.
+
+ More generally, the command @code{enriched-mode} turns Enriched mode
+on if it was off, and off if it was on. With a prefix argument, this
+command turns Enriched mode on if the argument is positive, and turns
+the mode off otherwise.
+
+ When you save a buffer while Enriched mode is enabled in it, Emacs
+automatically converts the text to text/enriched format while writing it
+into the file. When you visit the file again, Emacs will automatically
+recognize the format, reconvert the text, and turn on Enriched mode
+again.
+
+@vindex enriched-fill-after-visiting
+ Normally, after visiting a file in text/enriched format, Emacs refills
+each paragraph to fit the specified right margin. You can turn off this
+refilling, to save time, by setting the variable
+@code{enriched-fill-after-visiting} to @code{nil} or to @code{ask}.
+
+ However, when visiting a file that was saved from Enriched mode, there
+is no need for refilling, because Emacs saves the right margin settings
+along with the text.
+
+@vindex enriched-translations
+ You can add annotations for saving additional text properties, which
+Emacs normally does not save, by adding to @code{enriched-translations}.
+Note that the text/enriched standard requires any non-standard
+annotations to have names starting with @samp{x-}, as in
+@samp{x-read-only}. This ensures that they will not conflict with
+standard annotations that may be added later.
+
+@node Hard and Soft Newlines
+@subsection Hard and Soft Newlines
+@cindex hard newline
+@cindex soft newline
+@cindex newlines, hard and soft
+
+ In formatted text, Emacs distinguishes between two different kinds of
+newlines, @dfn{hard} newlines and @dfn{soft} newlines.
+
+ Hard newlines are used to separate paragraphs, or items in a list, or
+anywhere that there should always be a line break regardless of the
+margins. The @key{RET} command (@code{newline}) and @kbd{C-o}
+(@code{open-line}) insert hard newlines.
+
+ Soft newlines are used to make text fit between the margins. All the
+fill commands, including Auto Fill, insert soft newlines---and they
+delete only soft newlines.
+
+ Although hard and soft newlines look the same, it is important to bear
+the difference in mind. Do not use @key{RET} to break lines in the
+middle of filled paragraphs, or else you will get hard newlines that are
+barriers to further filling. Instead, let Auto Fill mode break lines,
+so that if the text or the margins change, Emacs can refill the lines
+properly. @xref{Auto Fill}.
+
+ On the other hand, in tables and lists, where the lines should always
+remain as you type them, you can use @key{RET} to end lines. For these
+lines, you may also want to set the justification style to
+@code{unfilled}. @xref{Format Justification}.
+
+@node Editing Format Info
+@subsection Editing Format Information
+
+ There are two ways to alter the formatting information for a formatted
+text file: with keyboard commands, and with the mouse.
+
+ The easiest way to add properties to your document is by using the Text
+Properties menu. You can get to this menu in two ways: from the Edit
+menu in the menu bar, or with @kbd{C-mouse-2} (hold the @key{CTRL} key
+and press the middle mouse button).
+
+ Most of the items in the Text Properties menu lead to other submenus.
+These are described in the sections that follow. Some items run
+commands directly:
+
+@table @code
+@findex facemenu-remove-props
+@item Remove Properties
+Delete from the region all the text properties that the Text Properties
+menu works with (@code{facemenu-remove-props}).
+
+@findex facemenu-remove-all
+@item Remove All
+Delete @emph{all} text properties from the region
+(@code{facemenu-remove-all}).
+
+@findex list-text-properties-at
+@item List Properties
+List all the text properties of the character following point
+(@code{list-text-properties-at}).
+
+@item Display Faces
+Display a list of all the defined faces.
+
+@item Display Colors
+Display a list of all the defined colors.
+@end table
+
+@node Format Faces
+@subsection Faces in Formatted Text
+
+ The Faces submenu lists various Emacs faces including @code{bold},
+@code{italic}, and @code{underline}. Selecting one of these adds the
+chosen face to the region. @xref{Faces}. You can also specify a face
+with these keyboard commands:
+
+@table @kbd
+@kindex M-g d @r{(Enriched mode)}
+@findex facemenu-set-default
+@item M-g d
+Set the region, or the next inserted character, to the @code{default} face
+(@code{facemenu-set-default}).
+@kindex M-g b @r{(Enriched mode)}
+@findex facemenu-set-bold
+@item M-g b
+Set the region, or the next inserted character, to the @code{bold} face
+(@code{facemenu-set-bold}).
+@kindex M-g i @r{(Enriched mode)}
+@findex facemenu-set-italic
+@item M-g i
+Set the region, or the next inserted character, to the @code{italic} face
+(@code{facemenu-set-italic}).
+@kindex M-g l @r{(Enriched mode)}
+@findex facemenu-set-bold-italic
+@item M-g l
+Set the region, or the next inserted character, to the @code{bold-italic} face
+(@code{facemenu-set-bold-italic}).
+@kindex M-g u @r{(Enriched mode)}
+@findex facemenu-set-underline
+@item M-g u
+Set the region, or the next inserted character, to the @code{underline} face
+(@code{facemenu-set-underline}).
+@kindex M-g o @r{(Enriched mode)}
+@findex facemenu-set-face
+@item M-g o @var{face} @key{RET}
+Set the region, or the next inserted character, to the face @var{face}
+(@code{facemenu-set-face}).
+@end table
+
+ If you use these commands with a prefix argument---or, in Transient Mark
+mode, if the region is not active---then these commands specify a face
+to use for your next self-inserting input. @xref{Transient Mark}. This
+applies to both the keyboard commands and the menu commands.
+
+ Enriched mode defines two additional faces: @code{excerpt} and
+@code{fixed}. These correspond to codes used in the text/enriched file
+format.
+
+ The @code{excerpt} face is intended for quotations. This face is the
+same as @code{italic} unless you customize it (@pxref{Face Customization}).
+
+ The @code{fixed} face is meant to say, ``Use a fixed-width font for this
+part of the text.'' Emacs currently supports only fixed-width fonts;
+therefore, the @code{fixed} annotation is not necessary now. However,
+we plan to support variable width fonts in future Emacs versions, and
+other systems that display text/enriched format may not use a
+fixed-width font as the default. So if you specifically want a certain
+part of the text to use a fixed-width font, you should specify the
+@code{fixed} face for that part.
+
+ The @code{fixed} face is normally defined to use a different font from
+the default. However, different systems have different fonts installed,
+so you may need to customize this.
+
+ If your terminal cannot display different faces, you will not be able
+to see them, but you can still edit documents containing faces. You can
+even add faces and colors to documents. They will be visible when the
+file is viewed on a terminal that can display them.
+
+@node Format Colors
+@subsection Colors in Formatted Text
+
+ You can specify foreground and background colors for portions of the
+text. There is a menu for specifying the foreground color and a menu
+for specifying the background color. Each color menu lists all the
+colors that you have used in Enriched mode in the current Emacs session.
+
+ If you specify a color with a prefix argument---or, in Transient Mark
+mode, if the region is not active---then it applies to your next
+self-inserting input. @xref{Transient Mark}. Otherwise, the command
+applies to the region.
+
+ Each color menu contains one additional item: @samp{Other}. You can use
+this item to specify a color that is not listed in the menu; it reads
+the color name with the minibuffer. To display list of available colors
+and their names, use the @samp{Display Colors} menu item in the Text
+Properties menu (@pxref{Editing Format Info}).
+
+ Any color that you specify in this way, or that is mentioned in a
+formatted text file that you read in, is added to both color menus for
+the duration of the Emacs session.
+
+@findex facemenu-set-foreground
+@findex facemenu-set-background
+ There are no key bindings for specifying colors, but you can do so
+with the extended commands @kbd{M-x facemenu-set-foreground} and
+@kbd{M-x facemenu-set-background}. Both of these commands read the name
+of the color with the minibuffer.
+
+@node Format Indentation
+@subsection Indentation in Formatted Text
+
+ When editing formatted text, you can specify different amounts of
+indentation for the right or left margin of an entire paragraph or a
+part of a paragraph. The margins you specify automatically affect the
+Emacs fill commands (@pxref{Filling}) and line-breaking commands.
+
+ The Indentation submenu provides a convenient interface for specifying
+these properties. The submenu contains four items:
+
+@table @code
+@kindex C-x TAB @r{(Enriched mode)}
+@findex increase-left-margin
+@item Indent More
+Indent the region by 4 columns (@code{increase-left-margin}). In
+Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if
+you supply a numeric argument, that says how many columns to add to the
+margin (a negative argument reduces the number of columns).
+
+@item Indent Less
+Remove 4 columns of indentation from the region.
+
+@item Indent Right More
+Make the text narrower by indenting 4 columns at the right margin.
+
+@item Indent Right Less
+Remove 4 columns of indentation from the right margin.
+@end table
+
+ You can use these commands repeatedly to increase or decrease the
+indentation.
+
+ The most common way to use these commands is to change the indentation
+of an entire paragraph. However, that is not the only use. You can
+change the margins at any point; the new values take effect at the end
+of the line (for right margins) or the beginning of the next line (for
+left margins).
+
+ This makes it possible to format paragraphs with @dfn{hanging indents},
+which means that the first line is indented less than subsequent lines.
+To set up a hanging indent, increase the indentation of the region
+starting after the first word of the paragraph and running until the end
+of the paragraph.
+
+ Indenting the first line of a paragraph is easier. Set the margin for
+the whole paragraph where you want it to be for the body of the
+paragraph, then indent the first line by inserting extra spaces or tabs.
+
+ Sometimes, as a result of editing, the filling of a paragraph becomes
+messed up---parts of the paragraph may extend past the left or right
+margins. When this happens, use @kbd{M-q} (@code{fill-paragraph}) to
+refill the paragraph.
+
+@vindex standard-indent
+ The variable @code{standard-indent} specifies how many columns these
+commands should add to or subtract from the indentation. The default
+value is 4. The overall default right margin for Enriched mode is
+controlled by the variable @code{fill-column}, as usual.
+
+ The fill prefix, if any, works in addition to the specified paragraph
+indentation: @kbd{C-x .} does not include the specified indentation's
+whitespace in the new value for the fill prefix, and the fill commands
+look for the fill prefix after the indentation on each line. @xref{Fill
+Prefix}.
+
+@node Format Justification
+@subsection Justification in Formatted Text
+
+ When editing formatted text, you can specify various styles of
+justification for a paragraph. The style you specify automatically
+affects the Emacs fill commands.
+
+ The Justification submenu provides a convenient interface for specifying
+the style. The submenu contains five items:
+
+@table @code
+@item Flush Left
+This is the most common style of justification (at least for English).
+Lines are aligned at the left margin but left uneven at the right.
+
+@item Flush Right
+This aligns each line with the right margin. Spaces and tabs are added
+on the left, if necessary, to make lines line up on the right.
+
+@item Full
+This justifies the text, aligning both edges of each line. Justified
+text looks very nice in a printed book, where the spaces can all be
+adjusted equally, but it does not look as nice with a fixed-width font
+on the screen. Perhaps a future version of Emacs will be able to adjust
+the width of spaces in a line to achieve elegant justification.
+
+@item Center
+This centers every line between the current margins.
+
+@item None
+This turns off filling entirely. Each line will remain as you wrote it;
+the fill and auto-fill functions will have no effect on text which has
+this setting. You can, however, still indent the left margin. In
+unfilled regions, all newlines are treated as hard newlines (@pxref{Hard
+and Soft Newlines}) .
+@end table
+
+ In Enriched mode, you can also specify justification from the keyboard
+using the @kbd{M-j} prefix character:
+
+@table @kbd
+@kindex M-j l @r{(Enriched mode)}
+@findex set-justification-left
+@item M-j l
+Make the region left-filled (@code{set-justification-left}).
+@kindex M-j r @r{(Enriched mode)}
+@findex set-justification-right
+@item M-j r
+Make the region right-filled (@code{set-justification-right}).
+@kindex M-j f @r{(Enriched mode)}
+@findex set-justification-full
+@item M-j f
+Make the region fully-justified (@code{set-justification-full}).
+@kindex M-j c @r{(Enriched mode)}
+@kindex M-S @r{(Enriched mode)}
+@findex set-justification-center
+@item M-j c
+@itemx M-S
+Make the region centered (@code{set-justification-center}).
+@kindex M-j u @r{(Enriched mode)}
+@findex set-justification-none
+@item M-j u
+Make the region unfilled (@code{set-justification-none}).
+@end table
+
+ Justification styles apply to entire paragraphs. All the
+justification-changing commands operate on the paragraph containing
+point, or, if the region is active, on all paragraphs which overlap the
+region.
+
+@vindex default-justification
+ The default justification style is specified by the variable
+@code{default-justification}. Its value should be one of the symbols
+@code{left}, @code{right}, @code{full}, @code{center}, or @code{none}.
+
+@node Format Properties
+@subsection Setting Other Text Properties
+
+ The Other Properties menu lets you add or remove three other useful text
+properties: @code{read-only}, @code{invisible} and @code{intangible}.
+The @code{intangible} property disallows moving point within the text,
+the @code{invisible} text property hides text from display, and the
+@code{read-only} property disallows alteration of the text.
+
+ Each of these special properties has a menu item to add it to the
+region. The last menu item, @samp{Remove Special}, removes all of these
+special properties from the text in the region.
+
+ Currently, the @code{invisible} and @code{intangible} properties are
+@emph{not} saved in the text/enriched format. The @code{read-only}
+property is saved, but it is not a standard part of the text/enriched
+format, so other editors may not respect it.
+
+@node Forcing Enriched Mode
+@subsection Forcing Enriched Mode
+
+ Normally, Emacs knows when you are editing formatted text because it
+recognizes the special annotations used in the file that you visited.
+However, there are situations in which you must take special actions
+to convert file contents or turn on Enriched mode:
+
+@itemize @bullet
+@item
+When you visit a file that was created with some other editor, Emacs may
+not recognize the file as being in the text/enriched format. In this
+case, when you visit the file you will see the formatting commands
+rather than the formatted text. Type @kbd{M-x format-decode-buffer} to
+translate it.
+
+@item
+When you @emph{insert} a file into a buffer, rather than visiting it.
+Emacs does the necessary conversions on the text which you insert, but
+it does not enable Enriched mode. If you wish to do that, type @kbd{M-x
+enriched-mode}.
+@end itemize
+
+ The command @code{format-decode-buffer} translates text in various
+formats into Emacs's internal format. It asks you to specify the format
+to translate from; however, normally you can type just @key{RET}, which
+tells Emacs to guess the format.
+
+@findex format-find-file
+ If you wish to look at text/enriched file in its raw form, as a
+sequence of characters rather than as formatted text, use the @kbd{M-x
+find-file-literally} command. This visits a file, like
+@code{find-file}, but does not do format conversion. It also inhibits
+character code conversion (@pxref{Coding Systems}) and automatic
+uncompression (@pxref{Compressed Files}). To disable format conversion
+but allow character code conversion and/or automatic uncompression if
+appropriate, use @code{format-find-file} with suitable arguments.
+
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@iftex
+@chapter Dealing with Common Problems
+
+ If you type an Emacs command you did not intend, the results are often
+mysterious. This chapter tells what you can do to cancel your mistake or
+recover from a mysterious situation. Emacs bugs and system crashes are
+also considered.
+@end iftex
+
+@node Quitting, Lossage, Customization, Top
+@section Quitting and Aborting
+@cindex quitting
+
+@table @kbd
+@item C-g
+@itemx C-@key{BREAK} (MS-DOS)
+Quit. Cancel running or partially typed command.
+@item C-]
+Abort innermost recursive editing level and cancel the command which
+invoked it (@code{abort-recursive-edit}).
+@item @key{ESC} @key{ESC} @key{ESC}
+Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}).
+@item M-x top-level
+Abort all recursive editing levels that are currently executing.
+@item C-x u
+Cancel a previously made change in the buffer contents (@code{undo}).
+@end table
+
+ There are two ways of canceling commands which are not finished
+executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with
+@kbd{C-]} or @kbd{M-x top-level}. Quitting cancels a partially typed
+command or one which is already running. Aborting exits a recursive
+editing level and cancels the command that invoked the recursive edit.
+(@xref{Recursive Edit}.)
+
+@cindex quitting
+@kindex C-g
+ Quitting with @kbd{C-g} is used for getting rid of a partially typed
+command, or a numeric argument that you don't want. It also stops a
+running command in the middle in a relatively safe way, so you can use
+it if you accidentally give a command which takes a long time. In
+particular, it is safe to quit out of killing; either your text will
+@emph{all} still be in the buffer, or it will @emph{all} be in the kill
+ring (or maybe both). Quitting an incremental search does special
+things documented under searching; in general, it may take two
+successive @kbd{C-g} characters to get out of a search
+(@pxref{Incremental Search}).
+
+ On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character
+like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to
+recognize @kbd{C-g} while a command is running, between interactions
+with the user. By contrast, it @emph{is} feasible to recognize
+@kbd{C-@key{BREAK}} at all times. @xref{MS-DOS Input}.
+
+ @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t}
+the instant @kbd{C-g} is typed; Emacs Lisp checks this variable
+frequently and quits if it is non-@code{nil}. @kbd{C-g} is only
+actually executed as a command if you type it while Emacs is waiting for
+input.
+
+ If you quit with @kbd{C-g} a second time before the first @kbd{C-g} is
+recognized, you activate the ``emergency escape'' feature and return to
+the shell. @xref{Emergency Escape}.
+
+@cindex NFS and quitting
+ There may be times when you cannot quit. When Emacs is waiting for
+the operating system to do something, quitting is impossible unless
+special pains are taken for the particular system call within Emacs
+where the waiting occurs. We have done this for the system calls that
+users are likely to want to quit from, but it's possible you will find
+another. In one very common case---waiting for file input or output
+using NFS---Emacs itself knows how to quit, but most NFS implementations
+simply do not allow user programs to stop waiting for NFS when the NFS
+server is hung.
+
+@cindex aborting recursive edit
+@findex abort-recursive-edit
+@kindex C-]
+ Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get
+out of a recursive editing level and cancel the command which invoked
+it. Quitting with @kbd{C-g} does not do this, and could not do this,
+because it is used to cancel a partially typed command @emph{within} the
+recursive editing level. Both operations are useful. For example, if
+you are in a recursive edit and type @kbd{C-u 8} to enter a numeric
+argument, you can cancel that argument with @kbd{C-g} and remain in the
+recursive edit.
+
+@findex keyboard-escape-quit
+@kindex ESC ESC ESC
+ The command @kbd{@key{ESC} @key{ESC} @key{ESC}}
+(@code{keyboard-escape-quit}) can either quit or abort. This key was
+defined because @key{ESC} is used to ``get out'' in many PC programs.
+It can cancel a prefix argument, clear a selected region, or get out of
+a Query Replace, like @kbd{C-g}. It can get out of the minibuffer or a
+recursive edit, like @kbd{C-]}. It can also get out of splitting the
+frame into multiple windows, like @kbd{C-x 1}. One thing it cannot do,
+however, is stop a command that is running. That's because it executes
+as an ordinary command, and Emacs doesn't notice it until it is ready
+for a command.
+
+@findex top-level
+ The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]}
+commands to get you out of all the levels of recursive edits that you
+are in. @kbd{C-]} gets you out one level at a time, but @kbd{M-x
+top-level} goes out all levels at once. Both @kbd{C-]} and @kbd{M-x
+top-level} are like all other commands, and unlike @kbd{C-g}, in that
+they take effect only when Emacs is ready for a command. @kbd{C-]} is
+an ordinary key and has its meaning only because of its binding in the
+keymap. @xref{Recursive Edit}.
+
+ @kbd{C-x u} (@code{undo}) is not strictly speaking a way of canceling
+a command, but you can think of it as canceling a command that already
+finished executing. @xref{Undo}.
+
+@node Lossage, Bugs, Quitting, Top
+@section Dealing with Emacs Trouble
+
+ This section describes various conditions in which Emacs fails to work
+normally, and how to recognize them and correct them.
+
+@menu
+* DEL Gets Help:: What to do if @key{DEL} doesn't delete.
+* Stuck Recursive:: `[...]' in mode line around the parentheses.
+* Screen Garbled:: Garbage on the screen.
+* Text Garbled:: Garbage in the text.
+* Unasked-for Search:: Spontaneous entry to incremental search.
+* Memory Full:: How to cope when you run out of memory.
+* After a Crash:: Recovering editing in an Emacs session that crashed.
+* Emergency Escape:: Emergency escape---
+ What to do if Emacs stops responding.
+* Total Frustration:: When you are at your wits' end.
+@end menu
+
+@node DEL Gets Help
+@subsection If @key{DEL} Fails to Delete
+
+ If you find that @key{DEL} enters Help like @kbd{Control-h} instead of
+deleting a character, your terminal is sending the wrong code for
+@key{DEL}. You can work around this problem by changing the keyboard
+translation table (@pxref{Keyboard Translations}).
+
+@node Stuck Recursive
+@subsection Recursive Editing Levels
+
+ Recursive editing levels are important and useful features of Emacs, but
+they can seem like malfunctions to the user who does not understand them.
+
+ If the mode line has square brackets @samp{[@dots{}]} around the parentheses
+that contain the names of the major and minor modes, you have entered a
+recursive editing level. If you did not do this on purpose, or if you
+don't understand what that means, you should just get out of the recursive
+editing level. To do so, type @kbd{M-x top-level}. This is called getting
+back to top level. @xref{Recursive Edit}.
+
+@node Screen Garbled
+@subsection Garbage on the Screen
+
+ If the data on the screen looks wrong, the first thing to do is see
+whether the text is really wrong. Type @kbd{C-l}, to redisplay the
+entire screen. If the screen appears correct after this, the problem
+was entirely in the previous screen update. (Otherwise, see @ref{Text
+Garbled}.)
+
+ Display updating problems often result from an incorrect termcap entry
+for the terminal you are using. The file @file{etc/TERMS} in the Emacs
+distribution gives the fixes for known problems of this sort.
+@file{INSTALL} contains general advice for these problems in one of its
+sections. Very likely there is simply insufficient padding for certain
+display operations. To investigate the possibility that you have this sort
+of problem, try Emacs on another terminal made by a different manufacturer.
+If problems happen frequently on one kind of terminal but not another kind,
+it is likely to be a bad termcap entry, though it could also be due to a
+bug in Emacs that appears for terminals that have or that lack specific
+features.
+
+@node Text Garbled
+@subsection Garbage in the Text
+
+ If @kbd{C-l} shows that the text is wrong, try undoing the changes to it
+using @kbd{C-x u} until it gets back to a state you consider correct. Also
+try @kbd{C-h l} to find out what command you typed to produce the observed
+results.
+
+ If a large portion of text appears to be missing at the beginning or
+end of the buffer, check for the word @samp{Narrow} in the mode line.
+If it appears, the text you don't see is probably still present, but
+temporarily off-limits. To make it accessible again, type @kbd{C-x n
+w}. @xref{Narrowing}.
+
+@node Unasked-for Search
+@subsection Spontaneous Entry to Incremental Search
+
+ If Emacs spontaneously displays @samp{I-search:} at the bottom of the
+screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q}
+according to the poorly designed xon/xoff ``flow control'' protocol.
+
+ If this happens to you, your best recourse is to put the terminal in a
+mode where it will not use flow control, or give it so much padding that
+it will never send a @kbd{C-s}. (One way to increase the amount of
+padding is to set the variable @code{baud-rate} to a larger value. Its
+value is the terminal output speed, measured in the conventional units
+of baud.)
+
+@cindex flow control
+@cindex xon-xoff
+@findex enable-flow-control
+ If you don't succeed in turning off flow control, the next best thing
+is to tell Emacs to cope with it. To do this, call the function
+@code{enable-flow-control}.
+
+@findex enable-flow-control-on
+ Typically there are particular terminal types with which you must use
+flow control. You can conveniently ask for flow control on those
+terminal types only, using @code{enable-flow-control-on}. For example,
+if you find you must use flow control on VT-100 and H19 terminals, put
+the following in your @file{.emacs} file:
+
+@example
+(enable-flow-control-on "vt100" "h19")
+@end example
+
+ When flow control is enabled, you must type @kbd{C-\} to get the
+effect of a @kbd{C-s}, and type @kbd{C-^} to get the effect of a
+@kbd{C-q}. (These aliases work by means of keyboard translations; see
+@ref{Keyboard Translations}.)
+
+@node Memory Full
+@subsection Running out of Memory
+@cindex memory full
+@cindex out of memory
+
+ If you get the error message @samp{Virtual memory exceeded}, save your
+modified buffers with @kbd{C-x s}. This method of saving them has the
+smallest need for additional memory. Emacs keeps a reserve of memory
+which it makes available when this error happens; that should be enough
+to enable @kbd{C-x s} to complete its work.
+
+ Once you have saved your modified buffers, you can exit this Emacs job
+and start another, or you can use @kbd{M-x kill-some-buffers} to free
+space in the current Emacs job. If you kill buffers containing a
+substantial amount of text, you can safely go on editing. Emacs refills
+its memory reserve automatically when it sees sufficient free space
+available, in case you run out of memory another time.
+
+ Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run
+out of memory, because the buffer menu needs a fair amount memory
+itself, and the reserve supply may not be enough.
+
+@node After a Crash
+@subsection Recovery After a Crash
+
+ If Emacs or the computer crashes, you can recover the files you were
+editing at the time of the crash from their auto-save files. To do
+this, start Emacs again and type the command @kbd{M-x recover-session}.
+
+ This command initially displays a buffer which lists interrupted
+session files, each with its date. You must choose which session to
+recover from. Typically the one you want is the most recent one. Move
+point to the one you choose, and type @kbd{C-c C-c}.
+
+ Then @code{recover-session} asks about each of the files that you were
+editing during that session; it asks whether to recover that file. If
+you answer @kbd{y} for a file, it shows the dates of that file and its
+auto-save file, then asks once again whether to recover that file. For
+the second question, you must confirm with @kbd{yes}. If you do, Emacs
+visits the file but gets the text from the auto-save file.
+
+ When @code{recover-session} is done, the files you've chosen to
+recover are present in Emacs buffers. You should then save them. Only
+this---saving them---updates the files themselves.
+
+@node Emergency Escape
+@subsection Emergency Escape
+
+ Because at times there have been bugs causing Emacs to loop without
+checking @code{quit-flag}, a special feature causes Emacs to be suspended
+immediately if you type a second @kbd{C-g} while the flag is already set,
+so you can always get out of GNU Emacs. Normally Emacs recognizes and
+clears @code{quit-flag} (and quits!) quickly enough to prevent this from
+happening. (On MS-DOS and compatible systems, type @kbd{C-@key{BREAK}}
+twice.)
+
+ When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it
+asks two questions before going back to what it had been doing:
+
+@example
+Auto-save? (y or n)
+Abort (and dump core)? (y or n)
+@end example
+
+@noindent
+Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}.
+
+ Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all
+modified buffers in which auto-saving is enabled.
+
+ Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be
+executed, dumping core. This is to enable a wizard to figure out why Emacs
+was failing to quit in the first place. Execution does not continue
+after a core dump. If you answer @kbd{n}, execution does continue. With
+luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally.
+If not, and you type another @kbd{C-g}, it is suspended again.
+
+ If Emacs is not really hung, just slow, you may invoke the double
+@kbd{C-g} feature without really meaning to. Then just resume and answer
+@kbd{n} to both questions, and you will arrive at your former state.
+Presumably the quit you requested will happen soon.
+
+ The double-@kbd{C-g} feature is turned off when Emacs is running under
+the X Window System, since you can use the window manager to kill Emacs
+or to create another window and run another program.
+
+ On MS-DOS and compatible systems, the emergency escape feature is
+sometimes unavailable, even if you press @kbd{C-@key{BREAK}} twice, when
+some system call (MS-DOS or BIOS) hangs, or when Emacs is stuck in a
+very tight endless loop (in C code, @strong{not} in Lisp code).
+
+@node Total Frustration
+@subsection Help for Total Frustration
+@cindex Eliza
+@cindex doctor
+
+ If using Emacs (or something else) becomes terribly frustrating and none
+of the techniques described above solve the problem, Emacs can still help
+you.
+
+ First, if the Emacs you are using is not responding to commands, type
+@kbd{C-g C-g} to get out of it and then start a new one.
+
+@findex doctor
+ Second, type @kbd{M-x doctor @key{RET}}.
+
+ The doctor will help you feel better. Each time you say something to
+the doctor, you must end it by typing @key{RET} @key{RET}. This lets
+the doctor know you are finished.
+
+@node Bugs, Contributing, Lossage, Top
+@section Reporting Bugs
+
+@cindex bugs
+ Sometimes you will encounter a bug in Emacs. Although we cannot
+promise we can or will fix the bug, and we might not even agree that it
+is a bug, we want to hear about problems you encounter. Often we agree
+they are bugs and want to fix them.
+
+ To make it possible for us to fix a bug, you must report it. In order
+to do so effectively, you must know when and how to do it.
+
+@menu
+* Criteria: Bug Criteria. Have you really found a bug?
+* Understanding Bug Reporting:: How to report a bug effectively.
+* Checklist:: Steps to follow for a good bug report.
+* Sending Patches:: How to send a patch for GNU Emacs.
+@end menu
+
+@node Bug Criteria
+@subsection When Is There a Bug
+
+ If Emacs executes an illegal instruction, or dies with an operating
+system error message that indicates a problem in the program (as opposed to
+something like ``disk full''), then it is certainly a bug.
+
+ If Emacs updates the display in a way that does not correspond to what is
+in the buffer, then it is certainly a bug. If a command seems to do the
+wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a
+case of incorrect display updating.
+
+ Taking forever to complete a command can be a bug, but you must make
+certain that it was really Emacs's fault. Some commands simply take a
+long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then @kbd{C-h l}
+to see whether the input Emacs received was what you intended to type;
+if the input was such that you @emph{know} it should have been processed
+quickly, report a bug. If you don't know whether the command should
+take a long time, find out by looking in the manual or by asking for
+assistance.
+
+ If a command you are familiar with causes an Emacs error message in a
+case where its usual definition ought to be reasonable, it is probably a
+bug.
+
+ If a command does the wrong thing, that is a bug. But be sure you know
+for certain what it ought to have done. If you aren't familiar with the
+command, or don't know for certain how the command is supposed to work,
+then it might actually be working right. Rather than jumping to
+conclusions, show the problem to someone who knows for certain.
+
+ Finally, a command's intended definition may not be best for editing
+with. This is a very important sort of problem, but it is also a matter of
+judgment. Also, it is easy to come to such a conclusion out of ignorance
+of some of the existing features. It is probably best not to complain
+about such a problem until you have checked the documentation in the usual
+ways, feel confident that you understand it, and know for certain that what
+you want is not available. If you are not sure what the command is
+supposed to do after a careful reading of the manual, check the index and
+glossary for any terms that may be unclear.
+
+ If after careful rereading of the manual you still do not understand
+what the command should do, that indicates a bug in the manual, which
+you should report. The manual's job is to make everything clear to
+people who are not Emacs experts---including you. It is just as
+important to report documentation bugs as program bugs.
+
+ If the on-line documentation string of a function or variable disagrees
+with the manual, one of them must be wrong; that is a bug.
+
+@node Understanding Bug Reporting
+@subsection Understanding Bug Reporting
+
+@findex emacs-version
+ When you decide that there is a bug, it is important to report it and to
+report it in a way which is useful. What is most useful is an exact
+description of what commands you type, starting with the shell command to
+run Emacs, until the problem happens.
+
+ The most important principle in reporting a bug is to report
+@emph{facts}. Hypotheses and verbal descriptions are no substitute for
+the detailed raw data. Reporting the facts is straightforward, but many
+people strain to posit explanations and report them instead of the
+facts. If the explanations are based on guesses about how Emacs is
+implemented, they will be useless; meanwhile, lacking the facts, we will
+have no real information about the bug.
+
+ For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
+@key{RET}}, visiting a file which (you know) happens to be rather large,
+and Emacs displayed @samp{I feel pretty today}. The best way to report
+the bug is with a sentence like the preceding one, because it gives all
+the facts.
+
+ A bad way would be to assume that the problem is due to the size of
+the file and say, ``I visited a large file, and Emacs displayed @samp{I
+feel pretty today}.'' This is what we mean by ``guessing
+explanations.'' The problem is just as likely to be due to the fact
+that there is a @samp{z} in the file name. If this is so, then when we
+got your report, we would try out the problem with some ``large file,''
+probably with no @samp{z} in its name, and not see any problem. There
+is no way in the world that we could guess that we should try visiting a
+file with a @samp{z} in its name.
+
+ Alternatively, the problem might be due to the fact that the file starts
+with exactly 25 spaces. For this reason, you should make sure that you
+inform us of the exact contents of any file that is needed to reproduce the
+bug. What if the problem only occurs when you have typed the @kbd{C-x C-a}
+command previously? This is why we ask you to give the exact sequence of
+characters you typed since starting the Emacs session.
+
+ You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless
+you @emph{know} that it makes no difference which visiting command is used.
+Similarly, rather than saying ``if I have three characters on the line,''
+say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is
+the way you entered the text.@refill
+
+ So please don't guess any explanations when you report a bug. If you
+want to actually @emph{debug} the problem, and report explanations that
+are more than guesses, that is useful---but please include the facts as
+well.
+
+@node Checklist
+@subsection Checklist for Bug Reports
+
+@cindex reporting bugs
+ The best way to send a bug report is to mail it electronically to the
+Emacs maintainers at @samp{bug-gnu-emacs@@gnu.org}. (If you
+want to suggest a change as an improvement, use the same address.)
+
+ If you'd like to read the bug reports, you can find them on the
+newsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as a
+spectator you should not criticize anything about what you see there.
+The purpose of bug reports is to give information to the Emacs
+maintainers. Spectators are welcome only as long as they do not
+interfere with this. In particular, some bug reports contain large
+amounts of data; spectators should not complain about this.
+
+ Please do not post bug reports using netnews; mail is more reliable
+than netnews about reporting your correct address, which we may need in
+order to ask you for more information.
+
+ If you can't send electronic mail, then mail the bug report on paper
+or machine-readable media to this address:
+
+@format
+GNU Emacs Bugs
+Free Software Foundation
+59 Temple Place, Suite 330
+Boston, MA 02111-1307 USA
+@end format
+
+ We do not promise to fix the bug; but if the bug is serious,
+or ugly, or easy to fix, chances are we will want to.
+
+@findex report-emacs-bug
+ A convenient way to send a bug report for Emacs is to use the command
+@kbd{M-x report-emacs-bug}. This sets up a mail buffer (@pxref{Sending
+Mail}) and automatically inserts @emph{some} of the essential
+information. However, it cannot supply all the necessary information;
+you should still read and follow the guidelines below, so you can enter
+the other crucial information by hand before you send the message.
+
+ To enable maintainers to investigate a bug, your report
+should include all these things:
+
+@itemize @bullet
+@item
+The version number of Emacs. Without this, we won't know whether there
+is any point in looking for the bug in the current version of GNU
+Emacs.
+
+You can get the version number by typing @kbd{M-x emacs-version
+@key{RET}}. If that command does not work, you probably have something
+other than GNU Emacs, so you will have to report the bug somewhere
+else.
+
+@item
+The type of machine you are using, and the operating system name and
+version number. @kbd{M-x emacs-version @key{RET}} provides this
+information too. Copy its output from the @samp{*Messages*} buffer, so
+that you get it all and get it accurately.
+
+@item
+The operands given to the @code{configure} command when Emacs was
+installed.
+
+@item
+A complete list of any modifications you have made to the Emacs source.
+(We may not have time to investigate the bug unless it happens in an
+unmodified Emacs. But if you've made modifications and you don't tell
+us, you are sending us on a wild goose chase.)
+
+Be precise about these changes. A description in English is not
+enough---send a context diff for them.
+
+Adding files of your own, or porting to another machine, is a
+modification of the source.
+
+@item
+Details of any other deviations from the standard procedure for installing
+GNU Emacs.
+
+@item
+The complete text of any files needed to reproduce the bug.
+
+ If you can tell us a way to cause the problem without visiting any files,
+please do so. This makes it much easier to debug. If you do need files,
+make sure you arrange for us to see their exact contents. For example, it
+can often matter whether there are spaces at the ends of lines, or a
+newline after the last line in the buffer (nothing ought to care whether
+the last line is terminated, but try telling the bugs that).
+
+@item
+The precise commands we need to type to reproduce the bug.
+
+@findex open-dribble-file
+@cindex dribble file
+ The easy way to record the input to Emacs precisely is to write a
+dribble file. To start the file, execute the Lisp expression
+
+@example
+(open-dribble-file "~/dribble")
+@end example
+
+@noindent
+using @kbd{M-:} or from the @samp{*scratch*} buffer just after
+starting Emacs. From then on, Emacs copies all your input to the
+specified dribble file until the Emacs process is killed.
+
+@item
+@findex open-termscript
+@cindex termscript file
+@cindex @code{TERM} environment variable
+For possible display bugs, the terminal type (the value of environment
+variable @code{TERM}), the complete termcap entry for the terminal from
+@file{/etc/termcap} (since that file is not identical on all machines),
+and the output that Emacs actually sent to the terminal.
+
+The way to collect the terminal output is to execute the Lisp expression
+
+@example
+(open-termscript "~/termscript")
+@end example
+
+@noindent
+using @kbd{M-:} or from the @samp{*scratch*} buffer just after
+starting Emacs. From then on, Emacs copies all terminal output to the
+specified termscript file as well, until the Emacs process is killed.
+If the problem happens when Emacs starts up, put this expression into
+your @file{.emacs} file so that the termscript file will be open when
+Emacs displays the screen for the first time.
+
+Be warned: it is often difficult, and sometimes impossible, to fix a
+terminal-dependent bug without access to a terminal of the type that
+stimulates the bug.@refill
+
+@item
+A description of what behavior you observe that you believe is
+incorrect. For example, ``The Emacs process gets a fatal signal,'' or,
+``The resulting text is as follows, which I think is wrong.''
+
+Of course, if the bug is that Emacs gets a fatal signal, then one can't
+miss it. But if the bug is incorrect text, the maintainer might fail to
+notice what is wrong. Why leave it to chance?
+
+Even if the problem you experience is a fatal signal, you should still
+say so explicitly. Suppose something strange is going on, such as, your
+copy of the source is out of sync, or you have encountered a bug in the
+C library on your system. (This has happened!) Your copy might crash
+and the copy here might not. If you @emph{said} to expect a crash, then
+when Emacs here fails to crash, we would know that the bug was not
+happening. If you don't say to expect a crash, then we would not know
+whether the bug was happening---we would not be able to draw any
+conclusion from our observations.
+
+@item
+If the manifestation of the bug is an Emacs error message, it is
+important to report the precise text of the error message, and a
+backtrace showing how the Lisp program in Emacs arrived at the error.
+
+To get the error message text accurately, copy it from the
+@samp{*Messages*} buffer into the bug report. Copy all of it, not just
+part.
+
+To make a backtrace for the error, evaluate the Lisp expression
+@code{(setq @w{debug-on-error t})} before the error happens (that is to
+say, you must execute that expression and then make the bug happen).
+This causes the error to run the Lisp debugger, which shows you a
+backtrace. Copy the text of the debugger's backtrace into the bug
+report.
+
+This use of the debugger is possible only if you know how to make the
+bug happen again. If you can't make it happen again, at least copy
+the whole error message.
+
+@item
+Check whether any programs you have loaded into the Lisp world,
+including your @file{.emacs} file, set any variables that may affect the
+functioning of Emacs. Also, see whether the problem happens in a
+freshly started Emacs without loading your @file{.emacs} file (start
+Emacs with the @code{-q} switch to prevent loading the init file). If
+the problem does @emph{not} occur then, you must report the precise
+contents of any programs that you must load into the Lisp world in order
+to cause the problem to occur.
+
+@item
+If the problem does depend on an init file or other Lisp programs that
+are not part of the standard Emacs system, then you should make sure it
+is not a bug in those programs by complaining to their maintainers
+first. After they verify that they are using Emacs in a way that is
+supposed to work, they should report the bug.
+
+@item
+If you wish to mention something in the GNU Emacs source, show the line
+of code with a few lines of context. Don't just give a line number.
+
+The line numbers in the development sources don't match those in your
+sources. It would take extra work for the maintainers to determine what
+code is in your version at a given line number, and we could not be
+certain.
+
+@item
+Additional information from a C debugger such as GDB might enable
+someone to find a problem on a machine which he does not have available.
+If you don't know how to use GDB, please read the GDB manual---it is not
+very long, and using GDB is easy. You can find the GDB distribution,
+including the GDB manual in online form, in most of the same places you
+can find the Emacs distribution. To run Emacs under GDB, you should
+switch to the @file{src} subdirectory in which Emacs was compiled, then
+do @samp{gdb emacs}. It is important for the directory @file{src} to be
+current so that GDB will read the @file{.gdbinit} file in this
+directory.
+
+However, you need to think when you collect the additional information
+if you want it to show what causes the bug.
+
+@cindex backtrace for bug reports
+For example, many people send just a backtrace, but that is not very
+useful by itself. A simple backtrace with arguments often conveys
+little about what is happening inside GNU Emacs, because most of the
+arguments listed in the backtrace are pointers to Lisp objects. The
+numeric values of these pointers have no significance whatever; all that
+matters is the contents of the objects they point to (and most of the
+contents are themselves pointers).
+
+@findex debug_print
+To provide useful information, you need to show the values of Lisp
+objects in Lisp notation. Do this for each variable which is a Lisp
+object, in several stack frames near the bottom of the stack. Look at
+the source to see which variables are Lisp objects, because the debugger
+thinks of them as integers.
+
+To show a variable's value in Lisp syntax, first print its value, then
+use the user-defined GDB command @code{pr} to print the Lisp object in
+Lisp syntax. (If you must use another debugger, call the function
+@code{debug_print} with the object as an argument.) The @code{pr}
+command is defined by the file @file{.gdbinit}, and it works only if you
+are debugging a running process (not with a core dump).
+
+To make Lisp errors stop Emacs and return to GDB, put a breakpoint at
+@code{Fsignal}.
+
+To find out which Lisp functions are running, using GDB, move up the
+stack, and each time you get to a frame for the function
+@code{Ffuncall}, type these GDB commands:
+
+@example
+p *args
+pr
+@end example
+
+@noindent
+To print the first argument that the function received, use these
+commands:
+
+@example
+p args[1]
+pr
+@end example
+
+@noindent
+You can print the other arguments likewise. The argument @code{nargs}
+of @code{Ffuncall} says how many arguments @code{Ffuncall} received;
+these include the Lisp function itself and the arguments for that
+function.
+
+The file @file{.gdbinit} defines several other commands that are useful
+for examining the data types and contents of Lisp objects. Their names
+begin with @samp{x}. These commands work at a lower level than
+@code{pr}, and are less convenient, but they may work even when
+@code{pr} does not, such as when debugging a core dump or when Emacs has
+had a fatal signal.
+
+@item
+If the symptom of the bug is that Emacs fails to respond, don't assume
+Emacs is ``hung''---it may instead be in an infinite loop. To find out
+which, make the problem happen under GDB and stop Emacs once it is not
+responding. (If Emacs is using X Windows directly, you can stop Emacs
+by typing @kbd{C-z} at the GDB job.) Then try stepping with
+@samp{step}. If Emacs is hung, the @samp{step} command won't return.
+If it is looping, @samp{step} will return.
+
+If this shows Emacs is hung in a system call, stop it again and examine
+the arguments of the call. In your bug report, state exactly where in
+the source the system call is, and what the arguments are.
+
+If Emacs is in an infinite loop, please determine where the loop starts
+and ends. The easiest way to do this is to use the GDB command
+@samp{finish}. Each time you use it, Emacs resumes execution until it
+exits one stack frame. Keep typing @samp{finish} until it doesn't
+return---that means the infinite loop is in the stack frame which you
+just tried to finish.
+
+Stop Emacs again, and use @samp{finish} repeatedly again until you get
+@emph{back to} that frame. Then use @samp{next} to step through that
+frame. By stepping, you will see where the loop starts and ends. Also
+please examine the data being used in the loop and try to determine why
+the loop does not exit when it should. Include all of this information
+in your bug report.
+@end itemize
+
+Here are some things that are not necessary in a bug report:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug---this is not necessary for a
+reproducible bug.
+
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
+
+This is often time-consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger with
+breakpoints, not by pure deduction from a series of examples. You might
+as well save time by not searching for additional examples.
+
+Of course, if you can find a simpler example to report @emph{instead} of
+the original one, that is a convenience. Errors in the output will be
+easier to spot, running under the debugger will take less time, etc.
+
+However, simplification is not vital; if you can't do this or don't have
+time to try, please report the bug with your original test case.
+
+@item
+A system-call trace of Emacs execution.
+
+System-call traces are very useful for certain special kinds of
+debugging, but in most cases they give little useful information. It is
+therefore strange that many people seem to think that @emph{the} way to
+report information about a crash is to send a system-call trace. Perhaps
+this is a habit formed from experience debugging programs that don't
+have source code or debugging symbols.
+
+In most programs, a backtrace is normally far, far more informative than
+a system-call trace. Even in Emacs, a simple backtrace is generally
+more informative, though to give full information you should supplement
+the backtrace by displaying variable values and printing them as Lisp
+objects with @code{pr} (see above).
+
+@item
+A patch for the bug.
+
+A patch for the bug is useful if it is a good one. But don't omit the
+other information that a bug report needs, such as the test case, on the
+assumption that a patch is sufficient. We might see problems with your
+patch and decide to fix the problem another way, or we might not
+understand it at all. And if we can't understand what bug you are
+trying to fix, or why your patch should be an improvement, we mustn't
+install it.
+
+@ifinfo
+@xref{Sending Patches}, for guidelines on how to make it easy for us to
+understand and install your patches.
+@end ifinfo
+
+@item
+A guess about what the bug is or what it depends on.
+
+Such guesses are usually wrong. Even experts can't guess right about
+such things without first using the debugger to find the facts.
+@end itemize
+
+@node Sending Patches
+@subsection Sending Patches for GNU Emacs
+
+@cindex sending patches for GNU Emacs
+@cindex patches, sending
+ If you would like to write bug fixes or improvements for GNU Emacs,
+that is very helpful. When you send your changes, please follow these
+guidelines to make it easy for the maintainers to use them. If you
+don't follow these guidelines, your information might still be useful,
+but using it will take extra work. Maintaining GNU Emacs is a lot of
+work in the best of circumstances, and we can't keep up unless you do
+your best to help.
+
+@itemize @bullet
+@item
+Send an explanation with your changes of what problem they fix or what
+improvement they bring about. For a bug fix, just include a copy of the
+bug report, and explain why the change fixes the bug.
+
+(Referring to a bug report is not as good as including it, because then
+we will have to look it up, and we have probably already deleted it if
+we've already fixed the bug.)
+
+@item
+Always include a proper bug report for the problem you think you have
+fixed. We need to convince ourselves that the change is right before
+installing it. Even if it is correct, we might have trouble
+understanding it if we don't have a way to reproduce the problem.
+
+@item
+Include all the comments that are appropriate to help people reading the
+source in the future understand why this change was needed.
+
+@item
+Don't mix together changes made for different reasons.
+Send them @emph{individually}.
+
+If you make two changes for separate reasons, then we might not want to
+install them both. We might want to install just one. If you send them
+all jumbled together in a single set of diffs, we have to do extra work
+to disentangle them---to figure out which parts of the change serve
+which purpose. If we don't have time for this, we might have to ignore
+your changes entirely.
+
+If you send each change as soon as you have written it, with its own
+explanation, then two changes never get tangled up, and we can consider
+each one properly without any extra work to disentangle them.
+
+@item
+Send each change as soon as that change is finished. Sometimes people
+think they are helping us by accumulating many changes to send them all
+together. As explained above, this is absolutely the worst thing you
+could do.
+
+Since you should send each change separately, you might as well send it
+right away. That gives us the option of installing it immediately if it
+is important.
+
+@item
+Use @samp{diff -c} to make your diffs. Diffs without context are hard
+to install reliably. More than that, they are hard to study; we must
+always study a patch to decide whether we want to install it. Unidiff
+format is better than contextless diffs, but not as easy to read as
+@samp{-c} format.
+
+If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when
+making diffs of C code. This shows the name of the function that each
+change occurs in.
+
+@item
+Avoid any ambiguity as to which is the old version and which is the new.
+Please make the old version the first argument to diff, and the new
+version the second argument. And please give one version or the other a
+name that indicates whether it is the old version or your new changed
+one.
+
+@item
+Write the change log entries for your changes. This is both to save us
+the extra work of writing them, and to help explain your changes so we
+can understand them.
+
+The purpose of the change log is to show people where to find what was
+changed. So you need to be specific about what functions you changed;
+in large functions, it's often helpful to indicate where within the
+function the change was.
+
+On the other hand, once you have shown people where to find the change,
+you need not explain its purpose in the change log. Thus, if you add a
+new function, all you need to say about it is that it is new. If you
+feel that the purpose needs explaining, it probably does---but put the
+explanation in comments in the code. It will be more useful there.
+
+Please read the @file{ChangeLog} files in the @file{src} and @file{lisp}
+directories to see what sorts of information to put in, and to learn the
+style that we use. If you would like your name to appear in the header
+line, showing who made the change, send us the header line.
+@xref{Change Log}.
+
+@item
+When you write the fix, keep in mind that we can't install a change that
+would break other systems. Please think about what effect your change
+will have if compiled on another type of system.
+
+Sometimes people send fixes that @emph{might} be an improvement in
+general---but it is hard to be sure of this. It's hard to install
+such changes because we have to study them very carefully. Of course,
+a good explanation of the reasoning by which you concluded the change
+was correct can help convince us.
+
+The safest changes are changes to the configuration files for a
+particular machine. These are safe because they can't create new bugs
+on other machines.
+
+Please help us keep up with the workload by designing the patch in a
+form that is clearly safe to install.
+@end itemize
+
+@node Contributing, Service, Bugs, Top
+@section Contributing to Emacs Development
+
+If you would like to help pretest Emacs releases to assure they work
+well, or if you would like to work on improving Emacs, please contact
+the maintainers at @code{bug-gnu-emacs@@gnu.org}. A pretester
+should be prepared to investigate bugs as well as report them. If you'd
+like to work on improving Emacs, please ask for suggested projects or
+suggest your own ideas.
+
+If you have already written an improvement, please tell us about it. If
+you have not yet started work, it is useful to contact
+@code{bug-gnu-emacs@@gnu.org} before you start; it might be
+possible to suggest ways to make your extension fit in better with the
+rest of Emacs.
+
+@node Service, Command Arguments, Contributing, Top
+@section How To Get Help with GNU Emacs
+
+If you need help installing, using or changing GNU Emacs, there are two
+ways to find it:
+
+@itemize @bullet
+@item
+Send a message to the mailing list
+@code{help-gnu-emacs@@gnu.org}, or post your request on
+newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup
+interconnect, so it does not matter which one you use.)
+
+@item
+Look in the service directory for someone who might help you for a fee.
+The service directory is found in the file named @file{etc/SERVICE} in the
+Emacs distribution.
+@end itemize
--- /dev/null
+\input texinfo
+
+@setfilename ../info/vip
+@settitle VIP
+
+@dircategory Editors
+@direntry
+* VIP: (vip). An older VI-emulation for Emacs.
+@end direntry
+
+@iftex
+@finalout
+@end iftex
+
+@titlepage
+@sp 10
+@center @titlefont{VIP}
+@sp 1
+@center A Vi Package for GNU Emacs
+@center (Version 3.5, September 15, 1987)
+@sp 2
+@center Masahiko Sato
+@sp 2
+@end titlepage
+
+@unnumbered Distribution
+
+Copyright @copyright{} 1987 Masahiko Sato.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the same conditions as for modified versions.
+
+@ifinfo
+@node Top, Survey,, (DIR)
+@top VIP
+
+VIP is a Vi emulating package written in Emacs Lisp. VIP implements most
+Vi commands including Ex commands. It is therefore hoped that this package
+will enable you to do Vi style editing under the powerful GNU Emacs
+environment. This info file describes the usage of VIP assuming that you
+are fairly accustomed to Vi but not so much with Emacs. Also we will
+concentrate mainly on differences from Vi, especially features unique to
+VIP.
+
+It is recommended that you read nodes on survey and on customization before
+you start using VIP. Other nodes may be visited as needed.
+
+Comments and bug reports are welcome. Please send messages to
+@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to
+@code{masahiko@@sato.riec.tohoku.junet} if you are in Japan.@refill
+
+@end ifinfo
+
+@menu
+* Survey:: A survey of VIP.
+* Vi Commands:: Details of Vi commands.
+* Ex Commands:: Details of Ex commands.
+* Customization:: How to customize VIP.
+@end menu
+@iftex
+@unnumbered Introduction
+
+VIP is a Vi emulating package written in Emacs Lisp. VIP implements most
+Vi commands including Ex commands. It is therefore hoped that this package
+will enable you to do Vi style editing under the powerful GNU Emacs
+environment. This manual describes the usage of VIP assuming that you are
+fairly accustomed to Vi but not so much with Emacs. Also we will
+concentrate mainly on differences from Vi, especially features unique to
+VIP.
+
+It is recommended that you read chapters on survey and on customization
+before you start using VIP. Other chapters may be used as future
+references.
+
+Comments and bug reports are welcome. Please send messages to
+@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to
+@code{masahiko@@unsun.riec.tohoku.junet} if you are in Japan.
+@end iftex
+
+@node Survey, Basic Concepts, Top, Top
+@chapter A Survey of VIP
+
+In this chapter we describe basics of VIP with emphasis on the features not
+found in Vi and on how to use VIP under GNU Emacs.
+
+@menu
+* Basic Concepts:: Basic concepts in Emacs.
+* Loading VIP:: How to load VIP automatically.
+* Modes in VIP:: VIP has three modes, which are orthogonal to modes
+ in Emacs.
+* Differences from Vi:: Differences of VIP from Vi is explained.
+@end menu
+
+@node Basic Concepts, Loading VIP, Survey, Survey
+@section Basic Concepts
+
+We begin by explaining some basic concepts of Emacs. These concepts are
+explained in more detail in the GNU Emacs Manual.
+
+@cindex buffer
+@cindex point
+@cindex mark
+@cindex text
+@cindex looking at
+@cindex end (of buffer)
+@cindex region
+
+Conceptually, a @dfn{buffer} is just a string of ASCII characters and two
+special characters @key{PNT} (@dfn{point}) and @key{MRK} (@dfn{mark}) such
+that the character @key{PNT} occurs exactly once and @key{MRK} occurs at
+most once. The @dfn{text} of a buffer is obtained by deleting the
+occurrences of @key{PNT} and @key{MRK}. If, in a buffer, there is a
+character following @key{PNT} then we say that point is @dfn{looking at}
+the character; otherwise we say that point is @dfn{at the end of buffer}.
+@key{PNT} and @key{MRK} are used
+to indicate positions in a buffer and they are not part of the text of the
+buffer. If a buffer contains a @key{MRK} then the text between @key{MRK}
+and @key{PNT} is called the @dfn{region} of the buffer.@refill
+
+@cindex window
+
+Emacs provides (multiple) @dfn{windows} on the screen, and you can see the
+content of a buffer through the window associated with the buffer. The
+cursor of the screen is always positioned on the character after @key{PNT}.
+@refill
+
+@cindex mode
+@cindex keymap
+@cindex local keymap
+@cindex global keymap
+
+A @dfn{keymap} is a table that records the bindings between characters and
+command functions. There is the @dfn{global keymap} common to all the
+buffers. Each buffer has its @dfn{local keymap} that determines the
+@dfn{mode} of the buffer. Local keymap overrides global keymap, so that if
+a function is bound to some key in the local keymap then that function will
+be executed when you type the key. If no function is bound to a key in the
+local map, however, the function bound to the key in the global map becomes
+in effect.@refill
+
+@node Loading VIP, Modes in VIP, Basic Concepts, Survey
+@section Loading VIP
+
+The recommended way to load VIP automatically is to include the line:
+@example
+(load "vip")
+@end example
+@noindent
+in your @file{.emacs} file. The @file{.emacs} file is placed in your home
+directory and it will be executed every time you invoke Emacs. If you wish
+to be in vi mode whenever Emacs starts up, you can include the following
+line in your @file{.emacs} file instead of the above line:
+@example
+(setq term-setup-hook 'vip-mode)
+@end example
+@noindent
+(@xref{Vi Mode}, for the explanation of vi mode.)
+
+Even if your @file{.emacs} file does not contain any of the above lines,
+you can load VIP and enter vi mode by typing the following from within
+Emacs.
+@example
+M-x vip-mode
+@end example
+@noindent
+
+@node Modes in VIP, Emacs Mode, Loading VIP, Survey
+@section Modes in VIP
+
+@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi})
+@kindex 0301 @kbd{C-x C-z} (@code{suspend-emacs})
+
+Loading VIP has the effect of globally binding @kbd{C-z} (@kbd{Control-z})
+to the function @code{vip-change-mode-to-vi}. The default binding of @kbd{C-z}
+in GNU Emacs is @code{suspend-emacs}, but, you can also call
+@code{suspend-emacs} by typing @kbd{C-x C-z}. Other than this, all the
+key bindings of Emacs remain the same after loading VIP.@refill
+
+@cindex vi mode
+
+Now, if you hit @kbd{C-z}, the function @code{vip-change-mode-to-vi} will be
+called and you will be in @dfn{vi mode}. (Some major modes may locally bind
+@kbd{C-z} to some special functions. In such cases, you can call
+@code{vip-change-mode-to-vi} by @code{execute-extended-command} which is
+invoked by @kbd{M-x}. Here @kbd{M-x} means @kbd{Meta-x}, and if your
+terminal does not have a @key{META} key you can enter it by typing
+@kbd{@key{ESC} x}. The same effect can also be achieve by typing
+@kbd{M-x vip-mode}.)@refill
+
+@cindex mode line
+
+You can observe the change of mode by looking at the @dfn{mode line}. For
+instance, if the mode line is:@refill
+@example
+-----Emacs: *scratch* (Lisp Interaction)----All------------
+@end example
+@noindent
+then it will change to:
+@example
+-----Vi: *scratch* (Lisp Interaction)----All------------
+@end example
+@noindent
+Thus the word @samp{Emacs} in the mode line will change to @samp{Vi}.
+
+@cindex insert mode
+@cindex emacs mode
+
+You can go back to the original @dfn{emacs mode} by typing @kbd{C-z} in
+vi mode. Thus @kbd{C-z} toggles between these two modes.@refill
+
+Note that modes in VIP exist orthogonally to modes in Emacs. This means
+that you can be in vi mode and at the same time, say, shell mode.
+
+Vi mode corresponds to Vi's command mode. From vi mode you can enter
+@dfn{insert mode} (which corresponds to Vi's insert mode) by usual Vi command
+keys like @kbd{i}, @kbd{a}, @kbd{o} @dots{} etc.
+
+In insert mode, the mode line will look like this:
+@example
+-----Insert *scratch* (Lisp Interaction)----All------------
+@end example
+@noindent
+You can exit from insert mode by hitting @key{ESC} key as you do in Vi.
+
+That VIP has three modes may seem very complicated, but in fact it is not
+so. VIP is implemented so that you can do most editing remaining only
+in the two modes for Vi (that is vi mode and insert mode).
+
+@ifinfo
+The figure below shows the transition of three modes in VIP.
+@display
+
+
+ === C-z ==> == i,o ... ==>
+emacs mode vi mode insert mode
+ <== X-z === <=== ESC ====
+@end display
+@end ifinfo
+
+@menu
+* Emacs Mode:: This is the mode you should know better.
+* Vi Mode:: Vi commands are executed in this mode.
+* Insert Mode:: You can enter text, and also can do editing if you
+ know enough Emacs commands.
+@end menu
+
+@node Emacs Mode, Vi Mode, Modes in VIP, Modes in VIP
+@subsection Emacs Mode
+
+@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi})
+
+You will be in this mode just after you loaded VIP. You can do all
+normal Emacs editing in this mode. Note that the key @kbd{C-z} is globally
+bound to @code{vip-change-mode-to-vi}. So, if you type @kbd{C-z} in this mode
+then you will be in vi mode.@refill
+
+@node Vi Mode, Insert Mode, Emacs Mode, Modes in VIP
+@subsection Vi Mode
+
+This mode corresponds to Vi's command mode. Most Vi commands work as they
+do in Vi. You can go back to emacs mode by typing @kbd{C-z}. You can
+enter insert mode, just as in Vi, by typing @kbd{i}, @kbd{a} etc.
+
+@node Insert Mode, Differences from Vi, Vi Mode, Modes in VIP
+@subsection Insert Mode
+
+The key bindings in this mode is the same as in the emacs mode except for
+the following 4 keys. So, you can move around in the buffer and change
+its content while you are in insert mode.
+
+@table @kbd
+@item @key{ESC}
+@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode)
+This key will take you back to vi mode.
+@item C-h
+@kindex 010 @kbd{C-h} (@code{vip-delete-backward-char}) (insert mode)
+Delete previous character.
+@item C-w
+@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode)
+Delete previous word.
+@item C-z
+@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode)
+Typing this key has the same effect as typing @key{ESC} in emacs mode.
+Thus typing @kbd{C-z x} in insert mode will have the same effect as typing
+@kbd{ESC x} in emacs mode.
+@end table
+
+@node Differences from Vi, Undoing, Insert Mode, Survey
+@section Differences from Vi
+
+The major differences from Vi are explained below.
+
+@menu
+* Undoing:: You can undo more in VIP.
+* Changing:: Commands for changing the text.
+* Searching:: Search commands.
+* z Command:: You can now use zH, zM and zL as well as z- etc.
+* Counts:: Some Vi commands which do not accept a count now
+ accept one.
+* Marking:: You can now mark the current point, beginning of
+ the buffer etc.
+* Region Commands:: You can now give a region as an argument for delete
+ commands etc.
+* New Commands:: Some new commands not available in Vi are added.
+* New Bindings:: Bindings of some keys are changed for the
+ convenience of editing under Emacs.
+* Window Commands:: Commands for moving among windows etc.
+* Buffer Commands:: Commands for selecting buffers etc.
+* File Commands:: Commands for visiting files etc.
+* Misc Commands:: Other useful commands.
+@end menu
+
+@node Undoing, Changing, Differences from Vi, Differences from Vi
+@subsection Undoing
+
+@kindex 165 @kbd{u} (@code{vip-undo})
+@kindex 056 @kbd{.} (@code{vip-repeat})
+
+You can repeat undoing by the @kbd{.} key. So, @kbd{u} will undo
+a single change, while @kbd{u .@: .@: .@:}, for instance, will undo 4 previous
+changes. Undo is undoable as in Vi. So the content of the buffer will
+be the same before and after @kbd{u u}.@refill
+
+@node Changing, Searching, Undoing, Differences from Vi
+@subsection Changing
+
+Some commands which change a small number of characters are executed
+slightly differently. Thus, if point is at the beginning of a word
+@samp{foo} and you wished to change it to @samp{bar} by typing @w{@kbd{c w}},
+then VIP will prompt you for a new word in the minibuffer by the prompt
+@samp{foo => }. You can then enter @samp{bar} followed by @key{RET} or
+@key{ESC} to complete the command. Before you enter @key{RET} or
+@key{ESC} you can abort the command by typing @kbd{C-g}. In general,
+@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit})
+you can abort a partially formed command by typing @kbd{C-g}.@refill
+
+@node Searching, z Command, Changing, Differences from Vi
+@subsection Searching
+
+@kindex 057 @kbd{/} (@code{vip-search-forward})
+@kindex 077 @kbd{?} (@code{vip-search-backward})
+
+As in Vi, searching is done by @kbd{/} and @kbd{?}. The string will be
+searched literally by default. To invoke a regular expression search,
+first execute the search command @kbd{/} (or @kbd{?}) with empty search
+string. (I.e, type @kbd{/} followed by @key{RET}.)
+A search for empty string will toggle the search mode between vanilla
+search and regular expression search. You cannot give an offset to the
+search string. (It is a limitation.) By default, search will wrap around
+the buffer as in Vi. You can change this by rebinding the variable
+@code{vip-search-wrap-around}. @xref{Customization}, for how to do this.@refill
+
+@node z Command, Counts, Searching, Differences from Vi
+@subsection z Command
+
+@kindex 1723 @kbd{z H} (@code{vip-line-to-top})
+@kindex 1721 @kbd{z RET} (@code{vip-line-to-top})
+@kindex 1723 @kbd{z M} (@code{vip-line-to-middle})
+@kindex 1722 @kbd{z .} (@code{vip-line-to-middle})
+@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom})
+@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom})
+
+For those of you who cannot remember which of @kbd{z} followed by @key{RET},
+@kbd{.}@: and @kbd{-} do what. You can also use @kbd{z} followed by @kbd{H},
+@kbd{M} and @kbd{L} to place the current line in the Home (Middle, and
+Last) line of the window.@refill
+
+@node Counts, Marking, z Command, Differences from Vi
+@subsection Counts
+
+Some Vi commands which do not accept a count now accept one
+
+@table @kbd
+@item p
+@itemx P
+@kindex 160 @kbd{p} (@code{vip-put-back})
+@kindex 120 @kbd{P} (@code{vip-Put-back})
+Given counts, text will be yanked (in Vi's sense) that many times. Thus
+@kbd{3 p} is the same as @kbd{p p p}.
+@item o
+@itemx O
+@kindex 157 @kbd{o} (@code{vip-open-line})
+@kindex 117 @kbd{O} (@code{vip-Open-line})
+Given counts, that many copies of text will be inserted. Thus
+@kbd{o a b c @key{ESC}} will insert 3 lines of @samp{abc} below the current
+line.
+@item /
+@itemx ?
+@kindex 057 @kbd{/} (@code{vip-search-forward})
+@kindex 077 @kbd{?} (@code{vip-search-backward})
+Given a count @var{n}, @var{n}-th occurrence will be searched.
+@end table
+
+@node Marking, Region Commands, Counts, Differences from Vi
+@subsection Marking
+
+Typing an @kbd{m} followed by a lower-case character @var{ch} marks the
+point to the register named @var{ch} as in Vi. In addition to these, we
+have following key bindings for marking.
+
+@kindex 155 @kbd{m} (@code{vip-mark-point})
+
+@table @kbd
+@item m <
+Set mark at the beginning of buffer.
+@item m >
+Set mark at the end of buffer.
+@item m .
+Set mark at point (and push old mark on mark ring).
+@item m ,
+Jump to mark (and pop mark off the mark ring).
+@end table
+
+@node Region Commands, New Commands, Marking, Differences from Vi
+@subsection Region Commands
+
+@cindex region
+
+Vi operators like @kbd{d}, @kbd{c} etc. are usually used in combination
+with motion commands. It is now possible to use current region as the
+argument to these operators. (A @dfn{region} is a part of buffer
+delimited by point and mark.) The key @kbd{r} is used for this purpose.
+Thus @kbd{d r} will delete the current region. If @kbd{R} is used instead
+of @kbd{r} the region will first be enlarged so that it will become the
+smallest region containing the original region and consisting of whole
+lines. Thus @kbd{m .@: d R} will have the same effect as @kbd{d d}.@refill
+
+@node New Commands, New Bindings, Region Commands, Differences from Vi
+@subsection Some New Commands
+
+Note that the keys below (except for @kbd{R}) are not used in Vi.
+
+@table @kbd
+@item C-a
+@kindex 001 @kbd{C-a} (@code{vip-beginning-of-line})
+Move point to the beginning of line.
+@item C-n
+@kindex 016 @kbd{C-n} (@code{vip-next-window})
+If you have two or more windows in the screen, this key will move point to
+the next window.
+@item C-o
+@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point})
+Insert a newline and leave point before it, and then enter insert mode.
+@item C-r
+@kindex 022 @kbd{C-r} (@code{isearch-backward})
+Backward incremental search.
+@item C-s
+@kindex 023 @kbd{C-s} (@code{isearch-forward})
+Forward incremental search.
+@item C-c
+@itemx C-x
+@itemx @key{ESC}
+@kindex 003 @kbd{C-c} (@code{vip-ctl-c})
+@kindex 0300 @kbd{C-x} (@code{vip-ctl-x})
+@kindex 033 @kbd{ESC} (@code{vip-ESC})
+These keys will exit from vi mode and return to emacs mode temporarily. If
+you hit one of these keys, Emacs will be in emacs mode and will believe
+that you hit that key in emacs mode. For example, if you hit @kbd{C-x}
+followed by @kbd{2}, then the current window will be split into 2 and you
+will be in vi mode again.
+@item \
+@kindex 134 @kbd{\} (@code{vip-escape-to-emacs})
+Escape to emacs mode. Hitting @kbd{\} will take you to emacs mode, and you
+can execute a single Emacs command. After executing the Emacs command you
+will be in vi mode again. You can give a count before typing @kbd{\}.
+Thus @kbd{5 \ *}, as well as @kbd{\ C-u 5 *}, will insert @samp{*****}
+before point. Similarly @kbd{1 0 \ C-p} will move the point 10 lines above
+the current line.@refill
+@item K
+@kindex 113 @kbd{K} (@code{vip-kill-buffer})
+Kill current buffer if it is not modified. Useful when you selected a
+buffer which you did not want.
+@item Q
+@itemx R
+@kindex 121 @kbd{Q} (@code{vip-query-replace})
+@kindex 122 @kbd{R} (@code{vip-replace-string})
+@kbd{Q} is for query replace and @kbd{R} is for replace. By default,
+string to be replaced are treated literally. If you wish to do a regular
+expression replace, first do replace with empty string as the string to be
+replaced. In this way, you can toggle between vanilla and regular
+expression replacement.
+@item v
+@itemx V
+@kindex 166 @kbd{v} (@code{vip-find-file})
+@kindex 126 @kbd{V} (@code{vip-find-file-other-window})
+These keys are used to Visit files. @kbd{v} will switch to a buffer
+visiting file whose name can be entered in the minibuffer. @kbd{V} is
+similar, but will use window different from the current window.
+@item #
+@kindex 0430 @kbd{#} (@code{vip-command-argument})
+If followed by a certain character @var{ch}, it becomes an operator whose
+argument is the region determined by the motion command that follows.
+Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q} and
+@kbd{s}.@refill
+@item # c
+@kindex 0432 @kbd{# c} (@code{downcase-region})
+Change upper-case characters in the region to lower case
+(@code{downcase-region}).
+@item # C
+@kindex 0431 @kbd{# C} (@code{upcase-region})
+Change lower-case characters in the region to upper case. For instance,
+@kbd{# C 3 w} will capitalize 3 words from the current point
+(@code{upcase-region}).
+@item # g
+@kindex 0432 @kbd{# g} (@code{vip-global-execute})
+Execute last keyboard macro for each line in the region
+(@code{vip-global-execute}).@refill
+@item # q
+@kindex 0432 @kbd{# q} (@code{vip-quote-region})
+Insert specified string at the beginning of each line in the region
+(@code{vip-quote-region}).
+@item # s
+@kindex 0432 @kbd{# s} (@code{spell-region})
+Check spelling of words in the region (@code{spell-region}).
+@item *
+@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro})
+Call last keyboard macro.
+@end table
+
+@node New Bindings, Window Commands, New Commands, Differences from Vi
+@subsection New Key Bindings
+
+In VIP the meanings of some keys are entirely different from Vi. These key
+bindings are done deliberately in the hope that editing under Emacs will
+become easier. It is however possible to rebind these keys to functions
+which behave similarly as in Vi. @xref{Customizing Key Bindings}, for
+details.
+
+@table @kbd
+@item C-g
+@itemx g
+@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit})
+@kindex 147 @kbd{g} (@code{vip-info-on-file})
+In Vi, @kbd{C-g} is used to get information about the file associated to
+the current buffer. Here, @kbd{g} will do that, and @kbd{C-g} is
+used to abort a command (this is for compatibility with emacs mode.)
+@item SPC
+@itemx @key{RET}
+@kindex 040 @kbd{SPC} (@code{vip-scroll})
+@kindex 015 @kbd{RET} (@code{vip-scroll-back})
+Now these keys will scroll up and down the text of current window.
+Convenient for viewing the text.
+@item s
+@itemx S
+@kindex 163 @kbd{s} (@code{vip-switch-to-buffer})
+@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window})
+They are used to switch to a specified buffer. Useful for switching to
+already existing buffer since buffer name completion is provided. Also
+a default buffer will be given as part of the prompt, to which you can
+switch by just typing @key{RET} key. @kbd{s} is used to select buffer
+in the current window, while @kbd{S} selects buffer in another window.
+@item C
+@itemx X
+@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent})
+@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent})
+These keys will exit from vi mode and return to emacs mode temporarily.
+If you type @kbd{C} (@kbd{X}), Emacs will be in emacs mode and will believe
+that you have typed @kbd{C-c} (@kbd{C-x}, resp.) in emacs mode. Moreover,
+if the following character you type is an upper-case letter, then Emacs
+will believe that you have typed the corresponding control character.
+You will be in vi mode again after the command is executed. For example,
+typing @kbd{X S} in vi mode is the same as typing @kbd{C-x C-s} in emacs
+mode. You get the same effect by typing @kbd{C-x C-s} in vi mode, but
+the idea here is that you can execute useful Emacs commands without typing
+control characters. For example, if you hit @kbd{X} (or @kbd{C-x}) followed
+by @kbd{2}, then the current window will be split into 2 and you will be in
+vi mode again.@refill
+@end table
+
+In addition to these, @code{ctl-x-map} is slightly modified:
+
+@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows})
+
+@table @kbd
+@item X 3
+@itemx C-x 3
+This is equivalent to @kbd{C-x 1 C-x 2} (1 + 2 = 3).
+@end table
+
+@node Window Commands, Buffer Commands, New Bindings, Differences from Vi
+@subsection Window Commands
+
+In this and following subsections, we give a summary of key bindings for
+basic functions related to windows, buffers and files.
+
+@table @kbd
+@item C-n
+@kindex 016 @kbd{C-n} (@code{vip-next-window})
+Switch to next window.
+@item X 1
+@itemx C-x 1
+@kindex 1301 @kbd{X 1} (@code{delete-other-windows})
+Delete other windows.
+@item X 2
+@itemx C-x 2
+@kindex 1301 @kbd{X 2} (@code{split-window-vertically})
+Split current window into two windows.
+@item X 3
+@itemx C-x 3
+@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows})
+Show current buffer in two windows.
+@end table
+
+@node Buffer Commands, File Commands, Window Commands, Differences from Vi
+@subsection Buffer Commands
+
+@table @kbd
+@item s
+@kindex 163 @kbd{s} (@code{vip-switch-to-buffer})
+Switch to the specified buffer in the current window
+(@code{vip-switch-to-buffer}).
+@item S
+@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window})
+Switch to the specified buffer in another window
+(@code{vip-switch-to-buffer-other-window}).
+@item K
+@kindex 113 @kbd{K} (@code{vip-kill-buffer})
+Kill the current buffer if it is not modified.
+@item X S
+@itemx C-x C-s
+@kindex 1302 @kbd{X S} (@code{save-buffer})
+Save the current buffer in the file associated to the buffer.
+@end table
+
+@node File Commands, Misc Commands, Buffer Commands, Differences from Vi
+@subsection File Commands
+
+@table @kbd
+@item v
+@kindex 166 @kbd{v} (@code{vip-find-file})
+Visit specified file in the current window.
+@item V
+@kindex 126 @kbd{V} (@code{vip-find-file-other-window})
+Visit specified file in another window.
+@item X W
+@itemx C-x C-w
+@kindex 1302 @kbd{X W} (@code{write-file})
+Write current buffer into the specified file.
+@item X I
+@itemx C-x C-i
+@kindex 1302 @kbd{X I} (@code{insert-file})
+
+Insert specified file at point.
+@end table
+
+@node Misc Commands, Vi Commands, File Commands, Differences from Vi
+@subsection Miscellaneous Commands
+
+@table @kbd
+@item X (
+@itemx C-x (
+@kindex 1301 @kbd{X (} (@code{start-kbd-macro})
+Start remembering keyboard macro.
+@item X )
+@itemx C-x )
+@kindex 1301 @kbd{X )} (@code{end-kbd-macro})
+Finish remembering keyboard macro.
+@item *
+@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro})
+Call last remembered keyboard macro.
+@item X Z
+@itemx C-x C-z
+@kindex 1302 @kbd{X Z} (@code{suspend-emacs})
+Suspend Emacs.
+@item Z Z
+Exit Emacs.
+@itemx Q
+Query replace.
+@itemx R
+Replace.
+@end table
+
+@node Vi Commands, Numeric Arguments, Misc Commands, Top
+@chapter Vi Commands
+
+This chapter describes Vi commands other than Ex commands implemented in
+VIP. Except for the last section which discusses insert mode, all the
+commands described in this chapter are to be used in vi mode.
+
+@menu
+* Numeric Arguments:: Many commands accept numeric arguments
+* Important Keys:: Some very important keys.
+* Buffers and Windows:: Commands for handling buffers and windows.
+* Files:: Commands for handling files.
+* Viewing the Buffer:: How you can view the current buffer.
+* Mark Commands:: Marking positions in a buffer.
+* Motion Commands:: Commands for moving point.
+* Searching and Replacing:: Commands for searching and replacing.
+* Modifying Commands:: Commands for modifying the buffer.
+* Other Vi Commands:: Miscellaneous Commands.
+* Commands in Insert Mode:: Commands for entering insert mode.
+@end menu
+
+@node Numeric Arguments, Important Keys, Vi Commands, Vi Commands
+@section Numeric Arguments
+
+@cindex numeric arguments
+@cindex count
+@kindex 061 @kbd{1} (numeric argument)
+@kindex 062 @kbd{2} (numeric argument)
+@kindex 063 @kbd{3} (numeric argument)
+@kindex 064 @kbd{4} (numeric argument)
+@kindex 065 @kbd{5} (numeric argument)
+@kindex 066 @kbd{6} (numeric argument)
+@kindex 067 @kbd{7} (numeric argument)
+@kindex 068 @kbd{8} (numeric argument)
+@kindex 069 @kbd{9} (numeric argument)
+
+Most Vi commands accept a @dfn{numeric argument} which can be supplied as
+a prefix to the commands. A numeric argument is also called a @dfn{count}.
+In many cases, if a count is given, the command is executed that many times.
+For instance, @kbd{5 d d} deletes 5 lines while simple @kbd{d d} deletes a
+line. In this manual the metavariable @var{n} will denote a count.@refill
+
+@node Important Keys, Buffers and Windows, Numeric Arguments, Vi Commands
+@section Important Keys
+
+The keys @kbd{C-g} and @kbd{C-l} are unique in that their associated
+functions are the same in any of emacs, vi and insert mode.
+
+@table @kbd
+@item C-g
+@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit})
+Quit. Cancel running or partially typed command (@code{keyboard-quit}).
+@item C-l
+@kindex 014 @kbd{C-l} (@code{recenter})
+Clear the screen and reprint everything (@code{recenter}).
+@end table
+
+In Emacs many commands are bound to the key strokes that start with
+@kbd{C-x}, @kbd{C-c} and @key{ESC}. These commands can be
+accessed from vi mode as easily as from emacs mode.@refill
+
+@table @kbd
+@item C-x
+@itemx C-c
+@itemx @key{ESC}
+@kindex 003 @kbd{C-c} (@code{vip-ctl-c})
+@kindex 0300 @kbd{C-x} (@code{vip-ctl-x})
+@kindex 033 @kbd{ESC} (@code{vip-ESC})
+Typing one of these keys have the same effect as typing it in emacs mode.
+Appropriate command will be executed according as the keys you type after
+it. You will be in vi mode again after the execution of the command.
+For instance, if you type @kbd{@key{ESC} <} (in vi mode) then the cursor will
+move to the beginning of the buffer and you will still be in vi mode.
+@item C
+@itemx X
+@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent})
+@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent})
+Typing one of these keys have the effect of typing the corresponding
+control character in emacs mode. Moreover, if you type an upper-case
+character following it, that character will also be translated to the
+corresponding control character. Thus typing @kbd{X W} in vi mode is the
+same as typing @kbd{C-x C-w} in emacs mode. You will be in vi mode again
+after the execution of a command.
+@item \
+@kindex 134 @kbd{\} (@code{vip-escape-to-emacs})
+Escape to emacs mode. Hitting the @kbd{\} key will take you to emacs mode,
+and you can execute a single Emacs command. After executing the
+Emacs command you will be in vi mode again. You can give a count before
+typing @kbd{\}. Thus @kbd{5 \ +}, as well as @kbd{\ C-u 5 +}, will insert
+@samp{+++++} before point.@refill
+@end table
+
+@node Buffers and Windows, Files, Important Keys, Vi Commands
+@section Buffers and Windows
+
+@cindex buffer
+@cindex selected buffer
+@cindex current buffer
+
+In Emacs the text you edit is stored in a @dfn{buffer}.
+See GNU Emacs Manual, for details. There is always one @dfn{selected}
+buffer which is called the @dfn{current buffer}.@refill
+
+@cindex window
+@cindex modified (buffer)
+
+You can see the contents of buffers through @dfn{windows} created by Emacs.
+When you have multiple windows on the screen only one of them is selected.
+Each buffer has a unique name, and each window has a mode line which shows
+the name of the buffer associated with the window and other information
+about the status of the buffer. You can change the format of the mode
+line, but normally if you see @samp{**} at the beginning of a mode line it
+means that the buffer is @dfn{modified}. If you write out the content of
+the buffer to a file, then the buffer will become not modified. Also if
+you see @samp{%%} at the beginning of the mode line, it means that the file
+associated with the buffer is write protected.
+
+We have the following commands related to windows and buffers.
+
+@table @kbd
+@item C-n
+@kindex 016 @kbd{C-n} (@code{vip-next-window})
+Move cursor to the next-window (@code{vip-next-window}).
+@item X 1
+@kindex 1301 @kbd{X 1} (@code{delete-other-windows})
+Delete other windows and make the selected window fill the screen
+@*(@code{delete-other-windows}).
+@item X 2
+@kindex 1301 @kbd{X 2} (@code{split-window-vertically})
+Split current window into two windows (@code{split-window-vertically}).
+@item X 3
+@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows})
+Show current buffer in two windows.
+@item s @var{buffer} @key{RET}
+@kindex 163 @kbd{s} (@code{vip-switch-to-buffer})
+Select or create a buffer named @var{buffer} (@code{vip-switch-to-buffer}).
+@item S @var{buffer} @key{RET}
+@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window})
+Similar but select a buffer named @var{buffer} in another window
+@*(@code{vip-switch-to-buffer-other-window}).
+@item K
+@kindex 113 @kbd{K} (@code{vip-kill-buffer})
+Kill the current buffer if it is not modified or if it is not associated
+with a file @*(@code{vip-kill-buffer}).
+@item X B
+@kindex 1302 @kbd{X B} (@code{list-buffers})
+List the existing buffers (@code{list-buffers}).
+@end table
+
+@cindex buffer name completion
+
+As @dfn{buffer name completion} is provided, you have only to type in
+initial substring of the buffer name which is sufficient to identify it
+among names of existing buffers. After that, if you hit @key{TAB} the rest
+of the buffer name will be supplied by the system, and you can confirm it
+by @key{RET}. The default buffer name to switch to will also be prompted,
+and you can select it by giving a simple @key{RET}. See GNU Emacs Manual
+for details of completion.
+
+@node Files, Viewing the Buffer, Buffers and Windows, Vi Commands
+@section Files
+
+We have the following commands related to files. They are used to visit,
+save and insert files.
+
+@table @kbd
+@item v @var{file} @key{RET}
+@kindex 166 @kbd{v} (@code{vip-find-file})
+Visit specified file in the current window (@code{vip-find-file}).
+@item V @var{file} @key{RET}
+@kindex 126 @kbd{V} (@code{vip-find-file-other-window})
+Visit specified file in another window (@code{vip-find-file-other-window}).
+@item X S
+@kindex 1302 @kbd{X S} (@code{save-buffer})
+Save current buffer to the file associated with the buffer. If no file is
+associated with the buffer, the name of the file to write out the content
+of the buffer will be asked in the minibuffer.
+@item X W @var{file} @key{RET}
+@kindex 1302 @kbd{X W} (@code{write-file})
+Write current buffer into a specified file.
+@item X I @var{file} @key{RET}
+@kindex 1302 @kbd{X I} (@code{insert-file})
+Insert a specified file at point.
+@item g
+@kindex 147 @kbd{g} (@code{vip-info-on-file})
+Give information on the file associated with the current buffer. Tell you
+the name of the file associated with the buffer, the line number of the
+current point and total line numbers in the buffer. If no file is
+associated with the buffer, this fact will be indicated by the null file
+name @samp{""}.
+@end table
+
+@cindex visiting (a file)
+@cindex default directory
+
+In Emacs, you can edit a file by @dfn{visiting} it. If you wish to visit a
+file in the current window, you can just type @kbd{v}. Emacs maintains the
+@dfn{default directory} which is specific to each buffer. Suppose, for
+instance, that the default directory of the current buffer is
+@file{/usr/masahiko/lisp/}. Then you will get the following prompt in the
+minibuffer.@refill
+@example
+visit file: /usr/masahiko/lisp/
+@end example
+@noindent
+@cindex file name completion
+If you wish to visit, say, @file{vip.el} in this directory, then you can
+just type @samp{vip.el} followed by @key{RET}. If the file @file{vip.el}
+already exists in the directory, Emacs will visit that file, and if not,
+the file will be created. Emacs will use the file name (@file{vip.el}, in
+this case) as the name of the buffer visiting the file. In order to make
+the buffer name unique, Emacs may append @samp{<2>}, @samp{<3>} etc., to
+the buffer name. As the @dfn{file name completion} is provided here, you
+can sometime save typing. For instance, suppose there is only one file in the
+default directory whose name starts with @samp{v}, that is @samp{vip.el}.
+Then if you just type @kbd{v @key{TAB}} then it will be completed to
+@samp{vip.el}. Thus, in this case, you just have to type @kbd{v v @key{TAB}
+@key{RET}} to visit @file{/usr/masahiko/lisp/vip.el}. Continuing the
+example, let us now suppose that you wished to visit the file
+@file{/usr/masahiko/man/vip.texinfo}. Then to the same prompt which you get
+after you typed @kbd{v}, you can enter @samp{/usr/masahiko/man/vip.texinfo} or
+@samp{../man/vip.texinfo} followed by @key{RET}.
+
+Use @kbd{V} instead of @kbd{v}, if you wish to visit a file in another
+window.
+
+You can verify which file you are editing by typing @kbd{g}. (You can also
+type @kbd{X B} to get nformation on other buffers too.) If you type
+@kbd{g} you will get an information like below in the echo area:@refill
+@example
+"/usr/masahiko/man/vip.texinfo" line 921 of 1949
+@end example
+
+After you edited the buffer (@samp{vip.texinfo}, in our example) for a while,
+you may wish to save it in a file. If you wish to save it in the file
+associated with the buffer (@file{/usr/masahiko/man/vip.texinfo}, in this
+case), you can just say @kbd{X S}. If you wish to save it in another file,
+you can type @kbd{X W}. You will then get a similar prompt as you get for
+@kbd{v}, to which you can enter the file name.@refill
+
+@node Viewing the Buffer, Mark Commands, Files, Vi Commands
+@section Viewing the Buffer
+
+In this and next section we discuss commands for moving around in the
+buffer. These command do not change the content of the buffer. The
+following commands are useful for viewing the content of the current
+buffer.
+
+@table @kbd
+@item @key{SPC}
+@itemx C-f
+@kindex 040 @kbd{SPC} (@code{vip-scroll})
+@kindex 006 @kbd{C-f} (@code{vip-scroll-back})
+Scroll text of current window upward almost full screen. You can go
+@i{forward} in the buffer by this command (@code{vip-scroll}).
+@item @key{RET}
+@itemx C-b
+@kindex 015 @kbd{RET} (@code{vip-scroll-back})
+@kindex 002 @kbd{C-b} (@code{vip-scroll-back})
+Scroll text of current window downward almost full screen. You can go
+@i{backward} in the buffer by this command (@code{vip-scroll-back}).
+@itemx C-d
+@kindex 004 @kbd{C-d} (@code{vip-scroll-up})
+Scroll text of current window upward half screen. You can go
+@i{down} in the buffer by this command (@code{vip-scroll-down}).
+@itemx C-u
+@kindex 025 @kbd{C-u} (@code{vip-scroll-down})
+Scroll text of current window downward half screen. You can go
+@i{up} in the buffer by this command (@code{vip-scroll-up}).
+@item C-y
+@kindex 031 @kbd{C-y} (@code{vip-scroll-down-one})
+Scroll text of current window upward by one line (@code{vip-scroll-down-one}).
+@item C-e
+@kindex 005 @kbd{C-e} (@code{vip-scroll-up-one})
+Scroll text of current window downward by one line (@code{vip-scroll-up-one}).
+@end table
+@noindent
+You can repeat these commands by giving a count. Thus, @kbd{2 @key{SPC}}
+has the same effect as @kbd{@key{SPC} @key{SPC}}.
+
+The following commands reposition point in the window.
+
+@table @kbd
+@item z H
+@itemx z @key{RET}
+@kindex 1723 @kbd{z H} (@code{vip-line-to-top})
+@kindex 1721 @kbd{z RET} (@code{vip-line-to-top})
+Put point on the top (@i{home}) line in the window. So the current line
+becomes the top line in the window. Given a count @var{n}, point will be
+placed in the @var{n}-th line from top (@code{vip-line-to-top}).
+@item z M
+@itemx z .
+@kindex 1723 @kbd{z M} (@code{vip-line-to-middle})
+@kindex 1722 @kbd{z .} (@code{vip-line-to-middle})
+Put point on the @i{middle} line in the window. Given a count @var{n},
+point will be placed in the @var{n}-th line from the middle line
+(@code{vip-line-to-middle}).
+@item z L
+@itemx z -
+@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom})
+@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom})
+Put point on the @i{bottom} line in the window. Given a count @var{n},
+point will be placed in the @var{n}-th line from bottom
+(@code{vip-line-to-bottom}).
+@item C-l
+Center point in window and redisplay screen (@code{recenter}).
+@end table
+
+@node Mark Commands, Motion Commands, Viewing the Buffer, Vi Commands
+@section Mark Commands
+
+The following commands are used to mark positions in the buffer.
+
+@table @kbd
+@item m @var{ch}
+@kindex 155 @kbd{m} (@code{vip-mark-point})
+Store current point in the register @var{ch}. @var{ch} must be a
+lower-case ASCII letter.
+@item m <
+Set mark at the beginning of current buffer.
+@item m >
+Set mark at the end of current buffer.
+@item m .
+Set mark at point.
+@item m ,
+Jump to mark (and pop mark off the mark ring).
+@end table
+
+@cindex mark ring
+
+Emacs uses the @dfn{mark ring} to store marked positions. The commands
+@kbd{m <}, @kbd{m >} and @kbd{m .}@: not only set mark but also add it as the
+latest element of the mark ring (replacing the oldest one). By repeating
+the command `@kbd{m ,}' you can visit older and older marked positions. You
+will eventually be in a loop as the mark ring is a ring.
+
+@node Motion Commands, Searching and Replacing, Mark Commands, Vi Commands
+@section Motion Commands
+
+Commands for moving around in the current buffer are collected here. These
+commands are used as an `argument' for the delete, change and yank commands
+to be described in the next section.
+
+@table @kbd
+@item h
+@kindex 150 @kbd{h} (@code{vip-backward-char})
+Move point backward by one character. Signal error if point is at the
+beginning of buffer, but (unlike Vi) do not complain otherwise
+(@code{vip-backward-char}).
+@item l
+@kindex 154 @kbd{l} (@code{vip-forward-char})
+Move point backward by one character. Signal error if point is at the
+end of buffer, but (unlike Vi) do not complain otherwise
+(@code{vip-forward-char}).
+@item j
+@kindex 152 @kbd{j} (@code{vip-next-line})
+Move point to the next line keeping the current column. If point is on the
+last line of the buffer, a new line will be created and point will move to
+that line (@code{vip-next-line}).
+@item k
+@kindex 153 @kbd{k} (@code{vip-previous-line})
+Move point to the previous line keeping the current column
+(@code{vip-next-line}).
+@item +
+@kindex 053 @kbd{+} (@code{vip-next-line-at-bol})
+Move point to the next line at the first non-white character. If point is
+on the last line of the buffer, a new line will be created and point will
+move to the beginning of that line (@code{vip-next-line-at-bol}).
+@item -
+@kindex 055 @kbd{-} (@code{vip-previous-line-at-bol})
+Move point to the previous line at the first non-white character
+(@code{vip-previous-line-at-bol}).
+@end table
+@noindent
+If a count is given to these commands, the commands will be repeated that
+many times.
+
+@table @kbd
+@item 0
+@kindex 060 @kbd{0} (@code{vip-beginning-of-line})
+Move point to the beginning of line (@code{vip-beginning-of-line}).
+@item ^
+@kindex 136 @kbd{^} (@code{vip-bol-and-skip-white})
+Move point to the first non-white character on the line
+(@code{vip-bol-and-skip-white}).
+@item $
+@kindex 044 @kbd{$} (@code{vip-goto-eol})
+Move point to the end of line (@code{vip-goto-eol}).
+@item @var{n} |
+@kindex 174 @kbd{|} (@code{vip-goto-col})
+Move point to the @var{n}-th column on the line (@code{vip-goto-col}).
+@end table
+@noindent
+Except for the @kbd{|} command, these commands neglect a count.
+
+@cindex word
+
+@table @kbd
+@item w
+@kindex 167 @kbd{w} (@code{vip-forward-word})
+Move point forward to the beginning of the next word
+(@code{vip-forward-word}).
+@item W
+@kindex 127 @kbd{W} (@code{vip-forward-Word})
+Move point forward to the beginning of the next word, where a @dfn{word} is
+considered as a sequence of non-white characters (@code{vip-forward-Word}).
+@item b
+@kindex 142 @kbd{b} (@code{vip-backward-word})
+Move point backward to the beginning of a word (@code{vip-backward-word}).
+@item B
+@kindex 102 @kbd{B} (@code{vip-backward-Word})
+Move point backward to the beginning of a word, where a @i{word} is
+considered as a sequence of non-white characters (@code{vip-forward-Word}).
+@item e
+@kindex 145 @kbd{e} (@code{vip-end-of-word})
+Move point forward to the end of a word (@code{vip-end-of-word}).
+@item E
+@kindex 105 @kbd{E} (@code{vip-end-of-Word})
+Move point forward to the end of a word, where a @i{word} is
+considered as a sequence of non-white characters (@code{vip-end-of-Word}).
+@end table
+@noindent
+@cindex syntax table
+Here the meaning of the word `word' for the @kbd{w}, @kbd{b} and @kbd{e}
+commands is determined by the @dfn{syntax table} effective in the current
+buffer. Each major mode has its syntax mode, and therefore the meaning of
+a word also changes as the major mode changes. See GNU Emacs Manual for
+details of syntax table.
+
+@table @kbd
+@item H
+@kindex 110 @kbd{H} (@code{vip-window-top})
+Move point to the beginning of the @i{home} (top) line of the window.
+Given a count @var{n}, go to the @var{n}-th line from top
+(@code{vip-window-top}).
+@item M
+@kindex 115 @kbd{M} (@code{vip-window-middle})
+Move point to the beginning of the @i{middle} line of the window. Given
+a count @var{n}, go to the @var{n}-th line from the middle line
+(@code{vip-window-middle}).
+@item L
+@kindex 114 @kbd{L} (@code{vip-window-bottom})
+Move point to the beginning of the @i{lowest} (bottom) line of the
+window. Given count, go to the @var{n}-th line from bottom
+(@code{vip-window-bottom}).
+@end table
+@noindent
+These commands can be used to go to the desired line visible on the screen.
+
+@table @kbd
+@item (
+@kindex 050 @kbd{(} (@code{vip-backward-sentence})
+Move point backward to the beginning of the sentence
+(@code{vip-backward-sentence}).
+@item )
+@kindex 051 @kbd{)} (@code{vip-forward-sentence})
+Move point forward to the end of the sentence
+(@code{vip-forward-sentence}).
+@item @{
+@kindex 173 @kbd{@{} (@code{vip-backward-paragraph})
+Move point backward to the beginning of the paragraph
+(@code{vip-backward-paragraph}).
+@item @}
+@kindex 175 @kbd{@}} (@code{vip-forward-paragraph})
+Move point forward to the end of the paragraph
+(@code{vip-forward-paragraph}).
+@end table
+@noindent
+A count repeats the effect for these commands.
+
+@table @kbd
+@item G
+@kindex 107 @kbd{G} (@code{vip-goto-line})
+Given a count @var{n}, move point to the @var{n}-th line in the buffer on
+the first non-white character. Without a count, go to the end of the buffer
+(@code{vip-goto-line}).
+@item ` `
+@kindex 140 @kbd{`} (@code{vip-goto-mark})
+Exchange point and mark (@code{vip-goto-mark}).
+@item ` @var{ch}
+Move point to the position stored in the register @var{ch}. @var{ch} must
+be a lower-case letter.
+@item ' '
+@kindex 047 @kbd{'} (@code{vip-goto-mark-and-skip-white})
+Exchange point and mark, and then move point to the first non-white
+character on the line (@code{vip-goto-mark-and-skip-white}).
+@item ' @var{ch}
+Move point to the position stored in the register @var{ch} and skip to the
+first non-white character on the line. @var{ch} must be a lower-case letter.
+@item %
+@kindex 045 @kbd{%} (@code{vip-paren-match})
+Move point to the matching parenthesis if point is looking at @kbd{(},
+@kbd{)}, @kbd{@{}, @kbd{@}}, @kbd{[} or @kbd{]}
+@*(@code{vip-paren-match}).
+@end table
+@noindent
+The command @kbd{G} mark point before move, so that you can return to the
+original point by @kbd{` `}. The original point will also be stored in
+the mark ring.
+
+The following commands are useful for moving points on the line. A count
+will repeat the effect.
+
+@table @kbd
+@item f @var{ch}
+@kindex 146 @kbd{f} (@code{vip-find-char-forward})
+Move point forward to the character @var{ch} on the line. Signal error if
+@var{ch} could not be found (@code{vip-find-char-forward}).
+@item F @var{ch}
+@kindex 106 @kbd{F} (@code{vip-find-char-backward})
+Move point backward to the character @var{ch} on the line. Signal error if
+@var{ch} could not be found (@code{vip-find-char-backward}).
+@item t @var{ch}
+@kindex 164 @kbd{t} (@code{vip-goto-char-forward})
+Move point forward upto the character @var{ch} on the line. Signal error if
+@var{ch} could not be found (@code{vip-goto-char-forward}).
+@item T @var{ch}
+@kindex 124 @kbd{T} (@code{vip-goto-char-backward})
+Move point backward upto the character @var{ch} on the line. Signal error if
+@var{ch} could not be found (@code{vip-goto-char-backward}).
+@item ;
+@kindex 073 @kbd{;} (@code{vip-repeat-find})
+Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command
+(@code{vip-repeat-find}).
+@item ,
+@kindex 054 @kbd{,} (@code{vip-repeat-find-opposite})
+Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command, in the
+opposite direction (@code{vip-repeat-find-opposite}).
+@end table
+
+@node Searching and Replacing, Modifying Commands, Motion Commands, Vi Commands
+@section Searching and Replacing
+
+Following commands are available for searching and replacing.
+
+@cindex regular expression (search)
+
+@table @kbd
+@item / @var{string} @key{RET}
+@kindex 057 @kbd{/} (@code{vip-search-forward})
+Search the first occurrence of the string @var{string} forward starting
+from point. Given a count @var{n}, the @var{n}-th occurrence of
+@var{string} will be searched. If the variable @code{vip-re-search} has value
+@code{t} then @dfn{regular expression} search is done and the string
+matching the regular expression @var{string} is found. If you give an
+empty string as @var{string} then the search mode will change from vanilla
+search to regular expression search and vice versa
+(@code{vip-search-forward}).
+@item ? @var{string} @key{RET}
+@kindex 077 @kbd{?} (@code{vip-search-backward})
+Same as @kbd{/}, except that search is done backward
+(@code{vip-search-backward}).
+@item n
+@kindex 156 @kbd{n} (@code{vip-search-next})
+Search the previous search pattern in the same direction as before
+(@code{vip-search-next}).
+@item N
+@kindex 116 @kbd{N} (@code{vip-search-Next})
+Search the previous search pattern in the opposite direction
+(@code{vip-search-Next}).
+@item C-s
+@kindex 023 @kbd{C-s} (@code{isearch-forward})
+Search forward incrementally. See GNU Emacs Manual for details
+(@code{isearch-forward}).
+@item C-r
+@kindex 022 @kbd{C-r} (@code{isearch-backward})
+Search backward incrementally (@code{isearch-backward}).
+@cindex vanilla (replacement)
+@cindex regular expression (replacement)
+@item R @var{string} RET @var{newstring}
+@kindex 122 @kbd{R} (@code{vip-replace-string})
+There are two modes of replacement, @dfn{vanilla} and @dfn{regular expression}.
+If the mode is @i{vanilla} you will get a prompt @samp{Replace string:},
+and if the mode is @i{regular expression} you will ge a prompt
+@samp{Replace regexp:}. The mode is initially @i{vanilla}, but you can
+toggle these modes by giving a null string as @var{string}. If the mode is
+vanilla, this command replaces every occurrence of @var{string} with
+@var{newstring}. If the mode is regular expression, @var{string} is
+treated as a regular expression and every string matching the regular
+expression is replaced with @var{newstring} (@code{vip-replace-string}).
+@item Q @var{string} RET @var{newstring}
+@kindex 121 @kbd{Q} (@code{vip-query-replace})
+Same as @kbd{R} except that you will be asked form confirmation before each
+replacement
+@*(@code{vip-query-replace}).
+@item r @var{ch}
+@kindex 162 @kbd{r} (@code{vip-replace-char})
+Replace the character point is looking at by the character @var{ch}. Give
+count, replace that many characters by @var{ch} (@code{vip-replace-char}).
+@end table
+@noindent
+The commands @kbd{/} and @kbd{?} mark point before move, so that you can
+return to the original point by @w{@kbd{` `}}.
+
+@node Modifying Commands, Delete Commands, Searching and Replacing, Vi Commands
+@section Modifying Commands
+
+In this section, commands for modifying the content of a buffer are
+described. These commands affect the region determined by a motion command
+which is given to the commands as their argument.
+
+@cindex point commands
+@cindex line commands
+
+We classify motion commands into @dfn{point commands} and
+@dfn{line commands}. The point commands are as follows:
+@example
+@kbd{h}, @kbd{l}, @kbd{0}, @kbd{^}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, @kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, @kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}
+@end example
+@noindent
+The line commands are as follows:
+@example
+@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, @kbd{@}}, @kbd{G}, @kbd{'}
+@end example
+@noindent
+@cindex expanding (region)
+If a point command is given as an argument to a modifying command, the
+region determined by the point command will be affected by the modifying
+command. On the other hand, if a line command is given as an argument to a
+modifying command, the region determined by the line command will be
+enlarged so that it will become the smallest region properly containing the
+region and consisting of whole lines (we call this process @dfn{expanding
+the region}), and then the enlarged region will be affected by the modifying
+command.
+
+@menu
+* Delete Commands:: Commands for deleting text.
+* Yank Commands:: Commands for yanking text in Vi's sense.
+* Put Back Commands:: Commands for putting back deleted/yanked text.
+* Change Commands:: Commands for changing text.
+* Repeating and Undoing Modifications::
+@end menu
+@node Delete Commands, Yank Commands, Modifying Commands, Modifying Commands
+@subsection Delete Commands
+
+@table @kbd
+@item d @var{motion-command}
+@kindex 1440 @kbd{d} (@code{vip-command-argument})
+Delete the region determined by the motion command @var{motion-command}.
+@end table
+@noindent
+For example, @kbd{d $} will delete the region between point and end of
+current line since @kbd{$} is a point command that moves point to end of line.
+@kbd{d G} will delete the region between the beginning of current line and
+end of the buffer, since @kbd{G} is a line command. A count given to the
+command above will become the count for the associated motion command.
+Thus, @kbd{3 d w} will delete three words.
+
+@kindex 042 @kbd{"} (@code{vip-command-argument})
+It is also possible to save the deleted text into a register you specify.
+For example, you can say @kbd{" t 3 d w} to delete three words and save it
+to register @kbd{t}. The name of a register is a lower-case letter between
+@kbd{a} and @kbd{z}. If you give an upper-case letter as an argument to
+a delete command, then the deleted text will be appended to the content of
+the register having the corresponding lower-case letter as its name. So,
+@kbd{" T d w} will delete a word and append it to register @kbd{t}. Other
+modifying commands also accept a register name as their argument, and we
+will not repeat similar explanations.
+
+We have more delete commands as below.
+
+@table @kbd
+@item d d
+@kindex 1442 @kbd{d d}
+Delete a line. Given a count @var{n}, delete @var{n} lines.
+@item d r
+@kindex 1442 @kbd{d r}
+Delete current region.
+@item d R
+@kindex 1441 @kbd{d R}
+Expand current region and delete it.
+@item D
+@kindex 104 @kbd{D} (@code{vip-kill-line})
+Delete to the end of a line (@code{vip-kill-line}).
+@item x
+@kindex 170 @kbd{x} (@code{vip-delete-char})
+Delete a character after point. Given @var{n}, delete @var{n} characters
+(@code{vip-delete-char}).
+@item @key{DEL}
+@kindex 177 @kbd{DEL} (@code{vip-delete-backward-char})
+Delete a character before point. Given @var{n}, delete @var{n} characters
+(@code{vip-delete-backward-char}).
+@end table
+
+@node Yank Commands, Put Back Commands, Delete Commands, Modifying Commands
+@subsection Yank Commands
+
+@cindex yank
+
+Yank commands @dfn{yank} a text of buffer into a (usually anonymous) register.
+Here the word `yank' is used in Vi's sense. Thus yank commands do not
+alter the content of the buffer, and useful only in combination with
+commands that put back the yanked text into the buffer.
+
+@table @kbd
+@item y @var{motion-command}
+@kindex 1710 @kbd{y} (@code{vip-command-argument})
+Yank the region determined by the motion command @var{motion-command}.
+@end table
+@noindent
+For example, @kbd{y $} will yank the text between point and the end of line
+into an anonymous register, while @kbd{"c y $} will yank the same text into
+register @kbd{c}.
+
+Use the following command to yank consecutive lines of text.
+
+@table @kbd
+@item y y
+@itemx Y
+@kindex 131 @kbd{Y} (@code{vip-yank-line})
+@kindex 1712 @kbd{y y} (@code{vip-yank-line})
+Yank a line. Given @var{n}, yank @var{n} lines (@code{vip-yank-line}).
+@item y r
+@kindex 1712 @kbd{y r}
+Yank current region.
+@item y R
+@kindex 1711 @kbd{y R}
+Expand current region and yank it.
+@end table
+
+@node Put Back Commands, Change Commands, Yank Commands, Modifying Commands
+@subsection Put Back Commands
+Deleted or yanked texts can be put back into the buffer by the command
+below.
+
+@table @kbd
+@item p
+@kindex 160 @kbd{p} (@code{vip-put-back})
+Insert, after the character point is looking at, most recently
+deleted/yanked text from anonymous register. Given a register name
+argument, the content of the named register will be put back. Given a
+count, the command will be repeated that many times. This command also
+checks if the text to put back ends with a new line character, and if so
+the text will be put below the current line (@code{vip-put-back}).
+@item P
+@kindex 120 @kbd{P} (@code{vip-Put-back})
+Insert at point most recently deleted/yanked text from anonymous register.
+Given a register name argument, the content of the named register will
+be put back. Given a count, the command will be repeated that many times.
+This command also checks if the text to put back ends with a new line
+character, and if so the text will be put above the current line rather
+than at point (@code{vip-Put-back}).
+@end table
+@noindent
+@cindex number register
+Thus, @kbd{" c p} will put back the content of the register @kbd{c} into the
+buffer. It is also possible to specify @dfn{number register} which is a
+numeral between @kbd{1} and @kbd{9}. If the number register @var{n} is
+specified, @var{n}-th previously deleted/yanked text will be put back. It
+is an error to specify a number register for the delete/yank commands.
+
+@node Change Commands, Repeating and Undoing Modifications, Put Back Commands, Modifying Commands
+@subsection Change Commands
+
+Most commonly used change command takes the following form.
+
+@table @kbd
+@item c @var{motion-command}
+@kindex 1430 @kbd{c} (@code{vip-command-argument})
+Replace the content of the region determined by the motion command
+@var{motion-command} by the text you type. If the motion command is a
+point command then you will type the text into minibuffer, and if the
+motion command is a line command then the region will be deleted first and
+you can insert the text in @var{insert mode}.
+@end table
+@noindent
+For example, if point is at the beginning of a word @samp{foo} and you
+wish to change it to @samp{bar}, you can type @kbd{c w}. Then, as @kbd{w}
+is a point command, you will get the prompt @samp{foo =>} in the
+minibuffer, for which you can type @kbd{b a r @key{RET}} to complete the change
+command.@refill
+
+@table @kbd
+@item c c
+@kindex 1432 @kbd{c c}
+Change a line. Given a count, that many lines are changed.
+@item c r
+@kindex 1432 @kbd{c r}
+Change current region.
+@item c R
+@kindex 1431 @kbd{c R}
+Expand current region and change it.
+@end table
+
+@node Repeating and Undoing Modifications, Other Vi Commands, Change Commands, Modifying Commands
+@subsection Repeating and Undoing Modifications
+
+VIP records the previous modifying command, so that it is easy to repeat
+it. It is also very easy to undo changes made by modifying commands.
+
+@table @kbd
+@item u
+@kindex 165 @kbd{u} (@code{vip-undo})
+Undo the last change. You can undo more by repeating undo by the repeat
+command @samp{.}. For example, you can undo 5 previous changes by typing
+@samp{u....}. If you type @samp{uu}, then the second @samp{u} undoes the
+first undo command (@code{vip-undo}).
+@item .
+@kindex 056 @kbd{.} (@code{vip-repeat})
+Repeat the last modifying command. Given count @var{n} it becomes the new
+count for the repeated command. Otherwise, the count for the last
+modifying command is used again (@code{vip-repeat}).
+@end table
+
+@node Other Vi Commands, Commands in Insert Mode, Repeating and Undoing Modifications, Vi Commands
+@section Other Vi Commands
+
+Miscellaneous Vi commands are collected here.
+
+@table @kbd
+@item Z Z
+@kindex 132 @kbd{Z Z} (@code{save-buffers-kill-emacs})
+Exit Emacs. If modified buffers exist, you will be asked whether you wish
+to save them or not (@code{save-buffers-kill-emacs}).
+@item !@: @var{motion-command} @var{format-command}
+@itemx @var{n} !@: !@: @var{format-command}
+@kindex 041 @kbd{!} (@code{vip-command-argument})
+The region determined by the motion command @var{motion-command} will be
+given to the shell command @var{format-command} and the region will be
+replaced by its output. If a count is given, it will be passed to
+@var{motion-command}. For example, @samp{3!Gsort} will sort the region
+between point and the 3rd line. If @kbd{!} is used instead of
+@var{motion-command} then @var{n} lines will be processed by
+@var{format-command} (@code{vip-command-argument}).
+@item J
+@kindex 112 @kbd{J} (@code{vip-join-lines})
+Join two lines. Given count, join that many lines. A space will be
+inserted at each junction (@code{vip-join-lines}).
+@item < @var{motion-command}
+@itemx @var{n} < <
+@kindex 074 @kbd{<} (@code{vip-command-argument})
+Shift region determined by the motion command @var{motion-command} to
+left by @var{shift-width} (default is 8). If @kbd{<} is used instead of
+@var{motion-command} then shift @var{n} lines
+@*(@code{vip-command-argument}).
+@item > @var{motion-command}
+@itemx @var{n} > >
+@kindex 076 @kbd{>} (@code{vip-command-argument})
+Shift region determined by the motion command @var{motion-command} to
+right by @var{shift-width} (default is 8). If @kbd{<} is used instead of
+@var{motion-command} then shift @var{n} lines
+@*(@code{vip-command-argument}).
+@item = @var{motion-command}
+@kindex 075 @kbd{=} (@code{vip-command-argument})
+Indent region determined by the motion command @var{motion-command}. If
+@kbd{=} is used instead of @var{motion-command} then indent @var{n} lines
+(@code{vip-command-argument}).
+@item *
+@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro})
+Call last remembered keyboard macro.
+@item #
+A new vi operator. @xref{New Commands}, for more details.
+@end table
+
+The following keys are reserved for future extensions, and currently
+assigned to a function that just beeps (@code{vip-nil}).
+
+@kindex 046 @kbd{&} (@code{vip-nil})
+@kindex 100 @kbd{@@} (@code{vip-nil})
+@kindex 125 @kbd{U} (@code{vip-nil})
+@kindex 133 @kbd{[} (@code{vip-nil})
+@kindex 135 @kbd{]} (@code{vip-nil})
+@kindex 137 @kbd{_} (@code{vip-nil})
+@kindex 161 @kbd{q} (@code{vip-nil})
+@kindex 176 @kbd{~} (@code{vip-nil})
+
+@example
+&, @@, U, [, ], _, q, ~
+@end example
+
+VIP uses a special local keymap to interpret key strokes you enter in vi
+mode. The following keys are bound to @var{nil} in the keymap. Therefore,
+these keys are interpreted by the global keymap of Emacs. We give below a
+short description of the functions bound to these keys in the global
+keymap. See GNU Emacs Manual for details.
+
+@table @kbd
+@item C-@@
+@kindex 000 @kbd{C-@@} (@code{set-mark-command})
+Set mark and push previous mark on mark ring (@code{set-mark-command}).
+@item TAB
+@kindex 011 @kbd{TAB} (@code{indent-for-tab-command})
+Indent line for current major mode (@code{indent-for-tab-command}).
+@item C-j
+@kindex 012 @kbd{C-j} (@code{newline-and-indent})
+Insert a newline, then indent according to mode (@code{newline-and-indent}).
+@item C-k
+@kindex 013 @kbd{C-k} (@code{kill-line})
+Kill the rest of the current line; before a newline, kill the newline.
+With a numeric argument, kill that many lines from point. Negative arguments
+kill lines backward (@code{kill-line}).
+@item C-l
+@kindex 014 @kbd{C-l} (@code{recenter})
+Clear the screen and reprint everything (@code{recenter}).
+@item @var{n} C-p
+@kindex 020 @kbd{C-p} (@code{previous-line})
+Move cursor vertically up @var{n} lines (@code{previous-line}).
+@item C-q
+@kindex 021 @kbd{C-q} (@code{quoted-insert})
+Read next input character and insert it. Useful for inserting control
+characters
+@*(@code{quoted-insert}).
+@item C-r
+@kindex 022 @kbd{C-r} (@code{isearch-backward})
+Search backward incrementally (@code{isearch-backward}).
+@item C-s
+@kindex 023 @kbd{C-s} (@code{isearch-forward})
+Search forward incrementally (@code{isearch-forward}).
+@item @var{n} C-t
+@kindex 024 @kbd{C-t} (@code{transpose-chars})
+Interchange characters around point, moving forward one character. With
+count @var{n}, take character before point and drag it forward past @var{n}
+other characters. If no argument and at end of line, the previous two
+characters are exchanged (@code{transpose-chars}).
+@item @var{n} C-v
+@kindex 026 @kbd{C-v} (@code{scroll-up})
+Scroll text upward @var{n} lines. If @var{n} is not given, scroll near
+full screen (@code{scroll-up}).
+@item C-w
+@kindex 027 @kbd{C-w} (@code{kill-region})
+Kill between point and mark. The text is save in the kill ring. The
+command @kbd{P} or @kbd{p} can retrieve it from kill ring
+(@code{kill-region}).
+@end table
+
+@node Commands in Insert Mode, Ex Commands, Other Vi Commands, Vi Commands
+@section Insert Mode
+
+You can enter insert mode by one of the following commands. In addition to
+these, you will enter insert mode if you give a change command with a line
+command as the motion command. Insert commands are also modifying commands
+and you can repeat them by the repeat command @kbd{.} (@code{vip-repeat}).
+
+@table @kbd
+@item i
+@kindex 151 @kbd{i} (@code{vip-insert})
+Enter insert mode at point (@code{vip-insert}).
+@item I
+@kindex 111 @kbd{I} (@code{vip-Insert})
+Enter insert mode at the first non white character on the line
+(@code{vip-Insert}).
+@item a
+@kindex 141 @kbd{a} (@code{vip-append})
+Move point forward by one character and then enter insert mode
+(@code{vip-append}).
+@item A
+@kindex 101 @kbd{A} (@code{vip-Append})
+Enter insert mode at end of line (@code{vip-Append}).
+@item o
+@kindex 157 @kbd{o} (@code{vip-open-line})
+Open a new line below the current line and enter insert mode
+(@code{vip-open-line}).
+@item O
+@kindex 117 @kbd{O} (@code{vip-Open-line})
+Open a new line above the current line and enter insert mode
+(@code{vip-Open-line}).
+@item C-o
+@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point})
+Insert a newline and leave point before it, and then enter insert mode
+@*(@code{vip-open-line-at-point}).
+@end table
+
+Insert mode is almost like emacs mode. Only the following 4 keys behave
+differently from emacs mode.
+
+@table @kbd
+@item @key{ESC}
+@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode)
+This key will take you back to vi mode (@code{vip-change-mode-to-vi}).
+@item C-h
+@kindex 010 @kbd{C-h} (@code{delete-backward-char}) (insert mode)
+Delete previous character (@code{delete-backward-char}).
+@item C-w
+@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode)
+Delete previous word (@code{vip-delete-backward-word}).
+@item C-z
+@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode)
+This key simulates @key{ESC} key in emacs mode. For instance, typing
+@kbd{C-z x} in insert mode iw the same as typing @kbd{ESC x} in emacs mode
+(@code{vip-ESC}).
+@end table
+@noindent
+You can also bind @kbd{C-h} to @code{help-command} if you like.
+(@xref{Customizing Key Bindings}, for details.) Binding @kbd{C-h} to
+@code{help-command} has the effect of making the meaning of @kbd{C-h}
+uniform among emacs, vi and insert modes.
+
+When you enter insert mode, VIP records point as the start point of
+insertion, and when you leave insert mode the region between point and
+start point is saved for later use by repeat command etc. Therefore, repeat
+command will not really repeat insertion if you move point by emacs
+commands while in insert mode.
+
+@node Ex Commands, Ex Command Reference, Commands in Insert Mode, Top
+@chapter Ex Commands
+
+@kindex 072 @kbd{:} (@code{vip-ex})
+
+In vi mode, you can execute an Ex command @var{ex-command} by typing:
+@example
+@kbd{:@: @var{ex-command} @key{RET}}
+@end example
+Every Ex command follows the following pattern:
+@example
+@var{address command} @kbd{!}@: @var{parameters count flags}
+@end example
+@noindent
+@cindex address
+where all parts are optional. For the syntax of @dfn{address}, the reader
+is referred to the reference manual of Ex.
+
+@cindex magic
+@cindex regular expression
+
+In the current version of VIP, searching by Ex commands is always
+@dfn{magic}. That is, search patterns are always treated as @dfn{regular
+expressions}. For example, a typical forward search would be invoked by
+@kbd{:/@var{pat}/}. If you wish to include @samp{/} as part of
+@var{pat} you must preceded it by @samp{\}. VIP strips off these @kbd{\}'s
+before @kbd{/} and the resulting @var{pat} becomes the actual search
+pattern. Emacs provides a different and richer class or regular
+expressions than Vi/Ex, and VIP uses Emacs' regular expressions. See GNU
+Emacs Manual for details of regular expressions.
+
+Several Ex commands can be entered in a line by separating them by a pipe
+character @samp{|}.
+
+@menu
+* Ex Command Reference:: Explain all the Ex commands available in VIP.
+@end menu
+@node Ex Command Reference, Customization, Ex Commands, Ex Commands
+@section Ex Command Reference
+In this section we briefly explain all the Ex commands supported by VIP.
+Most Ex commands expect @var{address} as their argument, and they use
+default addresses if they are not explicitly given. In the following, such
+default addresses will be shown in parentheses.
+
+Most command names can and preferably be given in abbreviated forms. In
+the following, optional parts of command names will be enclosed in
+brackets. For example, @samp{co[py]} will mean that copy command can be
+give as @samp{co} or @samp{cop} or @samp{copy}.
+
+If @var{command} is empty, point will move to the beginning of the line
+specified by the @var{address}. If @var{address} is also empty, point will
+move to the beginning of the current line.
+
+@cindex flag
+
+Some commands accept @dfn{flags} which are one of @kbd{p}, @kbd{l} and
+@kbd{#}. If @var{flags} are given, the text affected by the commands will
+be displayed on a temporary window, and you will be asked to hit return to
+continue. In this way, you can see the text affected by the commands
+before the commands will be executed. If you hit @kbd{C-g} instead of
+@key{RET} then the commands will be aborted. Note that the meaning of
+@var{flags} is different in VIP from that in Vi/Ex.
+
+@table @kbd
+@item (.,.@:) co[py] @var{addr} @var{flags}
+@itemx (.,.@:) t @var{addr} @var{flags}
+Place a copy of specified lines after @var{addr}. If @var{addr} is
+@kbd{0}, it will be placed before the first line.
+@item (.,.@:) d[elete] @var{register} @var{count} @var{flags}
+Delete specified lines. Text will be saved in a named @var{register} if a
+lower-case letter is given, and appended to a register if a capital letter is
+given.
+@item e[dit] !@: +@var{addr} @var{file}
+@itemx e[x] !@: +@var{addr} @var{file}
+@itemx vi[sual] !@: +@var{addr} @var{file}
+Edit a new file @var{file} in the current window. The command will abort
+if current buffer is modified, which you can override by giving @kbd{!}.
+If @kbd{+}@var{addr} is given, @var{addr} becomes the current line.
+@item file
+Give information about the current file.
+@item (1,$) g[lobal] !@: /@var{pat}/ @var{cmds}
+@itemx (1,$) v /@var{pat}/ @var{cmds}
+Among specified lines first mark each line which matches the regular
+expression @var{pat}, and then execute @var{cmds} on each marked line.
+If @kbd{!}@: is given, @var{cmds} will be executed on each line not matching
+@var{pat}. @kbd{v} is same as @kbd{g!}.
+@item (.,.+1) j[oin] !@: @var{count} @var{flags}
+Join specified lines into a line. Without @kbd{!}, a space character will
+be inserted at each junction.
+@item (.@:) k @var{ch}
+@itemx (.@:) mar[k] @var{ch}
+Mark specified line by a lower-case character @var{ch}. Then the
+addressing form @kbd{'}@var{ch} will refer to this line. No white space is
+required between @kbd{k} and @var{ch}. A white space is necessary between
+@kbd{mark} and @var{ch}, however.
+@item map @var{ch} @var{rhs}
+Define a macro for vi mode. After this command, the character @var{ch}
+will be expanded to @var{rhs} in vi mode.
+@item (.,.@:) m[ove] @var{addr}
+Move specified lines after @var{addr}.
+@item (.@:) pu[t] @var{register}
+Put back previously deleted or yanked text. If @var{register} is given,
+the text saved in the register will be put back; otherwise, last deleted or
+yanked text will be put back.
+@item q[uit] !
+Quit from Emacs. If modified buffers with associated files exist, you will
+be asked whether you wish to save each of them. At this point, you may
+choose not to quit, by hitting @kbd{C-g}. If @kbd{!}@: is given, exit from
+Emacs without saving modified buffers.
+@item (.@:) r[ead] @var{file}
+Read in the content of the file @var{file} after the specified line.
+@item (.@:) r[ead] !@: @var{command}
+Read in the output of the shell command @var{command} after the specified
+line.
+@item se[t]
+Set a variable's value. @xref{Customizing Constants}, for the list of variables
+you can set.
+@item sh[ell]
+Run a subshell in a window.
+@item (.,.@:) s[ubstitute] /@var{pat}/@var{repl}/ @var{options} @var{count} @var{flags}
+@itemx (.,.@:) & @var{options} @var{count} @var{flags}
+On each specified line, the first occurrence of string matching regular
+expression @var{pat} is replaced by replacement pattern @var{repl}. Option
+characters are @kbd{g} and @kbd{c}. If global option character @kbd{g}
+appears as part of @var{options}, all occurrences are substituted. If
+confirm option character @kbd{c} appears, you will be asked to give
+confirmation before each substitution. If @kbd{/@var{pat}/@var{repl}/} is
+missing, the last substitution is repeated.
+@item st[op]
+Suspend Emacs.
+@item ta[g] @var{tag}
+@cindex tag
+@cindex selected tags table
+Find first definition of @var{tag}. If no @var{tag} is given, previously
+given @var{tag} is used and next alternate definition is find. By default,
+the file @file{TAGS} in the current directory becomes the @dfn{selected tags
+table}. You can select another tags table by @kbd{set} command.
+@xref{Customizing Constants}, for details.
+@item und[o]
+Undo the last change.
+@item unm[ap] @var{ch}
+The macro expansion associated with @var{ch} is removed.
+@item ve[rsion]
+Tell the version number of VIP.
+@item (1,$) w[rite] !@: @var{file}
+Write out specified lines into file @var{file}. If no @var{file} is given,
+text will be written to the file associated to the current buffer. Unless
+@kbd{!}@: is given, if @var{file} is different from the file associated to
+the current buffer and if the file @var{file} exists, the command will not
+be executed. Unlike Ex, @var{file} becomes the file associated to the
+current buffer.
+@item (1,$) w[rite]>> @var{file}
+Write out specified lines at the end of file @var{file}. @var{file}
+becomes the file associated to the current buffer.
+@item (1,$) wq !@: @var{file}
+Same as @kbd{write} and then @kbd{quit}. If @kbd{!}@: is given, same as
+@kbd{write !}@: then @kbd{quit}.
+@item (.,.) y[ank] @var{register} @var{count}
+Save specified lines into register @var{register}. If no register is
+specified, text will be saved in an anonymous register.
+@item @var{addr} !@: @var{command}
+Execute shell command @var{command}. The output will be shown in a new
+window. If @var{addr} is given, specified lines will be used as standard
+input to @var{command}.
+@item ($) =
+Print the line number of the addressed line.
+@item (.,.) > @var{count} @var{flags}
+Shift specified lines to the right. The variable @code{vip-shift-width}
+(default value is 8) determines the amount of shift.
+@item (.,.) < @var{count} @var{flags}
+Shift specified lines to the left. The variable @code{vip-shift-width}
+(default value is 8) determines the amount of shift.
+@item (.,.@:) ~ @var{options} @var{count} @var{flags}
+Repeat the previous @kbd{substitute} command using previous search pattern
+as @var{pat} for matching.
+@end table
+
+The following Ex commands are available in Vi, but not implemented in VIP.
+@example
+@kbd{abbreviate}, @kbd{list}, @kbd{next}, @kbd{print}, @kbd{preserve}, @kbd{recover}, @kbd{rewind}, @kbd{source},
+@kbd{unabbreviate}, @kbd{xit}, @kbd{z}
+@end example
+
+@node Customization, Customizing Constants, Ex Command Reference, Top
+@chapter Customization
+
+If you have a file called @file{.vip} in your home directory, then it
+will also be loaded when VIP is loaded. This file is thus useful for
+customizing VIP.
+
+@menu
+* Customizing Constants:: How to change values of constants.
+* Customizing Key Bindings:: How to change key bindings.
+@end menu
+
+@node Customizing Constants, Customizing Key Bindings, Customization, Customization
+@section Customizing Constants
+An easy way to customize VIP is to change the values of constants used
+in VIP. Here is the list of the constants used in VIP and their default
+values.
+
+@table @code
+@item vip-shift-width 8
+The number of columns shifted by @kbd{>} and @kbd{<} command.
+@item vip-re-replace nil
+If @code{t} then do regexp replace, if @code{nil} then do string replace.
+@item vip-search-wrap-around t
+If @code{t}, search wraps around the buffer.
+@item vip-re-search nil
+If @code{t} then search is reg-exp search, if @code{nil} then vanilla
+search.
+@item vip-case-fold-search nil
+If @code{t} search ignores cases.
+@item vip-re-query-replace nil
+If @code{t} then do reg-exp replace in query replace.
+@item vip-open-with-indent nil
+If @code{t} then indent to the previous current line when open a new line
+by @kbd{o} or @kbd{O} command.
+@item vip-tags-file-name "TAGS"
+The name of the file used as the tags table.
+@item vip-help-in-insert-mode nil
+If @code{t} then @key{C-h} is bound to @code{help-command} in insert mode,
+if @code{nil} then it sis bound to @code{delete-backward-char}.
+@end table
+@noindent
+You can reset these constants in VIP by the Ex command @kbd{set}. Or you
+can include a line like this in your @file{.vip} file:
+@example
+(setq vip-case-fold-search t)
+@end example
+
+@node Customizing Key Bindings,, Customizing Constants, Customization
+@section Customizing Key Bindings
+
+@cindex local keymap
+
+VIP uses @code{vip-command-mode-map} as the @dfn{local keymap} for vi mode.
+For example, in vi mode, @key{SPC} is bound to the function
+@code{vip-scroll}. But, if you wish to make @key{SPC} and some other keys
+ behave like Vi, you can include the following lines in your @file{.vip}
+file.
+
+@example
+(define-key vip-command-mode-map "\C-g" 'vip-info-on-file)
+(define-key vip-command-mode-map "\C-h" 'vip-backward-char)
+(define-key vip-command-mode-map "\C-m" 'vip-next-line-at-bol)
+(define-key vip-command-mode-map " " 'vip-forward-char)
+(define-key vip-command-mode-map "g" 'vip-keyboard-quit)
+(define-key vip-command-mode-map "s" 'vip-substitute)
+(define-key vip-command-mode-map "C" 'vip-change-to-eol)
+(define-key vip-command-mode-map "R" 'vip-change-to-eol)
+(define-key vip-command-mode-map "S" 'vip-substitute-line)
+(define-key vip-command-mode-map "X" 'vip-delete-backward-char)
+@end example
+
+@unnumbered Key Index
+
+@printindex ky
+
+@unnumbered Concept Index
+@printindex cp
+
+@contents
+@bye
--- /dev/null
+% -*-texinfo-*-
+\input texinfo
+
+@comment Using viper.info instead of viper in setfilename breaks DOS.
+@comment @setfilename viper
+@comment @setfilename viper.info
+@setfilename ../info/viper
+
+@dircategory Editors
+@direntry
+* VIPER: (viper). The newest Emacs VI-emulation mode.
+ (also, A VI Plan for Emacs Rescue
+ or the VI PERil.)
+@end direntry
+
+@iftex
+@finalout
+@end iftex
+
+@titlepage
+@title Viper Is a Package for Emacs Rebels
+@subtitle a Vi emulator for Emacs
+@subtitle March 1998, Viper Version 3.02 (Polyglot)
+
+@author Michael Kifer (Viper)
+@author Aamod Sane (VIP 4.4)
+@author Masahiko Sato (VIP 3.5)
+
+@page
+@vskip 0pt plus 1fill
+@end titlepage
+
+@unnumbered Distribution
+
+@noindent
+Copyright @copyright{} 1995, 1996, 1997 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the same conditions as for modified versions.
+
+@ifinfo
+@node Top, Overview,, (DIR)
+
+@unnumbered Viper
+
+We believe that one or more of the following statements are adequate
+descriptions:
+
+@example
+Viper Is a Package for Emacs Rebels;
+it is a VI Plan for Emacs Rescue
+and/or a venomous VI PERil.
+@end example
+
+Technically speaking, Viper is a Vi emulation package for Emacs. It
+implements all Vi and Ex commands, occasionally improving on them and
+adding many new features. It gives the user the best of both worlds: Vi
+keystrokes for editing combined with the power of the Emacs environment.
+
+Viper emulates Vi at several levels, from the one that closely follows Vi
+conventions to the one that departs from many of them. It has many
+customizable options, which can be used to tailor Viper to the work habits
+of various users.
+This manual describes Viper, concentrating on the differences from Vi and
+new features of Viper.
+
+Viper, formerly known as VIP-19, was written by Michael Kifer. It is based
+on VIP version 3.5 by Masahiko Sato and VIP version 4.4 by Aamod Sane.
+Viper tries to be compatible with these packages.
+
+Viper is intended to be usable without reading this manual --- the defaults
+are set to make Viper as close to Vi as possible. At startup, Viper will
+try to set the most appropriate default environment for you, based on
+your familiarity with Emacs. It will also tell you the basic GNU Emacs window
+management commands to help you start immediately.
+
+Although this manual explains how to customize Viper, some basic
+familiarity with Emacs Lisp would be a plus.
+
+It is recommended that you read the Overview node. The other nodes may
+be visited as needed.
+
+Comments and bug reports are welcome.
+@code{kifer@@cs.emacs.edu} is the current address for Viper bug reports.
+Please use the Ex command @kbd{:submitReport} for this purpose.@refill
+
+@end ifinfo
+
+@menu
+* Overview:: Must read to get started
+* Improvements over Vi:: New features, Improvements
+* Customization:: How to customize Viper
+* Commands:: Vi and Ex Commands
+
+* Key Index:: Index of Vi and Ex Commands
+* Function Index:: Index of Viper Functions
+* Variable Index:: Index of Viper Variables
+* Package Index:: Index of Packages Mentioned in this Document
+* Concept Index:: Vi, Ex and Emacs concepts
+
+* Acknowledgments::
+@end menu
+@iftex
+@unnumbered Introduction
+
+We believe that one or more of the following statements are adequate
+descriptions:
+
+@example
+Viper Is a Package for Emacs Rebels;
+it is a VI Plan for Emacs Rescue
+and/or a venomous VI PERil.
+@end example
+
+Viper is a Vi emulation package for Emacs. Viper contains virtually all
+of Vi and Ex functionality and much more. It gives you the best of both
+worlds: Vi keystrokes for editing combined with the GNU Emacs
+environment. Viper also fixes some common complaints with Vi commands.
+This manual describes Viper, concentrating on the differences from Vi
+and on the new features of Viper.
+
+Viper was written by Michael Kifer. It is based on VIP version 3.5 by
+Masahiko Sato and VIP version 4.4 by Aamod Sane. Viper tries to be
+compatible with these packages.
+
+Viper is intended to be usable out of the box, without reading this manual
+--- the defaults are set to make Viper as close to Vi as possible. At
+startup, Viper will attempt to set the most appropriate default environment
+for you, based on your familiarity with Emacs. It will also tell you the
+basic GNU Emacs window management commands to help you start immediately.
+
+Although this manual explains how to customize Viper, some basic
+familiarity with Emacs Lisp would be a plus.
+
+It is recommended that you read the chapter Overview. The other chapters
+will be useful for customization and advanced usage.
+
+You should also learn to use the Info on-line hypertext manual system that
+comes with Emacs. This manual can be read as an Info file. Try the command
+@kbd{@key{ESC} x info} with vanilla Emacs sometime.
+
+Comments and bug reports are welcome.
+@code{kifer@@cs.sunysb.edu} is the current address for Viper bug reports.
+Please use the Ex command @kbd{:submitReport} for this purpose.@refill
+
+@end iftex
+
+@node Overview,Improvements over Vi,Top,Top
+@chapter Overview of Viper
+
+Viper is a Vi emulation on top of Emacs. At the same time, Viper provides a
+virtually unrestricted access to Emacs facilities. Perfect compatibility
+with Vi is possible but not desirable. This chapter tells you about the
+Emacs ideas that you should know about, how to use Viper within Emacs and
+some incompatibilities.
+
+Viper was formerly known as VIP-19, which was
+a descendant of VIP 3.5 by Masahiko Sato and VIP 4.4 by Aamod Sane.
+
+@menu
+* Emacs Preliminaries:: Basic concepts in Emacs.
+* Loading Viper:: Loading and Preliminary Configuration.
+* States in Viper:: Viper has four states orthogonal to Emacs
+ modes.
+* The Minibuffer:: Command line in Emacs.
+* Multiple Files in Viper:: True multiple file handling.
+* Unimplemented Features:: That are unlikely to be implemented.
+@end menu
+
+@node Emacs Preliminaries, Loading Viper, Overview, Overview
+@section Emacs Preliminaries
+
+@cindex buffer
+@cindex point
+@cindex mark
+@cindex text
+@cindex looking at
+@cindex end (of buffer)
+@cindex end (of line)
+@cindex region
+
+Emacs can edit several files at once. A file in Emacs is placed in a
+@dfn{buffer} that usually has the same name as the file. Buffers are also used
+for other purposes, such as shell interfaces, directory editing, etc.
+@xref{Dired,,Directory Editor,emacs,The
+Gnu Emacs Manual}, for an example.@refill
+
+A buffer has a distinguished position called the @dfn{point}.
+A @dfn{point} is always between 2 characters, and is @dfn{looking at}
+the right hand character. The cursor is positioned on the right hand
+character. Thus, when the @dfn{point} is looking at the end-of-line,
+the cursor is on the end-of-line character, i.e.@: beyond the last
+character on the line. This is the default Emacs behavior.@refill
+
+The default settings of Viper try to mimic the behavior of Vi, preventing
+the cursor from going beyond the last character on the line. By using
+Emacs commands directly (such as those bound to arrow keys), it is possible
+to get the cursor beyond the end-of-line. However, this won't (or
+shouldn't) happen if you restrict yourself to standard Vi keys, unless you
+modify the default editing style. @xref{Customization}.@refill
+
+In addition to the @dfn{point}, there is another distinguished buffer
+position called the @dfn{mark}. @xref{Mark,,Mark,emacs,The GNU Emacs
+manual}, for more info on the mark. The text between the @dfn{point} and
+the @dfn{mark} is called the @dfn{region} of the buffer. For the Viper
+user, this simply means that in addition to the Vi textmarkers a--z, there
+is another marker called @dfn{mark}. This is similar to the unnamed Vi
+marker used by the jump commands @kbd{``} and @kbd{''}, which move the
+cursor to the position of the last absolute jump. Viper provides access to
+the region in most text manipulation commands as @kbd{r} and @kbd{R} suffix
+to commands that operate on text regions, e.g., @kbd{dr} to delete region,
+etc.
+
+Furthermore, Viper lets Ex-style commands to work on the current region.
+This is done by typing a digit argument before @kbd{:}. For instance,
+typing @kbd{1:} will propmt you with something like @emph{:123,135},
+assuming that the current region starts at line 123 and ends at line
+135. There is no need to type the line numbers, since Viper inserts them
+automatically in front of the Ex command.
+
+@xref{Basics}, for more info.@refill
+
+@cindex window
+@cindex mode line
+@cindex buffer information
+@cindex Minibuffer
+@cindex command line
+@cindex buffer (modified)
+
+Emacs divides the screen into tiled @dfn{windows}. You can see the
+contents of a buffer through the window associated with the buffer. The
+cursor of the screen is positioned on the character after @dfn{point}.
+Every window has a @dfn{mode line} that displays information about the buffer.
+You can change the format of the mode
+line, but normally if you see @samp{**} at the beginning of a mode line it
+means that the buffer is @dfn{modified}. If you write out the contents of
+a buffer to a file, then the buffer will become not modified. Also if
+you see @samp{%%} at the beginning of the mode line, it means that the file
+associated with the buffer is write protected. The mode line will also
+show the buffer name and current major and minor modes (see below).
+A special buffer called @dfn{Minibuffer} is displayed as the last line
+in a Minibuffer window. The Minibuffer window is used for command input
+output. Viper uses Minibuffer window for @kbd{/} and @kbd{:}
+commands.@refill
+
+@cindex mode
+@cindex keymap
+@cindex local keymap
+@cindex global keymap
+@cindex major mode
+@cindex minor mode
+
+An Emacs buffer can have a @dfn{major mode} that customizes Emacs for
+editing text of a particular sort by changing the functionality of the keys.
+Keys are defined using a @dfn{keymap} that records the bindings between
+keystrokes and
+functions. The @dfn{global keymap} is common to all the
+buffers. Additionally, each buffer has its @dfn{local keymap} that determines the
+@dfn{mode} of the buffer. If a function is bound to some key in the local
+keymap then that function will be executed when you type the key.
+If no function is bound to a key in the
+local map, however, the function bound to the key in the global map
+will be executed. @xref{Major Modes,Major Modes,Major Modes,emacs,The
+GNU Emacs Manual}, for more information.@refill
+
+A buffer can also have a @dfn{minor mode}. Minor modes are options that
+you can use or not. A buffer in @code{text-mode} can have
+@code{auto-fill-mode} as minor mode, which can be turned off or on at
+any time. In Emacs, a minor mode may have it own keymap,
+which overrides the local keymap when the minor mode is turned on. For
+more information, @pxref{Minor Modes,Minor Modes,Minor Modes,emacs,The
+GNU Emacs Manual} @refill
+
+@cindex Viper as minor mode
+@cindex Control keys
+@cindex Meta key
+
+Viper is implemented as a collection of minor modes. Different minor modes
+are involved when Viper emulates Vi command mode, Vi insert mode, etc.
+You can also turn Viper on and off at any time while in Vi command mode.
+@xref{States in Viper}, for
+more information.@refill
+
+Emacs uses Control and Meta modifiers. These are denoted as C and M,
+e.g.@: @kbd{^Z} as @kbd{C-z} and @kbd{Meta-x} as @kbd{M-x}. The Meta key is
+usually located on each side of the Space bar; it is used in a manner
+similar to the Control key, e.g., @kbd{M-x} means typing @kbd{x} while
+holding the Meta key down. For keyboards that do not have a Meta key,
+@key{ESC} is used as Meta. Thus @kbd{M-x} is typed as @kbd{@key{ESC}
+x}. Viper uses @key{ESC} to switch from Insert state to Vi state. Therefore
+Viper defines @kbd{C-\} as its Meta key in Vi state. @xref{Vi State}, for
+more info.@refill
+
+Emacs is structured as a lisp interpreter around a C core. Emacs keys
+cause lisp functions to be called. It is possible to call these
+functions directly, by typing @kbd{M-x function-name}.
+
+@node Loading Viper, States in Viper, Emacs Preliminaries, Overview
+@section Loading Viper
+
+The most common way to load it automatically is to include the following
+lines (in the given order!):
+
+@lisp
+(setq viper-mode t)
+(require 'viper)
+@end lisp
+
+@noindent
+in your @file{~/.emacs} file. The @file{.emacs} file is placed in your
+home directory and it is be executed every time you invoke Emacs. This is
+the place where all general Emacs customization takes place. Beginning with
+version 20.0, Emacsen have an interactive interface, which simplifies the
+job of customization significantly.
+
+Viper also uses the file @file{~/.viper} for Viper-specific customization.
+If you wish to be in Vi command state whenever this is deemed appropriate
+by the author, you can include the following line in your @file{.viper}:
+@lisp
+(setq viper-always t)
+@end lisp
+@noindent
+(@xref{Vi State}, for the explanation of Vi command state.)
+
+The location of Viper customization file can be changed by setting the
+variable @code{viper-custom-file-name} in @file{.emacs} @emph{prior} to loading
+Viper.
+
+Once invoked, Viper will arrange to bring up Emacs buffers in Vi state
+whenever this makes sense.
+@xref{Packages that Change Keymaps}, to find out when forcing Vi command state
+on a buffer may be counter-productive.
+
+Even if your @file{.emacs} and @file{.viper} files do not contain any of the
+above lines, you can still load Viper and enter Vi command state by typing the
+following from within Emacs:
+
+@lisp
+M-x viper-mode
+@end lisp
+
+When Emacs first comes up, if you have not specified a file on the
+command line, it will show the @samp{*scratch*} buffer, in the
+@samp{Lisp Interaction} mode. After you invoke Viper, you can start
+editing files by using @kbd{:e}, @kbd{:vi}, or @kbd{v} commands.
+(@xref{File and Buffer Handling}, for more information on @kbd{v} and other
+new commands that, in many cases, are more convenient than @kbd{:e},
+@kbd{:vi}, and similar old-style Vi commands.)@refill
+
+Finally, if at some point you would want to get de-Viperize your running
+copy of Emacs after Viper has been loaded, the command @kbd{M-x
+viper-go-away} will do it for you. The function @code{toggle-viper-mode}
+toggles Viperization of Emacs on and off.
+
+@node States in Viper, The Minibuffer, Loading Viper,Overview
+@section States in Viper
+
+@kindex @kbd{C-z}
+@kindex @key{ESC}
+@kindex @kbd{i}
+@cindex Emacs state
+@cindex Vi state
+@cindex Insert state
+@cindex Replace state
+@cindex Ex commands
+@findex @code{viper-go-away}
+@findex @code{toggle-viper-mode}
+
+Viper has four states, Emacs, Vi, Insert, and Replace.
+
+@table @samp
+@item Emacs state
+This is the state plain vanilla Emacs is normally in. After you have loaded
+Viper, @kbd{C-z} will normally take you to Vi command state. Another
+@kbd{C-z} will take you back to Emacs state. This toggle key can be
+changed, @pxref{Customization} You can also type @kbd{M-x viper-mode} to
+change to Vi state.@refill
+
+
+For users who chose to set their user level to 1 at Viper setup time,
+switching to Emacs state is deliberately made harder in order to not
+confuse the novice user. In this case, @kbd{C-z} will either iconify Emacs
+(if Emacs runs as an application under X Windows) or it will stop Emacs (if
+Emacs runs on a dumb terminal or in an Xterm window).
+
+@item Vi state
+This is the Vi command mode. Any of the Vi commands, such as @kbd{i, o, a},
+@dots{}, will take you to Insert state. All Vi commands may
+be used in this mode. Most Ex commands can also be used.
+For a full list of Ex commands supported by Viper, type
+@kbd{:} and then @key{TAB}. To get help on any issue, including the Ex
+commands, type @kbd{:help}. This will invoke Viper Info
+(if it is installed). Then typing @kbd{i} will prompt you for a topic to
+search in the index. Note: to search for Ex commands in the index, you
+should start them with a ``@kbd{:}'', e.g., @kbd{:WW}.
+
+In Viper, Ex commands can be made to work on the current Emacs region.
+This is done by typing a digit argument before @kbd{:}.
+For instance, typing @kbd{1:} will propmt you with something like
+@emph{:123,135}, assuming that the current region starts at line 123 and
+ends at line 135. There is no need to type the line numbers, since Viper
+inserts them automatically in front of the Ex command.
+
+@item Insert state
+Insert state is the Vi insertion mode. @key{ESC} will take you back to
+Vi state. Insert state editing can be done, including auto-indentation. By
+default, Viper disables Emacs keybindings in Insert state.
+
+@item Replace state
+Commands like @kbd{cw} invoke the Replace state. When you cross the
+boundary of a replacement region (usually designated via a @samp{$} sign),
+it will automatically change to Insert state. You do not have to worry
+about it. The key bindings remain practically the same as in Insert
+state. If you type @key{ESC}, Viper will switch to Vi command mode, terminating the
+replacement state.@refill
+@end table
+
+@cindex mode line
+
+The modes are indicated on the @dfn{mode line} as <E>, <I>, <V>, and <R>,
+so that the multiple modes do not confuse you. Most of your editing can be
+done in Vi and Insert states. Viper will try to make all new buffers be in Vi
+state, but sometimes they may come up in Emacs state. @kbd{C-z}
+will take you to Vi state in such a case. In some major modes, like Dired,
+Info, Gnus, etc., you should not switch to Vi state (and Viper will not
+attempt to do so) because these modes are not intended for text editing and
+many of the Vi keys have special meaning there. If you plan to read news,
+browse directories, read mail, etc., from Emacs (which you should start
+doing soon!), you should learn about the meaning of the various keys in
+those special modes (typing @kbd{C-h m} in a buffer provides
+help with key bindings for the major mode of that buffer).
+
+If you switch to Vi in Dired or similar modes---no harm is done. It is just
+that the special keybindings provided by those modes will be temporarily
+overshadowed by Viper's bindings. Switching back to Viper's Emacs state
+will revive the environment provided by the current major mode.
+
+States in Viper are orthogonal to Emacs major modes, such as C mode or Dired
+mode. You can turn Viper on and off for any Emacs state. When Viper is turned
+on, Vi state can be used to move around. In Insert state, the bindings for
+these modes can be accessed. For beginners (users at Viper levels 1 and 2),
+these bindings are suppressed in Insert state, so that new users are not
+confused by the Emacs states. Note that unless you allow Emacs bindings in
+Insert state, you cannot do many interesting things, like language
+sensitive editing. For the novice user (at Viper level 1), all major mode
+bindings are turned off in Vi state as well. This includes the bindings for
+key sequences that start with @kbd{C-c}, which practically means that all
+major mode bindings are supported. @xref{Customization}, to find out how
+to allow Emacs keys in Insert state.
+
+@menu
+* Emacs State:: This is the state you should learn more about when
+ you get up to speed with Viper.
+* Vi State:: Vi commands are executed in this state.
+* Insert State:: You can enter text, and also can do sophisticated
+ editing if you know enough Emacs commands.
+* Replace State:: Like Insert mode, but it is invoked via the
+ replacement commands, such as cw, C, R, etc.
+@end menu
+
+@node Emacs State, Vi State, States in Viper, States in Viper
+@subsection Emacs State
+
+@kindex @kbd{C-z}
+@cindex Emacs state
+
+
+You will be in this mode only by accident (hopefully). This is the state
+Emacs is normally in (imagine!!). Now leave it as soon as possible by
+typing @kbd{C-z}. Then you will be in Vi state (sigh of relief) :-).
+
+Emacs state is actually a Viperism to denote all the major and minor modes
+(@pxref{Emacs Preliminaries}) other than Viper that Emacs can be in. Emacs
+can have several modes, such as C mode for editing C programs, LaTeX mode
+for editing LaTeX documents, Dired for directory editing, etc. These are
+major modes, each with a different set of key-bindings. Viper states are
+orthogonal to these Emacs major modes. The presence of these language
+sensitive and other modes is a major win over Vi. @xref{Improvements over
+Vi}, for more.@refill
+
+The bindings for these modes can be made available in the Viper Insert state
+as well as in Emacs state. Unless you specify your user level as 1 (a
+novice), all major mode key sequences that start with @kbd{C-x} and
+@kbd{C-c} are also available in Vi state. This is important because major
+modes designed for editing files, such as cc-mode or latex-mode, use key
+sequences that begin with @kbd{C-x} and @kbd{C-c}.
+
+There is also a key that lets you temporarily escape to Vi command state
+from Emacs or Insert states: typing @kbd{C-c \} will let you execute a
+single Vi command while staying in Viper's Emacs or Insert state.
+In Insert state, the same can also be achieved by typing @kbd{C-z}.
+
+
+@node Vi State, Insert State, Emacs State, States in Viper
+@subsection Vi State
+
+@cindex Vi state
+
+This is the Vi command mode. When Viper is in Vi state, you will see the sign
+<V> in the mode line. Most keys will work as in Vi. The notable
+exceptions are:
+
+@table @kbd
+@item C-x
+@kindex @kbd{C-x}
+@kbd{C-x} is used to invoke Emacs commands, mainly those that do window
+management. @kbd{C-x 2} will split a window, @kbd{C-x 0} will close a
+window. @kbd{C-x 1} will close all other windows. @kbd{C-xb} is used to
+switch buffers in a window, and @kbd{C-xo} to move through windows.
+These are about the only necessary keystrokes.
+For the rest, see the GNU Emacs Manual.
+
+@item C-c
+@kindex @kbd{C-c}
+For user levels 2 and higher, this key serves as a prefix key for the key
+sequences used by various major modes. For users at Viper level 1, @kbd{C-c}
+simply beeps.
+
+@item C-g and C-]
+@kindex @kbd{C-g}
+@kindex @kbd{C-]}
+
+These are the Emacs @samp{quit} keys.
+There will be cases where you will have to
+use @kbd{C-g} to quit. Similarly, @kbd{C-]} is used to exit
+@samp{Recursive Edits} in Emacs for which there is no comparable Vi
+functionality and no key-binding. Recursive edits are indicated by
+@samp{[]} brackets framing the modes on the mode line.
+@xref{Recursive Edit,Recursive
+Edit,Recursive Edit,emacs,The GNU Emacs Manual}.
+At user level 1, @kbd{C-g} is bound to @code{viper-info-on-file}
+function instead.
+@refill
+@item C-\
+@kindex @kbd{C-\}
+@cindex Meta key
+
+Viper uses @key{ESC} as a switch between Insert and Vi states. Emacs uses
+@key{ESC} for Meta. The Meta key is very important in Emacs since many
+finctions are accessible only via that key as @kbd{M-x function-name}.
+Therefore, we need to simulate it somehow. In Viper's Vi, Insert, and
+Replace states, the meta key is set to be @kbd{C-\}. Thus, to get
+@kbd{M-x}, you should type @kbd{C-\ x} (if the keyboard has no Meta key).
+This works both in the Vi command state and in the Insert and Replace
+states. In Vi command state, you can also use @kbd{\ @key{ESC}} as the
+meta key.
+
+Note: Emacs binds @kbd{C-\} to a function that offers to change the
+keyboard input method in the multilingual environment. Viper overrides this
+binding. However, it is still possible to switch the input method by typing
+@kbd{\ C-\} in the Vi command state and @kbd{C-z \ C-\} in the Insert state.
+Or you can use the MULE menu in the menubar.
+@end table
+@noindent
+Other differences are mostly improvements. The ones you should know
+about are:
+
+@table @samp
+@item Undo
+@kindex @kbd{u}
+@kbd{u} will undo. Undo can be repeated by the @kbd{.} key. Undo itself
+can be undone. Another @kbd{u} will change the direction. The presence
+of repeatable undo means that @kbd{U}, undoing lines, is not very
+important. Therefore, @kbd{U} also calls @code{viper-undo}.
+@cindex multiple undo
+@cindex undo
+
+
+@item Counts
+Most commands, @kbd{~}, @kbd{[[}, @kbd{p}, @kbd{/}, @dots{}, etc., take counts.
+
+@comment ]] Just to balance parens
+@item Regexps
+Viper uses Emacs Regular Expressions for searches. These are a superset of
+Vi regular
+expressions, excepting the change-of-case escapes @samp{\u}, @samp{\L},
+@dots{}, etc. @xref{Regular Expressions,,Regular Expressions,emacs,The
+GNU Emacs Manual}, for details.
+Files specified to @kbd{:e} use @code{csh} regular expressions
+(globbing, wildcards, what have you).
+However, the function @code{viper-toggle-search-style}, bound to @kbd{C-c /},
+lets the user switch from search with regular expressions to plain vanilla
+search and vice versa. It also lets one switch from case-sensitive search
+to case-insensitive and back.
+@xref{Viper Specials}, for more details.
+@cindex regular expressions
+@cindex vanilla search
+@cindex case-sensitive search
+@cindex case-insensitive search
+@kindex @kbd{C-c /}
+
+@item Ex commands
+@cindex Ex commands
+The current working directory of a buffer is automatically inserted in the
+minibuffer if you type @kbd{:e} then space. Absolute filenames are
+required less often in Viper. For path names, Emacs uses a convention that
+is slightly different from that of Unix. It is designed to minimize the
+need for deleting path names that Emacs provides in its prompts. (This is
+usually convenient, but occasionally the prompt may suggest a wrong path
+name for you.) If you see a prompt @kbd{/usr/foo/} and you wish to edit the
+file @kbd{~/.viper}, you don't have to erase the prompt. Instead, simply
+continue typing what you need. Emacs will interpret @kbd{/usr/foo/~/.viper}
+correctly. Similarly, if the prompt is @kbd{~/foo/} and you need to get to
+@kbd{/bar/file}, keep typing. Emacs interprets @kbd{~/foo//bar/} as
+@kbd{/bar/file}, since when it sees @samp{//}, it understands that
+@kbd{~/foo/} is to be discarded.
+
+The command @kbd{:cd} will change the default directory for the
+current buffer. The command @kbd{:e} will interpret the
+filename argument in @code{csh}. @xref{Customization}, if you
+want to change the default shell.
+The command @kbd{:next} takes counts from
+@kbd{:args}, so that @kbd{:rew} is obsolete. Also, @kbd{:args} will show only
+the invisible files (i.e., those that are not currently seen in Emacs
+windows).
+
+When applicable, Ex commands support file completion and history. This
+means that by typing a partial file name and then @key{TAB}, Emacs will try
+to complete the name or it will offer a menu of possible completions.
+This works similarly to Tcsh and extends the behavior of Csh. While Emacs
+is waiting for a file name, you can type @kbd{M-p} to get the previous file
+name you typed. Repeatedly typing @kbd{M-p} and @kbd{M-n} will let you
+browse through the file history.
+
+Like file names, partially typed Ex commands can be completed by typing
+@key{TAB}, and Viper keeps the history of Ex commands. After typing
+@kbd{:}, you can browse through the previously entered Ex commands by
+typing @kbd{M-p} and @kbd{M-n}. Viper tries to rationalize when it puts Ex
+commands on the history list. For instance, if you typed @kbd{:w!@: foo},
+only @kbd{:w!} will be placed on the history list. This is because the
+last history element is the default that can be invoked simply by typing
+@kbd{: @key{RET}}. If @kbd{:w!@: foo} were placed on the list, it would be all to
+easy to override valuable data in another file. Reconstructing the full
+command, @kbd{:w!@: foo}, from the history is still not that hard, since Viper
+has a separate history for file names. By typing @kbd{: M-p}, you will get
+@kbd{:w!} in the Minibuffer. Then, repeated @kbd{M-p} will get you through
+the file history, inserting one file name after another.
+
+In contrast to @kbd{:w!@: foo}, if the command were @kbd{:r foo}, the entire
+command will appear in the history list. This is because having @kbd{:r}
+alone as a default is meaningless, since this command requires a file
+argument.
+@refill
+@end table
+@noindent
+As Vi, Viper's destructive commands can be re-executed by typing `@kbd{.}'.
+However, in addition, Viper keeps track of the history of such commands. This
+history can be perused by typing @kbd{C-c M-p} and @kbd{C-c M-n}.
+Having found the appropriate command, it can be then executed by typing
+`@kbd{.}'.
+@xref{Improvements over Vi}, for more information.
+
+@node Insert State, Replace State, Vi State, States in Viper
+@subsection Insert State
+
+@cindex Insert state
+
+To avoid confusing the beginner (at Viper level 1 and 2), Viper makes only the
+standard Vi keys available in Insert state. The implication is that
+Emacs major modes cannot be used Insert state.
+It is strongly recommended that as soon as you are comfortable, make the
+Emacs state bindings visible (by changing your user level to 3 or higher).
+@xref{Customization},
+to see how to do this.@refill
+
+Once this is done, it is possible to do quite a bit of editing in
+Insert state. For instance, Emacs has a @dfn{yank} command, @kbd{C-y},
+which is similar to Vi's @kbd{p}. However, unlike @kbd{p}, @kbd{C-y} can be
+used in Insert state of Viper. Emacs also has a kill ring where it keeps
+pieces of text you deleted while editing buffers. The command @kbd{M-y} is
+used to delete the text previously put back by Emacs' @kbd{C-y} or by Vi's
+@kbd{p} command and reinsert text that was placed on the kill-ring earlier.
+
+This works both in Vi and Insert states.
+In Vi state, @kbd{M-y} is a much better alternative to the usual Vi's way
+of recovering the 10 previously deleted chunks of text. In Insert state,
+you can
+use this as follows. Suppose you deleted a piece of text and now you need
+to re-insert it while editing in Insert mode. The key @kbd{C-y} will put
+back the most recently deleted chunk. If this is not what you want, type
+@kbd{M-y} repeatedly and, hopefully, you will find the chunk you want.
+
+Finally, in Insert and Replace states, Viper provides the history of
+pieces of text inserted in previous insert or replace commands. These
+strings of text can be recovered by repeatedly typing @kbd{C-c M-p} or
+@kbd{C-c M-n} while in Insert or Replace state. (This feature is disabled
+in the minibuffer: the above keys are usually bound to other histories,
+which are more appropriate in the minibuffer.)
+
+
+@cindex Meta key
+
+You can call Meta functions from Insert state. As in Vi state, the Meta key
+is @kbd{C-\}. Thus @kbd{M-x} is typed as @kbd{C-\ x}.
+
+Other Emacs commands that are useful in Insert state are @kbd{C-e}
+and @kbd{C-a}, which move the cursor to the end and the beginning of the
+current line, respectively. You can also use @kbd{M-f} and @kbd{M-b},
+which move the cursor forward (or backward) one word.
+If your display has a Meta key, these functions are invoked by holding the
+Meta key and then typing @kbd{f} and @kbd{b}, respectively. On displays
+without the Meta key, these functions are invoked by typing
+@kbd{C-\ f} and @kbd{C-\ b} (@kbd{C-\} simulates the Meta key in Insert
+state, as explained above).
+
+The key @kbd{C-z} is sometimes also useful in Insert state: it allows you
+to execute a single command in Vi state without leaving the Insert state!
+For instance, @kbd{C-z d2w} will delete the next two words without leaving
+the Insert state.
+
+When Viper is in Insert state, you will see <I> in the mode line.
+
+@node Replace State,, Insert State, States in Viper
+@subsection Replace State
+
+@cindex Replace state
+
+This state is entered through Vi replacement commands, such as @kbd{C},
+@kbd{cw}, etc., or by typing @kbd{R}. In Replace state, Viper puts <R> in
+the mode line to let you know which state is in effect. If Replace state is
+entered through @kbd{R}, Viper stays in that state until the user hits
+@key{ESC}. If this state is entered via the other replacement commands,
+then Replace state is in effect until you hit @key{ESC} or until you cross
+the rightmost boundary of the replacement region. In the latter case, Viper
+changes its state from Replace to Insert (which you will notice by the
+change in the mode line).
+
+Since Viper runs under Emacs, it is possible to switch between buffers
+while in Replace state. You can also move the cursor using the arrow keys
+(even on dumb terminals!)@: and the mouse. Because of this freedom (which is
+unattainable in regular Vi), it is possible to take the cursor outside the
+replacement region. (This may be necessary for several reasons, including
+the need to enable text selection and region-setting with the mouse.)
+
+The issue then arises as to what to do when the user
+hits the @key{ESC} key. In Vi, this would cause the text between cursor and
+the end of the replacement region to be deleted. But what if, as is
+possible in Viper, the cursor is not inside the replacement region?
+
+To solve the problem, Viper keeps track of the last cursor position while it
+was still inside the replacement region. So, in the above situation, Viper
+would delete text between this position and the end of the replacement
+region.
+
+@node The Minibuffer,Multiple Files in Viper, States in Viper, Overview
+@section The Minibuffer
+
+@cindex Minibuffer
+
+The Minibuffer is where commands are entered in. Editing can be done
+by commands from Insert state, namely:
+
+@table @kbd
+@item C-h
+Backspace
+@item C-w
+Delete Word
+@item C-u
+Erase line
+@item C-v
+Quote the following character
+@item @key{RET}
+Execute command
+@item C-g and C-]
+Emacs quit and abort keys. These may be necessary. @xref{Vi State}, for an
+explanation.
+@item M-p and M-n
+These keys are bound to functions that peruse minibuffer history. The
+precise history to be perused depends on the context. It may be the history
+of search strings, Ex commands, file names, etc.
+@end table
+
+Most of the Emacs keys are functional in the Minibuffer. While in the
+Minibuffer, Viper tries to make editing resemble Vi's behavior when the
+latter is waiting for the user to type an Ex command. In particular, you
+can use the regular Vi commands to edit the Minibuffer. You can switch
+between the Vi state and Insert state at will, and even use the replace mode.
+Initially, the Minibuffer comes up in Insert state.
+
+Some users prefer plain Emacs bindings in the Minibuffer. To this end, set
+@code{viper-vi-style-in-minibuffer} to @code{nil} in @file{.viper}.
+@xref{Customization}, to learn how to do this.
+
+When the Minibuffer changes Viper states, you will notice that the appearance
+of the text there changes as well. This is useful because the Minibuffer
+has no mode line to tell which Vi state it is in.
+The appearance of the text in the Minibuffer can be changed.
+@xref{Viper Specials}, for more details.
+
+@node Multiple Files in Viper,Unimplemented Features,The Minibuffer,Overview
+@section Multiple Files in Viper
+
+@cindex multiple files
+@cindex managing multiple files
+
+Viper can edit multiple files. This means, for example that you never need
+to suffer through @code{No write since last change} errors.
+Some Viper elements are common over all the files.
+
+@table @samp
+@item Textmarkers
+@cindex markers
+@cindex textmarkers
+Textmarkers remember @emph{files and positions}.
+If you set marker @samp{a} in
+file @file{foo}, start editing file @file{bar} and type @kbd{'a}, then
+@emph{YOU WILL SWITCH TO FILE @file{foo}}. You can see the contents of a
+textmarker using the Viper command @kbd{[<a-z>} where <a-z> are the
+textmarkers, e.g., @kbd{[a} to view marker @samp{a} .@refill
+@item Repeated Commands
+Command repetitions are common over files. Typing @kbd{!!} will repeat the
+last @kbd{!} command whichever file it was issued from.
+Typing @kbd{.} will repeat the last command from any file, and
+searches will repeat the last search. Ex commands can be repeated by typing
+@kbd{: @key{RET}}.@refill
+Note: in some rare cases, that @kbd{: @key{RET}} may do something dangerous.
+However, usually its effect can be undone by typing @kbd{u}.
+@item Registers
+@cindex registers
+Registers are common to files. Also, text yanked with @kbd{y} can be
+put back (@kbd{p}) into any file. The Viper command @kbd{]<a-z>}, where <a-z> are
+the registers, can be used to look at the contents of a register, e.g.,
+type @kbd{]a} to view register @samp{a}.
+
+There is one difference in text deletion that you should be
+aware of. This difference comes from Emacs and was adopted in Viper
+because we find it very useful. In Vi, if you delete a line, say, and then
+another line, these two deletions are separated and are put back
+separately if you use the @samp{p} command. In Emacs (and Viper), successive
+series of deletions that are @emph{not interrupted} by other commands are
+lumped together, so the deleted text gets accumulated and can be put back
+as one chunk. If you want to break a sequence of deletions so that the
+newly deleted text could be put back separately from the previously deleted
+text, you should perform a non-deleting action, e.g., move the cursor one
+character in any direction.
+@item Absolute Filenames
+@cindex absolute paths
+The current directory name for a file is automatically prepended to the
+file name in any
+@kbd{:e}, @kbd{:r}, @kbd{:w}, etc., command (in Emacs, each buffer has a
+current directory).
+This directory is inserted in the Minibuffer once you type space after
+@kbd{:e, r}, etc. Viper also supports completion of file names and Ex
+commands (@key{TAB}), and it keeps track of
+command and file history (@kbd{M-p}, @kbd{M-n}).
+Absolute filenames are required less
+often in Viper.
+
+You should be aware that Emacs interprets @kbd{/foo/bar//bla} as
+@kbd{/bla} and @kbd{/foo/~/bar} as @kbd{~/bar}. This is designed to
+minimize the need for erasing path names that Emacs suggests in its
+prompts, if a suggested path name is not what you wanted.
+
+The command @kbd{:cd} will change the default directory for the
+current Emacs buffer. The Ex command @kbd{:e} will interpret the
+filename argument in @samp{csh}, by default. @xref{Customization}, if you
+want to change this.
+@end table
+
+@noindent
+Currently undisplayed files can be listed using the @kbd{:ar} command. The
+command @kbd{:n} can be given counts from the @kbd{:ar} list to switch to
+other files.
+
+@node Unimplemented Features,,Multiple Files in Viper,Overview
+@section Unimplemented Features
+
+Unimplemented features include:
+
+@itemize @bullet
+@item
+@kbd{:ab} and @kbd{:una} are not implemented.
+Both @kbd{:map} and @kbd{:ab} are considered obsolete, since Emacs has much
+more powerful facilities for defining keyboard macros and abbreviations.
+@item
+@kbd{:set option?} is not implemented. The current
+@kbd{:set} can also be used to set Emacs variables.
+@item
+@kbd{:se list} requires modification of the display code for Emacs, so
+it is not implemented.
+A useful alternative is @code{cat -t -e file}. Unfortunately, it cannot
+be used directly inside Emacs, since Emacs will obdurately change @samp{^I}
+back to normal tabs.@refill
+@end itemize
+
+@comment node-name, next, previous, up
+@node Improvements over Vi, Customization, Overview, Top
+@chapter Improvements over Vi
+
+Some common problems with Vi and Ex have been solved in Viper. This
+includes better implementation of existing commands, new commands, and
+the facilities provided by Emacs.
+
+@menu
+* Basics:: Basic Viper differences, Multi-file effects.
+* Undo and Backups:: Multiple undo, auto-save, backups and changes
+* History:: History for Ex and Vi commands.
+* Macros and Registers:: Keyboard Macros (extended ".")@: @@reg execution.
+* Completion:: Filename and Command Completion for Ex.
+* Improved Search:: Incremental Search and Buffer Content Search.
+* Abbreviation Facilities:: Normal Abbrevs, Templates, and Dynamic Abbrevs.
+* Movement and Markers:: Screen Editor movements, viewing textmarkers.
+* New Commands:: Commands that do not exist in Vi.
+* Useful Packages:: A Sampling of some Emacs packages, and things
+ you should know about.
+@end menu
+
+@node Basics, Undo and Backups, Improvements over Vi, Improvements over Vi
+@section Basics
+
+The Vi command set is based on the idea of combining motion commands
+with other commands. The motion command is used as a text region
+specifier for other commands.
+We classify motion commands into @dfn{point commands} and
+@dfn{line commands}.@refill
+
+@cindex point commands
+
+The point commands are:
+
+@quotation
+@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B},
+@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f},
+@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^}
+@end quotation
+
+@cindex line commands
+
+The line commands are:
+
+@quotation
+@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{},
+@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]}
+@end quotation
+
+@cindex region
+@cindex region specification
+@cindex expanding (region)
+@cindex describing regions
+@cindex movement commands
+
+@noindent
+If a point command is given as an argument to a modifying command, the
+region determined by the point command will be affected by the modifying
+command. On the other hand, if a line command is given as an argument to a
+modifying command, the region determined by the line command will be
+enlarged so that it will become the smallest region properly containing the
+region and consisting of whole lines (we call this process @dfn{expanding
+the region}), and then the enlarged region will be affected by the modifying
+command.
+Text Deletion Commands (@pxref{Deleting Text}), Change commands
+(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands})
+use these commands to describe a region of text to operate on.
+Thus, type @kbd{dw} to delete a word, @kbd{>@}} to shift a paragraph, or
+@kbd{!'afmt} to format a region from @samp{point} to textmarker
+@samp{a}.
+
+@cindex r and R region specifiers
+
+Viper adds the region specifiers @samp{r} and @samp{R}. Emacs has a
+special marker called @dfn{mark}. The text-area between the current cursor
+position @dfn{point} and the @dfn{mark} is called the @dfn{region}.
+@samp{r} specifies the raw region and @samp{R} is the expanded region
+(i.e., the minimal contiguous chunk of full lines that contains the raw
+region).
+@kbd{dr} will now delete the region, @kbd{>r} will shift it, etc.
+@kbd{r,R} are not motion commands, however. The special mark is set by
+@kbd{m.} and other commands. @xref{Marking}, for more info.
+
+Viper also adds counts to most commands for which it would make sense.
+
+In the Overview chapter, some Multiple File issues were discussed
+(@pxref{Multiple Files in Viper}). In addition to the files, Emacs has
+buffers. These can be seen in the @kbd{:args} list and switched using
+@kbd{:next} if you type @kbd{:set ex-cycle-through-non-files t}, or
+specify @code{(setq ex-cycle-through-non-files t)} in your @file{.viper}
+file. @xref{Customization}, for details.
+
+@node Undo and Backups, History, Basics, Improvements over Vi
+@section Undo and Backups
+
+@cindex undo
+
+Viper provides multiple undo. The number of undo's and the size is limited
+by the machine. The Viper command @kbd{u} does an undo. Undo can be
+repeated by typing @kbd{.} (a period). Another @kbd{u} will undo the undo,
+and further
+@kbd{.} will repeat it. Typing @kbd{u} does the first undo, and changes the
+direction.
+
+@cindex backup files
+@cindex auto save
+
+Since the undo size is limited, Viper can create backup files and
+auto-save files. It will normally do this automatically. It is possible
+to have numbered backups, etc. For details, @pxref{Backup,,Backup and
+Auto-Save,emacs,The GNU Emacs Manual} @refill
+
+@comment [ balance parens
+@cindex viewing registers and markers
+@cindex registers
+@cindex markers
+@cindex textmarkers
+
+The results of the 9 previous changes are available in the 9 numeric
+registers, as in Vi. The extra goody is the ability to @emph{view} these
+registers, in addition to being able to access them through @kbd{p} and
+@kbd{M-y} (@xref{Insert State}, for details.)
+The Viper command @kbd{] register} will display the contents of any
+register, numeric or alphabetical. The related command @kbd{[ textmarker}
+will show the text around the textmarker. @samp{register} and @samp{textmarker}
+can be any letters from a through z.
+@comment ] balance parens
+
+@node History, Macros and Registers, Undo and Backups,Improvements over Vi
+@section History
+
+@cindex history
+@cindex Minibuffer
+
+History is provided for Ex commands, Vi searches, file names, pieces of
+text inserted in earlier commands that use Insert or Replace state, and for
+destructive commands in Vi state. These are
+useful for fixing those small typos that screw up searches and @kbd{:s},
+and for eliminating routine associated with repeated typing of file names
+or pieces of text that need to be inserted frequently.
+At the @kbd{:} or @kbd{/} prompts in the Minibuffer, you can do the following:
+
+@table @kbd
+@item M-p and M-n
+To move to previous and next history items. This causes the history
+items to appear on the command line, where you can edit them, or
+simply type Return to execute.
+@item M-r and M-s
+To search backward and forward through the history.
+@item @key{RET}
+Type @key{RET} to accept a default (which is displayed in the prompt).
+@end table
+
+The history of insertions can be perused by
+typing @kbd{C-c M-p} and @kbd{C-c M-n} while in Insert or Replace state.
+The history of destructive Vi commands can be perused via the same keys
+when Viper is in Vi state. @xref{Viper Specials}, for details.
+
+All Ex commands have a file history. For instance, typing @kbd{:e}, space
+and then @kbd{M-p} will bring up the name of the previously typed file
+name. Repeatedly typing @kbd{M-p}, @kbd{M-n}, etc., will let you browse
+through the file history.
+
+Similarly, commands that have to do with switching buffers
+have a buffer history, and commands that expect strings or regular
+expressions keep a history on those items.
+
+@node Macros and Registers,Completion,History,Improvements over Vi
+@section Macros and Registers
+
+@cindex keyboard macros
+@cindex macros
+@cindex registers
+@cindex register execution
+
+Viper facilitates the use of Emacs-style keyboard macros. @kbd{@@#} will
+start a macro definition. As you type, the commands will be executed, and
+remembered (This is called ``learn mode'' in some editors.)
+@kbd{@@register} will complete the macro, putting it into @samp{register},
+where @samp{register} is any character from @samp{a} through @samp{z}. Then
+you can execute this macro using @kbd{@@register}. It is, of course,
+possible to yank some text into a register and execute it using
+@kbd{@@register}. Typing @kbd{@@@@}, @kbd{@@RET}, or @kbd{@@C-j} will
+execute the last macro that was executed using @kbd{@@register}.@refill
+
+Viper will automatically lowercase the register, so that pressing the
+@kbd{SHIFT} key for @kbd{@@} will not create problems. This is for
+@kbd{@@} macros and @kbd{"p} @emph{only}. In the case of @kbd{y},
+@kbd{"Ayy} will append to @emph{register a}. For @kbd{[,],',`}, it
+is an error to use a Uppercase register name.
+
+@comment [ balance parens
+@cindex viewing registers and markers
+
+The contents of a register can be seen by @kbd{]register}. (@kbd{[textmarker}
+will show the contents of a textmarker).
+@comment ] balance parens
+
+@cindex last keyboard macro
+
+The last keyboard macro can also be executed using
+@kbd{*}, and it can be yanked into a register using @kbd{@@!register}.
+This is useful for Emacs style keyboard macros defined using @kbd{C-x(}
+and @kbd{C-x)}. Emacs keyboard macros have more capabilities.
+@xref{Keyboard Macros,,Keyboard Macros,emacs, The GNU Emacs Manual}, for
+details.@refill
+
+Keyboard Macros allow an interesting form of Query-Replace:
+@kbd{/pattern} or @kbd{n} to go to the next pattern (the query), followed by a
+Keyboard Macro execution @kbd{@@@@} (the replace).
+
+Viper also provides Vi-style macros. @xref{Vi Macros}, for details.
+
+
+@node Completion, Improved Search, Macros and Registers, Improvements over Vi
+@section Completion
+
+@cindex completion
+
+Completion is done when you type @key{TAB}. The Emacs completer does not
+grok wildcards in filenames. Once you type a wildcard, the completer will
+no longer work for that path. Remember that Emacs interprets a file name
+of the form @kbd{/foo//bar} as @kbd{/bar} and @kbd{/foo/~/bar} as
+@kbd{~/bar}.
+
+@node Improved Search, Abbreviation Facilities, Completion, Improvements over Vi
+@section Improved Search
+
+@cindex buffer search
+@cindex word search
+
+Viper provides buffer search, the ability to search the buffer for a region
+under the cursor. You have to turn this on in @file{.viper} either by calling
+
+@example
+(viper-buffer-search-enable)
+@end example
+
+@noindent
+or by setting @code{viper-buffer-search-char} to, say, @kbd{f3}:
+@example
+(setq viper-buffer-search-char [f3])
+@end example
+
+@noindent
+If the user calls @code{viper-buffer-search-enable} explicitly (the first
+method), then @code{viper-buffer-search-char} will be set to @kbd{g}.
+Regardless of how this feature is enabled, the key
+@code{viper-buffer-search-char} will take movement commands, like
+@kbd{w,/,e}, to find a region and then search for the contents of that
+region. This command is very useful for searching for variable names, etc.,
+in a program. The search can be repeated by @kbd{n} or reversed by @kbd{N}.
+
+@cindex incremental search
+
+Emacs provides incremental search. As you type the string in, the
+cursor will move to the next match. You can snarf words from the buffer
+as you go along. Incremental Search is normally bound to @kbd{C-s} and
+@kbd{C-r}. @xref{Customization}, to find out how to change the bindings
+of @kbd{C-r or C-s}.
+For details, @pxref{Incremental Search,,Incremental
+Search,emacs,The GNU Emacs Manual} @refill
+
+@cindex query replace
+
+Viper also provides a query replace function that prompts through the
+Minibuffer. It is invoked by the @kbd{Q} key in Vi state.
+
+@cindex mouse search
+
+On a window display, Viper supports mouse search, i.e., you can search for a
+word by clicking on it. @xref{Viper Specials}, for details.
+
+Finally, on a window display, Viper highlights search patterns as it finds
+them. This is done through what is known as @emph{faces} in Emacs. The
+variable that controls how search patterns are highlighted is
+@code{viper-search-face}. If you don't want any highlighting at all, put
+@example
+(copy-face 'default 'viper-search-face)
+@end example
+@vindex @code{viper-search-face}
+@noindent
+in @file{~/.viper}. If you want to change how patterns are highlighted, you
+will have to change @code{viper-search-face} to your liking. The easiest
+way to do this is to use Emacs customization widget, which is accessible
+from the menubar. Viper customization group is located under the
+@emph{Emulations} customization group, which in turn is under the
+@emph{Editing} group. All Viper faces are grouped together under Viper's
+@emph{Highlighting} group.
+
+Try it: it is really simple!
+
+@node Abbreviation Facilities,Movement and Markers,Improved Search,Improvements over Vi
+@section Abbreviation Facilities
+
+@cindex abbrevs
+
+It is possible in Emacs to define abbrevs based on the contents of the
+buffer.
+Sophisticated templates can be defined using the Emacs abbreviation
+facilities. @xref{Abbrevs,,Abbreviations,emacs,The GNU Emacs Manual}, for
+details.
+
+@cindex dynamic abbrevs
+
+Emacs also provides Dynamic Abbreviations. Given a partial word, Emacs
+will search the buffer to find an extension for this word. For instance,
+one can type @samp{Abbreviations} by typing @samp{A}, followed by a keystroke
+that completed the @samp{A} to @samp{Abbreviations}. Repeated typing
+will search further back in the buffer, so that one could get
+@samp{Abbrevs} by repeating the
+keystroke, which appears earlier in the text. Emacs binds this to
+@kbd{@key{ESC} /}, so you will have to find a key and bind the function
+@code{dabbrev-expand} to that key.
+Facilities like this make Vi's @kbd{:ab} command obsolete.
+
+@node Movement and Markers, New Commands, Abbreviation Facilities, Improvements over Vi
+@section Movement and Markers
+
+@cindex Ex style motion
+@cindex line editor motion
+
+Viper can be set free from the line--limited movements in Vi, such as @kbd{l}
+refusing to move beyond the line, @key{ESC} moving one character back,
+etc. These derive from Ex, which is a line editor. If your @file{.viper}
+contains
+
+@example
+@code{(setq viper-ex-style-motion nil)}
+@end example
+
+@noindent
+the motion will be a true screen editor motion. One thing you must then
+watch out for is that it is possible to be on the end-of-line character.
+The keys @kbd{x} and @kbd{%} will still work correctly, i.e., as if they
+were on the last character.
+
+@vindex @code{viper-syntax-preference}
+@cindex syntax table
+
+The word-movement commands @kbd{w}, @kbd{e}, etc., and the associated
+deletion/yanking commands, @kbd{dw}, @kbd{yw}, etc., can be made to
+understand Emacs syntax tables. If the variable
+@code{viper-syntax-preference} is set to @code{strict-vi} then
+the meaning of @emph{word} is the same as in
+Vi. However, if the value is @code{reformed-vi} (the default) then the
+alphanumeric symbols will be those specified by the current Emacs syntax
+table (which may be different for different major modes) plus the
+underscore symbol @kbd{_}, minus some non-word symbols, like '.;,|, etc.
+Both @code{strict-vi} and @code{reformed-vi} work close to Vi in
+traditional cases, but @code{reformed-vi} does a better job when editing
+text in non-Latin alphabets.
+
+The user can also specify the value @code{emacs}, which would
+make Viper use exactly the Emacs notion of word. In particular, the
+underscore may not be part of a word. Finally, if
+@code{viper-syntax-preference} is set to @code{extended}, Viper words would
+consist of characters that are classified as alphanumeric @emph{or} as
+parts of symbols. This is convenient for writing programs and in many other
+situations.
+
+@code{viper-syntax-preference} is a local variable, so it can have different
+values for different major modes. For instance, in programming modes it can
+have the value @code{extended}. In text modes where words contain special
+characters, such as European (non-English) letters, Cyrillic letters, etc.,
+the value can be @code{reformed-vi} or @code{emacs}.
+
+Changes to @code{viper-syntax-preference} should be done in the hooks to
+various major modes by executing @code{viper-set-syntax-preference} as in
+the following example:
+
+@example
+(viper-set-syntax-preference nil "emacs")
+@end example
+
+@findex @code{viper-set-syntax-preference}
+
+The above discussion of the meaning of Viper's words concerns only Viper's
+movement commands. In regular expressions, words remain the same as in
+Emacs. That is, the expressions @code{\w}, @code{\>}, @code{\<}, etc., use
+Emacs' idea of what is a word, and they don't look into the value of
+variable @code{viper-syntax-preference}. This is because Viper doesn't change
+syntax tables in fear of upsetting the various major modes that set these
+tables.
+
+@cindex textmarkers
+
+Textmarkers in Viper remember the file and the position, so that you can
+switch files by simply doing @kbd{'a}. If you set up a regimen for using
+Textmarkers, this is very useful. Contents of textmarkers can be viewed
+by @kbd{[marker}. (Contents of registers can be viewed by @kbd{]register}).
+
+@node New Commands, Useful Packages, Movement and Markers, Improvements over Vi
+@section New Commands
+
+These commands have no Vi analogs.
+
+@table @kbd
+@item C-x, C-c
+@kindex @kbd{C-x}
+@kindex @kbd{C-c}
+These two keys invoke many important Emacs functions. For example, if you
+hit @kbd{C-x} followed by @kbd{2}, then the current window will be split
+into 2. Except for novice users, @kbd{C-c} is also set to execute an Emacs
+command from the current major mode. @key{ESC} will do the same, if you
+configure @key{ESC} as Meta by setting @code{viper-no-multiple-ESC} to nil
+in @file{.viper}. @xref{Customization}. @kbd{C-\} in Insert, Replace, or Vi
+states will make Emacs think @kbd{Meta} has been hit.@refill
+@item \
+@kindex @kbd{\}
+Escape to Emacs to execute a single Emacs command. For instance,
+@kbd{\ @key{ESC}} will act like a Meta key.
+@item Q
+@kindex @kbd{Q}
+@cindex query replace
+@kbd{Q} is for query replace. By default,
+each string to be replaced is treated as a regular expression. You can use
+@code{(setq viper-re-query-replace nil)} in your @file{.emacs} file to
+turn this off. (For normal searches, @kbd{:se nomagic} will work. Note
+that @kbd{:se nomagic} turns Regexps off completely, unlike Vi).
+@item v
+@itemx V
+@itemx C-v
+@kindex @kbd{v}
+@kindex @kbd{V}
+@kindex @kbd{C-v}
+These keys are used to visit files. @kbd{v} will switch to a buffer
+visiting file whose name can be entered in the Minibuffer. @kbd{V} is
+similar, but will use a window different from the current window.
+@kbd{C-v} is like @kbd{V}, except that a new frame (X window) will be used
+instead of a new Emacs window.
+@item #
+@kindex @kbd{#}
+If followed by a certain character @var{ch}, it becomes an operator whose
+argument is the region determined by the motion command that follows
+(indicated as <move>).
+Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q}, and
+@kbd{s}. For instance, @kbd{#qr} will prompt you for a string and then
+prepend this string to each line in the buffer.@refill
+@item # c
+@kindex @kbd{#c<move>}
+@cindex changing case
+Change upper-case characters in the region to lower-case
+(@code{downcase-region}).
+Emacs command @kbd{M-l} does the same for words.
+@item # C
+@kindex @kbd{#C<move>}
+Change lower-case characters in the region to upper-case. For instance,
+@kbd{# C 3 w} will capitalize 3 words from the current point
+(@code{upcase-region}).
+Emacs command @kbd{M-u} does the same for words.
+@item # g
+@kindex @kbd{#g<move>}
+Execute last keyboard macro for each line in the region
+(@code{viper-global-execute}).@refill
+@item # q
+@kindex @kbd{#q<move>}
+Insert specified string at the beginning of each line in the region
+(@code{viper-quote-region}). The default string is composed of the comment
+character(s) appropriate for the current major mode.
+@item # s
+@kindex @kbd{#s<move>}
+Check spelling of words in the region (@code{spell-region}).
+The function used for spelling is determined from the variable
+@code{viper-spell-function}.
+@vindex @code{viper-spell-function}
+@item *
+@kindex @kbd{*}
+Call last keyboard macro.
+@item m .
+Set mark at point and push old mark off the ring
+@item m<
+@item m>
+Set mark at beginning and end of buffer, respectively.
+@item m,
+Jump to mark and pop mark off the ring. @xref{Mark,,Mark,emacs,The GNU
+Emacs Manual}, for more info.
+@item ] register
+@kindex @kbd{]<a-z>}
+View contents of register
+@item [ textmarker
+@kindex @kbd{[<a-z>}
+View filename and position of textmarker
+@item @@#
+@item @@register
+@item @@!
+@kindex @kbd{@@#}
+@kindex @kbd{@@<a-z>}
+@kindex @kbd{@@!}
+@cindex keyboard macros
+@cindex register execution
+
+Begin/end keyboard macro. @@register has a different meaning when used after
+a @kbd{@@#}. @xref{Macros and Registers}, for details
+@item []
+@kindex @kbd{[]}
+Go to end of heading.
+@item g <@emph{movement command}>
+Search buffer for text delimited by movement command. The canonical
+example is @kbd{gw} to search for the word under the cursor.
+@xref{Improved Search}, for details.@refill
+@item C-g and C-]
+@kindex @kbd{C-g}
+@kindex @kbd{C-]}
+Quit and Abort Recursive edit. These may be necessary on occasion.
+@xref{Vi State}, for a reason.
+@item C-c g
+@kindex @kbd{C-c g}
+Hitting @kbd{C-c} followed by @kbd{g} will display the information on the
+current buffer. This is the same as hitting @kbd{C-g} in Vi, but, as
+explained above, @kbd{C-g} is needed for other purposes in Emacs.
+@item C-c /
+@kindex @kbd{C-c /}
+Without a prefix argument, this command toggles
+case-sensitive/case-insensitive search modes and plain vanilla/regular
+expression search. With the prefix argument 1, i.e.,
+@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2,
+toggles plain vanilla search and search using
+regular expressions. @xref{Viper Specials}, for alternative ways to invoke
+this function.
+@cindex vanilla search
+@cindex case-sensitive search
+@cindex case-insensitive search
+
+@item M-p and M-n
+@kindex @kbd{M-p}
+@kindex @kbd{M-n}
+In the Minibuffer, these commands navigate through the minibuffer
+histories, such as the history of search strings, Ex commands, etc.
+
+@item C-c M-p and C-c M-n
+@kindex @kbd{C-c M-p}
+@kindex @kbd{C-c M-n}
+@cindex Insertion history
+@cindex Insertion ring
+@cindex Command history
+@cindex Command ring
+
+In Insert or Replace state, these commands let the user
+peruse the history of insertion strings used in previous insert or replace
+commands. Try to hit @kbd{C-c M-p} or @kbd{C-c M-n} repeatedly and see what
+happens. @xref{Viper Specials}, for more.
+
+In Vi state, these commands let the user peruse the history of Vi-style
+destructive commands, such as @kbd{dw}, @kbd{J}, @kbd{a}, etc.
+By repeatedly typing @kbd{C-c M-p} or @kbd{C-c M-n} you will cycle Viper
+through the recent history of Vi commands, displaying the commands one by
+one. Once
+an appropriate command is found, it can be executed by typing `@kbd{.}'.
+
+Since typing @kbd{C-c M-p} is tedious, it is more convenient to bind an
+appropriate function to a function key on the keyboard and use that key.
+@xref{Viper Specials}, for details.
+
+@item Ex commands
+@findex @kbd{:args}
+@findex @kbd{:n}
+@findex @kbd{:pwd}
+@findex @kbd{:pre}
+The commands @kbd{:args}, @kbd{:next}, @kbd{:pre} behave
+differently. @kbd{:pwd} exists to get current directory.
+The commands @kbd{:b} and @kbd{:B} switch buffers around. @xref{File and
+Buffer Handling}, for details.
+There are also the new commands @kbd{:RelatedFile} and
+@kbd{PreviousRelatedFile} (which abbreviate to @kbd{R} and @kbd{P},
+respectively. @xref{Viper Specials}, for details.
+@findex @kbd{:RelatedFile}
+@findex @kbd{:PreviousRelatedFile}
+@end table
+
+Apart from the new commands, many old commands have been enhanced. Most
+notably, Vi style macros are much more powerful in Viper than in Vi. @xref{Vi
+Macros}, for details.
+
+@node Useful Packages, ,New Commands, Improvements over Vi
+@section Useful Packages
+
+Some Emacs packages are mentioned here as an aid to the new Viper user, to
+indicate what Viper is capable of.
+A vast number comes with the standard Emacs distribution, and many more exist
+on the net and on the archives.
+
+This manual also mentions some Emacs features a new user
+should know about. The details of these are found in the GNU Emacs
+Manual.
+
+The features first. For details, look up the Emacs Manual.
+
+@table @samp
+@item Make
+@cindex make
+@cindex compiling
+
+Makes and Compiles can be done from the editor. Error messages will be
+parsed and you can move to the error lines.
+@item Shell
+@cindex shell
+@cindex interactive shell
+You can talk to Shells from inside the editor. Your entire shell session
+can be treated as a file.
+@item Mail
+@cindex email
+@cindex mail
+Mail can be read from and sent within the editor. Several sophisticated
+packages exist.
+@item Language Sensitive Editing
+Editing modes are written for most computer languages in existence. By
+controlling indentation, they catch punctuation errors.
+@end table
+
+The packages, below, represents a drop in the sea of special-purpose
+packages that come with standard distribution of Emacs.
+
+@table @samp
+@item Transparent FTP
+@cindex transparent ftp
+@pindex ange-ftp.el
+@code{ange-ftp.el} can ftp from the editor to files on other machines
+transparent to the user.
+@item RCS Interfaces
+@cindex version maintenance
+@cindex RCS
+@pindex vc.el
+@code{vc.el} for doing RCS commands from inside the editor
+@item Directory Editor
+@cindex dired
+@pindex dired.el
+@code{dired.el} for editing contents of directories and for navigating in
+the file system.
+@item Syntactic Highlighting
+@cindex font-lock
+@pindex font-lock.el
+@code{font-lock.el} for automatic highlighting various parts of a buffer
+using different fonts and colors.
+@item Saving Emacs Configuration
+@cindex desktop
+@pindex desktop.el
+@code{desktop.el} for saving/restoring configuration on Emacs exit/startup.
+@item Spell Checker
+@cindex ispell
+@pindex ispell.el
+@code{ispell.el} for spell checking the buffer, words, regions, etc.
+@item File and Buffer Comparison
+@cindex ediff
+@pindex ediff.el
+@code{ediff.el} for finding differences between files and for applying
+patches.
+@end table
+
+@noindent
+Emacs Lisp archives exist on
+@samp{archive.cis.ohio-state.edu}
+and @samp{wuarchive.wustl.edu}@refill
+
+
+@node Customization,Commands,Improvements over Vi,Top
+@chapter Customization
+
+@cindex customization
+
+Customization can be done in 2 ways.
+
+@itemize @bullet
+@item
+@cindex initialization
+@cindex .viper
+Elisp code in a @file{.viper} file in your home directory. Viper
+loads @file{.viper} just before it does the binding for mode
+hooks. This is the recommended method.
+@item
+@cindex .emacs
+Elisp code in your @file{.emacs} file before and after the @code{(require
+'viper)} line. This method is not recommended, unless you know what you are
+doing. Only two variables, @code{viper-mode} and
+@code{viper-custom-file-name} are supposed to be customized in @file{.emacs},
+prior to loading Viper.@refill
+@end itemize
+
+@noindent
+Most of Viper's behavior can be customized via the interactive Emacs user
+interface. Choose "Customize" from the menubar, click on "Editing", then on
+"Emulations". The customization widget is self-explanatory. Once you are
+satisfied with your changes, save them into a file and then include the
+contents of that file in the Viper customization repository, @file{.viper}
+(except for @code{viper-mode} and @code{viper-custom-file-name}, which are
+supposed to go into @code{.emacs}).
+
+Some advanced customization cannot be accomplished this way, however, and
+has to be done in Emacs Lisp. For the common cases, examples are provided
+that you can use directly.
+
+@menu
+* Rudimentary Changes:: Simple constant definitions.
+* Keybindings:: Enabling Emacs Keys, Rebinding keys, etc.
+* Packages that Change Keymaps:: How to deal with such beasts.
+* Viper Specials:: Special Viper commands.
+* Vi Macros:: How to do Vi style macros.
+@end menu
+
+@node Rudimentary Changes,Keybindings,Customization,Customization
+@section Rudimentary Changes
+
+@cindex setting variables
+@cindex variables for customization
+@findex @kbd{:set}
+
+An easy way to customize Viper is to change the values of constants used in
+Viper. Here is the list of the constants used in Viper and their default
+values. The corresponding :se command is also indicated. (The symbols
+@code{t} and @code{nil} represent ``true'' and ``false'' in Lisp).
+
+Viper supports both the abbreviated Vi variable names and their full
+names. Variable completion is done on full names only. @key{TAB} and
+@key{SPC} complete
+variable names. Typing `=' will complete the name and then will prompt for
+a value, if applicable. For instance, @kbd{:se au @key{SPC}} will complete the
+command to @kbd{:set autoindent}; @kbd{:se ta @key{SPC}} will complete the command
+and prompt further like this: @kbd{:set tabstop = }.
+However, typing @kbd{:se ts @key{SPC}} will produce a ``No match'' message
+because @kbd{ts} is an abbreviation for @kbd{tabstop} and Viper supports
+completion on full names only. However, you can still hit @key{RET}
+or @kbd{=}, which will complete the command like this: @kbd{:set ts = } and
+Viper will be waiting for you to type a value for the tabstop variable.
+To get the full list of Vi variables, type @kbd{:se @key{SPC} @key{TAB}}.
+
+@table @code
+@item viper-auto-indent nil
+@itemx :se ai (:se autoindent)
+@itemx :se ai-g (:se autoindent-global)
+If @code{t}, enable auto indentation.
+by @key{RET}, @kbd{o} or @kbd{O} command.
+
+@code{viper-auto-indent} is a local variable. To change the value globally, use
+@code{setq-default}. It may be useful for certain major modes to have their
+own values of @code{viper-auto-indent}. This can be achieved by using
+@code{setq} to change the local value of this variable in the hooks to the
+appropriate major modes.
+
+@kbd{:se ai} changes the value of @code{viper-auto-indent} in the current
+buffer only; @kbd{:se ai-g} does the same globally.
+@item viper-electric-mode t
+If not @code{nil}, auto-indentation becomes electric, which means that
+@key{RET}, @kbd{O}, and @kbd{o} indent cursor according to the current
+major mode. In the future, this variable may control additional electric
+features.
+
+This is a local variable: @code{setq} changes the value of this variable
+in the current buffer only. Use @code{setq-default} to change the value in
+all buffers.
+@item viper-case-fold-search nil
+@itemx :se ic (:se ignorecase)
+If not @code{nil}, search ignores cases.
+This can also be toggled by quickly hitting @kbd{/} twice.
+@item viper-re-search nil
+@itemx :se magic
+If not @code{nil}, search will use regular expressions; if @code{nil} then
+use vanilla search.
+This behavior can also be toggled by quickly hitting @kbd{/} trice.
+@item buffer-read-only
+@itemx :se ro (:se readonly)
+Set current buffer to read only. To change globally put
+@code{(setq-default buffer-read-only t)} in your @file{.emacs} file.
+@item blink-matching-paren t
+@itemx :se sm (:se showmatch)
+Show matching parens by blinking cursor.
+@item tab-width t (default setting via @code{setq-default})
+@itemx :se ts=value (:se tabstop=value)
+@itemx :se ts-g=value (:se tabstop-global=value)
+@code{tab-width} is a local variable that controls the width of the tab stops.
+To change the value globally, use @code{setq-default}; for local settings,
+use @code{setq}.
+
+The command @kbd{:se ts}
+sets the tab width in the current
+buffer only; it has no effect on other buffers.
+
+The command @kbd{:se ts-g} sets tab width globally,
+for all buffers where the tab is not yet set locally,
+including the new buffers.
+
+Note that typing @key{TAB} normally
+doesn't insert the tab, since this key is usually bound to
+a text-formatting function, @code{indent-for-tab-command} (which facilitates
+programming and document writing). Instead, the tab is inserted via the
+command @code{viper-insert-tab}, which is bound to @kbd{S-tab} (shift + tab).
+
+On some non-windowing terminals, Shift doesn't modify the @key{TAB} key, so
+@kbd{S-tab} behaves as if it were @key{TAB}. In such a case, you will have
+to bind @code{viper-insert-tab} to some other convenient key.
+
+@item viper-shift-width 8
+@itemx :se sw=value (:se shiftwidth=value)
+The number of columns shifted by @kbd{>} and @kbd{<} commands.
+@item viper-search-wrap-around t
+@itemx :se ws (:se wrapscan)
+If not @code{nil}, search wraps around the end/beginning of buffer.
+@item viper-search-scroll-threshold 2
+If search lands within this many lines of the window top or bottom, the
+window will be scrolled up or down by about 1/7-th of its size, to reveal
+the context. If the value is negative---don't scroll.
+@item viper-tags-file-name "TAGS"
+The name of the file used as the tag table.
+@item viper-re-query-replace nil
+If not @code{nil}, use reg-exp replace in query replace.
+@item viper-want-ctl-h-help nil
+If not @code{nil}, @kbd{C-h} is bound to @code{help-command};
+otherwise, @kbd{C-h} is bound as usual in Vi.
+@item viper-vi-style-in-minibuffer t
+If not @code{nil}, Viper provides a high degree of compatibility with Vi
+insert mode when you type text in the Minibuffer; if @code{nil}, typing in
+the Minibuffer feels like plain Emacs.
+@item viper-no-multiple-ESC t
+If you set this to @code{nil}, you can use @key{ESC} as Meta in Vi state.
+Normally, this is not necessary, since graphical displays have separate
+Meta keys (usually on each side of the space bar). On a dumb terminal, Viper
+sets this variable to @code{twice}, which is almost like @code{nil}, except
+that double @key{ESC} beeps. This, too, lets @key{ESC} to be used as a Meta.
+@item viper-ESC-keyseq-timeout 200 on tty, 0 on windowing display
+Escape key sequences separated by this much delay (in milliseconds) are
+interpreted as command, ignoring the special meaning of @key{ESC} in
+VI. The default is suitable for most terminals. However, if your terminal
+is extremely slow, you might want to increase this slightly. You will know
+if your terminal is slow if the @key{ESC} key sequences emitted by the
+arrow keys are interpreted as separately typed characters (and thus the
+arrow keys won't work). Making this value too large will slow you down, so
+exercise restraint.
+@item viper-fast-keyseq-timeout 200
+Key sequences separated by this many milliseconds are treated as Vi-style
+keyboard macros. If the key sequence is defined as such a macro, it will be
+executed. Otherwise, it is processed as an ordinary sequence of typed keys.
+
+Setting this variable too high may slow down your typing. Setting it too
+low may make it hard to type macros quickly enough.
+@item viper-ex-style-motion t
+Set this to @code{nil}, if you want @kbd{l,h} to cross
+lines, etc. @xref{Movement and Markers}, for more info.
+@item viper-ex-style-editing t
+Set this to to @code{nil}, if you want
+@kbd{C-h} and @key{DEL} to not stop
+at the beginning of a line in Insert state, @key{X} and @key{x} to delete
+characters across lines in Vi command state, etc.
+@item viper-ESC-moves-cursor-back t
+It t, cursor moves back 1 character when switching from insert state to vi
+state. If nil, the cursor stays where it was before the switch.
+@item viper-always t
+@code{t} means: leave it to Viper to decide when a buffer must be brought
+up in Vi state,
+Insert state, or Emacs state. This heuristics works well in virtually all
+cases. @code{nil} means you either has to invoke @code{viper-mode} manually
+for each buffer (or you can add @code{viper-mode} to the appropriate major mode
+hooks using @code{viper-load-hook}).
+
+This option must be set in the file @file{~/.viper}.
+@item viper-custom-file-name "~/.viper"
+File used for Viper-specific customization.
+Change this setting, if you want. Must be set in @file{.emacs} (not @file{.viper}!)
+before Viper is loaded. Note that you
+have to set it as a string inside double quotes.
+@item viper-spell-function 'ispell-region
+Function used by the command @kbd{#c<move>} to spell.
+@item ex-nontrivial-find-file-function
+The value of this variable is the function used to find all files that
+match a wildcard. This is usually done when the user types @kbd{:e} and
+specifies a wildcard in the file name (or if the file name contains unusual
+symbols (e.g., a space). Viper provides two functions for this: one for
+Unix-like systems (@code{viper-ex-nontrivial-find-file-unix}) and one for
+DOS, W95, and NT (@code{viper-ex-nontrivial-find-file-ms}). If the default
+function doesn't quite do what you expect or if you prefer to use ``fancy''
+shells, you may have to write your own version of this function and make it
+into the value of @code{ex-nontrivial-find-file-function}. Use
+@code{viper-ex-nontrivial-find-file-unix} and
+@code{viper-ex-nontrivial-find-file-ms} as examples.
+@vindex @code{ex-nontrivial-find-file-function}.
+@findex @code{viper-ex-nontrivial-find-file-ms}
+@findex @code{viper-ex-nontrivial-find-file-unix}
+@item ex-cycle-other-window t
+If not @code{nil}, @kbd{:n} and @kbd{:b} will cycle through files in another
+window, if one exists.
+@item ex-cycle-through-non-files nil
+@kbd{:n} does not normally cycle through buffers. Set this to get
+buffers also.
+@item viper-want-emacs-keys-in-insert
+This is set to @code{nil} for user levels 1 and 2 and to @code{t} for user
+levels 3 and 4. Users who specify level 5 are allowed to set this variable
+as they please (the default for this level is @code{t}). If set to
+@code{nil}, complete Vi compatibility is provided in Insert state. This is
+really not recommended, as this precludes you from using language-specific
+features provided by the major modes.
+@item viper-want-emacs-keys-in-vi
+This is set to @code{nil} for user
+level 1 and to @code{t} for user levels 2--4.
+At level 5, users are allowed to set this variable as they please (the
+default for this level is @code{t}).
+If set to @code{nil}, complete Vi compatibility is provided
+in Vi command state. Setting this to @code{nil} is really a bad idea,
+unless you are a novice, as this precludes the use
+of language-specific features provided by the major modes.
+@item viper-keep-point-on-repeat t
+If not @code{nil}, point is not moved when the user repeats the previous
+command by typing `.' This is very useful for doing repeated changes with
+the @kbd{.} key.
+@item viper-repeat-from-history-key 'f12
+Prefix key used to invoke the macros @kbd{f12 1} and @kbd{f12 2} that repeat
+the second-last and the third-last destructive command.
+Both these macros are bound (as Viper macros) to
+@code{viper-repeat-from-history},
+which checks the second key by which it is invoked to see which of the
+previous commands to invoke. Viper binds @kbd{f12 1} and @kbd{f12 2} only,
+but the user can bind more in @file{~/.viper}. @xref{Vi Macros}, for how to do
+this.
+@item viper-keep-point-on-undo nil
+If not @code{nil}, Viper tries to not move point when undoing commands.
+Instead, it will briefly move the cursor to the place where change has
+taken place. However, if the undone piece of text is not seen in window,
+then point will be moved to the place where the change took place.
+Set it to @code{t} and see if you like it better.
+@item viper-delete-backwards-in-replace nil
+If not @code{nil}, @key{DEL} key will delete characters while moving the cursor
+backwards. If @code{nil}, the cursor will move backwards without deleting
+anything.
+@item viper-replace-overlay-face 'viper-replace-overlay-face
+On a graphical display, Viper highlights replacement regions instead of
+putting a @samp{$} at the end. This variable controls the so called
+@dfn{face} used to highlight the region.
+
+By default, @code{viper-replace-overlay-face} underlines the replacement on
+monochrome displays and also lays a stipple over them. On color displays,
+replacement regions are highlighted with color.
+
+If you know something about Emacs faces and don't like how Viper highlights
+replacement regions, you can change @code{viper-replace-overlay-face} by
+specifying a new face. (Emacs faces are described in the Emacs Lisp
+reference.) On a color display, the following customization method is
+usually most effective:
+@example
+(set-face-foreground viper-replace-overlay-face "DarkSlateBlue")
+(set-face-background viper-replace-overlay-face "yellow")
+@end example
+For a complete list of colors available to you, evaluate the expression
+@code{(x-defined-colors)}. (Type it in the buffer @code{*scratch*} and then
+hit the @kbd{C-j} key.
+
+@item viper-replace-overlay-cursor-color "Red"
+@vindex @code{viper-replace-overlay-cursor-color}
+Cursor color when it is inside the replacement region.
+This has effect only on color displays and only when Emacs runs as an X
+application.
+@item viper-insert-state-cursor-color nil
+@vindex @code{viper-insert-state-cursor-color}
+If set to a valid color, this will be the cursor color when Viper is in
+insert state.
+@item viper-replace-region-end-delimiter "$"
+A string used to mark the end of replacement regions. It is used only on
+TTYs or if @code{viper-use-replace-region-delimiters} is non-nil.
+@item viper-replace-region-start-delimiter ""
+A string used to mark the beginning of replacement regions. It is used
+only on TTYs or if @code{viper-use-replace-region-delimiters} is non-nil.
+@item viper-use-replace-region-delimiters
+If non-nil, Viper will always use @code{viper-replace-region-end-delimiter} and
+@code{viper-replace-region-start-delimiter} to delimit replacement regions,
+even on color displays (where this is unnecessary). By default, this
+variable is non-nil only on TTYs or monochrome displays.
+@item viper-allow-multiline-replace-regions t
+If non-nil, multi-line text replacement regions, such as those produced by
+commands @kbd{c55w}, @kbd{3C}, etc., will stay around until the user exits
+the replacement mode. In this variable is set to @code{nil}, Viper will
+emulate the standard Vi behavior, which supports only intra-line
+replacement regions (and multi-line replacement regions are deleted).
+@item viper-toggle-key "\C-z"
+Specifies the key used to switch from Emacs to Vi and back.
+Must be set in @file{.viper}. This variable can't be
+changed interactively after Viper is loaded.
+
+In Insert state, this key acts as a temporary escape to Vi state, i.e., it
+will set Viper up so that the very next command will be executed as if it
+were typed in Vi state.
+@item viper-ESC-key "\e"
+Specifies the key used to escape from Insert/Replace states to Vi.
+Must be set in @file{.viper}. This variable cannot be
+changed interactively after Viper is loaded.
+@item viper-buffer-search-char nil
+Key used for buffer search. @xref{Viper Specials}, for details.
+@item viper-surrounding-word-function 'viper-surrounding-word
+The value of this variable is a function name that is used to determine
+what constitutes a word clicked upon by the mouse. This is used by mouse
+search and insert.
+@item viper-search-face 'viper-search-face
+Variable that controls how search patterns are highlighted when they are
+found.
+@item viper-vi-state-hook nil
+List of parameterless functions to be run just after entering the Vi
+command state.
+@item viper-insert-state-hook nil
+Same for Insert state. This hook is also run after entering Replace state.
+@item viper-replace-state-hook nil
+List of (parameterless) functions called just after entering Replace state
+(and after all @code{viper-insert-state-hook}).
+@item viper-emacs-state-hook nil
+List of (parameterless) functions called just after switching from Vi state
+to Emacs state.
+@item viper-load-hook nil
+List of (parameterless) functions called just after loading Viper. This is
+the last chance to do customization before Viper is up and running.
+@end table
+@noindent
+You can reset some of these constants in Viper with the Ex command @kbd{:set}
+(when so indicated in the table). Or you
+can include a line like this in your @file{.viper} file:
+@example
+(setq viper-case-fold-search t)
+@end example
+@vindex @code{viper-auto-indent}
+@vindex @code{viper-electric-mode}
+@vindex @code{viper-case-fold-search}
+@vindex @code{viper-re-search}
+@vindex @code{viper-shift-width}
+@vindex @code{buffer-read-only}
+@vindex @code{viper-search-wrap-around}
+@vindex @code{viper-search-scroll-threshold}
+@vindex @code{viper-search-face}
+@vindex @code{viper-tags-file-name}
+@vindex @code{viper-re-query-replace}
+@vindex @code{viper-want-ctl-h-help}
+@vindex @code{viper-vi-style-in-minibuffer}
+@vindex @code{viper-no-multiple-ESC}
+@vindex @code{viper-always}
+@vindex @code{viper-ESC-keyseq-timeout}
+@vindex @code{viper-fast-keyseq-timeout}
+@vindex @code{viper-ex-style-motion}
+@vindex @code{viper-ex-style-editing}
+@vindex @code{viper-ESC-moves-cursor-back}
+@vindex @code{viper-custom-file-name}
+@vindex @code{viper-spell-function}
+@vindex @code{ex-cycle-other-window}
+@vindex @code{ex-cycle-through-non-files}
+@vindex @code{viper-want-emacs-keys-in-insert}
+@vindex @code{viper-want-emacs-keys-in-vi}
+@vindex @code{viper-keep-point-on-repeat}
+@vindex @code{viper-keep-point-on-undo}
+@vindex @code{viper-delete-backwards-in-replace}
+@vindex @code{viper-replace-overlay-face}
+@vindex @code{viper-replace-region-end-symbol}
+@vindex @code{viper-replace-region-start-symbol}
+@vindex @code{viper-allow-multiline-replace-regions}
+@vindex @code{viper-toggle-key}
+@vindex @code{viper-ESC-key}
+@vindex @code{viper-buffer-search-char}
+@vindex @code{viper-surrounding-word-function}
+@vindex @code{viper-vi-state-hook}
+@vindex @code{viper-insert-state-hook}
+@vindex @code{viper-replace-state-hook}
+@vindex @code{viper-emacs-state-hook}
+
+@node Keybindings, Packages that Change Keymaps, Rudimentary Changes,Customization
+@section Keybindings
+
+@cindex keybindings
+@cindex keymaps
+
+Viper lets you define hot keys, i.e., you can associate keyboard keys
+such as F1, Help, PgDn, etc., with Emacs Lisp functions (that may already
+exist or that you will write). Each key has a "preferred form" in
+Emacs. For instance, the Up key's preferred form is [up], the Help key's
+preferred form is [help], and the Undo key has the preferred form [f14].
+You can find out the preferred form of a key by typing @kbd{M-x
+describe-key-briefly} and then typing the key you want to know about.
+
+Under X Windows, every keyboard key emits its preferred form, so you can
+just type
+
+@lisp
+(global-set-key [f11] 'calendar) ; L1, Stop
+(global-set-key [f14] 'undo) ; L4, Undo
+@end lisp
+
+@noindent
+to bind L1 so it will invoke the Emacs Calendar and to bind L4 so it will
+undo changes.
+However, on a dumb terminal or in an Xterm window, even the standard arrow
+keys may
+not emit the right signals for Emacs to understand. To let Emacs know about
+those keys, you will have to find out which key sequences they emit
+by typing @kbd{C-q} and then the key (you should switch to Emacs state
+first). Then you can bind those sequences to their preferred forms using
+@code{function-key-map} as follows:
+
+@lisp
+(cond ((string= (getenv "TERM") "xterm")
+(define-key function-key-map "\e[192z" [f11]) ; L1
+(define-key function-key-map "\e[195z" [f14]) ; L4, Undo
+@end lisp
+
+The above illustrates how to do this for Xterm. On VT100, you would have to
+replace "xterm" with "vt100" and also change the key sequences (the same
+key may emit different sequences on different types of terminals).
+
+The above keys are global, so they are overwritten by the local maps
+defined by the major modes and by Viper itself. Therefore, if you wish to
+change a binding set by a major mode or by Viper, read this.
+
+Viper users who wish to specify their own key bindings should be concerned
+only with the following three keymaps:
+@code{viper-vi-global-user-map} for Vi state commands,
+@code{viper-insert-global-user-map} for Insert state commands,
+and @code{viper-emacs-global-user-map} for Emacs state commands (note:
+customized bindings for Emacs state made to @code{viper-emacs-global-user-map}
+are @emph{not} inherited by Insert state).
+
+For more information on Viper keymaps, see the header of the file
+@file{viper.el}.
+If you wish to change a Viper binding, you can use the
+@code{define-key} command, to modify @code{viper-vi-global-user-map},
+@code{viper-insert-global-user-map}, and @code{viper-emacs-global-user-map}, as
+explained below. Each of these key maps affects the corresponding Viper state.
+The keymap @code{viper-vi-global-user-map} also affects Viper's Replace state.
+
+@noindent
+If you want to
+bind a key, say @kbd{C-v}, to the function that scrolls
+page down and to make @kbd{0} display information on the current buffer,
+putting this in @file{.viper} will do the trick in Vi state:
+@example
+(define-key viper-vi-global-user-map "\C-v" 'scroll-down)
+@end example
+@noindent
+To set a key globally,
+@example
+(define-key viper-emacs-global-user-map "\C-c m" 'smail)
+(define-key viper-vi-global-user-map "0" 'viper-info-on-file)
+@end example
+@noindent
+Note, however, that this binding may be overwritten by other keymaps, since
+the global keymap has the lowest priority.
+To make sure that nothing will override a binding in Emacs state, you
+can write this:
+@example
+(define-key viper-emacs-global-user-map "\C-c m" 'smail)
+@end example
+@noindent
+To customize the binding for @kbd{C-h} in Insert state:
+@example
+(define-key viper-insert-global-user-map "\C-h" 'my-del-backwards-function)
+@end example
+@noindent
+
+Each Emacs command key calls some lisp function. If you have enabled the
+Help, (@pxref{Rudimentary Changes}) @kbd{C-h k} will show you the function
+for each specific key; @kbd{C-h b} will show all bindings, and @kbd{C-h m}
+will provide information on the major mode in effect. If Help is not
+enabled, you can still get help in Vi state by prefixing the above commands
+with @kbd{\}, e.g., @kbd{\ C-h k} (or you can use the Help menu in the
+menu bar, if Emacs runs under X Windows).
+
+Viper users can also change bindings on a per major mode basis. As with
+global bindings, this can be done separately for each of the three main Viper
+states. To this end, Viper provides the function
+@code{viper-modify-major-mode}.
+@findex @code{viper-modify-major-mode}
+
+To modify keys in Emacs state for @code{my-favorite-major-mode}, the user
+needs to create a sparse keymap, say, @code{my-fancy-map}, bind whatever
+keys necessary in that keymap, and put
+
+@example
+(viper-modify-major-mode 'dired-mode 'emacs-state my-fancy-map)
+@end example
+
+@noindent
+in @file{~/.viper}. To do the same in Vi and Insert states, you should use
+@code{vi-state} and @code{insert-state}. Changes in Insert state are also
+in effect in Replace state. For instance, suppose that the user wants to
+use @kbd{dd} in Vi state under Dired mode to delete files, @kbd{u} to unmark
+files, etc. The following code in @file{~/.viper} will then do the job:
+
+@example
+(setq my-dired-modifier-map (make-sparse-keymap))
+(define-key my-dired-modifier-map "dd" 'dired-flag-file-deletion)
+(define-key my-dired-modifier-map "u" 'dired-unmark)
+(viper-modify-major-mode 'dired-mode 'vi-state my-dired-modifier-map)
+@end example
+
+A Vi purist may want to modify Emacs state under Dired mode so that
+@kbd{k}, @kbd{l}, etc., will move around in directory buffers, as in
+Vi. Although this is not recommended, as these keys are bound to useful
+Dired functions, the trick can be accomplished via the following code:
+
+@example
+(setq my-dired-vi-purist-map (make-sparse-keymap))
+(define-key my-dired-vi-purist-map "k" 'viper-previous-line)
+(define-key my-dired-vi-purist-map "l" 'viper-forward-char)
+(viper-modify-major-mode 'dired-mode 'emacs-state my-dired-vi-purist-map)
+@end example
+
+Yet another way to customize key bindings in a major mode is to edit the
+list @code{viper-major-mode-modifier-list} using the customization widget.
+@vindex @code{viper-major-mode-modifier-list}
+(This variable is in the Viper-misc customization group.)
+The elements of this list are triples of the form: (major-mode viper-state
+keymap), where the keymap contains bindings that are supposed to be active
+in the given major mode and the given viper-state.
+
+Effects similar to key binding changes can be achieved by defining Vi
+keyboard macros using the Ex commands @kbd{:map} and @kbd{:map!}. The
+difference is that multi-key Vi macros do not override the keys they are
+bound to, unless these keys are typed in quick succession. So, with macros,
+one can use the normal keys alongside with the macros. If per-mode
+modifications are needed, the user can try both ways and see which one is
+more convenient.
+@findex @kbd{:map}
+@xref{Vi Macros}, for details.
+
+Note: in major modes that come up in @emph{Emacs state} by default, the
+aforesaid modifications may not take place immediately (but only after the
+buffer switches to some other Viper state and then back to Emacs state). To
+avoid this, one should add @code{viper-change-state-to-emacs} to an
+appropriate hook of that major mode. (Check the function
+@code{viper-set-hooks} in @file{viper.el} for examples.) However, if you
+have set @code{viper-always} to @code{t}, chances are that you won't need to
+perform the above procedure, because Viper will take care of most useful
+defaults.
+
+
+Finally, Viper has a facility that lets the user define per-buffer
+bindings, i.e., bindings that are in effect in some specific buffers
+only. Unlike per-mode bindings described above, per-buffer bindings can be
+defined based on considerations other than the major mode. This is done
+via the function @code{viper-add-local-keys}, which lets one specify bindings
+that should be in effect in the current buffer only and for a specific Viper
+state. For instance,
+@lisp
+(viper-add-local-keys 'vi-state '(("ZZ" .@: TeX-command-master)
+ ("ZQ" .@: viper-save-kill-buffer)))
+@end lisp
+@noindent
+redefines @kbd{ZZ} to invoke @code{TeX-command-master} in @code{vi-state}
+and @kbd{ZQ} to save-then-kill the current buffer. These bindings take
+effect only in the buffer where this command is executed. The typical use
+of this function is to execute the above expression from within a function
+that is included in a hook to some major mode. For instance, the above
+expression
+could be called from a function, @code{my-tex-init}, which may be added to
+@code{tex-mode-hook} as follows:
+@lisp
+(add-hook 'tex-mode-hook 'my-tex-init)
+@end lisp
+@noindent
+When TeX mode starts, the hook is executed and the above Lisp expression is
+evaluated. Then, the bindings for @kbd{ZZ} and @kbd{ZQ} are changed in Vi
+command mode for all buffers in TeX mode.
+
+Another useful application is to bind @kbd{ZZ} to @code{send-mail}
+in the Mail mode buffers (the specifics of this depend on which mail
+package you are using, @code{rmail}, @code{mh-e}, @code{vm}, etc.
+For instance, here is how to do this for @code{mh-e}, the Emacs interface
+to MH:
+@lisp
+(defun mh-add-vi-keys ()
+ "Set up ZZ for MH-e and XMH."
+ (viper-add-local-keys 'vi-state '(("ZZ" .@: mh-send-letter))))
+(add-hook 'mh-letter-mode-hook 'mh-add-vi-keys)
+@end lisp
+
+You can also use @code{viper-add-local-keys} to set per buffer
+bindings in Insert state and Emacs state by passing as a parameter the
+symbols @code{insert-state} and @code{emacs-state}, respectively.
+As with global bindings, customized local bindings done to Emacs state
+are not inherited by Insert state.
+
+On rare occasions, local keys may be added by mistake. Usually this is done
+indirectly, by invoking a major mode that adds local keys (e.g.,
+@code{shell-mode} redefines @key{RET}). In such a case, exiting the wrong
+major mode won't rid you from unwanted local keys, since these keys are
+local to Viper state and the current buffer, not to the major mode.
+In such situations, the remedy is to type @kbd{M-x viper-zap-local-keys}.
+
+So much about Viper-specific bindings.
+@xref{Customization,,Customization,emacs,The GNU Emacs
+Manual}, and the Emacs quick reference card for the general info on key
+bindings in Emacs.
+
+@vindex @code{function-key-map}
+@vindex @code{viper-vi-global-user-map}
+@vindex @code{viper-insert-global-user-map}
+@vindex @code{viper-emacs-global-user-map}
+@findex @code{viper-add-local-keys}
+@findex @code{viper-zap-local-keys}
+
+@node Packages that Change Keymaps,Viper Specials,Keybindings,Customization
+@subsection Packages that Change Keymaps
+@cindex C-c and Viper
+@cindex Viper and C-c
+
+Viper is designed to coexist with all major and minor modes of Emacs. This
+means that bindings set by those modes are generally available with Viper
+(unless you explicitly prohibit them by setting
+@code{viper-want-emacs-keys-in-vi} and @code{viper-want-emacs-keys-in-insert} to
+@code{nil}).
+If @code{viper-always} is set to @code{t}, Viper will try to bring each buffer
+in the Viper state that is most appropriate for that buffer.
+Usually, this would be the Vi state, but sometimes it could be the Insert
+state or the Emacs state.
+
+Some major mode bindings will necessarily be overwritten by Viper. Indeed, in
+Vi state, most of the 1-character keys are used for Vi-style editing. This
+usually causes no problems because most packages designed for editing files
+typically do not bind such keys. Instead, they use key sequences that start
+with @kbd{C-x} and @kbd{C-c}. This is why it was so important for us to
+free up @kbd{C-x} and @kbd{C-c}.
+It is common for language-specific major modes to bind @key{TAB} and
+@kbd{C-j} (the line feed) keys to various formatting functions. This is
+extremely useful, but may require some getting used to for a Vi user. If you
+decide that this feature is not for you, you can re-bind these keys as
+explained earlier (@pxref{Customization}).
+
+Binding for @key{TAB} is one of the most unusual aspects of Viper for many
+novice users. In Emacs, @key{TAB} is used to format text and programs, and
+is extremely useful. For instance, hitting @key{TAB} causes the current
+line to be re-indented in accordance with the context. In programming,
+this is very important, since improper automatic indentation would
+immediately alert the programmer to a possible error. For instance, if a
+@kbd{)} or a @kbd{"} is missing somewhere above the current
+line, @key{TAB} is likely to mis-indent the line.
+
+For this reason, Viper doesn't change the standard Emacs binding of
+@key{TAB}, thereby sacrificing Vi compatibility
+(except for users at level 1). Instead, in Viper, the key
+@kbd{S-tab} (shift+ tab) is chosen to emulate Vi's @key{TAB}.
+
+We should note that on some non-windowing terminals, Shift doesn't modify
+the @key{TAB} key, so @kbd{S-tab} behaves as if it were @key{TAB}. In such
+a case, you will have to bind @code{viper-insert-tab} to some other
+convenient key.
+
+Some packages, notably Dired, Gnus, Info, etc., attach special meaning to
+common keys like @key{SPC}, @kbd{x}, @kbd{d}, @kbd{v}, and others. This
+means that Vi command state is inappropriate for working with these
+packages. Fortunately, these modes operate on read-only buffers and are
+designed not for editing files, but for special-purpose browsing, reading
+news, mail, etc., and Vi commands are meaningless in these situations. For
+this reason, Viper doesn't force Vi state on such major modes---it
+brings them in Emacs state. You can switch to Vi state by typing @kbd{C-z}
+if, for instance, you want to do Vi-style search in a buffer (although,
+usually, incremental search, which is bound to @kbd{C-s}, is sufficient in
+these situations). But you should then switch back to Emacs state if you
+plan to continue using these major modes productively. You can also switch
+to Vi temporarily, to execute just one command. This is done by typing
+@kbd{C-c \}. (In some of these modes, @kbd{/} and @kbd{:} are bound
+Vi-style, unless these keys perform essential duties.)
+
+If you would like certain major modes to come up in Emacs state rather than
+Vi state (but Viper thinks otherwise), you should put these major modes
+on the @code{viper-emacs-state-mode-list} list and delete them from
+@code{viper-vi-state-mode-list}.
+Likewise, you can force Viper's Insert state on a major mode by putting it
+in @code{viper-insert-state-mode-list}.
+@vindex @code{viper-emacs-state-mode-list}
+@vindex @code{viper-insert-state-mode-list}
+@vindex @code{viper-vi-state-mode-list}
+
+It is also possible to impose Vi on some major modes, even though they may
+bind common keys to specialized commands. This might make sense for modes
+that bind only a small number of common keys. For instance, Viper subverts
+the Shell mode by changing the bindings for @kbd{C-m} and @kbd{C-d} using
+@code{viper-add-local-keys} described in section on customization
+(@pxref{Customization}).
+
+In some cases, some @emph{minor} modes might override certain essential
+bindings in Vi command state. This is not a big priblem because this
+can happen only in the beginning, when the minor mode kicks in. Typing
+@code{M-x viper-mode} will correct the situation. Viper knows about
+several such minor modes and takes care of them, so the above trick
+is usually not necessary. If you find that some minor mode, e.g.,
+@code{nasty-mode.el} interferes with Viper, putting the following in
+@file{.viper} should fix the problem:
+@lisp
+(viper-harness-minor-mode "nasty-mode")
+@end lisp
+@noindent
+The argument to @code{viper-harness-minor-mode} is the name of the file for the
+offending minor mode with the suffixes @file{.el} and @file{.elc} removed.
+
+It may not be always obvious which minor mode is at fault. The only
+guidance here is to look into the file that defines the minor mode you are
+suspecting, say @code{nasty-mode.el}, and see if it has a variable called
+@code{nasty-mode-map}. Then check if there is a statement of the form
+@lisp
+(define-key nasty-mode-map key function)
+@end lisp
+@noindent
+that binds the misbehaving
+keys. If so, use the above line to harness @code{nasty-mode}. If your
+suspicion is wrong, no harm is done if you harness a minor mode that
+doesn't need to be harnessed.
+
+@vindex @code{viper-want-emacs-keys-in-vi}
+@vindex @code{viper-want-emacs-keys-in-insert}
+@vindex @code{viper-always}
+@findex @code{viper-set-hooks}
+@findex @code{viper-mode}
+@findex @code{viper-harness-minor-mode}
+@findex @code{remove-hook}
+@findex @code{add-hook}
+
+@node Viper Specials,Vi Macros,Packages that Change Keymaps,Customization
+@section Viper Specials
+
+Viper extends Vi with a number of useful features. This includes various
+search functions, histories of search strings, Ex commands, insertions, and
+Vi's destructive commands. In addition, Viper supports file name completion
+and history, completion of Ex commands and variables, and many other
+features. Some of these features are explained in detail elsewhere in this
+document. Other features are explained here.
+
+@table @code
+@item (viper-buffer-search-enable)
+@item viper-buffer-search-char nil
+Enable buffer search. Explicit call to @code{viper-buffer-search-enable}
+sets @code{viper-buffer-search-char} to @kbd{g}. Alternatively, the user can
+set @code{viper-buffer-search-char} in @file{.viper} to a key sequence
+to be used for buffer search. There is no need to call
+@code{viper-buffer-search-enable} in that case.
+@findex @code{viper-buffer-search-enable}
+@vindex @code{viper-buffer-search-char}
+@item viper-toggle-search-style
+This function, bound to @kbd{C-c /}, lets one toggle case-sensitive and
+case-insensitive search, and also switch between plain vanilla search and
+search via regular expressions. Without the prefix argument, the user is
+asked which mode to toggle. With prefix argument 1, this toggles
+case-sensitivity. With prefix argument 2, regular expression/vanilla search
+will be toggled.
+
+However, we found that the most convenient way to toggle
+these options is to bind a Vi macro to
+bind @kbd{//} to toggles case sensitivity and to @kbd{///} to toggles
+vanilla search. Thus, quickly hitting @kbd{/} twice will switch Viper from
+case sensitive search to case-insensitive. Repeating this once again will
+restore the original state. Likewise, quickly hitting @kbd{/} three times
+will switch you from vanilla-style search to search via regular expressions.
+If you hit something other than @kbd{/} after the first @kbd{/} or if the
+second @kbd{/} doesn't follow quickly enough, then Viper will issue the
+usual prompt @kbd{/} and will wait for input, as usual in Vi.
+If you don't like this behavior, you can ``unrecord'' these macros in your
+@file{~/.viper} file. For instance, if you don't like the above feature, put
+this in @file{~/.viper}:
+@example
+(viper-set-searchstyle-toggling-macros 'undefine)
+@end example
+@findex @code{viper-set-searchstyle-toggling-macros}
+
+@item Vi-isms in Emacs state
+Some people find it useful to use the Vi-style search key, `/', to invoke
+search in modes which Viper leaves in emacs-state. These modes are:
+@code{dired-mode}, @code{mh-folder-mode}, @code{gnus-group-mode},
+@code{gnus-summary-mode}, @code{Info-mode}, and @code{Buffer-menu-mode}
+(more may be added in the future). So, in the above modes, Viper binds `/'
+so that it will behave Vi-style. Furthermore, in those major modes, Viper
+binds `:' to invoke ex-style commands, like in vi-state. And, as described
+above, `//' and `///' get bound to Vi-style macros that toggle
+case-insensitivity and regexp-search.
+
+If you don't like these features---which I don't really understand---you
+can unbind `/' and `:' in @code{viper-dired-modifier-map} (for Dired) or in
+@code{viper-slash-and-colon-map}, for other modes.
+@vindex @code{viper-slash-and-colon-map}
+@vindex @code{viper-dired-modifier-map}
+
+To unbind the macros `//' and `///' for a major mode where you feel they
+are undesirable, execute @code{viper-set-emacs-state-searchstyle-macros} with a
+non-nil argument. This can be done either interactively, by supplying a
+prefix argument, or by placing
+@example
+(viper-set-emacs-state-searchstyle-macros 'undefine)
+@end example
+@findex @code{viper-set-emacs-state-searchstyle-macros}
+in the hook to the major mode (e.g., @code{dired-mode-hook}).
+@xref{Vi Macros}, for more information on Vi macros.
+
+@item viper-heading-start
+@item viper-heading-end
+@cindex headings
+@cindex sections
+@cindex paragraphs
+@cindex sentences
+Regular Expressions for @kbd{[[} and @kbd{]]}. Note that Emacs defines
+Regexps for paragraphs and sentences. @xref{Paragraphs,,Paragraphs and
+Sentences,emacs,The GNU Emacs Manual}, for details.
+@item M-x viper-set-expert-level
+@findex @code{viper-set-expert-level}
+Change your user level interactively.
+@item viper-smart-suffix-list '("" "tex" "c" "cc" "el" "p")
+@vindex @code{viper-smart-suffix-list}
+Viper supports Emacs-style file completion when it prompts the user for a
+file name. However, in many cases, the same directory may contain files
+with identical prefix but different suffixes, e.g., prog.c, prog.o,
+paper.tex, paper.dvi. In such cases, completion will stop at the `.'.
+If the above variable is a list of strings representing suffixes, Viper will
+try these suffixes
+in the order listed and will check if the corresponding file exists.
+
+For instance, if completion stopped at `paper.'@: and the user typed
+@key{RET},
+then Viper will check if the files `paper.', `paper.tex', `paper.c', etc., exist.
+It will take the first such file. If no file exists, Viper will give a chance
+to complete the file name by typing the appropriate suffix. If `paper.'@: was
+the intended file name, hitting return will accept it.
+
+To turn this feature off, set the above variable to @code{nil}.
+
+@item viper-insertion-ring-size 14
+@vindex @code{viper-insertion-ring-size}
+@cindex Insertion ring
+Viper remembers what was previously inserted in Insert and Replace states.
+Several such recent insertions are kept in a special ring of strings of size
+@code{viper-insertion-ring-size}.
+If you enter Insert or Replace state you can reinsert strings from this
+ring by typing @kbd{C-c M-p} or @kbd{C-c M-n}. The former will search the
+ring in
+the direction of older insertions, and the latter will search in
+the direction of newer insertions. Hitting @kbd{C-c M-p} or @kbd{C-c M-n}
+in succession
+will undo the previous insertion from the ring and insert the next item on
+the ring. If a larger ring size is needed, change the value of the above
+variable in the @file{~/.viper} file.
+
+Since typing these sequences of keys may be tedious, it is suggested that the
+user should bind a function key, such as @kbd{f31}, as follows:
+@example
+(define-key viper-insert-global-user-map [f31]
+ 'viper-insert-prev-from-insertion-ring)
+@end example
+This binds @kbd{f31} (which is usually @kbd{R11} on a Sun workstation)
+to the function that inserts the previous string in the insertion history.
+To rotate the history in the opposite
+direction, you can either bind an unused key to
+@code{viper-insert-next-from-insertion-ring} or hit any digit (1 to 9) then
+@kbd{f31}.
+
+One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since
+this will interfere with the Minibuffer histories and, possibly, other
+major modes.
+
+@item viper-command-ring-size 14
+@vindex @code{viper-command-ring-size}
+@cindex Destructive command ring
+@cindex Destructive command history
+Viper keeps track of the recent history of destructive
+commands, such as @kbd{dw}, @kbd{i}, etc.
+In Vi state,
+the most recent command can be re-executed by hitting `@kbd{.}', as in Vi.
+However, repeated typing @kbd{C-c M-p} will cause Viper to show the
+previous destructive commands in the minibuffer. Subsequent hitting `@kbd{.}'
+will execute the command that was displayed last.
+The key @kbd{C-c M-n} will cycle through the command history in the
+opposite direction.
+Since typing @kbd{C-c M-p} may be tedious, it is more convenient to bind an
+appropriate function to an unused function key on the keyboard and use that
+key. For instance, the following
+@example
+(define-key viper-vi-global-user-map [f31]
+ 'viper-prev-destructive-command)
+@end example
+binds the key @kbd{f31} (which is usually @kbd{R11} on a Sun workstation)
+to the function that searches the command history in the direction of older
+commands. To search in the opposite
+direction, you can either bind an unused key to
+@code{viper-next-destructive-command} or hit any digit (1 to 9) then @kbd{f31}.
+
+One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since
+this will interfere with the Minibuffer histories and, possibly, other
+major modes.
+
+@item viper-minibuffer-vi-face 'viper-minibuffer-vi-face
+@item viper-minibuffer-insert-face 'viper-minibuffer-insert-face
+@item viper-minibuffer-emacs-face 'viper-minibuffer-emacs-face
+These faces control the appearance of the minibuffer text in the
+corresponding Viper states. You can change the appearance of these faces
+through Emacs' customization widget, which is accessible through the
+menubar.
+
+Viper is located in this widget under the @emph{Emulations} customization
+subgroup of the @emph{Editing} group. All Viper faces are grouped together
+in Viper's @emph{Highlighting} customization subgroup.
+
+Note that only the text you type in is affected by the above faces.
+Prompts and Minibuffer messages are not affected.
+
+Purists who do not like adornments in the minibuffer can always zap them by
+putting
+@example
+(copy-face 'default 'viper-minibuffer-vi-face)
+(copy-face 'default 'viper-minibuffer-insert-face)
+(copy-face 'default 'viper-minibuffer-emacs-face)
+@end example
+in the @file{~/.viper} file or through the customization widget, as
+described above. However, in that case, the user will not have any
+indication of the current Viper state in the minibuffer. (This is important
+if the user accidentally switches to another Viper state by typing @key{ESC} or
+@kbd{C-z}).
+@item M-x viper-go-away
+@findex @code{viper-go-away}
+Make Viper disappear from the face of your running Emacs instance. If your
+fingers start aching again, @kbd{M-x viper-mode} might save your day.
+@item M-x toggle-viper-mode
+@findex @code{toggle-viper-mode}
+Toggle Viperization of Emacs on and off.
+@end table
+
+@cindex Multifile documents and programs
+
+Viper provides some support for multi-file documents and programs.
+If a document consists of several files we can designate one of them as a
+master and put the following at the end of that file:
+@lisp
+;;; Local Variables:
+;;; eval: (viper-setup-master-buffer "file1" "file2" "file3" "file5" "file5")
+;;; End:
+@end lisp
+@noindent
+where @code{file1} to @code{file5} are names of files related to the master
+file. Next time, when the master file is visited, the command
+@code{viper-setup-master-buffer} will be evaluated and the above files will
+be associated with the master file. Then, the new Ex command
+@kbd{:RelatedFile} (abbr.@: @kbd{:R}) will display files 1 to 5 one after
+another, so you can edit them. If a file is not in any Emacs buffer, it
+will be visited. The command @kbd{PreviousRelatedFile} (abbr., @kbd{:P})
+goes through the file list in the opposite direction.
+@findex @kbd{:RelatedFile}
+@findex @kbd{:PreviousRelatedFile}
+
+These commands are akin to @kbd{:n} and @kbd{:N}, but they allow the user to
+focus on relevant files only.
+
+Note that only the master file needs to have the aforementioned block of
+commands. Also, ";;;" above can be replaced by some other
+markers. Semicolon is good for Lisp programs, since it is considered a
+comment designator there. For LaTeX, this could be "%%%", and for C the
+above block should be commented out.
+
+Even though these commands are sometimes useful, they are no substitute for
+the powerful @emph{tag table} facility of Emacs. Viper's @kbd{:tag} command
+in a primitive interface to Emacs tags. @xref{Tags,Tags,Tags,emacs,
+The Gnu Emacs Manual}, for more information on tags.
+
+The following two commands are normally bound to a mouse click and are part
+of Viper. They work only if Emacs runs as an application under X
+Windows (or under some other window system for which a port of GNU Emacs 20
+is available). Clicking the mouse when Emacs is invoked in an Xterm window
+(using @code{emacs -nw}) will do no good.
+
+@table @code
+@cindex mouse
+@cindex mouse-search
+@item viper-mouse-search-key (meta shift 1)
+@vindex @code{viper-mouse-insert-key}
+This variable controls the @emph{mouse-search} feature of Viper. The
+default value
+states that holding Meta and Shift keys while clicking mouse button 1
+should initiate search for a region under the mouse pointer (defined
+below). This command can take a prefix argument, which indicates the
+occurrence of the pattern to search for.
+
+Note: while loading initially, Viper binds this mouse action only if it is
+not already bound to something else. If you want to use the mouse-search
+feature and the Meta-Shift-button-1 mouse action is already bound to
+something else you can rebind the mouse-search feature by setting
+@code{viper-mouse-search-key} to something else in your @code{~/.viper}
+file:
+@lisp
+(setq viper-mouse-search-key '(meta 1))
+@end lisp
+This would bind mouse search to the action invoked by pressing the
+Meta key and clicking mouse button 1. The allowed values of
+@code{viper-mouse-search-key} are lists that contain a mouse-button number
+(1,2, or 3) and any combination of the words `control', `meta', and
+`shift'.
+
+If the requested mouse action (e.g., (meta 1)) is already taken for other
+purposes then you have to confirm your intention by placing the following
+command in @code{~/.viper} after setting @code{viper-mouse-search-key}:
+@lisp
+(viper-bind-mouse-search-key 'force)
+@end lisp
+
+You can also change this setting interactively, through the customization
+widget of Emacs (choose option "Customize.Customize Group" from the
+menubar).
+
+The region that is chosen as a pattern to search for is determined as
+follows. If search is invoked via a single click, Viper chooses the region
+that lies between the beginning of the ``word'' under the pointer (``word''
+is understood in Vi sense) and the end of that word. The only difference
+with Vi's words is that in Lisp major modes `-' is considered an
+alphanumeric symbol. This is done for the convenience of working with Lisp
+symbols, which often have an `-' in them. Also, if you click on a
+non-alphanumeric character that is not a word separator (in Vi sense) then
+this character will also be considered alphanumeric, provided that it is
+adjacent (from either side) to an alphanumeric character. This useful
+feature gives added control over the patterns selected by the mouse click.
+
+On a double-click, the region is determined by the beginning of the current
+Vi's ``Word'' (i.e., the largest non-separator chunk of text) and the End
+of that ``Word'' (as determined by the @kbd{E} command).
+
+On a triple-click, the region consists of the entire line where the click
+occurred with all leading and trailing spaces and tabs removed.
+
+@cindex mouse-insert
+@item viper-mouse-insert-key (meta shift 2)
+@vindex @code{viper-mouse-insert-key}
+This variable controls the @emph{mouse-insert} feature of Viper.
+The above default value states that
+holding Meta and Shift keys while clicking mouse button 2
+should insert the region surrounding the
+mouse pointer. The rules defining this region are the same as for
+mouse-search. This command takes an optional prefix argument, which
+indicates how many such regions to snarf from the buffer and insert. (In
+case of a triple-click, the prefix argument is ignored.)
+
+Note: while loading initially, Viper binds this mouse action only if it not
+already bound to something else. If you want to use this feature and the
+default mouse action is already bound, you can rebind mouse-insert by
+placing this command in @code{~/.viper}:
+@lisp
+(setq viper-mouse-insert-key '(meta 2))
+@end lisp
+If you want to bind mouse-insert to an action even if this action is
+already taked for other purposes in Emacs, then you should add this command
+to @code{~/.viper}, after setting @code{viper-mouse-insert-key}:
+@lisp
+(viper-bind-mouse-insert-key 'force)
+@end lisp
+
+This value can also be changed via the Emacs customization widget at the
+menubar.
+
+@item viper-multiclick-timeout
+This variable controls the rate at which double-clicking must occur for the
+purpose of mouse search and mouse insert. By default, this is set to
+@code{double-click-time}.
+@end table
+@kindex @kbd{S-mouse-1}
+@kindex @kbd{S-mouse-2}
+@kindex @kbd{meta shift button1up}
+@kindex @kbd{meta shift button2up}
+@vindex @code{viper-multiclick-timeout}
+@findex @code{viper-mouse-click-insert-word}
+@findex @code{viper-mouse-click-search-word}
+
+Note: The above functions search and insert in the selected window of
+the latest active frame. This means that you can click in another window or
+another frame and have search or insertion done in the frame and window you
+just left. This lets one use these functions in a multi-frame
+configuration. However, this may require some getting used to. For
+instance, if you are typing in a frame, A, and then move the mouse to frame
+B and click to invoke mouse search, search (or insertion) will be performed
+in frame A. To perform search/insertion in frame B, you will first have to
+shift focus there, which doesn't happen until you type a character or
+perform some other action in frame B---mouse search doesn't shift focus.
+
+If you decide that you don't like the above feature and always want
+search/insertion be performed in the frame where the click occurs, don't
+bind (and unbind, if necessary) @code{viper-mouse-catch-frame-switch} from
+the mouse event it is bound to.
+
+Mouse search is integrated with Vi-style search, so you can
+repeat it with @kbd{n} and @kbd{N}. It should be also noted that, while
+case-sensitivity of search in Viper is controlled by the variable
+@code{viper-case-fold-search}, the case of mouse search is
+controlled by the Emacs variable @code{case-fold-search}, which may be set
+differently from @code{viper-case-fold-search}. Therefore, case-sensitivity
+of mouse search may be different from that of the usual Vi-style search.
+
+Finally, if the way Viper determines the word to be searched for or to be
+inserted is not what you want, there is a variable,
+@code{viper-surrounding-word-function}, which can be changed to indicate
+another function for snarfing words out of the buffer. The catch is that
+you will then have to write such a function and make it known to your
+Emacs. The function @code{viper-surrounding-word} in @file{viper.el} can be
+used as a guiding example.
+
+@node Vi Macros, ,Viper Specials,Customization
+@section Vi Macros
+
+@cindex Vi macros
+
+Viper supports much enhanced Vi-style macros and also facilitates the use
+of Emacs-style macros. To define a temporary macro, it is generally more
+convenient to use Emacs keyboard macro facility. Emacs keyboard macros are
+usually defined anonymously, and the latest macro can be executed by typing
+@kbd{C-x e} (or @kbd{*}, if Viper is in Vi state). If you need to use several
+temporary macros, Viper lets you save them to a
+register (a lowercase letter); such macros can then be executed by typing
+@kbd{@@a} in Vi state (if a macro was previously saved in register
+@kbd{a}).
+@xref{Macros and Registers}, for details.
+
+If, however, you need to use a macro regularly, it must be given a
+permanent name and saved. Emacs manual explains how to do this, but
+invocation of named Emacs macros is quite different from Vi's. First,
+invocation of permanent Emacs macros takes time because of the extra keys.
+Second, binding such macros to function keys, for
+fast access, hogs valuable real estate on the keyboard.
+
+Vi-style macros are better in that respect, since Vi lets the user overload
+the meaning of key sequences: keys typed in fast succession are treated
+specially, if this key sequence is bound to a macro.
+
+Viper provides keyboard macros through the usual Ex commands, @kbd{:map} and
+@kbd{:map!}. Vi-style macros are much more powerful in Viper than
+they are in the original Vi and in other emulators. This is because Viper
+implements an enhanced vi-style
+interface to the powerful Emacs keyboard macro facility.
+
+First, any Emacs
+command can be executed while defining a macro, not just the Vi
+commands. In particular, the user can invoke Emacs commands via @kbd{M-x
+command-name} or by pressing various function keys on the keyboard. One
+can even use the mouse, although this is usually not useful and is not
+recommended (and macros defined with the use of the mouse cannot be saved in
+command history and in the startup file, for future use).
+
+Macros defined by mixing Vi and Emacs commands are represented as
+vectors. So, don't be confused when you see one (usually through the
+history of Ex commands). For instance, if @kbd{gg} is defined by typing
+@kbd{l}, the up-arrow key and @kbd{M-x next-line}, its definition will look
+as follows in Emacs:
+
+@example
+[l up (meta x) n e x t - l i n e return]
+@end example
+
+Second, Viper macros are defined in a WYSIWYG style. This means that
+commands are executed as you type them, so you can see precisely what is
+being defined. Third, macros can be bound to arbitrary sequences of keys,
+not just to printable keys. For instance, one can define a macro that will
+be invoked by hitting @kbd{f3} then @kbd{f2} function keys. (The keys
+@kbd{delete} and @kbd{backspace} are excluded; also, a macro invocation
+sequence can't start with @key{ESC}. Some other keys, such as @kbd{f1} and
+@kbd{help}, can't be bound to macros under Emacs, since they
+are bound in @code{key-translation-map}, which overrides any other binding
+the user gives to keys. In general, keys that have a binding in
+@code{key-translation-map} can't be bound to a macro.)
+
+Fourth, in Viper, one can define macros that are specific to a given
+buffer, a given major mode, or macros that are defined for all buffers. In
+fact, the same macro name can have several different definitions: one
+global, several definitions for various major modes, and
+definitions for various specific buffers. Buffer-specific definitions
+override mode-specific definitions, which, in turn, override global
+definitions.
+
+As if all that is not enough, Viper (through its interface to Emacs
+macros) lets the user define keyboard macros that ask for confirmation or
+even prompt the user for input and then continue. To do this, one should
+type @kbd{C-x q} (for confirmation) or @kbd{C-u C-x q} (for prompt).
+For details, @pxref{Kbd Macro Query,,Customization,emacs,The GNU Emacs
+Manual} @refill
+
+When the user finishes defining a macro (which is done by typing @kbd{C-x)} ---
+a departure from Vi), you will be asked whether you want this
+macro to be global, mode-specific, or buffer-specific. You will also be
+given a chance to save the macro in your @file{~/.viper} file.
+This is the easiest way to save a macro and make
+it permanently available. If you work your startup files with bare hands,
+here is how Viper saves the above macro so that it will be
+available in Viper's Insert state (and Replace state) in buffer @code{my-buf}
+only:
+
+@example
+(viper-record-kbd-macro "gg" 'insert-state
+ [l up (meta x) n e x t - l i n e return]
+ "my-buf")
+@end example
+
+@noindent
+To do the same for Vi state and all buffers with the major mode
+@code{cc-mode}, use:
+
+@example
+(viper-record-kbd-macro "gg" 'vi-state
+ [l up (meta x) n e x t - l i n e return]
+ 'cc-mode)
+@end example
+
+@noindent
+Both macro names and macro definitions are vectors of symbols that denote
+keys on the keyboard. Some keys, like @kbd{\}, @kbd{ }, or digit-keys must
+be escaped with a backslash. Modified keys are represented as lists. For
+instance, holding Meta and Control and pressing @kbd{f4} is represented as
+@kbd{(control meta f4)}.
+If all members of a vectors are printable characters (or sequences, such as
+@kbd{\e}, @kbd{\t}, for @key{ESC} and @key{TAB}), then they can also be represented as
+strings:
+
+@example
+(viper-record-kbd-macro "aa" 'vi-state "aaa\e" "my-buffer")
+@end example
+
+@noindent
+Thus, typing @kbd{aa} fast in Vi state will switch Viper to Insert state
+(due to the first @kbd{a}), insert @kbd{aa}, and then it will switch back to Vi
+state. All this will take effect only in the buffer named @code{my-buffer}.
+
+Note that the last argument to @code{viper-record-kbd-macro} must be either a
+string (a buffer name), a symbol representing a major mode, or @code{t};
+the latter says that the macro is to be defined for all buffers
+(which is how macros are defined in original Vi).
+
+For convenience, Viper also lets you define Vi-style macros in its Emacs
+state. There is no Ex command, like @kbd{:map} and @kbd{:map!} for doing
+this, but the user can include such a macro in the @file{~/.viper} file. The
+only thing is that the @code{viper-record-kbd-macro} command should specify
+@code{emacs-state} instead of @code{vi-state} or @code{insert-state}.
+
+The user can get rid of a macro either by using the Ex commands @kbd{:unmap}
+and @kbd{:unmap!} or by issuing a call to @code{viper-unrecord-kbd-macro}.
+The latter is more powerful, since it can delete macros even in
+@code{emacs-state}. However, @code{viper-unrecord-kbd-macro} is usually
+needed only when the user needs to get rid of the macros that are already
+predefined in Viper.
+The syntax is:
+@findex @code{viper-unrecord-kbd-macro}
+@example
+(viper-unrecord-kbd-macro macro state)
+@end example
+@noindent
+The second argument must be @code{vi-state}, @code{insert-state}, or
+@code{emacs-state}. The first argument is a name of a macro. To avoid
+mistakes in specifying names of existing macros, type @kbd{M-x
+viper-describe-kbd-macros} and use a name from the list displayed by this
+command.
+
+If an error occurs during macro definition, Emacs
+aborts the process, and it must be repeated. This is analogous to Vi,
+except that in Vi the user doesn't know there is an error until the macro is
+actually run. All that means that in order for a definition to be
+successful, the user must do some simple planning of the process in
+advance, to avoid errors. For instance, if you want to map @kbd{gg} to
+@kbd{llll} in Vi state, you must make sure that there is enough room on the
+current line. Since @kbd{l} moves the cursor forward, it may signal an
+error on reaching the end of line, which will abort the definition.
+
+These precautions are necessary only when defining macros; they will help
+avoid the need to redo the job. When macros are actually run, an error
+during the execution will simply terminate the current execution
+(but the macro will remain mapped).
+
+A macro name can be a string of characters or a vector of keys.
+The latter makes it possible to define macros bound to, say, double-hits
+on a function key, such as @kbd{up} or @kbd{f13}.
+This is very useful if you run out of function keys on your keyboard; it
+makes Viper macro facility a @emph{keyboard doubler}, so to speak.
+
+Elsewhere (@xref{Keybindings}, for details), we review
+the standard Emacs mechanism for binding function keys to commands.
+For instance,
+
+@example
+(global-set-key [f13] 'repeat-complex-command)
+@end example
+
+@noindent
+binds the key f13 to the Emacs function that repeats the last minibuffer
+command. Under Viper, however, you may still use this key for additional
+purposes, if you bind, say, a double-hitting action for that key to some
+other function. Emacs doesn't allow the user to do that, but Viper does
+this through its keyboard macro facility. To do this, type @kbd{:map }
+first. When you are asked to enter a macro name, hit f13 twice, followed by
+@key{RET} or @key{SPC}.
+
+Emacs will now start the mapping process by actually executing
+Vi and Emacs commands, so that you could see what will happen each time the
+macro is executed. Suppose now we wanted to bind the key sequence
+@kbd{f13 f13} to the command @code{eval-last-sexp}. To accomplish this, we
+can type @kbd{M-x eval-last-sexp} followed by @kbd{C-x )}.
+If you answer positively to Viper's offer to save this macro in @file{~/.viper}
+for future uses, the following will be inserted in that file:
+
+@example
+(viper-record-kbd-macro [f16 f16] 'vi-state
+ [(meta x) e v a l - l a s t - s e x p]
+ 'lisp-interaction-mode)
+@end example
+
+To illustrate the above point, Viper provides two canned macros, which, by
+default, are bound to @kbd{[f12 \1]} and @kbd{[f12 \2]} (invoked by typing
+@kbd{f12} then @kbd{1} and @kbd{2}, respectively). These macros are useful
+shortcuts to Viper's command ring history. The first macro will execute the
+second-last destructive command (the last one is executed by @kbd{.}, as
+usual). The second macro executes the third-last command.
+
+If you need to go deeper into the command history, you will have to use
+other commands, as described earlier in this section; or you can bind,
+say, @kbd{f12 \3} like this:
+
+@example
+(viper-record-kbd-macro [f12 \3] 'vi-state
+ [(meta x) r e p e a t - f r o m - h i s t o r y]
+ t)
+@end example
+
+
+Note that even though the macro uses the function key @kbd{f12}, the key is
+actually free and can still be bound to some Emacs function via
+@code{define-key} or @code{global-set-key}.
+
+
+Viper allows the user to define macro names that are prefixes of other macros.
+For instance, one can define @kbd{[[} and @kbd{[[[[} to be macros.
+If you type the exact sequence of such keys and then pause, Viper will
+execute the right macro. However, if you don't pause and, say, type
+@kbd{[[[[text} then the conflict is resolved as follows. If only one of the
+key sequences, @kbd{[[} or @kbd{[[[[} has a definition applicable to the
+current buffer, then, in fact, there is no conflict and the right macro
+will be chosen. If both have applicable definitions, then the first one
+found will be executed. Usually this is the macro with a shorter name. So,
+in our case, @kbd{[[[[text} will cause the macro @kbd{[[} to be executed
+twice and then the remaining keys, @kbd{t e x t}, will be processed.
+
+When defining macros using @kbd{:map} or @kbd{:map!}, the user enters the
+actually keys to be used to invoke the macro. For instance, you should hit
+the actual key @kbd{f6} if it is to be part of a macro name; you do
+@emph{not} write `f 6'. When entering keys, Viper displays them as strings or
+vectors (e.g., "abc" or [f6 f7 a]). The same holds for unmapping. Hitting
+@key{TAB} while typing a macro name in the @kbd{:unmap} or @kbd{:unmap!} command
+will cause name completion. Completions are displayed as strings or vectors.
+However, as before, you don't actually type ``"'', ``['', or ``]'' that
+appear in the completions. These are meta-symbols that indicate whether
+the corresponding macro name is a vector or a string.
+
+One last difference from Vi: Vi-style keyboard macros cannot be defined in
+terms of other Vi-style keyboard macros (but named Emacs macros are OK).
+More precisely, while defining or executing a macro, the special meaning
+of key sequences (as Vi macros) is ignored.
+This is because it is all too easy to create an infinite loop in this way.
+Since Viper macros are much more powerful than Vi's it is impossible to
+detect such loops. In practice, this is not really a limitation but,
+rather, a feature.
+
+We should also note that Vi macros are disabled in the Minibuffer, which
+helps keep some potential troubles away.
+
+The rate at which the user must type keys in order for them to be
+recognized as a timeout macro is controlled by the variable
+@code{viper-fast-keyseq-timeout}, which defaults to 200 milliseconds.
+
+For the most part, Viper macros defined in @file{~/.viper} can be shared
+between X and TTY modes.
+The problem with TTY may be that the function keys there generate sequences
+of events instead of a single event (as under a window system).
+Emacs maps some of these sequences back to the logical keys
+(e.g., the sequences generated by the arrow keys are mapped to @kbd{up},
+@kbd{left}, etc.). However, not all function keys are mapped in this way.
+Macros that are bound to key sequences that contain such unmapped function
+keys have to be redefined for TTY's (and possibly for every type of TTY you
+may be using). To do this, start Emacs on an appropriate TTY device and
+define the macro using @kbd{:map}, as usual.
+
+@findex @code{viper-describe-kbd-macros}
+Finally, Viper provides a function that conveniently displays all macros
+currently defined. To see all macros along with their definitions, type
+@kbd{M-x viper-describe-kbd-macros}.
+
+@node Commands,,Customization,Top
+@chapter Commands
+
+This section is a semi-automatically bowdlerized version of the Vi
+reference created by @* @samp{maart@@cs.vu.nl} and others. It can be
+found on the Vi archives. This reference has been adapted for Viper.@refill
+
+@menu
+* Groundwork:: Textual Conventions and Viper basics
+* Text Handling:: Moving, Editing, Undoing.
+* Display:: Scrolling.
+* File and Buffer Handling:: Editing, Writing and Quitting.
+* Mapping:: Mapping Keys, Keyboard Macros
+* Shell Commands:: Accessing Shell Commands, Processing Text
+* Options:: Ex options, the @kbd{:set} commands
+* Emacs Related Commands:: Meta Keys, Windows
+* Mouse-bound Commands:: Search and insertion of text
+@end menu
+
+@node Groundwork, Text Handling, Commands, Commands
+@comment node-name, next, previous, up
+@section Groundwork
+
+The VI command set is based on the idea of combining motion commands
+with other commands. The motion command is used as a text region
+specifier for other commands.
+We classify motion commands into @dfn{point commands} and
+@dfn{line commands}.@refill
+
+@cindex point commands
+
+The point commands are:
+
+@quotation
+@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B},
+@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f},
+@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^}
+@end quotation
+
+@cindex line commands
+
+The line commands are:
+
+@quotation
+@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{},
+@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]}
+@end quotation
+@noindent
+
+Text Deletion Commands (@pxref{Deleting Text}), Change commands
+(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands})
+use these commands to describe a region of text to operate on.
+
+@cindex r and R region specifiers
+
+Viper adds two region descriptors, @kbd{r} and @kbd{R}. These describe
+the Emacs regions (@pxref{Basics}), but they are not movement commands.
+
+The command description uses angle brackets @samp{<>} to indicate
+metasyntactic variables, since the normal conventions of using simple
+text can be confusing with Viper where the commands themselves are
+characters. Watch out where @kbd{<} shift commands and @kbd{<count>} are
+mentioned together!!!
+
+@kindex <move>
+@kindex <a-z>
+@kindex <address>
+@cindex <move>
+@cindex <a-z>
+@cindex <address>
+@cindex movements
+
+@samp{<move>} refers to the above movement commands, and @samp{<a-z>}
+refers to registers or textmarkers from @samp{a} to @samp{z}. Note
+that the @samp{<move>} is described by full move commands, that is to
+say they will take counts, and otherwise behave like normal move commands.
+@cindex Ex addresses
+@samp{<address>} refers to Ex line addresses, which include
+
+@table @kbd
+@item .@: <No address>
+Current line
+@item .+n .-n
+Add or subtract for current line
+@item number
+Actual line number, use @kbd{.=} to get the line number
+@item '<a-z>
+Textmarker
+@item $
+Last line
+@item x,y
+Where x and y are one of the above
+@item %
+@cindex % (Ex address)
+For the whole file, same as (1,$).
+@item /<pat>/
+@itemx ?<pat>?
+Next or previous line with pattern <pat>.
+
+Note that the pattern is allowed to contain newline character (inserted as
+@kbd{C-qC-j}). Therefore, one can search for patterns that span several
+lines.
+@end table
+
+@cindex % (Current file)
+Note that @samp{%} is used in Ex commands to mean current file. If you
+want a @samp{%} in your command, it must be escaped as @samp{\%}.
+@cindex # (Previous file)
+Similarly, @samp{#} expands to the previous file. The previous file is
+the first file in @kbd{:args} listing. This defaults to previous window
+in the VI sense if you have one window only.
+
+@kindex <args>
+@kindex <cmd>
+@cindex <args>
+@cindex <cmd>
+@noindent
+Others like @samp{<args> -- arguments}, @samp{<cmd> -- command} etc.
+should be fairly obvious.
+
+@noindent
+Common characters referred to include:
+
+@table @kbd
+@item <sp>
+Space
+@item <ht>
+Tab
+@item <lf>
+Linefeed
+@item <esc>
+Escape
+@item <cr>
+Return, Enter
+@end table
+@cindex <cr>
+@cindex <esc>
+@cindex <lf>
+@cindex <ht>
+@cindex <sp>
+
+@cindex words
+@cindex WORDS
+@cindex char
+@cindex CHAR
+
+We also use @samp{word} for alphanumeric/non-alphanumeric words, and
+@samp{WORD} for whitespace delimited words. @samp{char} refers to any
+ASCII character, @samp{CHAR} to non-whitespace character.
+Brackets @samp{[]} indicate optional parameters; @samp{<count>} also
+optional, usually defaulting to 1. Brackets are elided for
+@samp{<count>} to eschew obfuscation.
+
+Viper's idea of Vi's words is slightly different from Vi. First, Viper
+words understand Emacs symbol tables. Therefore, all symbols declared to be
+alphanumeric in a symbol table can automatically be made part of the Viper
+word. This is useful when, for instance, editing text containing European,
+Cyrillic, Japanese, etc., texts.
+
+Second, Viper lets you depart from Vi's idea of a word by changing the a
+syntax preference via the customization widget (the variable
+@code{viper-syntax-preference}) or by executing
+@code{viper-set-syntax-preference} interactively.
+
+By default, Viper syntax preference is @code{reformed-vi}, which means that
+Viper considers only those symbols to be part of a word that are specified
+as word-symbols by the current Emacs syntax table (which may be different
+for different major modes) plus the underscore symbol @kbd{_}, minus the
+symbols that are not considered words in Vi (e.g., `,',;, etc.), but may be
+considered as word-symbols by various Emacs major modes. Reformed-Vi works
+very close to Vi, and it also recognizes words in other
+alphabets. Therefore, this is the most appropriate mode for editing text
+and is likely to fit all your needs.
+
+You can also set Viper syntax preference to @code{strict-vi}, which would
+cause Viper to view all non-English letters as non-word-symbols.
+
+You can also specify @code{emacs} as your preference, which would
+make Viper use exactly the same notion of a word as Emacs does. In
+particular, the underscore may not be part of a word in some major modes.
+
+Finally, if @code{viper-syntax-preference} is set to @code{extended}, Viper
+words would consist of characters that are classified as alphanumeric
+@emph{or} as parts of symbols. This is convenient for editing programs.
+
+@code{viper-syntax-preference} is a local variable, so it can have different
+values for different major modes. For instance, in programming modes it can
+have the value @code{extended}. In text modes where words contain special
+characters, such as European (non-English) letters, Cyrillic letters, etc.,
+the value can be @code{reformed-vi} or @code{emacs}.
+If you consider using different syntactic preferences for different major
+modes, you should execute, for example,
+
+@example
+(viper-set-syntax-preference nil "extended")
+@end example
+
+in the appropriate major mode hooks.
+
+@vindex @code{viper-syntax-preference}
+@findex @code{viper-set-syntax-preference}
+@cindex syntax table
+
+
+
+The above discussion concerns only the movement commands. In regular
+expressions, words remain the same as in Emacs. That is, the expressions
+@code{\w}, @code{\>}, @code{\<}, etc., use Emacs' idea of what is a word,
+and they don't look into the value of variable
+@code{viper-syntax-preference}. This is because Viper avoids changing
+syntax tables in order to not thwart the various major modes that set these
+tables.
+
+The usual Emacs convention is used to indicate Control Characters, i.e
+C-h for Control-h. @emph{Do not confuse this to mean the separate
+characters C - h!!!} The @kbd{^} is itself, never used to indicate a
+Control character.
+
+Finally, we note that Viper's Ex-style commands can be made to work on the
+current Emacs region. This is done by typing a digit argument before
+@kbd{:}. For instance, typing @kbd{1:} will propmt you with something like
+@emph{:123,135}, assuming that the current region starts at line 123 and
+ends at line 135. There is no need to type the line numbers, since Viper
+inserts them automatically in front of the Ex command.
+@cindex Ex commands
+
+@node Text Handling, Display, Groundwork, Commands
+@section Text Handling
+
+@menu
+* Move Commands:: Moving, Searching
+* Marking:: Textmarkers in Viper and the Emacs Mark.
+* Appending Text:: Text insertion, Shifting, Putting
+* Editing in Insert State:: Autoindent, Quoting etc.
+* Deleting Text:: Deleting
+* Changing Text:: Changing, Replacement, Joining
+* Search and Replace:: Searches, Query Replace, Pattern Commands
+* Yanking:: Yanking, Viewing Registers
+* Undoing:: Multiple Undo, Backups
+@end menu
+
+@node Move Commands,Marking,,Text Handling
+@subsection Move Commands
+
+@cindex movement commands
+@cindex searching
+@cindex textmarkers
+@cindex markers
+@cindex column movement
+@cindex paragraphs
+@cindex headings
+@cindex sections
+@cindex sentences
+@cindex matching parens
+@cindex paren matching
+
+@table @kbd
+@item <count> h C-h
+<count> chars to the left.
+@item <count> j <lf> C-n
+<count> lines downward.
+@item <count> l <sp>
+<count> chars to the right.
+@item <count> k C-p
+<count> lines upward.
+@item <count> $
+To the end of line <count> from the cursor.
+@item <count> ^
+To the first CHAR <count> - 1 lines lower.
+@item <count> -
+To the first CHAR <count> lines higher.
+@item <count> + <cr>
+To the first CHAR <count> lines lower.
+@item 0
+To the first char of the line.
+@item <count> |
+To column <count>
+@item <count> f<char>
+<count> <char>s to the right (find).
+@item <count> t<char>
+Till before <count> <char>s to the right.
+@item <count> F<char>
+<count> <char>s to the left.
+@item <count> T<char>
+Till after <count> <char>s to the left.
+@item <count> ;
+Repeat latest @kbd{f t F T} <count> times.
+@item <count> ,
+Repeat latest @kbd{f t F T}
+<count> times in opposite direction.
+@item <count> w
+<count> words forward.
+@item <count> W
+<count> WORDS forward.
+@item <count> b
+<count> words backward.
+@item <count> B
+<count> WORDS backward.
+@item <count> e
+To the end of word <count> forward.
+@item <count> E
+To the end of WORD <count> forward.
+@item <count> G
+Go to line <count> (default end-of-file).
+@item <count> H
+To line <count> from top of the screen (home).
+@item <count> L
+To line <count> from bottom of the screen (last).
+@item M
+To the middle line of the screen.
+@item <count> )
+<count> sentences forward.
+@item <count> (
+<count> sentences backward.
+@item <count> @}
+<count> paragraphs forward.
+@item <count> @{
+<count> paragraphs backward.
+@item <count> ]]
+To the <count>th heading.
+@item <count> [[
+To the <count>th previous heading.
+@item <count> []
+To the end of <count>th heading.
+@item m<a-z>
+Mark the cursor position with a letter.
+@item `<a-z>
+To the mark.
+@item '<a-z>
+To the first CHAR of the line with the mark.
+@item [<a-z>
+Show contents of textmarker.
+@item ]<a-z>
+Show contents of register.
+@item ``
+To the cursor position before the latest absolute
+jump (of which are examples @kbd{/} and @kbd{G}).
+@item ''
+To the first CHAR of the line on which the cursor
+was placed before the latest absolute jump.
+@item <count> /<string>
+To the <count>th occurrence of <string>.
+@item <count> /<cr>
+To the <count>th occurrence of <string> from previous @kbd{/ or ?}.
+@item <count> ?<string>
+To the <count>th previous occurrence of <string>.
+@item <count> ?<cr>
+To the <count>th previous occurrence of <string> from previous @kbd{?@: or /}.
+@item n
+Repeat latest @kbd{/} @kbd{?} (next).
+@item N
+Repeat latest search in opposite direction.
+@item C-c /
+Without a prefix argument, this command toggles
+case-sensitive/case-insensitive search modes and plain vanilla/regular
+expression search. With the prefix argument 1, i.e.,
+@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2,
+toggles plain vanilla search and search using
+regular expressions. @xref{Viper Specials}, for alternative ways to invoke
+this function.
+@cindex vanilla search
+@cindex case-sensitive search
+@cindex case-insensitive search
+@item %
+Find the next bracket/parenthesis/brace and go to its match.
+By default, Viper ignores brackets/parentheses/braces that occur inside
+parentheses. You can change this by setting
+@code{viper-parse-sexp-ignore-comments} to nil in your @file{.viper} file.
+This option can also be toggled interactively if you quickly hit @kbd{%%%}.
+
+This latter feature is implemented as a vi-style keyboard macro. If you
+don't want this macro, put
+
+@example
+(viper-set-parsing-style-toggling-macro 'undefine)
+@end example
+@findex @code{viper-set-parsing-style-toggling-macro}
+
+in your @file{~/.viper} file.
+
+@end table
+@kindex @kbd{%}
+@kindex @kbd{C-c /}
+@kindex @kbd{N}
+@kindex @kbd{n}
+@kindex @kbd{?<cr>}
+@kindex @kbd{/<cr>}
+@kindex @kbd{?<string>}
+@kindex @kbd{/<string>}
+@kindex @kbd{''}
+@kindex @kbd{``}
+@kindex @kbd{]<a-z>}
+@kindex @kbd{[<a-z>}
+@kindex @kbd{'<a-z>}
+@kindex @kbd{`<a-z>}
+@kindex @kbd{m<a-z>}
+@kindex @kbd{[]}
+@kindex @kbd{[[}
+@kindex @kbd{]]}
+@kindex @kbd{@{}
+@kindex @kbd{@}}
+@kindex @kbd{(}
+@kindex @kbd{)}
+@kindex @kbd{M}
+@kindex @kbd{L}
+@kindex @kbd{H}
+@kindex @kbd{G}
+@kindex @kbd{E}
+@kindex @kbd{e}
+@kindex @kbd{B}
+@kindex @kbd{b}
+@kindex @kbd{W}
+@kindex @kbd{w}
+@kindex @kbd{,}
+@kindex @kbd{;}
+@kindex @kbd{T<char>}
+@kindex @kbd{F<char>}
+@kindex @kbd{t<char>}
+@kindex @kbd{f<char>}
+@kindex @kbd{|}
+@kindex @kbd{0}
+@kindex @kbd{<cr>}
+@kindex @kbd{+}
+@kindex @kbd{-}
+@kindex @kbd{^}
+@kindex @kbd{$}
+@kindex @kbd{C-p}
+@kindex @kbd{<lf>}
+@kindex @kbd{<sp>}
+@kindex @kbd{C-n}
+@kindex @kbd{C-h}
+@kindex @kbd{h}
+@kindex @kbd{j}
+@kindex @kbd{k}
+@kindex @kbd{l}
+@vindex @code{viper-parse-sexp-ignore-comments}
+
+@node Marking,Appending Text,Move Commands,Text Handling
+@subsection Marking
+
+Emacs mark is referred to in the region specifiers @kbd{r} and @kbd{R}.
+@xref{Emacs Preliminaries}, and @xref{Basics}, for explanation. Also
+see @ref{Mark,,Mark,emacs,The GNU Emacs manual}, for an explanation of
+the Emacs mark ring.
+
+@cindex marking
+
+@table @kbd
+@item m<a-z>
+Mark the current file and position with the specified letter.
+@item m .
+Set the Emacs mark (@pxref{Emacs Preliminaries}) at point.
+@item m <
+Set the Emacs mark at beginning of buffer.
+@item m >
+Set the Emacs mark at end of buffer.
+@item m ,
+Jump to the Emacs mark.
+@item :mark <char>
+Mark position with text marker named <char>. This is an Ex command.
+@item :k <char>
+Same as @kbd{:mark}.
+@item ``
+Exchange point and mark.
+@item ''
+Exchange point and mark and go to the first CHAR on line.
+@item '<a-z>
+Go to specified Viper mark.
+@item
+Go to specified Viper mark and go to the first CHAR on line.
+@end table
+@kindex @kbd{m<a-z>}
+@kindex @kbd{m.}
+@kindex @kbd{m>}
+@kindex @kbd{m<}
+@kindex @kbd{m,}
+@findex @kbd{:mark}
+@findex @kbd{:k}
+@kindex @kbd{''}
+@kindex @kbd{``}
+@kindex @kbd{`<a-z>}
+@kindex @kbd{'<a-z>}
+
+@node Appending Text, Editing in Insert State, Marking,Text Handling
+@subsection Appending Text
+
+@xref{Options}, to see how to change tab and shiftwidth size. See the GNU
+Emacs manual, or try @kbd{C-ha tabs} (If you have turned Emacs help on).
+Check out the variable @code{indent-tabs-mode} to put in just spaces.
+Also see options for word-wrap.
+
+@cindex inserting
+@cindex appending
+@cindex paste
+@cindex put
+
+@table @kbd
+@item <count> a
+<count> times after the cursor.
+@item <count> A
+<count> times at the end of line.
+@item <count> i
+<count> times before the cursor (insert).
+@item <count> I
+<count> times before the first CHAR of the line
+@item <count> o
+On a new line below the current (open).
+The count is only useful on a slow terminal.
+@item <count> O
+On a new line above the current.
+The count is only useful on a slow terminal.
+@item <count> ><move>
+Shift the lines described by <count><move> one
+shiftwidth to the right (layout!).
+@item <count> >>
+Shift <count> lines one shiftwidth to the right.
+@item <count> ["<a-z1-9>]p
+Put the contents of the (default undo) buffer
+<count> times after the cursor. The register will
+be automatically down-cased.
+@item <count> ["<a-z1-9>]P
+Put the contents of the (default undo) buffer
+<count> times before the cursor. The register will
+@item [<a-z>
+Show contents of textmarker.
+@item ]<a-z>
+Show contents of register.
+@item <count> .
+Repeat previous command <count> times. For destructive
+commands as well as undo.
+@item f1 1 and f1 2
+While @kbd{.} repeats the last destructive command,
+these two macros repeat the second-last and the third-last destructive
+commands. @xref{Vi Macros}, for more information on Vi macros.
+@item C-c M-p and C-c M-n
+In Vi state,
+these commands help peruse the history of Vi's destructive commands.
+Successive typing of @kbd{C-c M-p} causes Viper to search the history in
+the direction
+of older commands, while hitting @kbd{C-c M-n} does so in reverse
+order. Each command in the history is displayed in the Minibuffer. The
+displayed command can
+then be executed by typing `@kbd{.}'.
+
+Since typing the above sequences of keys may be tedious, the
+functions doing the perusing can be bound to unused keyboard keys in the
+@file{~/.viper} file. @xref{Viper Specials}, for details.
+@end table
+@kindex @kbd{C-c M-p}
+@kindex @kbd{C-c M-n}
+@kindex @kbd{.}
+@kindex @kbd{]<a-z>}
+@kindex @kbd{[<a-z>}
+@kindex @kbd{P}
+@kindex @kbd{p}
+@kindex @kbd{"<a-z1-9>p}
+@kindex @kbd{"<a-z1-9>P}
+@kindex @kbd{>>}
+@kindex @kbd{><move>}
+@kindex @kbd{O}
+@kindex @kbd{o}
+@kindex @kbd{i}
+@kindex @kbd{A}
+@kindex @kbd{a}
+
+@node Editing in Insert State, Deleting Text, Appending Text,Text Handling
+@subsection Editing in Insert State
+
+Minibuffer can be edited similarly to Insert state, and you can switch
+between Insert/Replace/Vi states at will.
+Some users prefer plain Emacs feel in the Minibuffer. To this end, set
+@var{viper-vi-style-in-minibuffer} to @code{nil}.
+
+@cindex Insert state
+
+@table @kbd
+@item C-v
+Deprive the next char of its special meaning (quoting).
+@item C-h
+One char back.
+@item C-w
+One word back.
+@item C-u
+Back to the begin of the change on the
+current line.
+
+@end table
+@kindex @kbd{C-u}
+@kindex @kbd{C-w}
+@kindex @kbd{C-v}
+
+@node Deleting Text, Changing Text, Editing in Insert State, Text Handling
+@subsection Deleting Text
+
+
+There is one difference in text deletion that you should be
+aware of. This difference comes from Emacs and was adopted in Viper
+because we find it very useful. In Vi, if you delete a line, say, and then
+another line, these two deletions are separated and are put back
+separately if you use the @samp{p} command. In Emacs (and Viper), successive
+series of deletions that are @emph{not interrupted} by other commands are
+lumped together, so the deleted text gets accumulated and can be put back
+as one chunk. If you want to break a sequence of deletions so that the
+newly deleted text could be put back separately from the previously deleted
+text, you should perform a non-deleting action, e.g., move the cursor one
+character in any direction.
+
+@cindex shifting text
+
+@table @kbd
+@item <count> x
+Delete <count> chars under and after the cursor.
+@item <count> X
+Delete <count> chars before the cursor.
+@item <count> d<move>
+Delete from point to endpoint of <count><move>.
+@item <count> dd
+Delete <count> lines.
+@item D
+The rest of the line.
+@item <count> <<move>
+Shift the lines described by <count><move> one
+shiftwidth to the left (layout!).
+@item <count> <<
+Shift <count> lines one shiftwidth to the left.
+@end table
+@kindex @kbd{<<}
+@kindex @kbd{<<move>}
+@kindex @kbd{D}
+@kindex @kbd{dd}
+@kindex @kbd{d<move>}
+@kindex @kbd{X}
+@kindex @kbd{x}
+
+@node Changing Text, Search and Replace, Deleting Text,Text Handling
+@subsection Changing Text
+
+@cindex joining lines
+@cindex changing case
+@cindex quoting regions
+@cindex substitution
+
+@table @kbd
+@item <count> r<char>
+Replace <count> chars by <char> - no <esc>.
+@item <count> R
+Overwrite the rest of the line,
+appending change @var{count - 1} times.
+@item <count> s
+Substitute <count> chars.
+@item <count> S
+Change <count> lines.
+@item <count> c<move>
+Change from begin to endpoint of <count><move>.
+@item <count> cc
+Change <count> lines.
+@item <count> C
+The rest of the line and <count> - 1 next lines.
+@item <count> =<move>
+Reindent the region described by move.
+@item <count> ~
+Switch lower and upper cases.
+@item <count> J
+Join <count> lines (default 2).
+@item :[x,y]s/<pat>/<repl>/<f>
+Substitute (on lines x through y) the pattern
+<pat> (default the last pattern) with <repl>. Useful
+flags <f> are @samp{g} for @samp{global} (i.e.@: change every
+non-overlapping occurrence of <pat>) and @samp{c} for
+@samp{confirm} (type @samp{y} to confirm a particular
+substitution, else @samp{n} ). Instead of @kbd{/} any
+punctuation CHAR unequal to <space> <tab> and <lf> can be used as
+delimiter.
+
+In Emacs, @samp{\&} stands for the last matched expression, so
+@kbd{s/[ab]+/\&\&/} will double the string matched by @kbd{[ab]}.
+Viper doesn't treat @samp{&} specially, unlike Vi: use @samp{\&} instead.
+
+Note: @emph{The newline character (inserted as @kbd{C-qC-j})
+can be used in <repl>}.
+@item :[x,y]copy [z]
+Copy text between @kbd{x} and @kbd{y} to the position after @kbd{z}.
+@item :[x,y]t [z]
+Same as @kbd{:copy}.
+@item :[x,y]move [z]
+Move text between @kbd{x} and @kbd{y} to the position after @kbd{z}.
+@item &
+Repeat latest Ex substitute command, e.g.
+@kbd{:s/wrong/right}.
+@item C-c /
+Toggle case-sensitive search. With prefix argument, toggle vanilla/regular
+expression search.
+@item #c<move>
+Change upper-case characters in the region to lower-case.
+@item #C<move>
+Change lower-case characters in the region to upper-case.
+@item #q<move>
+Insert specified string at the beginning of each line in the region
+@item C-c M-p and C-c M-n
+In Insert and Replace states, these keys are bound to commands that peruse
+the history of the text
+previously inserted in other insert or replace commands. By repeatedly typing
+@kbd{C-c M-p} or @kbd{C-c M-n}, you will cause Viper to
+insert these previously used strings one by one.
+When a new string is inserted, the previous one is deleted.
+
+In Vi state, these keys are bound to functions that peruse the history of
+destructive Vi commands.
+@xref{Viper Specials}, for details.
+@end table
+@kindex @kbd{C-c M-p}
+@kindex @kbd{C-c M-n}
+@kindex @kbd{#q<move> }
+@kindex @kbd{#C<move>}
+@kindex @kbd{#c<move>}
+@kindex @kbd{&}
+@kindex @kbd{\&}
+@findex @kbd{:substitute/<pat>/<repl>/<f>}
+@findex @kbd{:s/<pat>/<repl>/<f>}
+@findex @kbd{:copy [z]}
+@findex @kbd{:t [z]}
+@findex @kbd{:move [z]}
+@kindex @kbd{J}
+@kindex @kbd{~}
+@kindex @kbd{=<move>}
+@kindex @kbd{C}
+@kindex @kbd{cc}
+@kindex @kbd{c<move>}
+@kindex @kbd{S}
+@kindex @kbd{s}
+@kindex @kbd{R}
+@kindex @kbd{r<char>}
+
+@node Search and Replace, Yanking, Changing Text,Text Handling
+@subsection Search and Replace
+
+@xref{Groundwork}, for Ex address syntax. @xref{Options}, to see how to
+get literal (non-regular-expression) search and how to stop search from
+wrapping around.
+
+@table @kbd
+@item <count> /<string>
+To the <count>th occurrence of <string>.
+@item <count> ?<string>
+To the <count>th previous occurrence of <string>.
+@item <count> g<move>
+Search for the text described by move. (off by default)
+@item n
+Repeat latest @kbd{/} @kbd{?} (next).
+@item N
+Idem in opposite direction.
+@item %
+Find the next bracket and go to its match
+@item :[x,y]g/<string>/<cmd>
+@cindex text processing
+Search globally [from line x to y] for <string>
+and execute the Ex <cmd> on each occurrence.
+@item :[x,y]v/<string>/<cmd>
+Execute <cmd> on the lines that don't match.
+@item #g<move>
+Execute the last keyboard macro for each line in the region.
+@xref{Macros and Registers}, for more info.
+@item Q
+Query Replace.
+@item :ta <name>
+Search in the tags file where <name> is defined (file, line), and go to it.
+@item :[x,y]s/<pat>/<repl>/<f>
+Substitute (on lines x through y) the pattern <pat> (default the last
+pattern) with <repl>. Useful
+flags <f> are @samp{g} for @samp{global} (i.e.@: change every
+non-overlapping occurrence of <pat>) and @samp{c} for
+@samp{confirm} (type @samp{y} to confirm a particular
+substitution, else @samp{n}). Instead of @kbd{/} any
+punctuation character other than <space> <tab> and <lf> can be used as
+delimiter.
+
+Note: @emph{The newline character (inserted as @kbd{C-qC-j})
+can be used in <repl>}.
+@item &
+Repeat latest Ex substitute command, e.g.@: @kbd{:s/wrong/right}.
+@item :global /<pattern>/<ex-command>
+@itemx :g /<pattern>/<ex-command>
+Execute <ex-command> on all lines that match <pattern>.
+@item :vglobal /<pattern>/<ex-command>
+@itemx :v /<pattern>/<ex-command>
+Execute <ex-command> on all lines that do not match <pattern>.
+@end table
+@kindex @kbd{&}
+@findex @kbd{:substitute/<pat>/<repl>/<f>}
+@kindex @kbd{Q}
+@kindex @kbd{#g<move>}
+@findex @kbd{:v}
+@findex @kbd{:g}
+@findex @kbd{:global}
+@findex @kbd{:vglobal}
+@findex @kbd{:tag <name>}
+@kindex @kbd{%}
+@kindex @kbd{N}
+@kindex @kbd{n}
+@kindex @kbd{g<move>}
+@kindex @kbd{?<string>}
+@kindex @kbd{/<string>}
+
+@node Yanking,Undoing,Search and Replace,Text Handling
+@subsection Yanking
+
+@cindex cut and paste
+@cindex paste
+
+@table @kbd
+@item <count> y<move>
+Yank from begin to endpoint of <count><move>.
+@item <count> "<a-z>y<move>
+Yank from begin to endpoint of <count><move> to register.
+@item <count> "<A-Z>y<move>
+Yank from begin to endpoint of <count><move> and append
+to register.
+@item <count> yy
+<count> lines.
+@item <count> Y
+Idem (should be equivalent to @kbd{y$} though).
+@item m<a-z>
+Mark the cursor position with a letter.
+@item [<a-z>
+Show contents of textmarker.
+@item ]<a-z>
+Show contents of register.
+@item <count> ["<a-z1-9>]p
+Put the contents of the (default undo) buffer
+<count> times after the cursor. The register will
+be automatically down-cased.
+@item <count> ["<a-z1-9>]P
+Put the contents of the (default undo) buffer
+<count> times before the cursor. The register will
+@end table
+@kindex @kbd{P}
+@kindex @kbd{p}
+@kindex @kbd{"<a-z1-9>p}
+@kindex @kbd{"<a-z1-9>P}
+@kindex @kbd{]<a-z>}
+@kindex @kbd{[<a-z>}
+@kindex @kbd{m<a-z>}
+@kindex @kbd{Y}
+@kindex @kbd{yy}
+@kindex @kbd{"<A-Z>y<move>}
+@kindex @kbd{"<a-z>y<move>}
+@kindex @kbd{y<move>}
+@kindex @kbd{yank}
+@findex @kbd{:yank}
+
+@node Undoing,, Yanking,Text Handling
+@subsection Undoing
+
+@cindex undo
+@cindex backup files
+
+@table @kbd
+@item u U
+Undo the latest change.
+@item .
+Repeat undo.
+@item :q!
+Quit Vi without writing.
+@item :e!
+Re-edit a messed-up file.
+@item :rec
+Recover file from autosave. Viper also creates backup files
+that have a @samp{~} appended to them.
+@end table
+@findex @kbd{:rec}
+@findex @kbd{:e!}
+@findex @kbd{:q!}
+@kindex @kbd{.}
+@kindex @kbd{U}
+@kindex @kbd{u}
+
+@node Display, File and Buffer Handling, Text Handling, Commands
+@section Display
+
+@cindex scrolling
+
+@table @kbd
+@item C-g
+At user level 1,
+give file name, status, current line number
+and relative position.@*
+At user levels 2 and higher, abort the current command.
+@item C-c g
+Give file name, status, current line number and relative position -- all
+user levels.
+@item C-l
+Refresh the screen.
+@item <count> C-e
+Expose <count> more lines at bottom, cursor stays put (if possible).
+@item <count> C-y
+Expose <count> more lines at top, cursor stays put (if possible).
+@item <count> C-d
+Scroll <count> lines downward (default the number of the previous scroll;
+initialization: half a page).
+@item <count> C-u
+Scroll <count> lines upward (default the number of the previous scroll;
+initialization: half a page).
+@item <count> C-f
+<count> pages forward.
+@item <count> C-b
+<count> pages backward (in older versions @kbd{C-b} only works without count).
+@item <count> z<cr>
+@item zH
+Put line <count> at the top of the window (default the current line).
+@item <count> z-
+@item zL
+Put line <count> at the bottom of the window
+(default the current line).
+@item <count> z.
+@item zM
+Put line <count> in the center of the window
+(default the current line).
+@end table
+@kindex @kbd{zM}
+@kindex @kbd{zL}
+@kindex @kbd{zH}
+@kindex @kbd{z<cr>}
+@kindex @kbd{z.}
+@kindex @kbd{z-}
+@kindex @kbd{z<cr>}
+@kindex @kbd{C-b}
+@kindex @kbd{C-f}
+@kindex @kbd{C-u}
+@kindex @kbd{C-d}
+@kindex @kbd{C-y}
+@kindex @kbd{C-e}
+@kindex @kbd{C-l}
+@kindex @kbd{C-g}
+
+
+@node File and Buffer Handling, Mapping, Display,Commands
+@section File and Buffer Handling
+
+@cindex multiple files
+
+In all file handling commands, space should be typed before entering the file
+name. If you need to type a modifier, such as @kbd{>>} or @kbd{!}, don't
+put any space between the command and the modifier.
+
+@table @kbd
+@item :q
+Quit buffer except if modified.
+@item :q!
+Quit buffer without checking. In Viper, these two commands
+are identical. Confirmation is required if exiting modified buffers that
+visit files.
+@item :suspend
+@item :stop
+Suspend Viper
+@item :[x,y] w
+Write the file. Viper makes sure that a final newline is always added to
+any file where this newline is missing. This is done by setting Emacs
+variable @code{require-final-newline} to @code{t}. If you don't like this
+feature, use @code{setq-default} to set @code{require-final-newline} to
+@code{nil}. This must be done in @file{.viper} file.
+@item :[x,y] w <name>
+Write to the file <name>.
+@item :[x,y] w>> <name>
+Append the buffer to the file <name>. There should be no space between
+@kbd{w} and @kbd{>>}. Type space after the @kbd{>>} and see what happens.
+@item :w!@: <name>
+Overwrite the file <name>. In Viper, @kbd{:w} and @kbd{:w!} are identical.
+Confirmation is required for writing to an existing file (if this is not
+the file the buffer is visiting) or to a read-only file.
+@item :x,y w <name>
+Write lines x through y to the file <name>.
+@item :wq
+Write the file and kill buffer.
+@item :r <file> [<file> ...]
+Read file into a buffer, inserting its contents after the current line.
+@item :xit
+Same as @kbd{:wq}.
+@item :Write
+@itemx :W
+Save all unsaved buffers, asking for confirmation.
+@item :WWrite
+@itemx :WW
+Like @kbd{W}, but without asking for confirmation.
+@item ZZ
+Save current buffer and kill it. If user level is 1, then save all files
+and kill Emacs. Killing Emacs is the wrong way to use it, so you should
+switch to higher user levels as soon as possible.
+@item :x [<file>]
+Save and kill buffer.
+@item :x!@: [<file>]
+@kbd{:w![<file>]} and @kbd{:q}.
+@item :pre
+Preserve the file -- autosave buffers.
+@item :rec
+Recover file from autosave.
+@item :f
+Print file name and lines.
+@item :cd [<dir>]
+Set the working directory to <dir> (default home directory).
+@item :pwd
+Print present working directory.
+@item :e [+<cmd>] <files>
+Edit files. If no filename is given, edit the file visited by the current
+buffer. If buffer was modified or the file changed on disk, ask for
+confirmation. Unlike Vi, Viper allows @kbd{:e} to take multiple arguments.
+The first file is edited the same way as in Vi. The rest are visited
+in the usual Emacs way.
+@item :e!@: [+<cmd>] <files>
+Re-edit file. If no filename, re-edit current file.
+In Viper, unlike Vi, @kbd{e!} is identical to @kbd{:e}. In both cases, the
+user is asked to confirm if there is a danger of discarding changes to a
+buffer.
+@item :q!
+Quit Vi without writing.
+@item C-^
+Edit the alternate (normally the previous) file.
+@item :rew
+Obsolete
+@item :args
+List files not shown anywhere with counts for next
+@item :n [count] [+<cmd>] [<files>]
+Edit <count> file, or edit files. The count comes from @kbd{:args}.
+@item :N [count] [+<cmd>] [<files>]
+Like @kbd{:n}, but the meaning of the variable
+@var{ex-cycle-other-window} is reversed.
+@item :b
+Switch to another buffer. If @var{ex-cycle-other-window} is @code{t},
+switch in another window. Buffer completion is supported.
+@item :B
+Like @kbd{:b}, but the meaning of @var{ex-cycle-other-window} is reversed.
+@item :<address>r <name>
+Read the file <name> into the buffer after the line <address>.
+@item v, V, C-v
+Edit a file in current or another window, or in another frame. File name
+is typed in Minibuffer. File completion and history are supported.
+@end table
+@kindex @kbd{v}
+@kindex @kbd{V}
+@findex @kbd{:args}
+@findex @kbd{:rew}
+@kindex @kbd{C-^}
+@findex @kbd{:e!@: [<files>]}
+@findex @kbd{:e [<files>]}
+@findex @kbd{:edit [<files>]}
+@findex @kbd{:edit!@: [<files>]}
+@findex @kbd{:q!}
+@findex @kbd{:q}
+@findex @kbd{:quit}
+@findex @kbd{:quit!}
+@findex @kbd{:f}
+@findex @kbd{:rec}
+@findex @kbd{:r}
+@findex @kbd{:read}
+@findex @kbd{:pre}
+@kindex @kbd{ZZ}
+@findex @kbd{:wq}
+@findex @kbd{:w <file>}
+@findex @kbd{:w!@: <file>}
+@findex @kbd{:w >> <file>}
+@findex @kbd{:write <file>}
+@findex @kbd{:write!@: <file>}
+@findex @kbd{:write >> <file>}
+@findex @kbd{:W}
+@findex @kbd{:WW}
+@findex @kbd{:Write}
+@findex @kbd{:WWrite}
+@findex @kbd{:WWrite}
+@findex @kbd{:x}
+@findex @kbd{:x!}
+@findex @kbd{:suspend}
+@findex @kbd{:stop}
+@findex @kbd{:n [<count> | <file>]}
+@findex @kbd{:cd [<dir>]}
+@findex @kbd{:pwd}
+
+@node Mapping, Shell Commands, File and Buffer Handling, Commands
+@section Mapping
+
+@cindex keybindings
+@cindex key mapping
+
+@table @kbd
+@item :map <string>
+Start defining a Vi-style keyboard macro.
+For instance, typing
+@kbd{:map www} followed by @kbd{:!wc %} and then typing @kbd{C-x )}
+will cause @kbd{www} to run wc on
+current file (Vi replaces @samp{%} with the current file name).
+@item C-x )
+Finish defining a keyboard macro.
+In Viper, this command completes the process of defining all keyboard
+macros, whether they are Emacs-style or Vi-style.
+This is a departure from Vi, needed to allow WYSIWYG mapping of
+keyboard macros and to permit the use of function keys and arbitrary Emacs
+functions in the macros.
+@item :unmap <string>
+Deprive <string> of its mappings in Vi state.
+@item :map!@: <string>
+Map a macro for Insert state.
+@item :unmap!@: <string>
+Deprive <string> of its mapping in Insert state (see @kbd{:unmap}).
+@item @@<a-z>
+In Vi state,
+execute the contents of register as a command.
+@item @@@@
+In Vi state,
+repeat last register command.
+@item @@#
+In Vi state,
+begin keyboard macro. End with @@<a-z>. This will
+put the macro in the proper register. Register will
+be automatically down-cased.
+@xref{Macros and Registers}, for more info.
+@item @@!<a-z>
+In Vi state,
+yank anonymous macro to register
+@item *
+In Vi state,
+execute anonymous macro (defined by C-x( and C-x )).
+@item C-x e
+Like @kbd{*}, but works in all Viper states.
+@item #g<move>
+Execute the last keyboard macro for each line in the region.
+@xref{Macros and Registers}, for more info.
+@item [<a-z>
+Show contents of textmarker.
+@item ]<a-z>
+Show contents of register.
+@end table
+@kindex @kbd{]<a-z>}
+@kindex @kbd{[<a-z>}
+@kindex @kbd{#g<move>}
+@kindex @kbd{*}
+@kindex @kbd{@@!<a-z>}
+@kindex @kbd{@@#}
+@kindex @kbd{@@@@}
+@kindex @kbd{@@<a-z>}
+@findex @kbd{:unmap <char>}
+@findex @kbd{:map <char> <seq>}
+@findex @kbd{:unmap!@: <char>}
+@findex @kbd{:map!@: <char> <seq>}
+
+@node Shell Commands, Options, Mapping, Commands
+@section Shell Commands
+
+@cindex % (Current file)
+
+Note that % is used in Ex commands to mean current file. If you want a %
+in your command, it must be escaped as @samp{\%}.
+@cindex % (Ex address)
+However if % is the
+first character, it stands as the address for the whole file.
+@cindex # (Previous file)
+Similarly, @samp{#} expands to the previous file. The previous file is
+the first file in @kbd{:args} listing. This defaults
+to the previous file in the VI sense if you have one window.@refill
+
+@cindex shell commands
+
+@table @kbd
+@item :sh
+Execute a subshell in another window
+@item :[x,y]!<cmd>
+Execute a shell <cmd> [on lines x through y;
+% is replace by current file, \% is changed to %
+@item :[x,y]!!@: [<args>]
+Repeat last shell command [and append <args>].
+@item :!<cmd>
+Just execute command and display result in a buffer.
+@item :!!@: <args>
+Repeat last shell command and append <args>
+@item <count> !<move><cmd>
+The shell executes <cmd>, with standard
+input the lines described by <count><move>,
+next the standard output replaces those lines
+(think of @samp{cb}, @samp{sort}, @samp{nroff}, etc.).
+@item <count> !!<cmd>
+Give <count> lines as standard input to the
+shell <cmd>, next let the standard output
+replace those lines.
+@item :[x,y] w !<cmd>
+Let lines x to y be standard input for <cmd>
+(notice the <sp> between @kbd{w} and @kbd{!}).
+@item :<address>r !<cmd>
+Put the output of <cmd> after the line <address> (default current).
+@item :<address>r <name>
+Read the file <name> into the buffer after the line <address> (default
+current).
+@end table
+@findex @kbd{:<address>r <name>}
+@findex @kbd{:<address>r !<cmd>}
+@findex @kbd{!<cmd>}
+@findex @kbd{!!<cmd>}
+@findex @kbd{!<move><cmd>}
+@findex @kbd{:w !<cmd>}
+@findex @kbd{:x,y w !<cmd>}
+@findex @kbd{:!!@: <args>}
+@findex @kbd{:!<cmd>}
+@findex @kbd{:sh}
+
+@node Options,Emacs Related Commands,Shell Commands,Commands
+@section Options
+
+@cindex Vi options
+
+@table @kbd
+@item autoindent
+@itemx ai
+@cindex autoindent
+autoindent -- In append mode after a <cr> the
+cursor will move directly below the first
+character on the previous line.
+This setting affects the current buffer only.
+@item autoindent-global
+@itemx ai-global
+Same as `autoindent', but affects all buffers.
+@item noautoindent
+@itemx noai
+Cancel autoindent.
+@item noautoindent-global
+@itemx noai-g
+Cancel autoindent-global.
+@item ignorecase
+@itemx ic
+@cindex case and searching
+ignorecase -- No distinction between upper and lower cases when searching.
+@item noignorecase
+@itemx noic
+Cancel ignorecase.
+@item magic
+@itemx ma
+@cindex literal searching
+Regular expressions used in searches; nomagic means no regexps.
+@item nomagic
+@item noma
+Cancel magic.
+@item readonly
+@itemx ro
+@cindex readonly files
+readonly -- The file is not to be changed.
+If the user attempts to write to this file, confirmation will be requested.
+@item noreadonly
+@itemx noro
+Cancel readonly.
+@item shell=<string>
+@itemx sh=<string>
+@cindex shell
+shell -- The program to be used for shell escapes
+(default @samp{$SHELL} (default @file{/bin/sh})).
+@item shiftwidth=<count>
+@itemx sw=<count>
+@cindex layout
+@cindex shifting text
+shiftwidth -- Gives the shiftwidth (default 8 positions).
+@item showmatch
+@itemx sm
+@cindex paren matching
+@cindex matching parens
+showmatch -- Whenever you append a @kbd{)}, Vi shows
+its match if it's on the same page; also with
+@kbd{@{} and @kbd{@}}. If there's no match, Vi will beep.
+@item noshowmatch
+@itemx nosm
+Cancel showmatch.
+@item tabstop=<count>
+@itemx ts=<count>
+@cindex changing tab width
+@cindex tabbing
+tabstop -- The length of a <ht>; warning: this is
+only IN the editor, outside of it <ht>s have
+their normal length (default 8 positions).
+This setting affects the current buffer only.
+@item tabstop-global
+@itemx ts-g
+Same as `tabstop', but affects all buffers.
+@item wrapmargin=<count>
+@itemx wm=<count>
+@cindex auto fill
+@cindex word wrap
+wrapmargin -- In append mode Vi automatically
+puts a <lf> whenever there is a <sp> or <ht>
+within <wm> columns from the right margin.
+@item wrapscan
+@itemx ws
+@cindex searching
+wrapscan -- When searching, the end is
+considered @samp{stuck} to the begin of the file.
+@item nowrapscan
+@itemx nows
+Cancel wrapscan.
+@item :set <option>
+Turn <option> on.
+@item :set no<option>
+Turn <option> off.
+@item :set <option>=<value>
+Set <option> to <value>.
+@end table
+@findex @kbd{:set <option>=<value>}
+@findex @kbd{:set no<option>}
+@findex @kbd{:set <option>}
+@findex @kbd{:set ws}
+@findex @kbd{:set wrapscan}
+@findex @kbd{:set wm=<count>}
+@findex @kbd{:set wrapmargin=<count>}
+@findex @kbd{:set ts=<count>}
+@findex @kbd{:set tabstop=<count>}
+@findex @kbd{:set tab-stop-local=<count>}
+@findex @kbd{:set sm}
+@findex @kbd{:set showmatch}
+@findex @kbd{:set sw=<count>}
+@findex @kbd{:set shiftwidth=<count>}
+@findex @kbd{:set sh=<string>}
+@findex @kbd{:set shell=<string>}
+@findex @kbd{:set ro}
+@findex @kbd{:set readonly}
+@findex @kbd{:set magic}
+@findex @kbd{:set ic}
+@findex @kbd{:set ignorecase}
+@findex @kbd{:set ai}
+@findex @kbd{:set autoindent}
+
+@node Emacs Related Commands,,Options,Commands
+@section Emacs Related Commands
+
+@table @kbd
+@item C-\
+Begin Meta command in Vi or Insert states. Most often used as C-\ x (M-x).
+
+Note: Emacs binds @kbd{C-\} to a function that offers to change the
+keyboard input method in the multilingual environment. Viper overrides this
+binding. However, it is still possible to switch the input method by typing
+@kbd{\ C-\} in the Vi command state and @kbd{C-z \ C-\} in the Insert state.
+Or you can use the MULE menu on the menubar.
+@item C-z
+In Insert and Replace states, prepare Viper to accept the next command and
+execute it as if Viper was in Vi state. Then return to Insert state.
+
+In Vi state, switch to Emacs state; in Emacs state, switch to Vi state.
+@item C-c \
+Switches to Vi state for the duration of a single command. Then goes back
+to the original Viper state. Works from Vi, Insert, Replace, and Emacs states.
+@item C-x0
+Close Window
+@item C-x1
+Close Other Windows
+@item C-x2
+Split Window
+@item C-xo
+Move among windows
+@item C-xC-f
+Emacs find-file, useful in Insert state
+@item C-y
+Put back the last killed text. Similar to Vi's @kbd{p}, but also works in
+Insert and Replace state. This command doesn't work in Vi command state,
+since this binding is taken for something else.
+@item M-y
+Undoes the last @kbd{C-y} and puts another kill from the kill ring.
+Using this command, you can try may different kills until you find the one
+you need.
+@end table
+@kindex @kbd{M-y}
+@kindex @kbd{C-y}
+@kindex @kbd{C-xC-f}
+@kindex @kbd{C-xo}
+@kindex @kbd{C-x2}
+@kindex @kbd{C-x1}
+@kindex @kbd{C-x0}
+@kindex @kbd{C-z}
+@kindex @kbd{C-\}
+@kindex @kbd{C-c\}
+
+@node Mouse-bound Commands,,,Commands
+@section Mouse-bound Commands
+
+The following two mouse actions are normally bound to to special search and
+insert commands in of Viper:
+
+@table @kbd
+@item S-mouse-1
+Holding Shift and clicking mouse button 1 will
+initiate search for
+a region under the mouse pointer.
+This command can take a prefix argument. Note: Viper sets this
+binding only if this mouse action is not
+already bound to something else.
+@xref{Viper Specials}, for more information.@refill
+
+@item S-mouse-2
+Holding Shift and clicking button 2 of the mouse will
+insert a region surrounding the mouse pointer.
+This command can also take a prefix argument.
+Note: Viper sets this binding only if this mouse action is not
+already bound to something else.
+@xref{Viper Specials}, for more details.@refill
+@end table
+@kindex @kbd{S-mouse-1}
+@kindex @kbd{S-mouse-2}
+@kindex @kbd{meta button1up}
+@kindex @kbd{meta button2up}
+
+@node Acknowledgments,,,Top
+@comment node-name, next, previous, up
+@unnumbered Acknowledgments
+
+Viper, formerly known as VIP-19, was written by Michael Kifer. Viper is
+based on the original VIP package by Masahiko Sato and on its enhancement,
+VIP 4.4, by Aamod Sane. This manual is an adaptation of the manual for VIP
+4.4, which, in turn, was based on Sato's manual for VIP 3.5.
+
+Many contributors on the net pointed out bugs and suggested a number of
+useful features. Here is a (hopefully) complete list of contributors:
+
+@example
+ahg@@panix.com (Al Gelders),
+amade@@diagram.fr (Paul-Bernard Amade),
+ascott@@fws214.intel.com (Andy Scott),
+cook@@biostat.wisc.edu (Tom Cook),
+csdayton@@midway.uchicago.edu (Soren Dayton),
+dave@@hellgate.utah.edu,
+dominik@@strw.LeidenUniv.nl (Carsten Dominik),
+dwallach@@cs.princeton.edu (Dan Wallach),
+dwight@@toolucky.llnl.gov (Dwight Shih),
+edmonds@@edmonds.home.cs.ubc.ca (Brian Edmonds),
+gviswana@@cs.wisc.edu (Guhan Viswanathan),
+gvr@@halcyon.com (George V.@: Reilly),
+hatazaki@@bach.convex.com (Takao Hatazaki),
+hpz@@ibmhpz.aug.ipp-garching.mpg.de (Hans-Peter Zehrfeld),
+jackr@@dblues.engr.sgi.com (Jack Repenning),
+jamesm@@bga.com (D.J.@: Miller II),
+jjm@@hplb.hpl.hp.com (Jean-Jacques Moreau),
+jl@@cse.ogi.edu (John Launchbury),
+jobrien@@hchp.org (John O'Brien),
+johnw@@borland.com (John Wiegley),
+kanze@@gabi-soft.fr (James Kanze),
+kin@@isi.com (Kin Cho),
+kwzh@@gnu.org (Karl Heuer),
+lindstro@@biostat.wisc.edu (Mary Lindstrom),
+Mark.Bordas@@East.Sun.COM (Mark Bordas),
+meyering@@comco.com (Jim Meyering),
+mrb@@Eng.Sun.COM (Martin Buchholz),
+mveiga@@dit.upm.es (Marcelino Veiga Tuimil),
+paulk@@summit.esg.apertus.com (Paul Keusemann),
+pfister@@cs.sunysb.edu (Hanspeter Pfister),
+phil_brooks@@MENTORG.COM (Phil Brooks),
+pogrell@@informatik.hu-berlin.de (Lutz Pogrell),
+pradyut@@cs.uchicago.edu (Pradyut Shah),
+roderick@@argon.org (Roderick Schertler),
+rxga@@ulysses.att.com,
+sawdey@@lcse.umn.edu (Aaron Sawdey),
+simonb@@prl.philips.co.uk (Simon Blanchard),
+stephen@@farrell.org (Stephen Farrell),
+sudish@@MindSpring.COM (Sudish Joseph),
+schwab@@issan.informatik.uni-dortmund.de (Andreas Schwab)
+terra@@diku.dk (Morten Welinder),
+thanh@@informatics.muni.cz (Han The Thanh),
+toma@@convex.convex.com,
+vrenjak@@sun1.racal.com (Milan Vrenjak),
+whicken@@dragon.parasoft.com (Wendell Hicken),
+zapman@@cc.gatech.edu (Jason Zapman II),
+@end example
+
+
+@node Key Index,Function Index,,Top
+@comment node-name, next, previous, up
+@unnumbered Key Index
+
+@printindex ky
+
+@node Function Index,Variable Index,Key Index,Top
+@comment node-name, next, previous, up
+@unnumbered Function Index
+
+@printindex fn
+
+@node Variable Index,Package Index,Function Index,Top
+@comment node-name, next, previous, up
+@unnumbered Variable Index
+
+@printindex vr
+
+@node Package Index,Concept Index,Variable Index,Top
+@comment node-name, next, previous, up
+@unnumbered Package Index
+
+@printindex pg
+
+@node Concept Index,,Package Index,Top
+@comment node-name, next, previous, up
+@unnumbered Concept Index
+
+@printindex cp
+
+@contents
+@bye
--- /dev/null
+\input texinfo.tex
+
+@c %**start of header
+@setfilename ../info/widget
+@settitle The Emacs Widget Library
+@iftex
+@afourpaper
+@headings double
+@end iftex
+@c %**end of header
+
+@dircategory Editors
+@direntry
+* Widget: (widget). Documenting the "widget" package used by the
+ Emacs Custom facility.
+@end direntry
+
+@node Top, Introduction, (dir), (dir)
+@comment node-name, next, previous, up
+@top The Emacs Widget Library
+
+Version: 1.9914
+
+@menu
+* Introduction::
+* User Interface::
+* Programming Example::
+* Setting Up the Buffer::
+* Basic Types::
+* Sexp Types::
+* Widget Properties::
+* Defining New Widgets::
+* Widget Browser::
+* Widget Minor Mode::
+* Utilities::
+* Widget Wishlist::
+@end menu
+
+@node Introduction, User Interface, Top, Top
+@comment node-name, next, previous, up
+@section Introduction
+
+Most graphical user interface toolkits, such as Motif and XView, provide
+a number of standard user interface controls (sometimes known as
+`widgets' or `gadgets'). Emacs doesn't really support anything like
+this, except for an incredible powerful text ``widget''. On the other
+hand, Emacs does provide the necessary primitives to implement many
+other widgets within a text buffer. The @code{widget} package
+simplifies this task.
+
+The basic widgets are:
+
+@table @code
+@item link
+Areas of text with an associated action. Intended for hypertext links
+embedded in text.
+@item push-button
+Like link, but intended for stand-alone buttons.
+@item editable-field
+An editable text field. It can be either variable or fixed length.
+@item menu-choice
+Allows the user to choose one of multiple options from a menu, each
+option is itself a widget. Only the selected option will be visible in
+the buffer.
+@item radio-button-choice
+Allows the user to choose one of multiple options by activating radio
+buttons. The options are implemented as widgets. All options will be
+visible in the buffer.
+@item item
+A simple constant widget intended to be used in the @code{menu-choice} and
+@code{radio-button-choice} widgets.
+@item choice-item
+An button item only intended for use in choices. When invoked, the user
+will be asked to select another option from the choice widget.
+@item toggle
+A simple @samp{on}/@samp{off} switch.
+@item checkbox
+A checkbox (@samp{[ ]}/@samp{[X]}).
+@item editable-list
+Create an editable list. The user can insert or delete items in the
+list. Each list item is itself a widget.
+@end table
+
+Now of what possible use can support for widgets be in a text editor?
+I'm glad you asked. The answer is that widgets are useful for
+implementing forms. A @dfn{form} in Emacs is a buffer where the user is
+supposed to fill out a number of fields, each of which has a specific
+meaning. The user is not supposed to change or delete any of the text
+between the fields. Examples of forms in Emacs are the @file{forms}
+package (of course), the customize buffers, the mail and news compose
+modes, and the @sc{html} form support in the @file{w3} browser.
+
+The advantages for a programmer of using the @code{widget} package to
+implement forms are:
+
+@enumerate
+@item
+More complex field than just editable text are supported.
+@item
+You can give the user immediate feedback if he enters invalid data in a
+text field, and sometimes prevent entering invalid data.
+@item
+You can have fixed sized fields, thus allowing multiple field to be
+lined up in columns.
+@item
+It is simple to query or set the value of a field.
+@item
+Editing happens in buffer, not in the mini-buffer.
+@item
+Packages using the library get a uniform look, making them easier for
+the user to learn.
+@item
+As support for embedded graphics improve, the widget library will
+extended to support it. This means that your code using the widget
+library will also use the new graphic features by automatic.
+@end enumerate
+
+In order to minimize the code that is loaded by users who does not
+create any widgets, the code has been split in two files:
+
+@table @file
+@item widget.el
+This will declare the user variables, define the function
+@code{widget-define}, and autoload the function @code{widget-create}.
+@item wid-edit.el
+Everything else is here, there is no reason to load it explicitly, as
+it will be autoloaded when needed.
+@end table
+
+@node User Interface, Programming Example, Introduction, Top
+@comment node-name, next, previous, up
+@section User Interface
+
+A form consist of read only text for documentation and some fields,
+where each the fields contain two parts, as tag and a value. The tags
+are used to identify the fields, so the documentation can refer to the
+foo field, meaning the field tagged with @samp{Foo}. Here is an example
+form:
+
+@example
+Here is some documentation.
+
+Name: @i{My Name} @strong{Choose}: This option
+Address: @i{Some Place
+In some City
+Some country.}
+
+See also @b{_other work_} for more information.
+
+Numbers: count to three below
+@b{[INS]} @b{[DEL]} @i{One}
+@b{[INS]} @b{[DEL]} @i{Eh, two?}
+@b{[INS]} @b{[DEL]} @i{Five!}
+@b{[INS]}
+
+Select multiple:
+
+@b{[X]} This
+@b{[ ]} That
+@b{[X]} Thus
+
+Select one:
+
+@b{(*)} One
+@b{( )} Another One.
+@b{( )} A Final One.
+
+@b{[Apply Form]} @b{[Reset Form]}
+@end example
+
+The top level widgets in is example are tagged @samp{Name},
+@samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers},
+@samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and
+@samp{[Reset Form]}. There are basically two thing the user can do within
+a form, namely editing the editable text fields and activating the
+buttons.
+
+@subsection Editable Text Fields
+
+In the example, the value for the @samp{Name} is most likely displayed
+in an editable text field, and so are values for each of the members of
+the @samp{Numbers} list. All the normal Emacs editing operations are
+available for editing these fields. The only restriction is that each
+change you make must be contained within a single editable text field.
+For example, capitalizing all text from the middle of one field to the
+middle of another field is prohibited.
+
+Editing text fields are created by the @code{editable-field} widget.
+
+The editing text fields are highlighted with the
+@code{widget-field-face} face, making them easy to find.
+
+@deffn Face widget-field-face
+Face used for other editing fields.
+@end deffn
+
+@subsection Buttons
+
+Some portions of the buffer have an associated @dfn{action}, which can
+be @dfn{invoked} by a standard key or mouse command. These portions
+are called @dfn{buttons}. The default commands for activating a button
+are:
+
+@table @kbd
+@item @key{RET}
+@deffn Command widget-button-press @var{pos} &optional @var{event}
+Invoke the button at @var{pos}, defaulting to point.
+If point is not located on a button, invoke the binding in
+@code{widget-global-map} (by default the global map).
+@end deffn
+
+@item mouse-2
+@deffn Command widget-button-click @var{event}
+Invoke the button at the location of the mouse pointer. If the mouse
+pointer is located in an editable text field, invoke the binding in
+@code{widget-global-map} (by default the global map).
+@end deffn
+@end table
+
+There are several different kind of buttons, all of which are present in
+the example:
+
+@table @emph
+@item The Option Field Tags.
+When you invoke one of these buttons, you will be asked to choose
+between a number of different options. This is how you edit an option
+field. Option fields are created by the @code{menu-choice} widget. In
+the example, @samp{@b{Choose}} is an option field tag.
+@item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons.
+Activating these will insert or delete elements from a editable list.
+The list is created by the @code{editable-list} widget.
+@item Embedded Buttons.
+The @samp{@b{_other work_}} is an example of an embedded
+button. Embedded buttons are not associated with a fields, but can serve
+any purpose, such as implementing hypertext references. They are
+usually created by the @code{link} widget.
+@item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons.
+Activating one of these will convert it to the other. This is useful
+for implementing multiple-choice fields. You can create it wit
+@item The @samp{@b{( )}} and @samp{@b{(*)}} buttons.
+Only one radio button in a @code{radio-button-choice} widget can be
+selected at any time. When you invoke one of the unselected radio
+buttons, it will be selected and the previous selected radio button will
+become unselected.
+@item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons.
+These are explicit buttons made with the @code{push-button} widget. The main
+difference from the @code{link} widget is that the buttons are will be
+displayed as GUI buttons when possible.
+enough.
+@end table
+
+To make them easier to locate, buttons are emphasized in the buffer.
+
+@deffn Face widget-button-face
+Face used for buttons.
+@end deffn
+
+@defopt widget-mouse-face
+Face used for buttons when the mouse pointer is above it.
+@end defopt
+
+@subsection Navigation
+
+You can use all the normal Emacs commands to move around in a form
+buffer, plus you will have these additional commands:
+
+@table @kbd
+@item @key{TAB}
+@deffn Command widget-forward &optional count
+Move point @var{count} buttons or editing fields forward.
+@end deffn
+@item @key{M-TAB}
+@deffn Command widget-backward &optional count
+Move point @var{count} buttons or editing fields backward.
+@end deffn
+@end table
+
+@node Programming Example, Setting Up the Buffer, User Interface, Top
+@comment node-name, next, previous, up
+@section Programming Example
+
+Here is the code to implement the user interface example (@pxref{User
+Interface}).
+
+@lisp
+(require 'widget)
+
+(eval-when-compile
+ (require 'wid-edit))
+
+(defvar widget-example-repeat)
+
+(defun widget-example ()
+ "Create the widgets from the Widget manual."
+ (interactive)
+ (switch-to-buffer "*Widget Example*")
+ (kill-all-local-variables)
+ (make-local-variable 'widget-example-repeat)
+ (let ((inhibit-read-only t))
+ (erase-buffer))
+ (widget-insert "Here is some documentation.\n\nName: ")
+ (widget-create 'editable-field
+ :size 13
+ "My Name")
+ (widget-create 'menu-choice
+ :tag "Choose"
+ :value "This"
+ :help-echo "Choose me, please!"
+ :notify (lambda (widget &rest ignore)
+ (message "%s is a good choice!"
+ (widget-value widget)))
+ '(item :tag "This option" :value "This")
+ '(choice-item "That option")
+ '(editable-field :menu-tag "No option" "Thus option"))
+ (widget-insert "Address: ")
+ (widget-create 'editable-field
+ "Some Place\nIn some City\nSome country.")
+ (widget-insert "\nSee also ")
+ (widget-create 'link
+ :notify (lambda (&rest ignore)
+ (widget-value-set widget-example-repeat
+ '("En" "To" "Tre"))
+ (widget-setup))
+ "other work")
+ (widget-insert " for more information.\n\nNumbers: count to three below\n")
+ (setq widget-example-repeat
+ (widget-create 'editable-list
+ :entry-format "%i %d %v"
+ :notify (lambda (widget &rest ignore)
+ (let ((old (widget-get widget
+ ':example-length))
+ (new (length (widget-value widget))))
+ (unless (eq old new)
+ (widget-put widget ':example-length new)
+ (message "You can count to %d." new))))
+ :value '("One" "Eh, two?" "Five!")
+ '(editable-field :value "three")))
+ (widget-insert "\n\nSelect multiple:\n\n")
+ (widget-create 'checkbox t)
+ (widget-insert " This\n")
+ (widget-create 'checkbox nil)
+ (widget-insert " That\n")
+ (widget-create 'checkbox
+ :notify (lambda (&rest ignore) (message "Tickle"))
+ t)
+ (widget-insert " Thus\n\nSelect one:\n\n")
+ (widget-create 'radio-button-choice
+ :value "One"
+ :notify (lambda (widget &rest ignore)
+ (message "You selected %s"
+ (widget-value widget)))
+ '(item "One") '(item "Another One.") '(item "A Final One."))
+ (widget-insert "\n")
+ (widget-create 'push-button
+ :notify (lambda (&rest ignore)
+ (if (= (length (widget-value widget-example-repeat))
+ 3)
+ (message "Congratulation!")
+ (error "Three was the count!")))
+ "Apply Form")
+ (widget-insert " ")
+ (widget-create 'push-button
+ :notify (lambda (&rest ignore)
+ (widget-example))
+ "Reset Form")
+ (widget-insert "\n")
+ (use-local-map widget-keymap)
+ (widget-setup))
+@end lisp
+
+@node Setting Up the Buffer, Basic Types, Programming Example, Top
+@comment node-name, next, previous, up
+@section Setting Up the Buffer
+
+Widgets are created with @code{widget-create}, which returns a
+@dfn{widget} object. This object can be queried and manipulated by
+other widget functions, until it is deleted with @code{widget-delete}.
+After the widgets have been created, @code{widget-setup} must be called
+to enable them.
+
+@defun widget-create type [ keyword argument ]@dots{}
+Create and return a widget of type @var{type}.
+The syntax for the @var{type} argument is described in @ref{Basic Types}.
+
+The keyword arguments can be used to overwrite the keyword arguments
+that are part of @var{type}.
+@end defun
+
+@defun widget-delete widget
+Delete @var{widget} and remove it from the buffer.
+@end defun
+
+@defun widget-setup
+Setup a buffer to support widgets.
+
+This should be called after creating all the widgets and before allowing
+the user to edit them.
+@refill
+@end defun
+
+If you want to insert text outside the widgets in the form, the
+recommended way to do that is with @code{widget-insert}.
+
+@defun widget-insert
+Insert the arguments, either strings or characters, at point.
+The inserted text will be read only.
+@end defun
+
+There is a standard widget keymap which you might find useful.
+
+@defvr Const widget-keymap
+A keymap with the global keymap as its parent.@*
+@key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and
+@code{widget-backward}, respectively. @kbd{@key{RET}} and @kbd{mouse-2}
+are bound to @code{widget-button-press} and
+@code{widget-button-}.@refill
+@end defvr
+
+@defvar widget-global-map
+Keymap used by @code{widget-button-press} and @code{widget-button-click}
+when not on a button. By default this is @code{global-map}.
+@end defvar
+
+@node Basic Types, Sexp Types, Setting Up the Buffer, Top
+@comment node-name, next, previous, up
+@section Basic Types
+
+The syntax of a type specification is given below:
+
+@example
+NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
+ | NAME
+@end example
+
+Where, @var{name} is a widget name, @var{keyword} is the name of a
+property, @var{argument} is the value of the property, and @var{args}
+are interpreted in a widget specific way.
+
+There following keyword arguments that apply to all widgets:
+
+@table @code
+@item :value
+The initial value for widgets of this type.
+
+@item :format
+This string will be inserted in the buffer when you create a widget.
+The following @samp{%} escapes are available:
+
+@table @samp
+@item %[
+@itemx %]
+The text inside will be marked as a button.
+
+By default, the text will be shown in @code{widget-button-face}, and
+surrounded by brackets.
+
+@defopt widget-button-prefix
+String to prefix buttons.
+@end defopt
+
+@defopt widget-button-suffix
+String to suffix buttons.
+@end defopt
+
+@item %@{
+@itemx %@}
+The text inside will be displayed with the face specified by
+@code{:sample-face}.
+
+@item %v
+This will be replaces with the buffer representation of the widgets
+value. What this is depends on the widget type.
+
+@item %d
+Insert the string specified by @code{:doc} here.
+
+@item %h
+Like @samp{%d}, with the following modifications: If the documentation
+string is more than one line, it will add a button which will toggle
+between showing only the first line, and showing the full text.
+Furthermore, if there is no @code{:doc} property in the widget, it will
+instead examine the @code{:documentation-property} property. If it is a
+lambda expression, it will be called with the widget's value as an
+argument, and the result will be used as the documentation text.
+
+@item %t
+Insert the string specified by @code{:tag} here, or the @code{princ}
+representation of the value if there is no tag.
+
+@item %%
+Insert a literal @samp{%}.
+@end table
+
+@item :button-face
+Face used to highlight text inside %[ %] in the format.
+
+@item :button-prefix
+@itemx :button-suffix
+
+Text around %[ %] in the format.
+
+These can be
+@table @emph
+@item nil
+No text is inserted.
+
+@item a string
+The string is inserted literally.
+
+@item a symbol
+The value of the symbol is expanded according to this table.
+@end table
+
+@item :doc
+The string inserted by the @samp{%d} escape in the format
+string.
+
+@item :tag
+The string inserted by the @samp{%t} escape in the format
+string.
+
+@item :tag-glyph
+Name of image to use instead of the string specified by `:tag' on
+Emacsen that supports it.
+
+@item :help-echo
+Message displayed whenever you move to the widget with either
+@code{widget-forward} or @code{widget-backward}.
+
+@item :indent
+An integer indicating the absolute number of spaces to indent children
+of this widget.
+
+@item :offset
+An integer indicating how many extra spaces to add to the widget's
+grandchildren compared to this widget.
+
+@item :extra-offset
+An integer indicating how many extra spaces to add to the widget's
+children compared to this widget.
+
+@item :notify
+A function called each time the widget or a nested widget is changed.
+The function is called with two or three arguments. The first argument
+is the widget itself, the second argument is the widget that was
+changed, and the third argument is the event leading to the change, if
+any.
+
+@item :menu-tag
+Tag used in the menu when the widget is used as an option in a
+@code{menu-choice} widget.
+
+@item :menu-tag-get
+Function used for finding the tag when the widget is used as an option
+in a @code{menu-choice} widget. By default, the tag used will be either the
+@code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
+representation of the @code{:value} property if not.
+
+@item :match
+Should be a function called with two arguments, the widget and a value,
+and returning non-nil if the widget can represent the specified value.
+
+@item :validate
+A function which takes a widget as an argument, and return nil if the
+widgets current value is valid for the widget. Otherwise, it should
+return the widget containing the invalid data, and set that widgets
+@code{:error} property to a string explaining the error.
+
+The following predefined function can be used:
+
+@defun widget-children-validate widget
+All the @code{:children} of @var{widget} must be valid.
+@end defun
+
+@item :tab-order
+Specify the order in which widgets are traversed with
+@code{widget-forward} or @code{widget-backward}. This is only partially
+implemented.
+
+@enumerate a
+@item
+Widgets with tabbing order @code{-1} are ignored.
+
+@item
+(Unimplemented) When on a widget with tabbing order @var{n}, go to the
+next widget in the buffer with tabbing order @var{n+1} or @code{nil},
+whichever comes first.
+
+@item
+When on a widget with no tabbing order specified, go to the next widget
+in the buffer with a positive tabbing order, or @code{nil}
+@end enumerate
+
+@item :parent
+The parent of a nested widget (e.g. a @code{menu-choice} item or an
+element of a @code{editable-list} widget).
+
+@item :sibling-args
+This keyword is only used for members of a @code{radio-button-choice} or
+@code{checklist}. The value should be a list of extra keyword
+arguments, which will be used when creating the @code{radio-button} or
+@code{checkbox} associated with this item.
+
+@end table
+
+@deffn {User Option} widget-glyph-directory
+Directory where glyphs are found.
+Widget will look here for a file with the same name as specified for the
+image, with either a @samp{.xpm} (if supported) or @samp{.xbm} extension.
+@end deffn
+
+@deffn{User Option} widget-glyph-enable
+If non-nil, allow glyphs to appear on displays where they are supported.
+@end deffn
+
+
+@menu
+* link::
+* url-link::
+* info-link::
+* push-button::
+* editable-field::
+* text::
+* menu-choice::
+* radio-button-choice::
+* item::
+* choice-item::
+* toggle::
+* checkbox::
+* checklist::
+* editable-list::
+* group::
+@end menu
+
+@node link, url-link, Basic Types, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{link} Widget
+
+Syntax:
+
+@example
+TYPE ::= (link [KEYWORD ARGUMENT]... [ VALUE ])
+@end example
+
+The @var{value}, if present, is used to initialize the @code{:value}
+property. The value should be a string, which will be inserted in the
+buffer.
+
+By default the link will be shown in brackets.
+
+@defopt widget-link-prefix
+String to prefix links.
+@end defopt
+
+@defopt widget-link-suffix
+String to suffix links.
+@end defopt
+
+@node url-link, info-link, link, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{url-link} Widget
+
+Syntax:
+
+@example
+TYPE ::= (url-link [KEYWORD ARGUMENT]... URL)
+@end example
+
+When this link is invoked, the @sc{www} browser specified by
+@code{browse-url-browser-function} will be called with @var{url}.
+
+@node info-link, push-button, url-link, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{info-link} Widget
+
+Syntax:
+
+@example
+TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS)
+@end example
+
+When this link is invoked, the build-in info browser is started on
+@var{address}.
+
+@node push-button, editable-field, info-link, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{push-button} Widget
+
+Syntax:
+
+@example
+TYPE ::= (push-button [KEYWORD ARGUMENT]... [ VALUE ])
+@end example
+
+The @var{value}, if present, is used to initialize the @code{:value}
+property. The value should be a string, which will be inserted in the
+buffer.
+
+By default the tag will be shown in brackets.
+
+@defopt widget-push-button-prefix
+String to prefix push buttons.
+@end defopt
+
+@defopt widget-push-button-suffix
+String to suffix push buttons.
+@end defopt
+
+@node editable-field, text, push-button, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{editable-field} Widget
+
+Syntax:
+
+@example
+TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
+@end example
+
+The @var{value}, if present, is used to initialize the @code{:value}
+property. The value should be a string, which will be inserted in
+field. This widget will match all string values.
+
+The following extra properties are recognized.
+
+@table @code
+@item :size
+The width of the editable field.@*
+By default the field will reach to the end of the line.
+
+@item :value-face
+Face used for highlighting the editable field. Default is
+@code{widget-field-face}.
+
+@item :secret
+Character used to display the value. You can set this to e.g. @code{?*}
+if the field contains a password or other secret information. By
+default, the value is not secret.
+
+@item :valid-regexp
+By default the @code{:validate} function will match the content of the
+field with the value of this attribute. The default value is @code{""}
+which matches everything.
+
+@item :keymap
+Keymap used in the editable field. The default value is
+@code{widget-field-keymap}, which allows you to use all the normal
+editing commands, even if the buffers major mode suppress some of them.
+Pressing return invokes the function specified by @code{:action}.
+@end table
+
+@node text, menu-choice, editable-field, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{text} Widget
+
+This is just like @code{editable-field}, but intended for multiline text
+fields. The default @code{:keymap} is @code{widget-text-keymap}, which
+does not rebind the return key.
+
+@node menu-choice, radio-button-choice, text, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{menu-choice} Widget
+
+Syntax:
+
+@example
+TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
+@end example
+
+The @var{type} arguments represents each possible choice. The widgets
+value of will be the value of the chosen @var{type} argument. This
+widget will match any value that matches at least one of the specified
+@var{type} arguments.
+
+@table @code
+@item :void
+Widget type used as a fallback when the value does not match any of the
+specified @var{type} arguments.
+
+@item :case-fold
+Set this to nil if you don't want to ignore case when prompting for a
+choice through the minibuffer.
+
+@item :children
+A list whose car is the widget representing the currently chosen type in
+the buffer.
+
+@item :choice
+The current chosen type
+
+@item :args
+The list of types.
+@end table
+
+@node radio-button-choice, item, menu-choice, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{radio-button-choice} Widget
+
+Syntax:
+
+@example
+TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]... TYPE ... )
+@end example
+
+The @var{type} arguments represents each possible choice. The widgets
+value of will be the value of the chosen @var{type} argument. This
+widget will match any value that matches at least one of the specified
+@var{type} arguments.
+
+The following extra properties are recognized.
+
+@table @code
+@item :entry-format
+This string will be inserted for each entry in the list.
+The following @samp{%} escapes are available:
+@table @samp
+@item %v
+Replaced with the buffer representation of the @var{type} widget.
+@item %b
+Replace with the radio button.
+@item %%
+Insert a literal @samp{%}.
+@end table
+
+@item button-args
+A list of keywords to pass to the radio buttons. Useful for setting
+e.g. the @samp{:help-echo} for each button.
+
+@item :buttons
+The widgets representing the radio buttons.
+
+@item :children
+The widgets representing each type.
+
+@item :choice
+The current chosen type
+
+@item :args
+The list of types.
+@end table
+
+You can add extra radio button items to a @code{radio-button-choice}
+widget after it has been created with the function
+@code{widget-radio-add-item}.
+
+@defun widget-radio-add-item widget type
+Add to @code{radio-button-choice} widget @var{widget} a new radio button item of type
+@var{type}.
+@end defun
+
+Please note that such items added after the @code{radio-button-choice}
+widget has been created will @strong{not} be properly destructed when
+you call @code{widget-delete}.
+
+@node item, choice-item, radio-button-choice, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{item} Widget
+
+Syntax:
+
+@example
+ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)
+@end example
+
+The @var{value}, if present, is used to initialize the @code{:value}
+property. The value should be a string, which will be inserted in the
+buffer. This widget will only match the specified value.
+
+@node choice-item, toggle, item, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{choice-item} Widget
+
+Syntax:
+
+@example
+ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE)
+@end example
+
+The @var{value}, if present, is used to initialize the @code{:value}
+property. The value should be a string, which will be inserted in the
+buffer as a button. Activating the button of a @code{choice-item} is
+equivalent to activating the parent widget. This widget will only match
+the specified value.
+
+@node toggle, checkbox, choice-item, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{toggle} Widget
+
+Syntax:
+
+@example
+TYPE ::= (toggle [KEYWORD ARGUMENT]...)
+@end example
+
+The widget has two possible states, `on' and `off', which corresponds to
+a @code{t} or @code{nil} value.
+
+The following extra properties are recognized.
+
+@table @code
+@item :on
+String representing the `on' state. By default the string @samp{on}.
+@item :off
+String representing the `off' state. By default the string @samp{off}.
+@item :on-glyph
+Name of a glyph to be used instead of the `:on' text string, on emacsen
+that supports it.
+@item :off-glyph
+Name of a glyph to be used instead of the `:off' text string, on emacsen
+that supports it.
+@end table
+
+@node checkbox, checklist, toggle, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{checkbox} Widget
+
+The widget has two possible states, `selected' and `unselected', which
+corresponds to a @code{t} or @code{nil} value.
+
+Syntax:
+
+@example
+TYPE ::= (checkbox [KEYWORD ARGUMENT]...)
+@end example
+
+@node checklist, editable-list, checkbox, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{checklist} Widget
+
+Syntax:
+
+@example
+TYPE ::= (checklist [KEYWORD ARGUMENT]... TYPE ... )
+@end example
+
+The @var{type} arguments represents each checklist item. The widgets
+value of will be a list containing the value of each ticked @var{type}
+argument. The checklist widget will match a list whose elements all
+matches at least one of the specified @var{type} arguments.
+
+The following extra properties are recognized.
+
+@table @code
+@item :entry-format
+This string will be inserted for each entry in the list.
+The following @samp{%} escapes are available:
+@table @samp
+@item %v
+Replaced with the buffer representation of the @var{type} widget.
+@item %b
+Replace with the checkbox.
+@item %%
+Insert a literal @samp{%}.
+@end table
+
+@item :greedy
+Usually, a checklist will only match if the items are in the exact
+sequence given in the specification. By setting @code{:greedy} to
+non-nil, it will allow the items to come in any sequence. However, if
+you extract the value they will be in the sequence given in the
+checklist. I.e. the original sequence is forgotten.
+
+@item button-args
+A list of keywords to pass to the checkboxes. Useful for setting
+e.g. the @samp{:help-echo} for each checkbox.
+
+@item :buttons
+The widgets representing the checkboxes.
+
+@item :children
+The widgets representing each type.
+
+@item :args
+The list of types.
+@end table
+
+@node editable-list, group, checklist, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{editable-list} Widget
+
+Syntax:
+
+@example
+TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE)
+@end example
+
+The value is a list, where each member represents one widget of type
+@var{type}.
+
+The following extra properties are recognized.
+
+@table @code
+@item :entry-format
+This string will be inserted for each entry in the list.
+The following @samp{%} escapes are available:
+@table @samp
+@item %v
+This will be replaced with the buffer representation of the @var{type}
+widget.
+@item %i
+Insert the @b{[INS]} button.
+@item %d
+Insert the @b{[DEL]} button.
+@item %%
+Insert a literal @samp{%}.
+@end table
+
+@item :insert-button-args
+A list of keyword arguments to pass to the insert buttons.
+
+@item :delete-button-args
+A list of keyword arguments to pass to the delete buttons.
+
+@item :append-button-args
+A list of keyword arguments to pass to the trailing insert button.
+
+
+@item :buttons
+The widgets representing the insert and delete buttons.
+
+@item :children
+The widgets representing the elements of the list.
+
+@item :args
+List whose car is the type of the list elements.
+
+@end table
+
+@node group, , editable-list, Basic Types
+@comment node-name, next, previous, up
+@subsection The @code{group} Widget
+
+This widget simply group other widget together.
+
+Syntax:
+
+@example
+TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...)
+@end example
+
+The value is a list, with one member for each @var{type}.
+
+@node Sexp Types, Widget Properties, Basic Types, Top
+@comment
+@section Sexp Types
+
+A number of widgets for editing s-expressions (lisp types) are also
+available. These basically fall in the following categories.
+
+@menu
+* constants::
+* generic::
+* atoms::
+* composite::
+@end menu
+
+@node constants, generic, Sexp Types, Sexp Types
+@comment node-name, next, previous, up
+@subsection The Constant Widgets.
+
+The @code{const} widget can contain any lisp expression, but the user is
+prohibited from editing edit it, which is mainly useful as a component
+of one of the composite widgets.
+
+The syntax for the @code{const} widget is
+
+@example
+TYPE ::= (const [KEYWORD ARGUMENT]... [ VALUE ])
+@end example
+
+The @var{value}, if present, is used to initialize the @code{:value}
+property and can be any s-expression.
+
+@deffn Widget const
+This will display any valid s-expression in an immutable part of the
+buffer.
+@end deffn
+
+There are two variations of the @code{const} widget, namely
+@code{variable-item} and @code{function-item}. These should contain a
+symbol with a variable or function binding. The major difference from
+the @code{const} widget is that they will allow the user to see the
+variable or function documentation for the symbol.
+
+@deffn Widget variable-item
+An immutable symbol that is bound as a variable.
+@end deffn
+
+@deffn Widget function-item
+An immutable symbol that is bound as a function.
+@end deffn
+
+@node generic, atoms, constants, Sexp Types
+@comment node-name, next, previous, up
+@subsection Generic Sexp Widget.
+
+The @code{sexp} widget can contain any lisp expression, and allows the
+user to edit it inline in the buffer.
+
+The syntax for the @code{sexp} widget is
+
+@example
+TYPE ::= (sexp [KEYWORD ARGUMENT]... [ VALUE ])
+@end example
+
+@deffn Widget sexp
+This will allow you to edit any valid s-expression in an editable buffer
+field.
+
+The @code{sexp} widget takes the same keyword arguments as the
+@code{editable-field} widget.
+@end deffn
+
+@node atoms, composite, generic, Sexp Types
+@comment node-name, next, previous, up
+@subsection Atomic Sexp Widgets.
+
+The atoms are s-expressions that does not consist of other
+s-expressions. A string is an atom, while a list is a composite type.
+You can edit the value of an atom with the following widgets.
+
+The syntax for all the atoms are
+
+@example
+TYPE ::= (NAME [KEYWORD ARGUMENT]... [ VALUE ])
+@end example
+
+The @var{value}, if present, is used to initialize the @code{:value}
+property and must be an expression of the same type as the widget.
+I.e. the string widget can only be initialized with a string.
+
+All the atom widgets take the same keyword arguments as the
+@code{editable-field} widget.
+
+@deffn Widget string
+Allows you to edit a string in an editable field.
+@end deffn
+
+@deffn Widget regexp
+Allows you to edit a regular expression in an editable field.
+@end deffn
+
+@deffn Widget character
+Allows you to enter a character in an editable field.
+@end deffn
+
+@deffn Widget file
+Allows you to edit a file name in an editable field. If you invoke
+the tag button, you can edit the file name in the mini-buffer with
+completion.
+
+Keywords:
+@table @code
+@item :must-match
+If this is set to non-nil, only existing file names will be allowed in
+the minibuffer.
+@end table
+@end deffn
+
+@deffn Widget directory
+Allows you to edit a directory name in an editable field.
+Similar to the @code{file} widget.
+@end deffn
+
+@deffn Widget symbol
+Allows you to edit a lisp symbol in an editable field.
+@end deffn
+
+@deffn Widget function
+Allows you to edit a lambda expression, or a function name with completion.
+@end deffn
+
+@deffn Widget variable
+Allows you to edit a variable name, with completion.
+@end deffn
+
+@deffn Widget integer
+Allows you to edit an integer in an editable field.
+@end deffn
+
+@deffn Widget number
+Allows you to edit a number in an editable field.
+@end deffn
+
+@deffn Widget boolean
+Allows you to edit a boolean. In lisp this means a variable which is
+either nil meaning false, or non-nil meaning true.
+@end deffn
+
+
+@node composite, , atoms, Sexp Types
+@comment node-name, next, previous, up
+@subsection Composite Sexp Widgets.
+
+The syntax for the composite are
+
+@example
+TYPE ::= (NAME [KEYWORD ARGUMENT]... COMPONENT...)
+@end example
+
+Where each @var{component} must be a widget type. Each component widget
+will be displayed in the buffer, and be editable to the user.
+
+@deffn Widget cons
+The value of a @code{cons} widget is a cons-cell where the car is the
+value of the first component and the cdr is the value of the second
+component. There must be exactly two components.
+@end deffn
+
+@deffn Widget list
+The value of a @code{list} widget is a list containing the value of
+each of its component.
+@end deffn
+
+@deffn Widget vector
+The value of a @code{vector} widget is a vector containing the value of
+each of its component.
+@end deffn
+
+The above suffice for specifying fixed size lists and vectors. To get
+variable length lists and vectors, you can use a @code{choice},
+@code{set} or @code{repeat} widgets together with the @code{:inline}
+keywords. If any component of a composite widget has the @code{:inline}
+keyword set, its value must be a list which will then be spliced into
+the composite. For example, to specify a list whose first element must
+be a file name, and whose remaining arguments should either by the
+symbol @code{t} or two files, you can use the following widget
+specification:
+
+@example
+(list file
+ (choice (const t)
+ (list :inline t
+ :value ("foo" "bar")
+ string string)))
+@end example
+
+The value of a widget of this type will either have the form
+@samp{(file t)} or @code{(file string string)}.
+
+This concept of inline is probably hard to understand. It was certainly
+hard to implement so instead of confuse you more by trying to explain it
+here, I'll just suggest you meditate over it for a while.
+
+@deffn Widget choice
+Allows you to edit a sexp which may have one of fixed set of types. It
+is currently implemented with the @code{choice-menu} basic widget, and
+has a similar syntax.
+@end deffn
+
+@deffn Widget set
+Allows you to specify a type which must be a list whose elements all
+belong to given set. The elements of the list is not significant. This
+is implemented on top of the @code{checklist} basic widget, and has a
+similar syntax.
+@end deffn
+
+@deffn Widget repeat
+Allows you to specify a variable length list whose members are all of
+the same type. Implemented on top of the `editable-list' basic widget,
+and has a similar syntax.
+@end deffn
+
+@node Widget Properties, Defining New Widgets, Sexp Types, Top
+@comment node-name, next, previous, up
+@section Properties
+
+You can examine or set the value of a widget by using the widget object
+that was returned by @code{widget-create}.
+
+@defun widget-value widget
+Return the current value contained in @var{widget}.
+It is an error to call this function on an uninitialized widget.
+@end defun
+
+@defun widget-value-set widget value
+Set the value contained in @var{widget} to @var{value}.
+It is an error to call this function with an invalid @var{value}.
+@end defun
+
+@strong{Important:} You @emph{must} call @code{widget-setup} after
+modifying the value of a widget before the user is allowed to edit the
+widget again. It is enough to call @code{widget-setup} once if you
+modify multiple widgets. This is currently only necessary if the widget
+contains an editing field, but may be necessary for other widgets in the
+future.
+
+If your application needs to associate some information with the widget
+objects, for example a reference to the item being edited, it can be
+done with @code{widget-put} and @code{widget-get}. The property names
+must begin with a @samp{:}.
+
+@defun widget-put widget property value
+In @var{widget} set @var{property} to @var{value}.
+@var{property} should be a symbol, while @var{value} can be anything.
+@end defun
+
+@defun widget-get widget property
+In @var{widget} return the value for @var{property}.
+@var{property} should be a symbol, the value is what was last set by
+@code{widget-put} for @var{property}.
+@end defun
+
+@defun widget-member widget property
+Non-nil if @var{widget} has a value (even nil) for property @var{property}.
+@end defun
+
+Occasionally it can be useful to know which kind of widget you have,
+i.e. the name of the widget type you gave when the widget was created.
+
+@defun widget-type widget
+Return the name of @var{widget}, a symbol.
+@end defun
+
+Widgets can be in two states: active, which means they are modifiable by
+the user, or inactive, which means they cannot be modified by the user.
+You can query or set the state with the following code:
+
+@lisp
+;; Examine if @var{widget} is active or not.
+(if (widget-apply @var{widget} :active)
+ (message "Widget is active.")
+ (message "Widget is inactive.")
+
+;; Make @var{widget} inactive.
+(widget-apply @var{widget} :deactivate)
+
+;; Make @var{widget} active.
+(widget-apply @var{widget} :activate)
+@end lisp
+
+A widget is inactive if itself, or any of its ancestors (found by
+following the @code{:parent} link) have been deactivated. To make sure
+a widget is really active, you must therefore activate both itself, and
+all its ancestors.
+
+@lisp
+(while widget
+ (widget-apply widget :activate)
+ (setq widget (widget-get widget :parent)))
+@end lisp
+
+You can check if a widget has been made inactive by examining the value
+of @code{:inactive} keyword. If this is non-nil, the widget itself has
+been deactivated. This is different from using the @code{:active}
+keyword, in that the later tell you if the widget @strong{or} any of its
+ancestors have been deactivated. Do not attempt to set the
+@code{:inactive} keyword directly. Use the @code{:activate}
+@code{:deactivated} keywords instead.
+
+
+@node Defining New Widgets, Widget Browser, Widget Properties, Top
+@comment node-name, next, previous, up
+@section Defining New Widgets
+
+You can define specialized widgets with @code{define-widget}. It allows
+you to create a shorthand for more complex widgets, including specifying
+component widgets and default new default values for the keyword
+arguments.
+
+@defun widget-define name class doc &rest args
+Define a new widget type named @var{name} from @code{class}.
+
+@var{name} and class should both be symbols, @code{class} should be one
+of the existing widget types.
+
+The third argument @var{DOC} is a documentation string for the widget.
+
+After the new widget has been defined, the following two calls will
+create identical widgets:
+
+@itemize @bullet
+@item
+@lisp
+(widget-create @var{name})
+@end lisp
+
+@item
+@lisp
+(apply widget-create @var{class} @var{args})
+@end lisp
+@end itemize
+
+@end defun
+
+Using @code{widget-define} does just store the definition of the widget
+type in the @code{widget-type} property of @var{name}, which is what
+@code{widget-create} uses.
+
+If you just want to specify defaults for keywords with no complex
+conversions, you can use @code{identity} as your conversion function.
+
+The following additional keyword arguments are useful when defining new
+widgets:
+@table @code
+@item :convert-widget
+Function to convert a widget type before creating a widget of that
+type. It takes a widget type as an argument, and returns the converted
+widget type. When a widget is created, this function is called for the
+widget type and all the widgets parent types, most derived first.
+
+The following predefined functions can be used here:
+
+@defun widget-types-convert-widget widget
+Convert @code{:args} as widget types in @var{widget}.
+@end defun
+
+@defun widget-value-convert-widget widget
+Initialize @code{:value} from @code{:args} in @var{widget}.
+@end defun
+
+@item :value-to-internal
+Function to convert the value to the internal format. The function
+takes two arguments, a widget and an external value, and returns the
+internal value. The function is called on the present @code{:value}
+when the widget is created, and on any value set later with
+@code{widget-value-set}.
+
+@item :value-to-external
+Function to convert the value to the external format. The function
+takes two arguments, a widget and an internal value, and returns the
+internal value. The function is called on the present @code{:value}
+when the widget is created, and on any value set later with
+@code{widget-value-set}.
+
+@item :create
+Function to create a widget from scratch. The function takes one
+argument, a widget type, and create a widget of that type, insert it in
+the buffer, and return a widget object.
+
+@item :delete
+Function to delete a widget. The function takes one argument, a widget,
+and should remove all traces of the widget from the buffer.
+
+@item :value-create
+Function to expand the @samp{%v} escape in the format string. It will
+be called with the widget as its argument. Should
+insert a representation of the widgets value in the buffer.
+
+@item :value-delete
+Should remove the representation of the widgets value from the buffer.
+It will be called with the widget as its argument. It doesn't have to
+remove the text, but it should release markers and delete nested widgets
+if such has been used.
+
+The following predefined function can be used here:
+
+@defun widget-children-value-delete widget
+Delete all @code{:children} and @code{:buttons} in @var{widget}.
+@end defun
+
+@item :value-get
+Function to extract the value of a widget, as it is displayed in the
+buffer.
+
+The following predefined function can be used here:
+
+@defun widget-value-value-get widget
+Return the @code{:value} property of @var{widget}.
+@end defun
+
+@item :format-handler
+Function to handle unknown @samp{%} escapes in the format string. It
+will be called with the widget and the escape character as arguments.
+You can set this to allow your widget to handle non-standard escapes.
+
+You should end up calling @code{widget-default-format-handler} to handle
+unknown escape sequences, which will handle the @samp{%h} and any future
+escape sequences, as well as give an error for unknown escapes.
+
+@item :action
+Function to handle user initiated events. By default, @code{:notify}
+the parent.
+
+The following predefined function can be used here:
+
+@defun widget-parent-action widget &optional event
+Tell @code{:parent} of @var{widget} to handle the @code{:action}.
+Optional @var{event} is the event that triggered the action.
+@end defun
+
+@item :prompt-value
+Function to prompt for a value in the minibuffer. The function should
+take four arguments, @var{widget}, @var{prompt}, @var{value}, and
+@var{unbound} and should return a value for widget entered by the user.
+@var{prompt} is the prompt to use. @var{value} is the default value to
+use, unless @var{unbound} is non-nil in which case there are no default
+value. The function should read the value using the method most natural
+for this widget, and does not have to check that it matches.
+@end table
+
+If you want to define a new widget from scratch, use the @code{default}
+widget as its base.
+
+@deffn Widget default
+Widget used as a base for other widgets.
+
+It provides most of the functionality that is referred to as ``by
+default'' in this text.
+@end deffn
+
+@node Widget Browser, Widget Minor Mode, Defining New Widgets, Top
+@comment node-name, next, previous, up
+@section Widget Browser
+
+There is a separate package to browse widgets. This is intended to help
+programmers who want to examine the content of a widget. The browser
+shows the value of each keyword, but uses links for certain keywords
+such as `:parent', which avoids printing cyclic structures.
+
+@deffn Command widget-browse WIDGET
+Create a widget browser for WIDGET.
+When called interactively, prompt for WIDGET.
+@end deffn
+
+@deffn Command widget-browse-other-window WIDGET
+Create a widget browser for WIDGET and show it in another window.
+When called interactively, prompt for WIDGET.
+@end deffn
+
+@deffn Command widget-browse-at POS
+Create a widget browser for the widget at POS.
+When called interactively, use the position of point.
+@end deffn
+
+@node Widget Minor Mode, Utilities, Widget Browser, Top
+@comment node-name, next, previous, up
+@section Widget Minor Mode
+
+There is a minor mode for manipulating widgets in major modes that
+doesn't provide any support for widgets themselves. This is mostly
+intended to be useful for programmers doing experiments.
+
+@deffn Command widget-minor-mode
+Toggle minor mode for traversing widgets.
+With arg, turn widget mode on if and only if arg is positive.
+@end deffn
+
+@defvar widget-minor-mode-keymap
+Keymap used in @code{widget-minor-mode}.
+@end defvar
+
+@node Utilities, Widget Wishlist, Widget Minor Mode, Top
+@comment node-name, next, previous, up
+@section Utilities.
+
+@defun widget-prompt-value widget prompt [ value unbound ]
+Prompt for a value matching @var{widget}, using @var{prompt}.
+The current value is assumed to be @var{value}, unless @var{unbound} is
+non-nil.@refill
+@end defun
+
+@defun widget-get-sibling widget
+Get the item @var{widget} is assumed to toggle.
+This is only meaningful for radio buttons or checkboxes in a list.
+@end defun
+
+@node Widget Wishlist, , Utilities, Top
+@comment node-name, next, previous, up
+@section Wishlist
+
+@itemize @bullet
+@item
+It should be possible to add or remove items from a list with @kbd{C-k}
+and @kbd{C-o} (suggested by @sc{rms}).
+
+@item
+The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single
+dash (@samp{-}). The dash should be a button that, when invoked, ask
+whether you want to add or delete an item (@sc{rms} wanted to git rid of
+the ugly buttons, the dash is my idea).
+
+@item
+The @code{menu-choice} tag should be prettier, something like the abbreviated
+menus in Open Look.
+
+@item
+Finish @code{:tab-order}.
+
+@item
+Make indentation work with glyphs and proportional fonts.
+
+@item
+Add commands to show overview of object and class hierarchies to the
+browser.
+
+@item
+Find a way to disable mouse highlight for inactive widgets.
+
+@item
+Find a way to make glyphs look inactive.
+
+@item
+Add @code{property-list} widget.
+
+@item
+Add @code{association-list} widget.
+
+@item
+Add @code{key-binding} widget.
+
+@item
+Add @code{widget} widget for editing widget specifications.
+
+@item
+Find clean way to implement variable length list.
+See @code{TeX-printer-list} for an explanation.
+
+@item
+@kbd{C-h} in @code{widget-prompt-value} should give type specific help.
+
+@item
+A mailto widget.
+
+@end itemize
+
+@contents
+@bye
--- /dev/null
+@c This is part of the Emacs manual.
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Windows, Frames, Buffers, Top
+@chapter Multiple Windows
+@cindex windows in Emacs
+@cindex multiple windows in Emacs
+
+ Emacs can split a frame into two or many windows. Multiple windows
+can display parts of different buffers, or different parts of one
+buffer. Multiple frames always imply multiple windows, because each
+frame has its own set of windows. Each window belongs to one and only
+one frame.
+
+@menu
+* Basic Window:: Introduction to Emacs windows.
+* Split Window:: New windows are made by splitting existing windows.
+* Other Window:: Moving to another window or doing something to it.
+* Pop Up Window:: Finding a file or buffer in another window.
+* Force Same Window:: Forcing certain buffers to appear in the selected
+ window rather than in another window.
+* Change Window:: Deleting windows and changing their sizes.
+@end menu
+
+@node Basic Window
+@section Concepts of Emacs Windows
+
+ Each Emacs window displays one Emacs buffer at any time. A single
+buffer may appear in more than one window; if it does, any changes in
+its text are displayed in all the windows where it appears. But the
+windows showing the same buffer can show different parts of it, because
+each window has its own value of point.
+
+@cindex selected window
+ At any time, one of the windows is the @dfn{selected window}; the
+buffer this window is displaying is the current buffer. The terminal's
+cursor shows the location of point in this window. Each other window
+has a location of point as well, but since the terminal has only one
+cursor there is no way to show where those locations are. When multiple
+frames are visible in X Windows, each frame has a cursor which appears
+in the frame's selected window. The cursor in the selected frame is
+solid; the cursor in other frames is a hollow box.
+
+ Commands to move point affect the value of point for the selected Emacs
+window only. They do not change the value of point in any other Emacs
+window, even one showing the same buffer. The same is true for commands
+such as @kbd{C-x b} to change the selected buffer in the selected window;
+they do not affect other windows at all. However, there are other commands
+such as @kbd{C-x 4 b} that select a different window and switch buffers in
+it. Also, all commands that display information in a window, including
+(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
+(@code{list-buffers}), work by switching buffers in a nonselected window
+without affecting the selected window.
+
+ When multiple windows show the same buffer, they can have different
+regions, because they can have different values of point. However,
+they all have the same value for the mark, because each buffer has
+only one mark position.
+
+ Each window has its own mode line, which displays the buffer name,
+modification status and major and minor modes of the buffer that is
+displayed in the window. @xref{Mode Line}, for full details on the mode
+line.
+
+@iftex
+@break
+@end iftex
+
+@node Split Window
+@section Splitting Windows
+
+@table @kbd
+@item C-x 2
+Split the selected window into two windows, one above the other
+(@code{split-window-vertically}).
+@item C-x 3
+Split the selected window into two windows positioned side by side
+(@code{split-window-horizontally}).
+@item C-Mouse-2
+In the mode line or scroll bar of a window, split that window.
+@end table
+
+@kindex C-x 2
+@findex split-window-vertically
+ The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the
+selected window into two windows, one above the other. Both windows start
+out displaying the same buffer, with the same value of point. By default
+the two windows each get half the height of the window that was split; a
+numeric argument specifies how many lines to give to the top window.
+
+@kindex C-x 3
+@findex split-window-horizontally
+ @kbd{C-x 3} (@code{split-window-horizontally}) breaks the selected
+window into two side-by-side windows. A numeric argument specifies how
+many columns to give the one on the left. A line of vertical bars
+separates the two windows. Windows that are not the full width of the
+screen have mode lines, but they are truncated. On terminals where
+Emacs does not support highlighting, truncated mode lines sometimes do
+not appear in inverse video.
+
+@kindex C-Mouse-2 @r{(scroll bar)}
+ You can split a window horizontally or vertically by clicking
+@kbd{C-Mouse-2} in the mode line or the scroll bar. The line of
+splitting goes through the place where you click: if you click on the
+mode line, the new scroll bar goes above the spot; if you click in the
+scroll bar, the mode line of the split window is side by side with your
+click.
+
+@vindex truncate-partial-width-windows
+ When a window is less than the full width, text lines too long to fit are
+frequent. Continuing all those lines might be confusing. The variable
+@code{truncate-partial-width-windows} can be set non-@code{nil} to force
+truncation in all windows less than the full width of the screen,
+independent of the buffer being displayed and its value for
+@code{truncate-lines}. @xref{Continuation Lines}.@refill
+
+ Horizontal scrolling is often used in side-by-side windows.
+@xref{Display}.
+
+@vindex split-window-keep-point
+ If @code{split-window-keep-point} is non-@code{nil}, the default, both
+of the windows resulting from @kbd{C-x 2} inherit the value of point
+from the window that was split. This means that scrolling is
+inevitable. If this variable is @code{nil}, then @kbd{C-x 2} tries to
+avoid shifting any text the screen, by putting point in each window at a
+position already visible in the window. It also selects whichever
+window contain the screen line that the cursor was previously on. Some
+users prefer the latter mode on slow terminals.
+
+@node Other Window
+@section Using Other Windows
+
+@table @kbd
+@item C-x o
+Select another window (@code{other-window}). That is @kbd{o}, not zero.
+@item C-M-v
+Scroll the next window (@code{scroll-other-window}).
+@item M-x compare-windows
+Find next place where the text in the selected window does not match
+the text in the next window.
+@item Mouse-1
+@kbd{Mouse-1}, in a window's mode line, selects that window
+but does not move point in it (@code{mouse-select-window}).
+@end table
+
+@kindex C-x o
+@findex other-window
+ To select a different window, click with @kbd{Mouse-1} on its mode
+line. With the keyboard, you can switch windows by typing @kbd{C-x o}
+(@code{other-window}). That is an @kbd{o}, for `other', not a zero.
+When there are more than two windows, this command moves through all the
+windows in a cyclic order, generally top to bottom and left to right.
+After the rightmost and bottommost window, it goes back to the one at
+the upper left corner. A numeric argument means to move several steps
+in the cyclic order of windows. A negative argument moves around the
+cycle in the opposite order. When the minibuffer is active, the
+minibuffer is the last window in the cycle; you can switch from the
+minibuffer window to one of the other windows, and later switch back and
+finish supplying the minibuffer argument that is requested.
+@xref{Minibuffer Edit}.
+
+@kindex C-M-v
+@findex scroll-other-window
+ The usual scrolling commands (@pxref{Display}) apply to the selected
+window only, but there is one command to scroll the next window.
+@kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that
+@kbd{C-x o} would select. It takes arguments, positive and negative,
+like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the window
+that contains the minibuffer help display, if any, rather than the
+next window in the standard cyclic order.)
+
+ The command @kbd{M-x compare-windows} lets you compare two files or
+buffers visible in two windows, by moving through them to the next
+mismatch. @xref{Comparing Files}, for details.
+
+@node Pop Up Window
+@section Displaying in Another Window
+
+@cindex selecting buffers in other windows
+@kindex C-x 4
+ @kbd{C-x 4} is a prefix key for commands that select another window
+(splitting the window if there is only one) and select a buffer in that
+window. Different @kbd{C-x 4} commands have different ways of finding the
+buffer to select.
+
+@table @kbd
+@item C-x 4 b @var{bufname} @key{RET}
+Select buffer @var{bufname} in another window. This runs
+@code{switch-to-buffer-other-window}.
+@item C-x 4 C-o @var{bufname} @key{RET}
+Display buffer @var{bufname} in another window, but
+don't select that buffer or that window. This runs
+@code{display-buffer}.
+@item C-x 4 f @var{filename} @key{RET}
+Visit file @var{filename} and select its buffer in another window. This
+runs @code{find-file-other-window}. @xref{Visiting}.
+@item C-x 4 d @var{directory} @key{RET}
+Select a Dired buffer for directory @var{directory} in another window.
+This runs @code{dired-other-window}. @xref{Dired}.
+@item C-x 4 m
+Start composing a mail message in another window. This runs
+@code{mail-other-window}; its same-window analogue is @kbd{C-x m}
+(@pxref{Sending Mail}).
+@item C-x 4 .
+Find a tag in the current tags table, in another window. This runs
+@code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
+(@pxref{Tags}).
+@item C-x 4 r @var{filename} @key{RET}
+Visit file @var{filename} read-only, and select its buffer in another
+window. This runs @code{find-file-read-only-other-window}.
+@xref{Visiting}.
+@end table
+
+@node Force Same Window
+@section Forcing Display in the Same Window
+
+ Certain Emacs commands switch to a specific buffer with special
+contents. For example, @kbd{M-x shell} switches to a buffer named
+@samp{*Shell*}. By convention, all these commands are written to pop up
+the buffer in a separate window. But you can specify that certain of
+these buffers should appear in the selected window.
+
+@vindex same-window-buffer-names
+ If you add a buffer name to the list @code{same-window-buffer-names},
+the effect is that such commands display that particular buffer by
+switching to it in the selected window. For example, if you add the
+element @code{"*grep*"} to the list, the @code{grep} command will
+display its output buffer in the selected window.
+
+ The default value of @code{same-window-buffer-names} is not
+@code{nil}: it specifies buffer names @samp{*info*}, @samp{*mail*} and
+@samp{*shell*} (as well as others used by more obscure Emacs packages).
+This is why @kbd{M-x shell} normally switches to the @samp{*shell*}
+buffer in the selected window. If you delete this element from the
+value of @code{same-window-buffer-names}, the behavior of @kbd{M-x
+shell} will change---it will pop up the buffer in another window
+instead.
+
+@vindex same-window-regexps
+ You can specify these buffers more generally with the variable
+@code{same-window-regexps}. Set it to a list of regular expressions;
+then any buffer whose name matches one of those regular expressions is
+displayed by switching to it in the selected window. (Once again, this
+applies only to buffers that normally get displayed for you in a
+separate window.) The default value of this variable specifies Telnet
+and rlogin buffers.
+
+ An analogous feature lets you specify buffers which should be
+displayed in their own individual frames. @xref{Special Buffer Frames}.
+
+@node Change Window
+@section Deleting and Rearranging Windows
+
+@table @kbd
+@item C-x 0
+Delete the selected window (@code{delete-window}). The last character
+in this key sequence is a zero.
+@item C-x 1
+Delete all windows in the selected frame except the selected window
+(@code{delete-other-windows}).
+@item C-x 4 0
+Delete the selected window and kill the buffer that was showing in it
+(@code{kill-buffer-and-window}). The last character in this key
+sequence is a zero.
+@item C-x ^
+Make selected window taller (@code{enlarge-window}).
+@item C-x @}
+Make selected window wider (@code{enlarge-window-horizontally}).
+@item C-x @{
+Make selected window narrower (@code{shrink-window-horizontally}).
+@item C-x -
+Shrink this window if its buffer doesn't need so many lines
+(@code{shrink-window-if-larger-than-buffer}).
+@item C-x +
+Make all windows the same height (@code{balance-windows}).
+@item Drag-Mouse-1
+Dragging a window's mode line up or down with @kbd{Mouse-1} changes
+window heights.
+@item Mouse-2
+@kbd{Mouse-2} in a window's mode line deletes all other windows in the frame
+(@code{mouse-delete-other-windows}).
+@item Mouse-3
+@kbd{Mouse-3} in a window's mode line deletes that window
+(@code{mouse-delete-window}).
+@end table
+
+@kindex C-x 0
+@findex delete-window
+ To delete a window, type @kbd{C-x 0} (@code{delete-window}). (That is
+a zero.) The space occupied by the deleted window is given to an
+adjacent window (but not the minibuffer window, even if that is active
+at the time). Once a window is deleted, its attributes are forgotten;
+only restoring a window configuration can bring it back. Deleting the
+window has no effect on the buffer it used to display; the buffer
+continues to exist, and you can select it in any window with @kbd{C-x
+b}.
+
+@findex kill-buffer-and-window
+@kindex C-x 4 0
+ @kbd{C-x 4 0} (@code{kill-buffer-and-window}) is a stronger command
+than @kbd{C-x 0}; it kills the current buffer and then deletes the
+selected window.
+
+@kindex C-x 1
+@findex delete-other-windows
+ @kbd{C-x 1} (@code{delete-other-windows}) is more powerful in a
+different way; it deletes all the windows except the selected one (and
+the minibuffer); the selected window expands to use the whole frame
+except for the echo area.
+
+ You can also delete a window by clicking on its mode line with
+@kbd{Mouse-2}, and delete all the windows in a frame except one window
+by clicking on that window's mode line with @kbd{Mouse-3}.
+
+ The easiest way to adjust window heights is with a mouse. If you
+press @kbd{Mouse-1} on a mode line, you can drag that mode line up or
+down, changing the heights of the windows above and below it.
+
+@kindex C-x ^
+@findex enlarge-window
+@kindex C-x @}
+@findex enlarge-window-horizontally
+@vindex window-min-height
+@vindex window-min-width
+ To readjust the division of space among vertically adjacent windows,
+use @kbd{C-x ^} (@code{enlarge-window}). It makes the currently
+selected window get one line bigger, or as many lines as is specified
+with a numeric argument. With a negative argument, it makes the
+selected window smaller. @kbd{C-x @}}
+(@code{enlarge-window-horizontally}) makes the selected window wider by
+the specified number of columns. @kbd{C-x @{}
+(@code{shrink-window-horizontally}) makes the selected window narrower
+by the specified number of columns.
+
+ When you make a window bigger, the space comes from one of its
+neighbors. If this makes any window too small, it is deleted and its
+space is given to an adjacent window. The minimum size is specified by
+the variables @code{window-min-height} and @code{window-min-width}.
+
+@kindex C-x -
+@findex shrink-window-if-larger-than-buffer
+ The command @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer})
+reduces the height of the selected window, if it is taller than
+necessary to show the whole text of the buffer it is displaying. It
+gives the extra lines to other windows in the frame.
+
+@kindex C-x +
+@findex balance-windows
+ You can also use @kbd{C-x +} (@code{balance-windows}) to even out the
+heights of all the windows in the selected frame.
+
+ @xref{Minibuffer Edit}, for information about the Resize-Minibuffer
+mode, which automatically changes the size of the minibuffer window to
+fit the text in the minibuffer.